---
url: https://developers.zarv.com/api/id-v3/enrichment-batch.md
description: >-
  Crie até 500 enriquecimentos do Zarv ID v3 num único request: resposta com o
  documento de cada item, erros por item, idempotência por bloco e como listar
  os itens do lote.
---

# Enriquecimento em lote

## Visão Geral

`POST /api/v3/enrichments/batch` cria até **500 enriquecimentos** de uma vez, todos com o mesmo perfil. É a rota para processar uma base de documentos sem fazer um `POST /api/v3/enrichments` por documento.

Diferente da criação unitária, o lote **não espera** o resultado: a resposta é sempre `202`, assim que os itens estão gravados. O andamento é acompanhado pelos próprios enriquecimentos (veja [Ler os resultados](#ler-os-resultados)).

Os lotes rodam numa fila própria, separada da fila das consultas unitárias. Um lote grande não atrasa as consultas feitas por `POST /api/v3/enrichments`.

## Requisição

Para mais de 500 documentos, divida o arquivo em blocos de até 500 e envie os requests em sequência. Acima de 500 itens, o request inteiro é recusado com `413 batch_too_large`.

| Campo       | Tipo   | Obrigatório | Descrição                                                                                                                          |
| ----------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `profileId` | string | Sim         | Um perfil para todos os itens.                                                                                                     |
| `items`     | array  | Sim         | De 1 a 500 itens, cada um com `document` (obrigatório) e `metadata` (opcional).                                                    |
| `options`   | object | Não         | As mesmas opções da criação unitária (add-ons e `deadline`).                                                                       |
| `callback`  | object | Não         | Veja [Webhook](/api/id-v3/webhook). Copiado para cada item: cada enriquecimento que não termina logo envia o seu próprio callback. |
| `metadata`  | object | Não         | Objeto livre, copiado para cada item.                                                                                              |

Perfil, `options`, `callback` e `metadata` valem para o request inteiro. O `metadata` de um item **sobrescreve, chave a chave**, o `metadata` do lote para aquele item (só no primeiro nível: o valor de uma chave é substituído por inteiro).

```json
{
  "profileId": "8f14e45f-ceea-4e7a-9c1a-2b3c4d5e6f70",
  "metadata": { "campanha": "out-2026", "origem": "carga-1" },
  "callback": { "url": "https://sua-empresa.com/webhooks/zarv" },
  "items": [
    { "document": "111.444.777-35" },
    { "document": "529.982.247-25", "metadata": { "origem": "carga-2" } },
    { "document": "123" }
  ]
}
```

Neste exemplo, o `metadata` gravado em cada item criado fica:

| Item | `metadata` do enriquecimento                 |
| ---- | -------------------------------------------- |
| `0`  | `{"campanha":"out-2026","origem":"carga-1"}` |
| `1`  | `{"campanha":"out-2026","origem":"carga-2"}` |

O item `2` não é criado (`invalid_document`), então não tem `metadata`.

Envie um `Idempotency-Key` por request (por bloco). Veja [Reenvio seguro](#reenvio-seguro).

## Resposta

A resposta `202` traz uma entrada por item enviado, **na ordem do request**, cada uma com o seu `index` (posição do item no array `items`, começando em `0`) e o seu `document`: **o documento exatamente como enviado**, sem normalização, tanto no item criado quanto no item com erro. Assim o seu sistema liga cada documento que enviou ao `id` gerado (ou ao `error`) sem depender da posição.

```json
{
  "batchId": "bat_0199a0b2-7c1e-7d4a-9f0e-3b1c2d4e5f60",
  "total": 3,
  "created": 2,
  "failed": 1,
  "items": [
    {
      "index": 0,
      "id": "enr_0199a0b2-7c1f-7a31-8c2d-5e6f7a8b9c0d",
      "document": "111.444.777-35"
    },
    {
      "index": 1,
      "id": "enr_0199a0b2-7c20-7b42-9d3e-6f7a8b9c0d1e",
      "document": "529.982.247-25"
    },
    {
      "index": 2,
      "document": "123",
      "error": {
        "code": "invalid_document",
        "message": "document is not a valid CPF or CNPJ"
      }
    }
  ]
}
```

| Campo     | Descrição                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------- |
| `batchId` | Identifica o lote. Use para listar os itens.                                                   |
| `total`   | Quantos itens o request trouxe.                                                                |
| `created` | Quantos enriquecimentos foram criados.                                                         |
| `failed`  | Quantos itens não foram criados (têm `error`).                                                 |
| `items`   | `{index, id, document}` para o item criado ou `{index, document, error}` para o item recusado. |

O `document` de cada entrada é o único lugar onde o documento aparece na resposta: a `message` de um erro nunca o traz.

Não há estado do lote, endpoint de progresso nem aviso de "lote concluído": acompanhe pelos itens.

## Erros

### Erros do request inteiro

Nada é criado nem cobrado. A resposta usa o envelope de erro de sempre e os mesmos códigos da criação unitária para perfil, contrato e opções (`400 invalid_body`, `404 profile_not_found`, `402 contract_required` ou `action_not_contracted`, `422 module_not_in_profile`, `422 profile_kind_mismatch`, `422 profile_not_billable`, `503 profiles_unavailable`, entre outros), além de:

| Status | Código                   | Quando                                                      |
| ------ | ------------------------ | ----------------------------------------------------------- |
| `400`  | `batch_empty`            | O request não tem nenhum item.                              |
| `413`  | `batch_too_large`        | Mais de 500 itens. Divida em requests sequenciais.          |
| `422`  | `idempotency_key_reused` | A mesma `Idempotency-Key` foi usada com um corpo diferente. |

### Erros por item

O request responde `202` e o item recusado traz `error` na própria entrada. **Um item com erro não é criado nem cobrado**; os demais seguem normalmente.

| Código                    | Quando                                                                                                                      |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `invalid_document`        | O `document` não é um CPF ou CNPJ válido.                                                                                   |
| `profile_entity_mismatch` | O documento não é do tipo do perfil (CPF num perfil de CNPJ, ou o contrário).                                               |
| `duplicate_in_request`    | O mesmo documento (já normalizado) aparece mais de uma vez no request. O primeiro é criado; os seguintes recebem este erro. |
| `invalid_metadata`        | O `metadata` do item é inválido.                                                                                            |

O mesmo documento em requests **diferentes** gera enriquecimentos diferentes, como na criação unitária.

## Reenvio seguro

Mande um `Idempotency-Key` por request (por bloco, por exemplo um UUID gravado junto do bloco). Se a conexão cair ou o resultado ficar incerto, reenvie o **mesmo bloco com a mesma chave**: a resposta original é devolvida, sem duplicar nem cobrar de novo. O replay traz os mesmos `id` e o mesmo `document` de cada item, como enviado no corpo reenviado. A mesma chave com um corpo diferente é `422 idempotency_key_reused`.

## Ler os resultados

Cada item criado é um enriquecimento comum:

* leitura por `GET /api/v3/enrichments/{id}`, `GET /api/v3/enrichments/{id}/modules/{module}` e a [rede de processos](/api/id-v3/lawsuits-network), como em qualquer outro;
* callback por item, quando o request trouxe `callback` ([Webhook](/api/id-v3/webhook));
* cobrança por item criado.

Para listar os itens de um lote, filtre pelo `batchId`:

```
GET /api/v3/enrichments?batchId=bat_0199a0b2-7c1e-7d4a-9f0e-3b1c2d4e5f60
```

Para casar cada item da listagem com o que você enviou, use o mapa documento → `id` da resposta do lote: cada enriquecimento listado traz o seu `id`. O `document` da listagem vem normalizado (só dígitos, ou maiúsculas no CNPJ alfanumérico), então compare por `id`, ou normalize o documento enviado antes de comparar pelo documento.

A listagem aceita também `lane=batch` (ou `lane=interactive`) para separar o que veio de lote do que veio da criação unitária. Cada enriquecimento traz `lane` e, quando criado por um lote, `batchId`.