API REST LeadCNPJ — Consulta CNPJ e Enriquecimento | Ajuda

O que é a API REST da LeadCNPJ?

A API REST permite integrar os dados da LeadCNPJ diretamente ao seu sistema, CRM ou pipeline de dados — sem passar pela interface. Ela usa o mesmo saldo de créditos da plataforma, com uma diferença a seu favor: nos planos com API cada consulta custa metade de uma consulta feita no app (veja abaixo).

O que dá para fazer

• Consultar uma empresa por CNPJ — GET /api/v1/empresa/{cnpj}: dados cadastrais completos da Receita Federal.
• Buscar empresas com filtros — POST /api/v1/empresas/buscar: os principais filtros da Busca Avançada, em JSON.
• Enriquecer em lote — POST /api/v1/enriquecer: envia uma lista de CNPJs e acompanha o processamento assíncrono pelo job_id.

Chaves de API

Gere e revogue suas chaves em Configurações → API (/app/api_keys/). A autenticação é por Bearer token no cabeçalho Authorization. A chave só é exibida uma vez, na criação — guarde-a em local seguro. Em contas com Grupo Empresarial, o consumo debita do saldo compartilhado do grupo.

Créditos valem em dobro na API

Nos planos com API, cada crédito rende exatamente 2 consultas: cada unidade faturável (resultado retornado na busca, CNPJ enriquecido, consulta avulsa) custa 0,5 crédito. A contabilidade de meio crédito garante isso mesmo em consultas avulsas — duas consultas de 1 unidade, ainda que em momentos diferentes, debitam 1 crédito no total. Exemplos: uma busca que retorna 10 empresas debita 5 créditos; um lote de enriquecimento com 100 CNPJs encontrados debita 50. CNPJs não encontrados nunca são cobrados.

Limites e boas práticas

• Limite de requisições por minuto conforme o plano (Growth 30, Scale 60, Scale AI 100, Enterprise ilimitado) — a resposta informa quando o limite é atingido (HTTP 429).
• Idempotência — envie o cabeçalho Idempotency-Key (padrão Stripe: uma string única por operação) nos POST para que uma retentativa não gere cobrança duplicada. A resposta repetida vem com Idempotency-Replayed: true.
• Auditoria — todas as chamadas ficam registradas com os créditos consumidos, em conformidade com a LGPD.