--- title: "API e MCP para desenvolvedores — CNPJpedia" description: "API REST v1 e servidor MCP (Claude, ChatGPT, Cursor) com dados de todas as empresas do Brasil. Autenticação por API key ou OAuth 2.1, exemplos em cURL, Python e JavaScript." url: "https://cnpjpedia.com.br/desenvolvedores" language: "pt-BR" updated: "2026-11-09" publisher: "CNPJpedia" --- Para desenvolvedores # Dados de empresas do Brasil via API REST e servidor MCP Integre a base da Receita Federal ao seu produto, ao seu CRM ou ao seu agente de IA. Chave de API ou OAuth 2.1, exemplos prontos e consumo em créditos transparente. - API v1 · OpenAPI - MCP · Streamable HTTP - OAuth 2.1 + API key [Começar com o Premium](https://cnpjpedia.com.br/cadastro?plan=premium&interval=year) [Ver planos e créditos](https://cnpjpedia.com.br/precos) API e MCP não estão disponíveis no plano Grátis. ``` curl "https://api.cnpjpedia.com.br/v1/companies/12345678000195" \ -H "Authorization: Bearer cnpj_live_SUA_CHAVE" ``` Resposta (exemplo com dados fictícios) ``` { "cnpj": "12345678000195", "razao_social": "ALFA SISTEMAS LTDA", "situacao": "Ativa", "porte": "ME", "cnae_principal": "6201501", "uf": "SP", "capital_social": 150000.0, "socios": [ { "nome": "MARIA HELENA SOUZA", "qualificacao": "Sócia" } ], "contatos": { "revealed": true, "email": "…" } } ``` Primeiros passos ## Da assinatura à primeira consulta em minutos ### Passo 1: Assine o Premium API e MCP fazem parte do plano Premium e usam o mesmo saldo de créditos do seu workspace. ### Passo 2: Crie uma chave de API No app, abra **API** e crie uma chave. Ela começa com `cnpj_live_` e é exibida uma única vez — guarde-a em um cofre de segredos. ### Passo 3: Faça a primeira chamada Envie a chave no cabeçalho Authorization e consulte um CNPJ. Cada resposta traz o saldo restante de créditos. API REST v1 ## Consulte e busque empresas por HTTP Respostas em JSON, filtros idênticos aos do app e paginação por página. A referência interativa completa está no OpenAPI. URL base `https://api.cnpjpedia.com.br/v1` Autenticação (cabeçalho) `Authorization: Bearer cnpj_live_SUA_CHAVE` Também aceitamos a chave no cabeçalho `X-API-Key`. Nunca exponha a chave em código de navegador. [Referência OpenAPI](https://api.cnpjpedia.com.br/docs) · [Especificação OpenAPI em JSON](https://api.cnpjpedia.com.br/openapi.json) ### Detalhe de uma empresa `GET /v1/companies/{cnpj}` ``` curl "https://api.cnpjpedia.com.br/v1/companies/12345678000195" \ -H "Authorization: Bearer cnpj_live_SUA_CHAVE" ``` Resposta (exemplo com dados fictícios) ``` { "cnpj": "12345678000195", "razao_social": "ALFA SISTEMAS LTDA", "situacao": "Ativa", "porte": "ME", "cnae_principal": "6201501", "uf": "SP", "capital_social": 150000.0, "socios": [ { "nome": "MARIA HELENA SOUZA", "qualificacao": "Sócia" } ], "contatos": { "revealed": true, "email": "…" } } ``` ### Busca com filtros `POST /v1/companies/search` ``` curl -X POST "https://api.cnpjpedia.com.br/v1/companies/search" \ -H "Authorization: Bearer cnpj_live_SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{ "filters": { "uf": ["SP"], "cnae": ["6201501"], "porte": ["01", "03"], "abertura_from": "2024-01-01", "has_email": true }, "page": 1, "page_size": 50 }' ``` ### Endpoints | Método | Endpoint | Descrição | Custo | | --- | --- | --- | --- | | GET | /v1/companies/{cnpj} | Ficha completa, com contatos e sócios. | 1 crédito | | POST | /v1/companies/search | Busca com filtros; contatos não incluídos. | 1 crédito por página | | POST | /v1/companies/count | Conta empresas que casam com os filtros. | Grátis | | GET | /v1/companies/{cnpj}/partners | Quadro societário (QSA). | Grátis em 24 h após o detalhe | | GET | /v1/companies/{cnpj}/branches | Matriz e filiais do CNPJ raiz. | 1 crédito por página | | GET | /v1/companies/{cnpj}/events | Histórico de mudanças da empresa. | 1 crédito | | POST | /v1/companies/batch | Até 100 CNPJs por chamada. | 1 crédito por CNPJ encontrado | | GET | /v1/partners/search?name= | Empresas em que uma pessoa é sócia. | 1 crédito por página | | GET | /v1/meta/cnaes · /municipios · /naturezas | Tabelas de apoio para montar filtros. | Grátis | | GET | /v1/credits | Saldo de créditos do workspace. | Grátis | | GET | /v1/lists · /v1/lists/{id}/items | Listas do workspace (escopo lists). | Grátis | ### Escopos da chave Crie chaves com o mínimo de permissões necessárias para cada integração. - `companies:read`Consultar e buscar empresas - `contacts:reveal`Revelar telefones e e-mails (consome créditos) - `lists:read`Ler listas do workspace - `lists:write`Criar listas e adicionar empresas - `exports:write`Criar exportações - `monitoring:read`Ler eventos de monitoramento ### Limites, créditos e erros - **Rate limit por chave:** padrão de 120 requisições por minuto. Os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset` mostram o seu consumo. - **Créditos:** o saldo restante vem em `X-Credits-Remaining`. Chamadas repetidas ao mesmo CNPJ em 24 horas são cobradas uma vez, e contatos já revelados não são cobrados de novo. [Ver tabela de créditos](https://cnpjpedia.com.br/precos#creditos). | 401 | Chave ausente, inválida ou revogada. | | --- | --- | | 402 | Saldo de créditos insuficiente ou recurso fora do plano (code: insufficient\_credits, plan\_required). | | 403 | A chave não tem o escopo necessário para a operação. | | 404 | CNPJ ou recurso não encontrado. | | 422 | Parâmetros ou filtros inválidos. | | 429 | Limite de requisições por minuto excedido (code: rate\_limited). Aguarde o tempo do cabeçalho Retry-After e tente novamente. | Erros seguem o formato `{"detail": {"code": "…", "message": "…"}}`. Servidor MCP ## Conecte a sua IA diretamente à base de empresas A CNPJpedia expõe um servidor MCP (Model Context Protocol) por Streamable HTTP. Claude, ChatGPT, Cursor e outros clientes conseguem buscar, detalhar e listar empresas em linguagem natural. URL do servidor MCP `https://mcp.cnpjpedia.com.br/mcp` Autenticação **OAuth 2.1** (PKCE S256 e registro dinâmico de cliente) ou **API key** no cabeçalho Authorization. Descoberta automática para agentes: [MCP Server Card](https://cnpjpedia.com.br/.well-known/mcp/server-card.json), [catálogo ARD (Agentic Resource Discovery)](https://cnpjpedia.com.br/.well-known/ard.json) e [llms.txt com o resumo do site](https://cnpjpedia.com.br/llms.txt). Toda página pública também tem uma versão em Markdown (ex.: `/empresa/{cnpj}.md`). ### Como conectar - Claude Abra **Configurações → Conectores**, adicione um conector personalizado e cole a URL do servidor. Entre na CNPJpedia e autorize o acesso ao workspace. - ChatGPT Em **Configurações → Conectores** (modo desenvolvedor), crie um conector com a URL do servidor MCP e conclua o login OAuth. O caminho exato varia conforme o plano e a versão do ChatGPT. - Cursor Adicione o servidor ao arquivo `mcp.json` (exemplo ao lado) com a URL e a sua API key. - Claude Code Rode `claude mcp add` com o transporte HTTP e autorize o acesso pelo comando `/mcp`. Você pode ver e revogar as conexões de IA a qualquer momento na área **MCP** do app. Cada chamada que retorna dados consome créditos do workspace. ``` { "mcpServers": { "cnpjpedia": { "url": "https://mcp.cnpjpedia.com.br/mcp", "headers": { "Authorization": "Bearer cnpj_live_SUA_CHAVE" } } } } ``` Ferramentas do MCP ## O que o seu assistente consegue fazer Cada ferramenta tem nome curto, descrição rica e saída compacta e paginada, para que o agente escolha a chamada certa. - `buscar_empresas` Busca empresas com filtros (CNAE, UF, município, porte, capital, abertura…), paginado. 1 crédito por página - `contar_empresas` Quantas empresas casam com os filtros — rápido e sem custo. Gratuita - `detalhar_empresa` Ficha completa por CNPJ: situação, atividades, endereço, capital, porte e sócios. 1 crédito por empresa (24 h) - `revelar_contatos` Telefones e e-mails de uma empresa. Cobrado uma vez por CNPJ; sem contatos públicos, não cobra. 1 crédito por empresa, uma vez - `detalhar_empresas_em_lote` Ficha completa de até 25 CNPJs em uma só chamada. 1 crédito por empresa (24 h) - `revelar_contatos_em_lote` Telefones e e-mails de até 50 empresas em uma só chamada. Cobrado uma vez por CNPJ com contato. 1 crédito por empresa, uma vez - `listar_filiais` Matriz e filiais do mesmo CNPJ raiz. 1 crédito por página - `socios_da_empresa` Quadro societário (QSA) de um CNPJ, com documentos mascarados. 1 crédito por empresa (24 h) - `buscar_socio` Encontra empresas em que uma pessoa aparece como sócia. 1 crédito por página - `empresas_relacionadas` Empresas que compartilham sócios com o CNPJ informado. 1 crédito por página - `empresas_recem_abertas` Empresas abertas nos últimos dias que casam com os filtros. 1 crédito por página - `eventos_da_empresa` Histórico de mudanças: situação, endereço, atividade, capital e sócios. 1 crédito por empresa (24 h) - `tamanho_de_mercado` Agrupa e conta empresas (por UF, porte, CNAE…) para dimensionar um mercado. Gratuita - `buscar_cnae` Encontra códigos CNAE a partir de um texto. Gratuita - `buscar_municipio` Encontra o código de um município por nome e UF. Gratuita - `criar_lista` Cria uma lista a partir de CNPJs ou de filtros. Gratuita - `listar_listas` Lista as listas do seu workspace. Gratuita - `exportar_lista` Exporta uma lista em CSV/XLSX com as colunas escolhidas. 1 crédito por linha exportada - `saldo_de_creditos` Consulta o saldo de créditos do workspace. Gratuita ### Recursos (resources) - `cnpjpedia://cnae/{codigo}` - `cnpjpedia://empresa/{cnpj}` ### Prompts prontos - `prospectar_icp` - `analisar_concorrentes` ## Pronto para integrar dados de empresas ao seu produto? Assine o Premium, gere a sua chave e faça a primeira chamada hoje mesmo. Dúvidas técnicas? Nossa equipe ajuda. [Começar com o Premium](https://cnpjpedia.com.br/cadastro?plan=premium&interval=year) [Falar com o suporte](https://cnpjpedia.com.br/contato?topic=support)