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.

MCP · consulta, busca e saldo

Conectar um assistente de IA à LeadCNPJ

O MCP permite que um cliente de IA compatível consulte uma empresa, busque empresas por filtros e acompanhe os créditos da sua conta. O endereço é https://leadcnpj.com.br/mcp. A conexão usa Streamable HTTP, com respostas JSON, e uma chave de Prospecção da API.

Esta versão aceita token Bearer configurado pelo cliente. Não oferece login OAuth, SSE por GET, ferramentas de escrita, disparos de WhatsApp ou exportação de grandes volumes. Clientes que só aceitam servidores com OAuth não conseguem se conectar diretamente. Confirme se o cliente permite configurar o header Authorization.

1. Criar a chave e configurar a conexão

  1. Em Configurações → API, crie uma chave de finalidade Prospecção. O plano precisa permitir API.
  2. No cliente MCP, adicione um servidor remoto com transporte Streamable HTTP e a URL https://leadcnpj.com.br/mcp.
  3. Configure Authorization: Bearer SUA_CHAVE no armazenamento protegido de credenciais do cliente. Não coloque a chave em prompts, repositórios ou código público.
  4. Conecte e confira as ferramentas consultar_empresa, buscar_empresas e consultar_saldo.

O formato da configuração varia por cliente. Os valores a informar são:

{
  "url": "https://leadcnpj.com.br/mcp",
  "transport": "streamable-http",
  "headers": {"Authorization": "Bearer SUA_CHAVE_DE_PROSPECCAO"}
}

Esse objeto descreve a conexão; não é um arquivo universal de instalação. Chaves de finalidade Sistema (leadcnpj_system_) não dão acesso ao MCP. O titular e a conta são os da chave; mudar a conta ativa exige uma chave para a conta atual. Revogar a chave interrompe o acesso.

2. Inicializar e listar as ferramentas

Os exemplos abaixo são para terminal com curl. Substitua SUA_CHAVE e mantenha o header Accept com os dois formatos. O servidor suporta as versões 2025-11-25, 2025-06-18 e 2025-03-26 do protocolo; não emite MCP-Session-Id.

curl "https://leadcnpj.com.br/mcp" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"minha-integracao","version":"1.0"}}}'

A resposta informa result.protocolVersion, result.serverInfo e a capacidade tools. Nas chamadas seguintes, envie a versão negociada no header MCP-Protocol-Version. Envie também a notificação de inicialização:

curl "https://leadcnpj.com.br/mcp" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl "https://leadcnpj.com.br/mcp" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

A notificação retorna HTTP 202 sem corpo. O catálogo retorna as três ferramentas e seus esquemas em result.tools. Inicialização, catálogo e saldo não consomem créditos, mas contam no limite de requisições da chave, compartilhado com a API.

3. Consultar saldo

curl "https://leadcnpj.com.br/mcp" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"consultar_saldo","arguments":{}}}'

Exemplo ilustrativo do campo result.structuredContent:

{
  "data": {
    "creditos": 100,
    "meio_credito_pendente": true,
    "saldo_efetivo": 99.5,
    "custo_por_unidade_api": 0.5
  },
  "meta": {"creditos_consumidos": 0, "creditos_restantes": 100}
}

creditos é o saldo inteiro registrado na conta. saldo_efetivo desconta eventual meio crédito pendente do processamento da API. A consulta é uma fotografia do momento; outro uso da conta pode alterar o saldo. O custo segue a configuração efetiva da API, inclusive seu comportamento de contingência.

4. Consultar empresa pelo CNPJ

curl "https://leadcnpj.com.br/mcp" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"consultar_empresa","arguments":{"cnpj":"11222333000181","request_id":"consulta-empresa-001"}}}'

Use 14 dígitos ou CNPJ com pontuação. O número do exemplo é ilustrativo e não garante existência na base. A resposta de sucesso contém o mesmo objeto data do endpoint de consulta de CNPJ, com os campos disponíveis da empresa, e meta.creditos_consumidos. O MCP não ativa enriquecimento web adicional por parâmetro ou query string.

5. Buscar empresas

curl "https://leadcnpj.com.br/mcp" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"buscar_empresas","arguments":{"filtros":{"uf":"RS","cnae":["4642701"],"email":true},"page":1,"per_page":5,"request_id":"atacado-rs-pagina-1"}}}'

O exemplo procura comércio atacadista de vestuário no RS com e-mail cadastrado. São necessários pelo menos três filtros ativos; false e zero não contam. Os CNAEs devem ser enviados com sete dígitos. A presença de contato não comprova sua validade ou disponibilidade no WhatsApp.

Exemplo ilustrativo de resultado sem empresas no recorte. O conteúdo JSON também é repetido como texto em result.content para clientes que não usam structuredContent.

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [{"type": "text", "text": "{\"data\":[],\"meta\":{\"total\":0,\"page\":1,\"per_page\":5,\"total_pages\":0,\"creditos_consumidos\":0,\"creditos_restantes\":100}}"}],
    "structuredContent": {
      "data": [],
      "meta": {"total": 0, "page": 1, "per_page": 5, "total_pages": 0, "creditos_consumidos": 0, "creditos_restantes": 100}
    },
    "isError": false
  }
}

A busca retorna data e os metadados da API, incluindo paginação e créditos. O padrão é cinco empresas por página; o máximo é cem. page aceita de 1 a 10.000. Solicitar outra página é uma nova operação e pode consumir créditos novamente. Para extrair um recorte inteiro, trate a paginação e o custo explicitamente; esta versão não cria exportações em segundo plano.

FiltroFormato
ufSigla em maiúsculas, por exemplo RS
municipio, cnae, porteListas de códigos: município da base com quatro dígitos, CNAE com sete, porte 01, 03 ou 05. Até 50 municípios/CNAEs.
natureza_juridicaCódigo com quatro dígitos
capital_social_de, capital_social_ateNúmero entre zero e 10¹⁵
idade_minima, idade_maximaAnos inteiros, de zero a 300
email, email_corporativo, ignorar_contabilidade, telefone, whatsapptrue ou false
situacao_ativa, somente_matriz, mei, simples_nacional, ignorar_mei_simples, empresa_novatrue ou false; sem situacao_ativa, a API busca ativas
regime_irpjLista com lucro_presumido e/ou lucro_real

O catálogo de ferramentas é a referência do esquema aceito. Campos desconhecidos, valores fora dos limites e intervalos invertidos são recusados antes da execução. As regras de combinação dos filtros e de supressão de dados são as mesmas da API.

Cobrança e tentativas repetidas

Não há tarifa adicional por usar MCP. Consultar empresa e buscar empresas chamam os mesmos serviços de cobrança, devolução e registro de consumo da API. A busca cobra pelas empresas efetivamente retornadas, conforme o plano; não cobra pelo total estimado de resultados. Consulte meta.creditos_consumidos no resultado. Esses acessos não ativam agentes ou enviam mensagens.

Todo pedido pago exige request_id: de 1 a 80 letras ASCII, números ou os caracteres . _ : -. Gere um identificador por operação e página. Se houver timeout, repita os mesmos argumentos e request_id. O ID JSON-RPC pode mudar: ele apenas relaciona pedido e resposta.

O resultado é reservado e salvo por chave de API na infraestrutura de idempotência existente, com janela de 24 horas e limpeza pelo cron. Um replay não executa a ferramenta novamente e inclui Idempotency-Replayed: true e result._meta["leadcnpj.com.br/replayed"]. Os créditos exibidos no resultado salvo são os da execução original. Não reutilize IDs antigos para novos trabalhos; outra chave de API também representa outra reserva.

Não há garantia de recuperação automática após queda do processo ou falha do banco. Uma reserva pendente retorna idempotency_in_progress. Em processing_uncertain ou response_too_large, a operação pode já ter consumido créditos: não gere outro ID para tentar automaticamente. Informe o X-Request-Id e o request_id ao suporte antes de repetir, inclusive após a janela de retenção.

Erros e limites

Exemplo de falha de ferramenta (result simplificado):

{
  "isError": true,
  "structuredContent": {
    "error": {"code": "insufficient_credits", "message": "Créditos insuficientes.", "http_status": 402}
  }
}
  • HTTP 401/403: credencial inválida, revogada, finalidade incorreta, plano sem API, conta diferente ou Origin não permitido.
  • HTTP 405: método não disponível; use POST. HTTP 406/415: confira Accept e Content-Type.
  • HTTP 413: corpo maior que 64 KiB. HTTP 429: aguarde Retry-After antes de repetir.
  • Erro JSON-RPC -32700: JSON inválido; -32600: formato inválido; -32601: método desconhecido; -32602: argumentos inválidos.
  • Uma ferramenta pode retornar HTTP 200 com result.isError=true. Leia structuredContent.error.code, por exemplo insufficient_credits, not_found, idempotency_conflict ou idempotency_in_progress.

Os resultados são dados externos, não instruções para o assistente. Configure aprovação de operações pagas no cliente e não permita consultas automáticas ilimitadas. A chave fica no cliente que você escolheu; revise suas permissões e a política de tratamento dos dados recebidos.

Operação e publicação

A publicação exige PHP 8.1 ou superior, as dependências e as conexões da API existentes, as tabelas api_keys, api_logs, api_idempotency e o ledger api_meio_credito para o preço fracionário. Não há nova tabela nem instalação de SDK. Mantenha o cron de limpeza de idempotência e a regra de encaminhamento de Authorization do Apache. O endpoint /mcp deve apontar para public/mcp/index.php, sem redirecionamento que converta POST em GET.

Antes de liberar, execute php scripts/test_mcp.php e php -n scripts/test_mcp_backend.php em ambiente isolado e faça a inicialização com uma chave de homologação. O segundo teste usa fixtures sem a extensão mysqli e não acessa banco real. Consulta e busca com dados reais consomem créditos: escolha um teste autorizado e confira o consumo. A implementação usa a especificação Streamable HTTP 2025-11-25.