Upsert por Lote

Crie ou atualize até 500 rotas em uma única operação, com relatório de resultado por item.

POST /api/integration/routes/batch-upsert

Cria ou atualiza (upsert) até 500 rotas em uma única operação. É o ponto de entrada de integração para carregar o catálogo de rotas a partir de um sistema externo.

Auth: Obrigatório — permissão route:batch-upsert

Sucesso parcial. Depois que o corpo passa na validação de formato, cada item é processado de forma independente: os que podem ser persistidos são persistidos, e os que falham são reportados em errors[] com um código estável — um item que falha não desfaz os demais. Sempre verifique summary.failed e errors na resposta.

Chave do upsert

Cada item é procurado entre as rotas existentes por code. Se existir uma rota com esse code, ela é atualizada (conta em summary.updated); caso contrário, é criada (summary.created).

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`items`	object[]	Sim	Lista de rotas a gravar (mínimo 1, máximo 500).

Cada elemento de items:

Campo	Tipo	Obrigatório	Descrição
`code`	string	Sim	Código da rota. Chave do upsert.
`name`	string	Sim	Nome de exibição da rota.

Exemplo

curl -X POST "https://api.reten.ai/api/integration/routes/batch-upsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "code": "ROUTE-NORTH", "name": "North Zone" },
      { "code": "ROUTE-SOUTH", "name": "South Zone" },
      { "code": "ROUTE-CENTRAL", "name": "Central Zone" }
    ]
  }'

const response = await fetch(
  "https://api.reten.ai/api/integration/routes/batch-upsert",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      items: [
        { code: "ROUTE-NORTH", name: "North Zone" },
        { code: "ROUTE-SOUTH", name: "South Zone" },
        { code: "ROUTE-CENTRAL", name: "Central Zone" },
      ],
    }),
  },
);
const result = await response.json();

import requests

response = requests.post(
    "https://api.reten.ai/api/integration/routes/batch-upsert",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "items": [
            {"code": "ROUTE-NORTH", "name": "North Zone"},
            {"code": "ROUTE-SOUTH", "name": "South Zone"},
            {"code": "ROUTE-CENTRAL", "name": "Central Zone"},
        ],
    },
)
result = response.json()

Resposta `200 OK`

Neste exemplo, ROUTE-NORTH já existia e foi atualizada, e as outras duas rotas foram criadas:

{
  "summary": {
    "total": 3,
    "created": 2,
    "updated": 1,
    "failed": 0
  },
  "errors": []
}

Campos da resposta

Campo	Tipo	Descrição
`summary.total`	number	Total de items enviados.
`summary.created`	number	Items inseridos (rotas novas).
`summary.updated`	number	Items atualizados (rotas existentes modificadas).
`summary.failed`	number	Items que não puderam ser persistidos.
`errors`	object[]	Detalhe por item que falhou (vazio se todos tiveram sucesso).
`errors[].index`	number	Posição (base 0) do item dentro do array `items` enviado.
`errors[].identifier`	string	O `code` do item que falhou.
`errors[].error`	string	Código de erro estável (veja tabela abaixo).
`errors[].message`	string	Mensagem legível para humanos/logs com a causa.

Códigos de erro por item

`error`	Significado
`upsert_error`	O item não pôde ser persistido; `message` traz a causa.

Erros (da request completa)

Status	Descrição
`400`	`items` vazio ou com mais de 500 elementos; um item que não cumpre o formato (campo obrigatório ausente ou tipo inválido); ou uma propriedade não declarada aqui.
`401`	Chave de API ausente ou inválida.
`403`	A chave de API não tem a permissão `route:batch-upsert`.