Documentação da API LeadCNPJ

Endpoints · Enriquecimento

Enriquece uma lista de CNPJs com dados completos

Recebe uma lista de até 1000 CNPJs e retorna dados completos (mesma estrutura da consulta unitária) pra cada um.

Modo síncrono (até 100 CNPJs): processa imediatamente, retorna 200 com results. Modo assíncrono (101-1000 CNPJs): cria job, retorna 202 com job_id. Faça polling em GET /enriquecer/:job_id a cada 5-10s.

Custo: 1 consulta por CNPJ encontrado (0,5 crédito nos planos com API). Não-encontrados não são cobrados.

Recomendação forte: envie sempre Idempotency-Key neste endpoint. Em caso de timeout de rede o cliente pode retentar sem risco de criar 2 jobs ou debitar créditos em duplicata.

Parâmetros

Nome	Em	Obrigatório	Descrição
Idempotency-Key	header	não	Identificador único da requisição (sugestão: UUID v4 ou ULID gerado pelo cliente). Se a mesma key for reenviada com mesmo body em até 24h, a API retorna a resposta cacheada da primeira chamada com header `Idempotency-Replayed: true`. Reuso com body diferente → 409 idempotency_conflict.

Body da requisição

Campo	Tipo	Descrição
cnpjs obrigatório	array<string>	Lista de CNPJs (com ou sem máscara).

Exemplo:

{
    "cnpjs": [
        "12.345.678/0001-90",
        "98765432000110"
    ]
}

Respostas

Status	Descrição
200	Resultado síncrono (≤100 CNPJs).
202	Job assíncrono criado (>100 CNPJs).
401	Token ausente, inválido ou revogado.
402	Créditos insuficientes pra completar a operação.
403	Plano não permite uso da API ou escopo insuficiente.
422	Body ou query params inválidos.
429	Excedeu o rate limit. Veja header Retry-After.
409	Idempotency-Key já foi usada em até 24h com um corpo de requisição diferente. Errors codes possíveis: `idempotency_conflict` (mesma key, body diferente), `idempotency_in_progress` (outra request com a mesma key ainda processando — Retry-After=1).

Exemplo curl

curl -X POST https://leadcnpj.com.br/api/v1/enriquecer \
  -H "Authorization: Bearer leadcnpj_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"cnpjs":["12.345.678/0001-90","98765432000110"]}'