> ## 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.

# Solicitações em lote

> Resolva muitas consultas em uma única chamada, com resultados por elemento e falhas parciais.

Algumas consultas se fazem naturalmente em bloco: você tem uma lista de radicados,
cédulas ou NITs e quer resolver todos de uma vez. Os endpoints em lote
recebem um array de entradas, resolvem essas entradas **de forma concorrente** do lado
do Croma e retornam um resultado por elemento, assim você faz uma única chamada em
vez de iterar.

<Note>
  O modo em lote é uma adição, não uma substituição. O endpoint de um único
  elemento continua sendo o caminho mais simples para uma consulta. Use o lote
  quando você tiver uma lista.
</Note>

## Quais endpoints aceitam lote?

| Fonte                                                             | Endpoint em lote                                    |
| ----------------------------------------------------------------- | --------------------------------------------------- |
| [Rama Judicial](/pt/guides/colombia/rama-judicial) (por radicado) | `POST /co/rama-judicial/cases-by-radicado/v1/batch` |

Mais endpoints em lote estão a caminho. Cada um segue exatamente a forma desta
página, então uma vez que você integra um, integra todos.

## Forma da solicitação

O corpo de um lote é sempre `{ "items": [ … ] }`, onde cada elemento é o
**mesmo corpo que o endpoint individual recebe**. Envie entre **1 e 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 da resposta

Um lote sempre retorna `200` com um array `results` (na mesma ordem dos seus
`items`) e um `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`     | Posição de base 0 no seu array `items`. Os resultados são retornados na ordem de entrada.                               |
| `results[].status`    | `completed` ou `error` para esse elemento.                                                                              |
| `results[].data`      | A carga útil `data` normal do endpoint individual. Presente quando `status` é `completed`.                              |
| `results[].cache_hit` | `true` quando esse elemento foi servido a partir do cache. Presente quando `status` é `completed`.                      |
| `results[].error`     | `{ type, code, message }`, a mesma forma de erro que o endpoint individual retorna. Presente quando `status` é `error`. |
| `summary`             | Contagens do lote: `total`, `completed`, `errors`, `cache_hits`.                                                        |

## Falhas parciais

Um único elemento defeituoso nunca faz o lote inteiro falhar. Se a consulta de um
radicado falha, esse elemento volta com `status: "error"` enquanto o resto é
resolvido. Sempre itere sobre `results` e verifique o `status` de cada elemento.

Há duas camadas distintas a tratar:

<Note>
  **Os erros de validação fazem toda a solicitação falhar; os erros da
  fonte são por elemento.**

  * Um elemento malformado (por exemplo um `registration_number` que não tem de
    20 a 25 dígitos) é rejeitado de imediato com um `400` e um `param` como
    `items.0.registration_number`. Nada é executado.
  * Um elemento bem formado cuja consulta à fonte falha volta dentro de
    `results` como `status: "error"`, com o lote em si ainda em `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);
  }
}
```

## Limites e comportamento

* **Até 50 elementos** por solicitação. Mais do que isso é rejeitado com um `400`.
* **Cada elemento conta como uma solicitação** contra a sua cota. Um lote de 10
  elementos consome 10 do seu [limite de taxa](/pt/rate-limits), igual a 10
  chamadas individuais, então um lote que excederia sua cota restante retorna
  `429`.
* **Os duplicados são deduplicados.** A mesma entrada duas vezes em um lote é
  consultada uma única vez; ambas as posições recebem o resultado.
* **O cache é compartilhado** com o endpoint individual. Um elemento que você
  consultou há pouco (individual ou em lote) volta com `cache_hit: true`.

<Card title="Limites de taxa" icon="gauge-high" href="/pt/rate-limits">
  Como funcionam a cota por elemento e os cabeçalhos `X-RateLimit-*`.
</Card>

<Card title="Erros" icon="triangle-exclamation" href="/pt/errors">
  O envelope de erro e cada código de erro.
</Card>