Solicitações em lote

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.

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.

Quais endpoints aceitam lote?

Fonte	Endpoint em lote
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.

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:

{
  "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:

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.

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);
  }
}

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

Limites de taxa

Como funcionam a cota por elemento e os cabeçalhos X-RateLimit-*.

Erros

O envelope de erro e cada código de erro.

Primeiros passos

Países

Solicitações em lote

Quais endpoints aceitam lote?

Forma da solicitação

Forma da resposta

Falhas parciais

Limites e comportamento

Limites de taxa

Erros

​Quais endpoints aceitam lote?

​Forma da solicitação

​Forma da resposta

​Falhas parciais

​Limites e comportamento

Limites de taxa

Erros

Quais endpoints aceitam lote?

Forma da solicitação

Forma da resposta

Falhas parciais

Limites e comportamento