Documentação da API LeadCNPJ

Visão Geral

Idempotency-Key

Em métodos não-idempotentes por natureza (POST, PUT, PATCH, DELETE), envie o header opcional Idempotency-Key pra dedup de retries:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Se a mesma key for reenviada com mesmo body em até 24h, a API retorna a resposta cacheada da primeira chamada — sem re-debitar créditos nem criar duplicatas. A resposta repetida vem com o header Idempotency-Replayed: true.

Quando usar

• Sempre em POST /v1/enriquecer — criar 2 jobs em paralelo por timeout debita créditos em duplicata.
• Em POST /v1/empresas/buscar — útil em pipelines de ETL que retentam pra robustez.

Formato recomendado

Use UUID v4 ou ULID. 1-100 caracteres ASCII imprimíveis. Gere no cliente, persista junto com o request:

# Bash
KEY=$(uuidgen)

curl -X POST https://leadcnpj.com.br/api/v1/enriquecer \
  -H "Authorization: Bearer leadcnpj_live_..." \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpjs":["12345678000190"]}'

Conflitos

• 409 idempotency_conflict: mesma key reenviada com body diferente — use uma key nova.
• 409 idempotency_in_progress: outra request com a mesma key ainda processando — aguarde Retry-After: 1 segundo e tente de novo.

Política de cache

• Cacheia: 2xx (sucesso) e 4xx exceto 429 (erros determinísticos).
• Não cacheia: 429 (rate limit) e 5xx (erros transientes) — libera reserva pra retry funcionar.
• TTL: 24h após a primeira chamada.