Referência da API ZenPJ

• URL base: https://api.zenpj.com/v1
• Formato: JSON (UTF-8). Erros em application/problem+json (RFC 9457).
• Autenticação: chave de API no cabeçalho Authorization: Bearer zpj_….
• Planos e preços: zenpj.com/#precos. O plano gratuito tem 100 consultas de API por mês, sem cartão.
• Versão desta página: outubro de 2026. Este arquivo também existe em Markdown: zenpj.com/api/referencia.md.

Autenticação

1. Crie uma conta grátis em app.zenpj.com.
2. No app, abra a tela API e crie uma chave. Ela começa com zpj_ e aparece uma única vez: guarde-a num cofre de segredos. A ZenPJ guarda só um hash dela.
3. Envie a chave em toda chamada:

curl -H "Authorization: Bearer zpj_SUA_CHAVE" https://api.zenpj.com/v1/companies/33000167000101

Cada conta pode ter até 5 chaves ativas. Chaves são criadas e revogadas no app; uma chave não cria nem revoga outras chaves (403 session_required).

Consultas por mês e limites

• O que conta: cada chamada feita com a chave conta 1 consulta. O lote (POST /companies/batch) conta 1 por CNPJ distinto e válido enviado. As ferramentas do servidor MCP contam pelas chamadas que fazem. GET /me/queries não conta.
• Erros não contam: uma chamada que termina em erro (4xx ou 5xx) é devolvida ao saldo.
• Renovação: no dia 1º de cada mês, horário de Brasília.
• Cabeçalhos de saldo: X-Queries-Limit e X-Queries-Remaining em cada resposta. Passou do saldo: 429 query_quota_exceeded.
• Buscas do plano gratuito: além das consultas, o plano gratuito tem 15 buscas novas por mês. Repetir a mesma busca ou pedir o total dela não conta outra vez. Passou: 429 monthly_quota_exceeded.
• Empresas por busca no plano gratuito: a lista traz as 10 primeiras empresas (um limit maior devolve 10) e o total, sem nextCursor; pedir uma página com cursor responde 403 page_limit. O cabeçalho X-Page-Limit diz o tamanho. A primeira ordem (sort) de uma busca está incluída; outra ordem da mesma busca conta como busca nova (o total continua sem contar). Os planos pagos paginam todos os resultados.
• Um estado por busca (Gratuito, Pesquisa, Exportação): mais de um estado responde 422 state_limit; uma busca sem estado e sem cidade, raio, nome, CNPJ, sócio, telefone, e-mail ou CEP responde 422 state_required.
• Ritmo: até 5 requisições por segundo por conta, com rajadas de até 30. Acima disso, 429 com o cabeçalho Retry-After (segundos).

GET /me/queries

O saldo do mês.

{ "limit": 1000, "used": 120, "remaining": 880, "unlimited": false, "resetsAt": "2026-11-01T00:00:00-03:00" }

Buscar empresas

GET /companies

Todos os parâmetros são opcionais e se combinam com E (AND). Listas aceitam vírgulas (state=SP,RJ) ou repetição (state=SP&state=RJ). Toda busca precisa de ao menos um filtro (422 filter_required). Sem status, a busca traz só empresas ativas.

Filtros

Valores inválidos respondem 422 com uma mensagem por campo.

Paginação, total e ordem

A paginação é por cursor (sem OFFSET): custo estável por página, sem repetir nem pular empresas.

Resposta

Exemplo ilustrativo:

{
  "items": [
    {
      "cnpj": "12345678000190",
      "legalName": "EXEMPLO PADARIA LTDA",
      "tradeName": "PADARIA EXEMPLO",
      "isHeadquarters": true,
      "status": "active",
      "activityStartDate": "2019-03-14T00:00:00Z",
      "mainCnae": 1091102,
      "legalNatureCode": 2062,
      "size": "micro",
      "shareCapital": 50000,
      "mei": "never",
      "simples": "opted",
      "state": "MG",
      "municipalityCode": 4123,
      "municipality": "BELO HORIZONTE",
      "district": "CENTRO",
      "zipCode": "30110000",
      "email": "[email protected]",
      "emailShared": false,
      "phones": ["3130000000"],
      "taxRegime": [],
      "federalDebt": 0
    }
  ],
  "nextCursor": "…",
  "total": 5636
}

• status: active, closed, unfit, suspended, null.
• mei e simples: opted (optante), excluded (excluída), never (nunca optou).
• size: micro, small, other, not_informed.
• taxRegime: subconjunto de real, presumido, arbitrado, imune, da última ECF; vazio = não informado (empresas do Simples não entregam ECF).
• federalDebt: total da dívida ativa da União da empresa (raiz do CNPJ) como devedora principal, em reais; repetido em cada filial. 0 = nenhuma.
• emailShared: true quando o e-mail é usado por muitas empresas (provável contador).
• municipalityCode: código da Receita (SIAFI).
• splitQuery (só às vezes): quando nada foi achado e a API separou palavras digitadas juntas ("ctvoicer" → "CT VOICER"), a resposta traz splitQuery; use-o como q nas próximas páginas.

Ficha de uma empresa

GET /companies/{cnpj}

CNPJ com ou sem pontuação, numérico ou alfanumérico (IN RFB 2.229/2024). Traz qualquer situação cadastral. 404 quando o CNPJ não existe na base.

Campos:

Conferir CNPJs em lote

POST /companies/batch

Até 1.000 CNPJs por chamada. Ideal para enriquecer um CRM ou conferir fornecedores. Conta 1 consulta por CNPJ distinto e válido.

curl -X POST -H "Authorization: Bearer zpj_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"cnpjs":["33000167000101","00.000.000/0001-91"]}' \
  https://api.zenpj.com/v1/companies/batch

Resposta (exemplo ilustrativo):

{
  "asked": 2,
  "checked": 2,
  "found": 2,
  "items": [
    {
      "cnpj": "33000167000101",
      "found": true,
      "valid": true,
      "legalName": "EXEMPLO S.A.",
      "status": "active",
      "statusDate": "2005-11-03",
      "simples": "never",
      "mei": "never",
      "taxRegime": ["real"],
      "federalDebt": 0,
      "mainCnae": 600001,
      "cnaeName": "Extração de petróleo e gás natural",
      "city": "RIO DE JANEIRO",
      "state": "RJ",
      "openedAt": "1966-09-28",
      "size": "other",
      "isHeadquarters": true
    }
  ]
}

• Os itens vêm na ordem enviada; CNPJs repetidos aparecem uma vez.
• valid: false: o texto não é um CNPJ válido (não conta consulta). found: false: CNPJ válido que não está na base.
• asked = itens enviados, checked = CNPJs distintos e válidos consultados (o que é cobrado), found = encontrados.
• Mais de 1.000 ou nenhum CNPJ: 422.

Códigos para os filtros

Respostas no formato { "items": [...] }.

Servidor MCP

Para agentes de IA (Claude, ChatGPT, Cursor e qualquer cliente MCP).

• Endpoint: POST https://api.zenpj.com/v1/mcp.
• Autenticação, duas formas:
  • Entrar com a conta ZenPJ (OAuth 2.1), sem chave: no Claude ou no ChatGPT, adicione um conector com esse endereço. Listar as ferramentas não pede login; na primeira ferramenta usada, o aplicativo abre o login da ZenPJ e uma tela para você autorizar. Você vê e desconecta os apps conectados no app, na tela API.
  • Chave de API: o cabeçalho Authorization: Bearer zpj_…, como na API REST.
• Transporte: Streamable HTTP, respostas JSON, sem sessão. Atende as versões 2025-03-26 a 2025-11-25 (com initialize) e 2026-07-28 da especificação.
• Consultas: cada ferramenta conta as consultas da chamada REST que faz, com OAuth ou com chave, no plano da sua conta.

# Com login (OAuth): o Claude Code abre o navegador na primeira ferramenta usada
claude mcp add --transport http zenpj https://api.zenpj.com/v1/mcp

# Com chave
claude mcp add --transport http zenpj https://api.zenpj.com/v1/mcp --header "Authorization: Bearer zpj_SUA_CHAVE"

Detalhes do OAuth para quem integra: metadados em https://api.zenpj.com/.well-known/oauth-authorization-server e https://api.zenpj.com/.well-known/oauth-protected-resource/v1/mcp; código de autorização com PKCE (S256); registro dinâmico de cliente (RFC 7591) ou documento de metadados do cliente (CIMD); escopos companies:read e offline_access; o token só vale para o endereço do MCP.

Filtros das ferramentas: nome, cnae (lista), cnae_qualquer (principal ou secundária), uf (lista), municipio (lista de códigos da Receita), raio_km (em volta do primeiro município), abertura_de e abertura_ate (AAAA-MM-DD), porte (micro, small, other), simples (opted, excluded, outside), mei (only, not, excluded), regime (lista), dividas (with, without), com_email, com_celular, com_telefone, so_matriz, capital_minimo.

Servidor MCP público (sem chave)

Para usar dados públicos da ZenPJ no Claude, no ChatGPT ou em qualquer cliente MCP sem conta e sem chave.

• Endpoint: POST https://api.zenpj.com/v1/public/mcp, sem autenticação. Mesmo transporte do servidor com chave (Streamable HTTP, JSON, sem sessão).
• O que não traz: contatos (telefone, e-mail), endereço e sócios. Para listas com esses dados, use o app ou o servidor MCP com chave.
• Limites: até 5 requisições por segundo por IP (rajadas de 30); consultas de CNPJ, dados de governo e licitações: até 30 por minuto por IP.
• Privacidade: o servidor não recebe nem guarda as conversas, só as chamadas de ferramenta. Para operação e segurança, registra método, endereço chamado (que pode incluir o CNPJ consultado), código de resposta e duração de cada requisição, além dos registros técnicos de acesso descritos na política de privacidade; os demais argumentos das ferramentas não são gravados.

claude mcp add --transport http zenpj-publico https://api.zenpj.com/v1/public/mcp

Exemplos de pedidos ao assistente: "Quantas construtoras ativas com celular existem no Paraná?", "Qual a situação cadastral do CNPJ 33.000.167/0001-01?", "Quantas empresas abriram em São Paulo no último mês, comparado ao ano passado?", "Quais licitações de software estão abertas em Minas Gerais?".

Erros

Formato (RFC 9457):

{ "title": "Unprocessable Entity", "status": 422, "detail": "…", "code": "state_required" }

Erros de validação trazem errors com uma mensagem por campo ({ "title": "Validation failed", "status": 422, "errors": { "cnpjs": "…" } }).

Dados

• Fonte: Dados Abertos do CNPJ da Receita Federal (cerca de 73 milhões de estabelecimentos, 27 milhões ativos), atualizados todo mês; dívida ativa da União (PGFN); Simples Nacional e MEI; regime tributário (ECF); população e localização dos municípios (IBGE).
• Nomes sem CPF: razões sociais antigas de empresário individual terminam com o CPF na base da Receita; a API remove o CPF de todos os nomes.
• Sócios menores de idade não são exibidos.
• Remoção: empresas que pediram remoção da ZenPJ não aparecem em nenhuma resposta.
• Não existe na base oficial e por isso a API não traz: faturamento, número de funcionários e site.
• Tratamento conforme a LGPD: dados públicos de pessoas jurídicas, para prospecção B2B.

Suporte

Dúvidas sobre a API: pelo WhatsApp da página zenpj.com/suporte ou pela página zenpj.com/api.