API REST · v1.2.0

Documentação da API LeadCNPJ

Consulte dados de prospecção ou conecte seu sistema ao CRM: leads, oportunidades, plano, créditos e agentes de IA. Cada finalidade usa uma chave própria.

API REST · v1.2.0

Introdução

API pública do LeadCNPJ pra consultar dados de empresas brasileiras (Receita Federal), buscar empresas por filtros firmográficos e enriquecer listas de CNPJs em lote.

Base URL

https://leadcnpj.com.br/api/v1

Planos com acesso à API

API disponível nos planos Growth, Scale, Scale AI e Enterprise. Limites de rate limit por plano:

  • Growth: 30 requisições por minuto
  • Scale: 60 requisições por minuto
  • Scale AI: 100 requisições por minuto
  • Enterprise: ilimitado

API do sistema

Em Configurações → API, crie uma chave com finalidade Sistema. Ela usa o prefixo leadcnpj_system_ e só lê dados da conta em que foi criada: leads visíveis ao titular, vencimento do plano, saldo de créditos e status dos agentes do titular. As consultas e gravações de cadastros não consomem créditos e seguem o limite por minuto do plano. Para criar ou atualizar, escolha Leitura e escrita e consulte o guia de escrita.

curl -H "Authorization: Bearer leadcnpj_system_..." \
     https://leadcnpj.com.br/api/v1/sistema/conta

Consulte também /sistema/crm/leads, /sistema/crm/leads/{id}, /sistema/agentes e /sistema/agentes/{id} na lista de endpoints. Chaves de prospecção e de sistema não são intercambiáveis. A troca da conta ativa exige uma nova chave, e o titular precisa manter acesso de proprietário ou administrador.

Créditos por chamada

As chamadas de prospecção consomem créditos do plano do dono da chave. As consultas da API do sistema não consomem créditos:

EndpointCustoRefund
GET /v1/empresa/:cnpj1 consulta (+3 com ?enriquecer=true, total 4)Sim, se CNPJ não existir
POST /v1/empresas/buscar1 consulta por CNPJ retornado—
POST /v1/enriquecer1 consulta por CNPJ enriquecidoSim, refund de não-encontrados

Benefício Growth, Scale e Scale AI: cada consulta via API custa apenas 0,5 crédito — o mesmo saldo do plano rende o dobro de consultas pela API. Nos demais planos, 1 consulta = 1 crédito. O campo meta.creditos_consumidos de cada resposta mostra o custo efetivo.

Política de dados

A API entrega apenas:

  • Dados públicos da Receita Federal (CNPJ, razão social, QSA, CNAE, endereço, contatos públicos);
  • Dados da conta da chave de sistema: leads e oportunidades visíveis ao titular, plano, créditos e agentes.

O acesso ao CRM respeita a conta e a visibilidade do titular. A API não executa o Copilot nem envia mensagens de WhatsApp; a consulta de agentes informa apenas seu estado.

Normalização automática (diferencial)

A Receita Federal entrega tudo em CAIXA ALTA, sem máscaras, com placeholders como (0000) 00000000 e e-mails em maiúsculas como CONTATO@EMPRESA.COM.BR. A API faz a limpeza pra você, entregando dados prontos pra CRM, e-mails de outreach e exportação CSV:

  • Title Case pt-BR em razão social, nome fantasia, logradouro, bairro, município, complemento e nome dos sócios. Conectores (de, da, do, e, em, …) ficam minúsculos quando não são a primeira palavra. Acrônimos legais (LTDA, ME, EPP, EIRELI, S/A), UFs (SP, RJ, MG, RS…) e siglas comuns (CIA, TI, RG…) voltam pra CAPS.
  • E-mails em lowercase + validados. CONTATO@EMPRESA.COM.BR → contato@empresa.com.br. E-mails inválidos viram null. Listas (enriquecimento) ficam dedup'd case-insensitive.
  • Telefones com máscara e filtro de placeholder. (0000) 00000000 e variantes (campo "declarado vazio" da RFB) viram null. Números válidos ganham hífen no formato fixo (XXXX-XXXX) ou móvel (XXXXX-XXXX).
  • CNPJ formatado: além do raw 14-dígitos, vem cnpj_formatado: "12.345.678/0001-90".
  • CEP formatado: além do raw 8-dígitos, vem cep_formatado: "01310-100".
  • Endereço completo pronto pra uso: campo endereco.completo monta a string final "Avenida Exemplo, 1000, Sala 100, Bairro, Cidade - UF, CEP" pulando campos nulos.
  • Datas em ISO 8601 (YYYY-MM-DD) — RFB usa YYYYMMDD ou '00000000' pra ausente. A API converte.
  • "S/N" padronizado em endereco.numero — variações como "S/N", "s/n", "SN" normalizam pra "S/N"; valores "0" ou vazio viram null.
  • nome_empresa pra MEI/EI: a RFB usa o formato "12345678901 FULANO DA SILVA" em MEI/EI. O campo nome_empresa entrega só a parte do nome sem o CPF na frente — pra empresas normais (LTDA/SA) é igual a razao_social.

Comportamentos default importantes

  • Busca filtra Ativas por padrão: POST /v1/empresas/buscar aplica situacao_ativa=true automaticamente. Pra incluir Baixadas/Suspensas/Inaptas/Nulas, envie "situacao_ativa": false explicitamente.
  • Busca exige no mínimo 3 filtros: body com menos que 3 campos preenchidos retorna 422 validation_error. Controle de uso justo — combine UF + CNAE + outro (porte, idade, capital, email, etc.).
  • Enriquecimento é opt-in: GET /v1/empresa/:cnpj retorna cache de enriquecimento (dados cruzados na web) quando existe — sem custo extra. Pra disparar enriquecimento ativo, use ?enriquecer=true (cobra +3 consultas).
  • Datas em ISO 8601: todos os campos de data vêm como YYYY-MM-DD (local time America/Sao_Paulo, sem offset).

Primeiros passos

  1. Crie uma chave em Configurações → API (apenas owner/admin de Growth, Scale, Scale AI ou Enterprise).
  2. Copie a chave em claro (mostrada uma única vez).
  3. Teste com a primeira chamada:
curl -H "Authorization: Bearer leadcnpj_live_..." \
     https://leadcnpj.com.br/api/v1/empresa/12345678000190

Continue em Exemplos práticos pra ver receitas de busca, enriquecimento em lote e paginação.