# Referência da API ZenPJ

> API REST e servidor MCP sobre a base pública de empresas da Receita Federal (CNPJ), cruzada com PGFN (dívida ativa da União), Simples Nacional, ECF (regime tributário) e IBGE. Busca com todos os filtros, contagem de mercado, ficha completa do CNPJ e conferência em lote de até 1.000 CNPJs. Atualizada todo mês com a base da Receita.

- **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](https://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](https://zenpj.com/api/referencia.md).

## Autenticação

1. Crie uma conta grátis em [app.zenpj.com](https://app.zenpj.com/login?mode=register).
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:

```bash
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

| Plano | Consultas de API e lote por mês | Estados por busca | Buscas novas por mês |
|---|---|---|---|
| Gratuito | 100 | 1 | 15 |
| Pesquisa | 1.000 | 1 | sem limite |
| Exportação | 3.000 | 1 | sem limite |
| Plus | 10.000 | vários ou o Brasil inteiro | sem limite |

- **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.

```json
{ "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

| Parâmetro | Exemplo | Observações |
|---|---|---|
| `cnae` | `cnae=5611201` | Atividade **principal**, código CNAE de 7 dígitos (pontuação e zero à esquerda opcionais: `0111-3/01`). Códigos em `GET /reference/cnaes`. |
| `secondaryCnae` | `secondaryCnae=5611201` | Atividade principal **ou** secundária. |
| `q` | `q=padaria` | Palavras no nome (razão social ou fantasia). Todas as palavras precisam aparecer; acentos ignorados; palavras inteiras de 3+ letras. Uma palavra só de dígitos com 6+ dígitos é recusada (422): use `cnpj`. |
| `prefix` | `q=padar&prefix=true` | A **última** palavra de `q` vale como início de palavra ("padar" acha PADARIA) quando tem 3+ letras. Não é busca por trecho: "daria" não acha PADARIA. |
| `nameField` | `nameField=legal` | Com `q`: só a razão social (`legal`) ou só o nome fantasia (`trade`). Padrão: os dois. |
| `cnpj` | `cnpj=33000167` | Início do CNPJ, 2 a 14 caracteres, pontuação ignorada. Sem `status`, traz todas as situações. Para um CNPJ completo use `GET /companies/{cnpj}`. |
| `state` | `state=SP,RJ` | Siglas das UFs. |
| `municipality` | `municipality=7107,6291` | Códigos de município da Receita (SIAFI), não do IBGE. Códigos em `GET /reference/municipalities`. Uma cidade restringe o seu estado. |
| `near`, `radiusKm` | `near=7107&radiusKm=50` | Municípios cujo centro (IBGE) está até `radiusKm` (1 a 1.000 km) do município `near`. |
| `populationMin`, `populationMax` | `populationMin=100000` | População estimada do município (IBGE). |
| `district` | `district=CENTRO` | Bairro exato (maiúsculas e acentos ignorados). |
| `street`, `streetNumber` | `street=paulista&streetNumber=1000` | Palavras do logradouro e número. |
| `zip` | `zip=01310` | Início do CEP, 2 a 8 dígitos. |
| `status` | `status=active` | `active` (padrão), `closed` (baixada), `unfit` (inapta), `suspended` (suspensa), `null` (nula), `any` (todas). Aceita lista. |
| `headquarters` | `headquarters=true` | `true` só matrizes, `false` só filiais. |
| `legalNature` | `legalNature=2062,2135` | Natureza jurídica, código de 4 dígitos da Receita. Lista em `GET /reference/legal-natures`. |
| `openedFrom`, `openedTo` | `openedFrom=2026-01-01` | Data de abertura (AAAA-MM-DD). |
| `size` | `size=micro,small` | Porte: `micro` (ME), `small` (EPP), `other` (demais), `not_informed`. |
| `shareCapitalMin`, `shareCapitalMax` | `shareCapitalMin=100000` | Capital social em reais. |
| `simples` | `simples=opted` | Simples Nacional: `opted` (optante), `excluded` (excluída), `outside` (fora). |
| `mei` | `mei=not` | `only` (só MEI), `not` (sem MEI), `excluded` (ex-MEI). |
| `regime` | `regime=real,presumido` | Regime da última ECF: `real`, `presumido`, `arbitrado`, `imune` (imune ou isenta). |
| `debts` | `debts=without` | Dívida ativa da União (PGFN), empresa como devedora principal: `with` ou `without`. |
| `hasEmail`, `hasMobile`, `hasLandline`, `hasPhone` | `hasMobile=true` | Só empresas com e-mail, celular, telefone fixo ou algum telefone. |
| `hideAccountant` | `hideAccountant=true` | E-mails compartilhados por muitas empresas (em geral do contador) não contam para `hasEmail` e saem em branco. |
| `phone` | `phone=11987654321` | Telefone, 8 a 11 dígitos, DDD opcional. |
| `email`, `emailDomain` | `emailDomain=empresa.com.br` | E-mail exato ou domínio do e-mail. |
| `partner` | `partner=joao silva` | Nome de sócio (palavras inteiras, todas no nome do mesmo sócio). |
| `partnerDoc` | `partnerDoc=12345678000190` | CPF ou CNPJ do sócio, como publicado pela Receita (a Receita mascara o CPF: só os dígitos do meio aparecem, então um CPF pode achar mais de uma pessoa). |

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

### Paginação, total e ordem

| Parâmetro | Observações |
|---|---|
| `limit` | Empresas por página, 1 a 200 (padrão 50). |
| `cursor` | O `nextCursor` da resposta anterior, com os **mesmos** filtros e ordem. `nextCursor: null` = última página. Um cursor de outra ordem responde 422. |
| `includeTotal=true` | Inclui `total` (contagem exata) na resposta. |
| `totalOnly=true` | Responde só `{ "total": N }`, sem listar: tamanho de mercado. |
| `sort` | `bestContacts` (melhores contatos: e-mail próprio, celular, fixo), `newest`, `oldest` (data de abertura), `capitalDesc`, `capitalAsc`, `name` (razão social A–Z), `municipality` (código do município), `debtDesc` (maior dívida). Sem `sort`, a ordem é a mais rápida para os filtros. |

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

### Resposta

Exemplo ilustrativo:

```json
{
  "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": "contato@exemplo.com.br",
      "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:

| Campo | Descrição |
|---|---|
| `cnpj`, `cnpjBase` | CNPJ e raiz (8 primeiros caracteres). |
| `isHeadquarters` | Matriz (`true`) ou filial. |
| `legalName`, `tradeName` | Razão social e nome fantasia. |
| `status`, `statusDate`, `statusReason` | Situação cadastral, data e motivo (texto da Receita). |
| `activityStartDate` | Data de abertura. |
| `legalNature` | Natureza jurídica (texto). |
| `size`, `shareCapital` | Porte e capital social. |
| `mainCnae`, `secondaryCnaes` | `{ "code", "description" }` da atividade principal e lista das secundárias. |
| `address` | `streetType`, `street`, `number`, `complement`, `district`, `zipCode`, `municipality`, `state`. |
| `phones`, `email`, `emailShared` | Contatos publicados pela Receita. |
| `simples`, `mei` | `opted`, `excluded` ou `never`; `simplesOption` e `meiOption` (booleanos da Receita). |
| `taxRegime`, `federalDebt` | Regime da última ECF e dívida ativa da União (PGFN). |
| `establishmentCount` | Quantos estabelecimentos a raiz tem. |
| `partners` | Sócios: `type`, `name`, `document` (como publicado; CPF mascarado pela Receita), `qualification`, `entryDate`, `ageRange`. |
| `release` | Base da Receita usada na resposta (ex.: `rfb_2026_09`). |

## 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.

```bash
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):

```json
{
  "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": [...] }`.

| Chamada | Itens |
|---|---|
| `GET /reference/cnaes?q=padaria&limit=20` | `code`, `description`, `current` (false = código antigo que a Receita mantém), `class`, `className`, `division`, `divisionName`, `section`, `sectionName`. Sem `q`, a lista inteira. |
| `GET /reference/municipalities?q=campinas&state=SP&limit=20` | `code` (Receita, usado nos filtros), `ibgeCode`, `name`, `state`, `population`. Sem `q`, todos os municípios dos estados pedidos (ou do país). |
| `GET /reference/states` | `uf`, `ibgeCode`, `name`, `region`. |
| `GET /reference/legal-natures` | Naturezas jurídicas (`code`, descrição, grupo). |
| `GET /reference/registration-statuses`, `company-sizes`, `status-reasons`, `partner-types`, `partner-qualifications`, `countries` | Demais tabelas da Receita usadas nas respostas. |

## 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.

```bash
# 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.

| Ferramenta | O que faz | Argumentos |
|---|---|---|
| `buscar_atividade` | Acha códigos CNAE por palavras. | `termo` |
| `buscar_cidade` | Acha o código de município da Receita pelo nome. | `termo` |
| `contar_empresas` | Conta empresas ativas que atendem aos filtros, sem listar. | filtros (abaixo) |
| `buscar_empresas` | Lista empresas ativas, paginado. | filtros, `ordem`, `limite` (1–50, padrão 20), `cursor` |
| `consultar_cnpj` | Ficha completa de um CNPJ. | `cnpj` |
| `consultar_lote` | Confere até 100 CNPJs. | `cnpjs` |

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](https://zenpj.com/l/u6yksv7649/privacidade); os demais argumentos das ferramentas não são gravados.

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

| Ferramenta | O que faz | Argumentos |
|---|---|---|
| `buscar_atividade` | Acha códigos CNAE por palavras. | `termo` |
| `buscar_cidade` | Acha o código de município da Receita pelo nome. | `termo`, `uf` (opcional) |
| `contar_empresas` | Conta exatamente as empresas ativas por atividade principal, estado, cidade e tipo de contato. Sem filtros, o Brasil inteiro. | `cnae` (7 dígitos, ou de 2 a 6 para um grupo), `uf`, `municipio`, `com_email`, `com_telefone`, `com_celular`, `sem_mei`, `so_matriz` |
| `consultar_cnpj` | Situação cadastral de um CNPJ: situação, data e motivo, nome, abertura, natureza jurídica, atividade, cidade, Simples/MEI e se há dívida ativa da União. | `cnpj` |
| `consultar_governo` | Inscrições estaduais ativas (estados com arquivo aberto) e sanções CEIS/CNEP da CGU. | `cnpj` |
| `indice_aberturas` | Empresas abertas e baixadas por mês, no Brasil ou num estado, com comparação anual e divisão por atividade. | `uf` (opcional) |
| `licitacoes_abertas` | Licitações com proposta aberta no PNCP, 20 por página. | `termo`, `uf`, `pagina` (1–50) |

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):

```json
{ "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": "…" } }`).

| Status | `code` | Quando |
|---|---|---|
| 400 | — | Corpo JSON inválido ou com campos desconhecidos. |
| 401 | — | Chave ausente, inválida ou revogada. |
| 403 | `session_required` | Tentativa de gerenciar chaves com uma chave. |
| 403 | `page_limit` | Próxima página no plano gratuito (ele mostra as 10 primeiras empresas de cada busca). |
| 404 | — | CNPJ não encontrado. |
| 422 | — | Parâmetro inválido (`errors` por campo), inclusive cursor de outra ordem. |
| 422 | `filter_required` | Busca sem nenhum filtro. |
| 422 | `state_limit` / `state_required` | Regra de um estado por busca do plano. |
| 429 | `query_quota_exceeded` | Consultas de API do mês esgotadas. |
| 429 | `monthly_quota_exceeded` | Buscas novas do plano gratuito esgotadas. |
| 429 | — | Ritmo acima do limite; espere `Retry-After` segundos. |
| 503 | — | Base em carga (raro); tente de novo. |

## 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](https://zenpj.com/suporte) ou pela página [zenpj.com/api](https://zenpj.com/api).