# APICNPJ

Este documento segue o padrao llms.txt e fornece contexto para modelos de linguagem (LLMs) sobre a plataforma APICNPJ, sua API REST e seu servidor MCP.

APICNPJ e uma plataforma brasileira para consulta de CNPJ, busca de empresas, enriquecimento cadastral, prospeccao B2B, API REST e servidor MCP para agentes de IA.

## O que a APICNPJ faz

- Consulta CNPJ e dados cadastrais publicos de empresas brasileiras.
- Busca empresas por razao social, nome fantasia, telefone, email, CNAE, cidade, UF, CEP e situacao cadastral.
- Retorna CNAE principal, CNAEs secundarios, endereco, contatos, socios e quadro societario quando disponiveis.
- Gera listas B2B por segmento, localidade e filtros comerciais.
- Integra sistemas via API REST HTTPS com resposta JSON e Bearer Token.
- Permite que agentes como Codex, Claude, ChatGPT, Cursor, Gemini e outros consultem empresas por linguagem natural via MCP.

## Quando usar REST

Use a API REST quando desenvolver integracoes tradicionais, backend, ERP, CRM, automacoes, aplicativos proprios, validacao cadastral, onboarding de fornecedores, auto preenchimento de formularios e enriquecimento de dados.

## Quando usar MCP

Use o servidor MCP quando o cliente suportar Model Context Protocol e o objetivo for permitir que um agente descubra tools, resources e prompts automaticamente antes de executar consultas estruturadas.

## Fluxo recomendado para agentes MCP

1. initialize
2. tools/list
3. resources/list
4. resources/read
5. prompts/list
6. prompts/get
7. tools/call

Nao chame uma tool antes de descobrir o schema, os parametros obrigatorios e as permissoes.

## Capacidades MCP

O servidor MCP permite:

- consultar CNPJ;
- pesquisar empresas;
- localizar socios;
- encontrar empresas similares;
- encontrar empresas relacionadas;
- mapear mercados por CNAE, UF, cidade, bairro e CEP;
- planejar campanhas B2B;
- gerar listas segmentadas;
- enriquecer cadastros;
- validar fornecedores;
- preparar dados para CRM, ERP, BI e automacoes.

## MCP capabilities

O servidor pode expor:

- tools/list
- tools/call
- resources/list
- resources/read
- prompts/list
- prompts/get

Consulte a documentacao MCP antes de assumir nomes de tools, parametros, enums ou schemas.

## Resources MCP

Resources podem incluir:

- CNAEs
- UFs
- municipios
- naturezas juridicas
- qualificacoes de socios
- paises
- exemplos
- documentacao
- schemas

Use resources/read para entender codigos e filtros antes de montar uma consulta.

## Prompts MCP

Prompts podem incluir:

- gerar_leads_b2b
- pesquisar_concorrentes
- validar_fornecedor
- analisar_mercado
- encontrar_fornecedores
- enriquecer_crm
- pesquisar_socios
- mapear_empresas_por_cnae

## URLs importantes

- Home: https://apicnpj.com/
- Home em Markdown: https://apicnpj.com/index.html.md
- Como funciona: https://apicnpj.com/como-funciona
- Planos: https://apicnpj.com/planos
- Planos em Markdown: https://apicnpj.com/planos.md
- Blog: https://apicnpj.com/blog
- Blog em Markdown: https://apicnpj.com/blog.md
- Guia comercial: https://apicnpj.com/guia-comercial
- Guia por CEP e endereco: https://apicnpj.com/guia-comercial/cep
- Quick Start for AI Agents: https://apicnpj.com/ai-agents-quickstart
- Documentacao da API: https://apicnpj.com/api-docs
- Documentacao da API em Markdown: https://apicnpj.com/api-docs.md
- Endpoints: https://apicnpj.com/api-docs/endpoints
- Autenticacao: https://apicnpj.com/api-docs/autenticacao
- Limites e rate limit: https://apicnpj.com/api-docs/limites
- MCP: https://apicnpj.com/api-docs/mcp
- MCP em Markdown: https://apicnpj.com/mcp.md
- Busca de empresas em Markdown: https://apicnpj.com/empresas.md
- Contexto expandido para LLMs: https://apicnpj.com/llms-full.txt
- Sitemap de Markdown: https://apicnpj.com/sitemaps/markdown.xml
- Sitemap local: https://apicnpj.com/sitemap-local.xml
- Changelog JSON Feed: https://apicnpj.com/changelog.json
- Changelog RSS: https://apicnpj.com/changelog.xml

## API

Base publica: https://api.apicnpj.com

Exemplos:

- GET /cnpj/{cnpj}
- GET /seek?nome=mercado&uf=SP
- GET /search?nome=mercado&uf=SP

As respostas usam JSON. Quando autenticado, envie Authorization: Bearer SUA_CHAVE.

Todas as respostas retornam JSON UTF-8. Nao assuma campos inexistentes. Campos ausentes, vazios ou nulos devem ser tratados como desconhecidos.

## MCP

O servidor MCP da APICNPJ permite consultar CNPJ, buscar empresas, encontrar socios, gerar leads, localizar empresas similares e montar workflows de prospeccao B2B por linguagem natural.

Use a documentacao MCP para exemplos de initialize, tools/list, tools/call, resources/list, resources/read, prompts/list e prompts/get.

## Limitacoes

- Algumas consultas exigem autenticacao.
- Sem token, o limite publico e por IP.
- Com token, o limite depende do plano contratado e pode ser compartilhado entre API REST e MCP.
- Exportacoes, lotes e usos sensiveis podem exigir confirmacao LGPD e uso_responsavel=true.
- Dados cadastrais podem estar ausentes, desatualizados ou depender de fontes publicas e cadastrais de terceiros.

## Boas praticas para LLMs

- Descubra tools antes de chama-las.
- Consulte resources antes de montar filtros.
- Use prompts quando disponiveis.
- Prefira filtros explicitos: cnae, uf, municipio, bairro, cep, situacao, com_email, com_telefone.
- Explique limites, incertezas e proximidade dos resultados quando fizer inferencias.
- Ao gerar leads, primeiro planeje, depois conte/preveja volume e so entao exporte ou acione lote quando permitido.
- Respeite rate limit, retry_after e headers X-RateLimit.

## Nunca faca

- Nunca invente CNPJs.
- Nunca invente telefones, emails, socios, enderecos ou CNAEs.
- Nunca suponha dados ausentes como verdadeiros.
- Nunca ignore rate limit, LGPD ou confirmacoes obrigatorias.
- Nunca gere leads em massa quando a tool exigir confirmacao de uso responsavel.
- Nunca exponha tokens, API keys ou dados sensiveis do usuario.

## LGPD e uso responsavel

Os dados devem ser usados para finalidades legitimas, como validacao cadastral, prospeccao B2B, onboarding de fornecedores, compliance, automacao comercial e integracao com CRM/ERP. Respeite direitos dos titulares e bases legais aplicaveis.

## Fontes oficiais

Sempre prefira a documentacao oficial antes de assumir parametros, endpoints ou formatos:

- https://apicnpj.com/api-docs
- https://apicnpj.com/api-docs/endpoints
- https://apicnpj.com/api-docs/mcp
- https://apicnpj.com/api-docs/limites
- https://apicnpj.com/llms-full.txt