Solicitudes en lote

Algunas consultas se hacen naturalmente en bloque: tienes una lista de radicados, cédulas o NITs y quieres resolverlos todos de una vez. Los endpoints en lote reciben un arreglo de entradas, las resuelven de forma concurrente del lado de Croma y devuelven un resultado por elemento, así haces una sola llamada en lugar de iterar.

El modo en lote es una adición, no un reemplazo. El endpoint de un solo elemento sigue siendo el camino más simple para una consulta. Usa el lote cuando tengas una lista.

¿Qué endpoints admiten lote?

Fuente	Endpoint en lote
Rama Judicial (por radicado)	`POST /co/rama-judicial/cases-by-radicado/v1/batch`

Hay más endpoints en lote en camino. Cada uno sigue exactamente la forma de esta página, así que una vez integras uno, los integras todos.

Forma de la solicitud

El cuerpo de un lote siempre es { "items": [ … ] }, donde cada elemento es el mismo cuerpo que recibe el endpoint individual. Envía entre 1 y 50 elementos.

curl https://api.croma.run/co/rama-judicial/cases-by-radicado/v1/batch \
  -H "Authorization: Bearer $CROMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "items": [
        { "registration_number": "11001600001720180327700" },
        { "registration_number": "05001310300120190012300" }
      ] }'

Forma de la respuesta

Un lote siempre devuelve 200 con un arreglo results (en el mismo orden que tus items) y un summary:

{
  "data": {
    "results": [
      {
        "index": 0,
        "status": "completed",
        "cache_hit": false,
        "data": { "found": true, "registration_number": "11001600001720180327700", "primary_case": {  }, "actions": [  ] }
      },
      {
        "index": 1,
        "status": "error",
        "error": { "type": "upstream_error", "code": "rama_judicial_upstream", "message": "The Rama Judicial lookup could not be completed." }
      }
    ],
    "summary": { "total": 2, "completed": 1, "errors": 1, "cache_hits": 0 }
  }
}

Campo	Significado
`results[].index`	Posición de base 0 en tu arreglo `items`. Los resultados se devuelven en el orden de entrada.
`results[].status`	`completed` o `error` para ese elemento.
`results[].data`	La carga útil `data` normal del endpoint individual. Presente cuando `status` es `completed`.
`results[].cache_hit`	`true` cuando ese elemento se sirvió desde caché. Presente cuando `status` es `completed`.
`results[].error`	`{ type, code, message }`, la misma forma de error que devuelve el endpoint individual. Presente cuando `status` es `error`.
`summary`	Conteos del lote: `total`, `completed`, `errors`, `cache_hits`.

Fallas parciales

Un solo elemento defectuoso nunca hace fallar todo el lote. Si la consulta de un radicado falla, ese elemento regresa con status: "error" mientras el resto se resuelve. Itera siempre results y revisa el status de cada elemento. Hay dos capas distintas que manejar:

Los errores de validación hacen fallar toda la solicitud; los errores de la fuente son por elemento.

Un elemento mal formado (por ejemplo un registration_number que no tiene de 20 a 25 dígitos) se rechaza de entrada con un 400 y un param como items.0.registration_number. No se ejecuta nada.
Un elemento bien formado cuya consulta a la fuente falla regresa dentro de results como status: "error", con el lote en sí todavía en 200.

TypeScript

const res = await fetch(
  "https://api.croma.run/co/rama-judicial/cases-by-radicado/v1/batch",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CROMA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      items: [
        { registration_number: "11001600001720180327700" },
        { registration_number: "05001310300120190012300" },
      ],
    }),
  },
);

if (res.status === 400) {
  // un elemento mal formado; no se ejecutó nada. Corrígelo y reenvía.
  throw new Error("invalid batch body");
}

const { data } = await res.json();
for (const item of data.results) {
  if (item.status === "completed") {
    handle(item.data); // tu lógica normal por consulta
  } else {
    console.warn(`item ${item.index} failed:`, item.error.message);
  }
}

Límites y comportamiento

Hasta 50 elementos por solicitud. Más de eso se rechaza con un 400.
Cada elemento cuenta como una solicitud contra tu cuota. Un lote de 10 elementos consume 10 de tu límite de tasa, igual que 10 llamadas individuales, así que un lote que excedería tu cuota restante devuelve 429.
Los duplicados se deduplican. La misma entrada dos veces en un lote se consulta una sola vez; ambas posiciones reciben el resultado.
El caché se comparte con el endpoint individual. Un elemento que consultaste hace poco (individual o en lote) regresa con cache_hit: true.

Límites de tasa

Cómo funcionan la cuota por elemento y los encabezados X-RateLimit-*.

Errores

El sobre de error y cada código de error.

Primeros pasos

Colombia

Perú

Global

Solicitudes en lote

¿Qué endpoints admiten lote?

Forma de la solicitud

Forma de la respuesta

Fallas parciales

Límites y comportamiento

Límites de tasa

Errores

​¿Qué endpoints admiten lote?

​Forma de la solicitud

​Forma de la respuesta

​Fallas parciales

​Límites y comportamiento

Límites de tasa

Errores

¿Qué endpoints admiten lote?

Forma de la solicitud

Forma de la respuesta

Fallas parciales

Límites y comportamiento