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

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

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

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.

{
  "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, como em qualquer outro;
• callback por item, quando o request trouxe callback (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.