# CPF.CNPJ API

> API REST para consulta de dados cadastrais brasileiros em tempo real (D+0), direto da Receita Federal e demais fontes oficiais: CPF, CNPJ, Notas Fiscais (NFe), Certidões CGU, verificação de WhatsApp e análise de crédito. Sem captcha e sem data de nascimento. Toda a comunicação é HTTP via método **GET**, a autenticação é um token embutido no próprio caminho da URL e as respostas são sempre **JSON** (`application/json; charset=UTF-8`). Tempo médio de resposta em torno de 2 segundos. Qualquer linguagem que faça uma requisição HTTP é compatível — não há SDK obrigatório.

A consulta segue sempre o formato `https://api.cpfcnpj.com.br/{token}/{pacote}/{documento}`, onde `{pacote}` é o ID numérico do tipo de consulta (ex.: `9` para CPF E, `6` para CNPJ D) e `{documento}` é o CPF, CNPJ, telefone ou chave informado **apenas com dígitos** (sem pontos, traços ou barras). A maioria das consultas é **síncrona** (resposta imediata, sem polling). As de **Análise de Crédito (300–305)** são **assíncronas**: a 1ª requisição inicia a consulta e responde `estado: "processando"`; **repita a MESMA requisição** (mesma URL) após cerca de 1 minuto para obter o resultado. O resultado fica em **cache por 1 hora** — repetir dentro desse período devolve o resultado **sem cobrar de novo**; o crédito é debitado **uma única vez**, na conclusão. Os dados são **100% em tempo real (D+0)**, refletindo a Receita Federal no instante da consulta — sem bases antigas, incompletas ou vazadas.

- **Base URL**: `https://api.cpfcnpj.com.br`
- **Método**: `GET` (todas as operações)
- **Autenticação**: token de integração como **1º segmento da URL** (não é cabeçalho HTTP), atrelado ao IP de origem. Obtenha em [Painel → API → Tokens](https://www.cpfcnpj.com.br/admin/tokens.html).
- **Token de testes** (retorna apenas dados fictícios, sem custo): `5ae973d7a997af13f0aaf2bf60e65803`
- **Content-Type das respostas**: `application/json; charset=UTF-8`
- **TLS mínimo**: 1.3 (todo o tráfego passa pela Cloudflare; libere os [IPs da Cloudflare](https://www.cloudflare.com/ips/) no firewall).
- **Timeout recomendado**: 60 segundos.
- **Rate limit**: 20 requisições por segundo por token/IP (excedido → erro `1007`).

## OpenAPI (especificação completa)

A especificação OpenAPI **3.1** é a fonte canônica do contrato da API: descreve todos os paths, parâmetros, schemas de resposta, exemplos, campos e códigos de erro. Use-a para integrar sem ler documentação manualmente.

- [openapi.json (download)](https://api.cpfcnpj.com.br/doc/openapi.json): especificação OpenAPI 3.1 completa, em JSON.
- **Gerar SDK/client**: rode um gerador sobre o arquivo, por exemplo `npx @openapitools/openapi-generator-cli generate -i https://api.cpfcnpj.com.br/doc/openapi.json -g <linguagem> -o ./sdk` (suporta TypeScript, Python, Go, Java, PHP, C#, etc.). Também funciona com `openapi-typescript`, `oapi-codegen`, `swagger-codegen` e similares.
- **Validar contratos**: use a spec em testes de contrato (Schemathesis, Dredd, Prism mock server) para garantir que sua integração bate com os schemas reais.
- **Importar em ferramentas**: Postman, Insomnia, Stoplight, Swagger UI e VS Code (REST Client / extensões OpenAPI) importam o arquivo diretamente e montam as requisições para você.
- Toda a referência de campos, exemplos e erros está dentro da própria spec — não há contrato paralelo a manter.

## Postman

A maneira mais rápida de testar e explorar a API:

1. No Postman, clique em **Import**.
2. Escolha a aba **Link** e cole `https://api.cpfcnpj.com.br/doc/openapi.json`.
3. Confirme — o Postman gera **automaticamente** a collection com todas as operações (CPF, CNPJ, WhatsApp, NFe, Análise de Crédito, Certidões, Saldo), já com os parâmetros de caminho.
4. Defina a variável `{token}` com o token de testes `5ae973d7a997af13f0aaf2bf60e65803` e dispare qualquer requisição para ver respostas fictícias de exemplo.

Uma collection Postman pronta também está disponível em [/doc/postman_collection.json](https://api.cpfcnpj.com.br/doc/postman_collection.json) (com environment em [/doc/postman_environment.json](https://api.cpfcnpj.com.br/doc/postman_environment.json)). O mesmo arquivo OpenAPI importa em Insomnia (Import → URL) e em qualquer cliente compatível.

## Servidor MCP

- [mcp.cpfcnpj.com.br](https://mcp.cpfcnpj.com.br): servidor **MCP (Model Context Protocol)** para consumir a API diretamente de agentes e assistentes de IA (Claude, ChatGPT e outros compatíveis), **sem implementar a chamada HTTP manualmente**. O agente passa a "enxergar" as ferramentas de consulta de CPF, CNPJ e demais serviços e executá-las com o seu token.

## Como consultar

- **Formato**: `GET https://api.cpfcnpj.com.br/{token}/{pacote}/{documento}`
- O `{documento}` deve conter **somente dígitos** (sem máscara). CNPJ aceita também o novo formato **alfanumérico** (IN RFB 2.229/2024, vigência jul/2026) — envie sem pontuação e compare em maiúsculas; CNPJs numéricos atuais continuam válidos.
- **Exemplo (CPF E, pacote 9)** com o token de testes:

  ```
  curl 'https://api.cpfcnpj.com.br/5ae973d7a997af13f0aaf2bf60e65803/9/00000000000'
  ```

- **Exemplo (CNPJ D, pacote 6)**:

  ```
  curl 'https://api.cpfcnpj.com.br/5ae973d7a997af13f0aaf2bf60e65803/6/11222333000181'
  ```

- **Consulta por Razão Social** (lista empresas), pacote 4, via query string `razao_social`:

  ```
  curl 'https://api.cpfcnpj.com.br/5ae973d7a997af13f0aaf2bf60e65803/4?razao_social=GOOGLE BRASIL'
  ```

## Pacotes de CPF

Consultas de pessoa física pelo número do CPF: `GET /{token}/{id}/{cpf}`.

- `1` **CPF A** — Nome Completo.
- `7` **CPF B** — Nome Completo, Data de Nascimento.
- `2` **CPF C** — Nome Completo, Data de Nascimento, Nome Completo da Mãe, Gênero.
- `8` **CPF D** — Nome Completo, Nome Social, Data de Nascimento, Situação Cadastral na Receita Federal, Óbito e Data, Número de Comprovante da Consulta, PDF Comprovante da Consulta.
- `9` **CPF E** — Nome Completo, Nome Social, Nome Completo da Mãe, Data de Nascimento, Gênero, Situação Cadastral na Receita Federal, Óbito e Data, Número de Comprovante da Consulta, PDF Comprovante da Consulta.
- `3` **CPF F** — Nome Completo, Data de Nascimento, Gênero, Endereço Completo.
- `14` **CPF H** — Nome Completo, Pessoa Politicamente Exposta e Relacionados (PPE / PEP).
- `15` **CPF I** — Empresas no Nome.
- `18` **CPF K** — Nome Completo, Data de Nascimento, Endereço Completo, Situação Cadastral na Receita Federal.
- `21` **CPF Lookalike** — Nome Completo, E-mails, Telefones, WhatsApp.
- `20` **CPF Family** — Mandados de Prisão (BNMP/CNJ).
- `22` **CPF Programas Sociais** — Nome Completo, Lista dos Programas Sociais em que o titular é participante no atual ano.
- `23` **CPF Mandados de Busca e Apreensão** — Mandados de Busca e Apreensão BNMP, Lista INTERPOL.
- `26` **CPF D Simplificado** — Nome Completo, Data de Nascimento, Situação Cadastral na Receita Federal.
- `27` **CPF CAC/SINIC** — Certidão de Antecedentes Criminais (PF), PDF + Número de Controle + Nada Consta.
- `24` **CPF CNS** — Cartão Nacional de Saúde (CNS).
- `29` **CPF CNH** — Nome, CPF, Número da CNH, UF da CNH, Data da primeira CNH.

## Pacotes de CNPJ

Consultas de pessoa jurídica pelo número do CNPJ: `GET /{token}/{id}/{cnpj}`.

- `4` **CNPJ A** — Razão Social.
- `4` **CNPJ Pesquisa** — lista de empresas pela Razão Social: `GET /{token}/4?razao_social=...` (query string, sem documento no caminho).
- `5` **CNPJ B** — Razão Social, Nome Fantasia, Endereço Completo.
- `10` **CNPJ C** — Razão Social, Nome Fantasia, Endereço Completo, Início das Atividades, Telefones, Faxes, E-mail, Situação Cadastral na Receita Federal.
- `6` **CNPJ D** — Razão Social, Nome Fantasia, Endereço Completo, Início das Atividades, Telefones, Faxes, E-mail, Código e Descrição da Atividade Econômica Principal, Código e Descrição da Natureza Jurídica, Nome do Responsável pela Empresa, Porte da Empresa, Quadro de Sócios e Administradores (QSA), Situação Cadastral na Receita Federal, Informações sobre Simples Nacional, CPF do Responsável Legal e Sócios.
- `11` **CNPJ F** — Razão Social, Informações sobre Simples Nacional, Informações sobre SIMEI, Informações sobre Suframa.
- `16` **CNPJ H** — Inscrições Estaduais, Razão Social.
- `19` **CNPJ Lookalike** — Razão Social, E-mails dos Sócios, Telefones dos Sócios, WhatsApp dos Sócios.
- `25` **CNPJ QsA Detalhado** — Porcentagem Societária de cada Sócio.

## Pacotes de WhatsApp

Verificação de número de telefone (formato E.164, com DDI): `GET /{token}/{id}/{telefone}`. **Rate limit: 2 requisições por segundo por conta**, compartilhado entre todos os pacotes WhatsApp (200–203); excedido → erro `1007`. Precisa de mais? Fale com o comercial.

- `200` **WhatsApp Número Ativo** — Verifica número ativo.
- `201` **WhatsApp Número Ativo + Avatar** — Verifica número ativo + avatar.
- `202` **WhatsApp Número Ativo + Conta Business** — Verifica número ativo + conta business.
- `203` **WhatsApp Completo** — Número ativo, avatar, business, empresa (site, e-mail, endereço) e catálogo de produtos.

## Notas Fiscais

- `100` **NFe Unificada PF e PJ** — Consulta em tempo real de notas fiscais NFe PF e PJ.

## Análise de Crédito

Consultas de crédito por CPF ou CNPJ: `GET /{token}/{id}/{cpfcnpj}`. **Assíncronas**: repita a MESMA requisição até `estado: concluido` (resultado em cache 1h; cobra 1×).

- `300` **Dívidas e Negativações** — Pefin/Refin, Score de Crédito, Protestos, Ações Cíveis, CCF, Alertas.
- `301` **SRC Banco Central** — Score, Operações de Crédito (SCR/Banco Central).
- `302` **Boa Vista SCPC** — Pendências e Consultas (Boa Vista SCPC).
- `303` **Protestos Cenprot Nacional** — Protestos em Cartório (Cenprot Nacional).
- `304` **CADIN** — Pendências no CADIN (órgão, tipo, situação, data).
- `305` **PGFN** — Dívida Ativa da União (PGFN), Valor total da dívida, Razão Social, Detalhamento por natureza (débitos e convênios), UF, Município e CNAE.

## Outros

- `101` **CGU Certidões PF e PJ** — CEIS, CEPIM, CNEP, CGU-PJ, ePAD e CEAF + PDF.

## Conta

- **Consulta de saldo** (sem custo) — saldo disponível de um pacote: `GET /{token}/saldo/{pacote}`. Retorna um objeto `pacote{}` com `id` (int), `nome` (string) e `saldo` (int).

## Formato das respostas

Toda resposta traz o campo `status`: **1** em caso de sucesso, **0** em caso de falha. Em falhas, vêm também `erro` (mensagem) e `erroCodigo` (código numérico). Campos comuns:

- `pacoteUsado` — ID do pacote utilizado na consulta.
- `saldo` — saldo do pacote após a consulta.
- `consultaID` — ID da consulta (16 dígitos).
- `delay` — tempo total da consulta, em segundos.
- `status` — `1` sucesso, `0` falha.
- `erro` / `erroCodigo` — presentes somente em falha.

Nos pacotes assíncronos de Análise de Crédito (300–305), a resposta traz `estado` (`processando` ou `concluido`) e, quando pronta, o objeto `data` com o resultado.

## Códigos de erro

Em sucesso, `status: 1`; em falha, `status: 0` acompanhado de `erro` e `erroCodigo`.

- `100` (CPF) — `CPF inválido!`: número digitado não é um CPF válido.
- `101` (CPF) — `Informe um CPF com 11 dígitos!`: CPF com menos de 11 dígitos.
- `102` (CPF) — `O CPF informado não existe`: CPF válido, mas ausente nas bases da Receita.
- `110` (WhatsApp) — `Número de telefone inválido (informe com DDI).`
- `111` (WhatsApp) — `Não foi possível verificar o número no WhatsApp.`
- `200` (CNPJ) — `CNPJ inválido!`: número digitado não é um CNPJ válido.
- `201` (CNPJ) — `Informe um CNPJ com 14 dígitos!`: CNPJ com menos de 14 dígitos.
- `202` (CNPJ) — `O CNPJ informado não existe`: CNPJ válido, mas ausente nas bases da Receita.
- `400` (CPF/CNPJ) — `Incorrect parameters.`: a formatação da URI está incorreta.
- `1000` (transversal) — `Token inválido!`: token não pertence ao IP de origem.
- `1001` (transversal) — `Créditos insuficientes!`: sem créditos no pacote selecionado.
- `1002` (transversal) — `Conta suspensa e/ou inativa!`: contate o suporte.
- `1003` (transversal) — `Blacklist até *DATA*`: IP e token suspensos temporariamente.
- `1004` (transversal) — `Pacote indisponível para consultas!`: ID do pacote inválido ou indisponível.
- `1005` (transversal) — `Não é possível consultar *CPF/CNPJ* neste pacote!`: falha no fornecedor ou erro interno.
- `1006` (transversal) — `Serviço temporariamente indisponível`: fornecedor de dados off-line; tente novamente.
- `1007` (transversal) — `Limite de requisições (20) por segundo excedido`: aguarde o próximo segundo e tente novamente.
- `1009` (Análise de Crédito) — `Pacote requer liberação`: pacote restrito; fale com o comercial para habilitar.

## Regras anti-abuso

- 3 consultas consecutivas com token inválido → bloqueio de 5 minutos.
- 3 consultas do mesmo documento no mesmo pacote em menos de 1 minuto → bloqueio de 3 minutos.
- 3 consultas consecutivas sem créditos em menos de 1 minuto → bloqueio de 5 minutos.
- Rate limit de 20 req/s (erro `1007`). Aumento sob demanda com o suporte técnico.

## Recursos

- [Documentação interativa](https://api.cpfcnpj.com.br/doc): portal de referência com exemplos de código, painel "Testar" e todos os pacotes.
- [Especificação OpenAPI 3.1](https://api.cpfcnpj.com.br/doc/openapi.json): contrato completo (paths, schemas, exemplos, erros) em JSON.
- [Servidor MCP](https://mcp.cpfcnpj.com.br): Model Context Protocol para consumir a API a partir de agentes de IA.
- [Página de status](https://status.cpfcnpj.com.br): disponibilidade e latência dos pacotes em tempo real.
- [Painel de Controle](https://www.cpfcnpj.com.br/admin): cadastro, créditos e gestão de tokens.
- [API → Tokens](https://www.cpfcnpj.com.br/admin/tokens.html): criação e gestão de tokens (vinculados ao IP).

## Optional

- [Segurança e TLS 1.3](https://www.cloudflare.com/ips/): todo o tráfego passa pela Cloudflare; TLS mínimo 1.3 e liberação dos IPs da Cloudflare no firewall.
- **CNPJ Alfanumérico** (IN RFB 2.229/2024, jul/2026): 12 posições alfanuméricas (`0-9`, `A-Z`) + 2 dígitos verificadores numéricos; sem breaking changes, CNPJs numéricos coexistem. Exemplo válido: `12ABC34501DE35`.
- **Certificações ISO/IEC (2025)**: ISO/IEC 27001:2022 (Segurança da Informação), ISO/IEC 27701:2025 (Privacidade — LGPD/GDPR) e ISO/IEC 37301:2021 (Compliance).