> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solicitudes en lote

> Resuelve muchas consultas en una sola llamada, con resultados por elemento y fallas parciales.

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.

<Note>
  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.
</Note>

## ¿Qué endpoints admiten lote?

| Fuente                                                            | Endpoint en lote                                    |
| ----------------------------------------------------------------- | --------------------------------------------------- |
| [Rama Judicial](/es/guides/colombia/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.

```bash theme={"dark"}
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`:

```json theme={"dark"}
{
  "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:

<Note>
  **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`.
</Note>

```ts TypeScript theme={"dark"}
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](/es/rate-limits), 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`.

<Card title="Límites de tasa" icon="gauge-high" href="/es/rate-limits">
  Cómo funcionan la cuota por elemento y los encabezados `X-RateLimit-*`.
</Card>

<Card title="Errores" icon="triangle-exclamation" href="/es/errors">
  El sobre de error y cada código de error.
</Card>