Upsert por Lote

Crea o actualiza hasta 500 rutas en una sola operación, con reporte de resultado por item.

POST /api/integration/routes/batch-upsert

Crea o actualiza (upsert) hasta 500 rutas en una sola operación. Es el punto de entrada de integración para cargar el catálogo de rutas desde un sistema externo.

Auth: Requerida — permiso route:batch-upsert

Éxito parcial. Una vez que el cuerpo pasa la validación de formato, cada item se procesa de forma independiente: los que se pueden persistir se persisten, y los que fallan se reportan en errors[] con un código estable — un item que falla no deshace a los demás. Revisa siempre summary.failed y errors en la respuesta.

Clave del upsert

Cada item se busca entre las rutas existentes por code. Si existe una ruta con ese code se actualiza (cuenta en summary.updated); si no, se crea (summary.created).

Cuerpo de la Petición

Campo	Tipo	Requerido	Descripción
`items`	object[]	Sí	Lista de rutas a escribir (mínimo 1, máximo 500).

Cada elemento de items:

Campo	Tipo	Requerido	Descripción
`code`	string	Sí	Código de la ruta. Clave del upsert.
`name`	string	Sí	Nombre visible de la ruta.

Ejemplo

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()

Respuesta `200 OK`

En este ejemplo, ROUTE-NORTH ya existía y se actualizó, y las otras dos rutas se crearon:

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

Campos de la respuesta

Campo	Tipo	Descripción
`summary.total`	number	Total de items enviados.
`summary.created`	number	Items insertados (rutas nuevas).
`summary.updated`	number	Items actualizados (rutas existentes modificadas).
`summary.failed`	number	Items que no se pudieron persistir.
`errors`	object[]	Detalle por item fallido (vacío si todos tuvieron éxito).
`errors[].index`	number	Posición (base 0) del item dentro del array `items` enviado.
`errors[].identifier`	string	El `code` del item fallido.
`errors[].error`	string	Código de error estable (ver tabla siguiente).
`errors[].message`	string	Mensaje legible para humanos/logs con la causa.

Códigos de error por item

`error`	Significado
`upsert_error`	El item no se pudo persistir; `message` trae la causa.

Errores (de la request completa)

Status	Descripción
`400`	`items` vacío o con más de 500 elementos; un item que no cumple el formato (campo requerido ausente o tipo inválido); o una propiedad no declarada aquí.
`401`	Clave de API faltante o inválida.
`403`	La clave de API no tiene el permiso `route:batch-upsert`.