Guias · atualizado em 09/10/2026 · 5 min de leitura · Equipe apipj

API de CNPJ: dados cadastrais da Receita Federal em JSON

Uma API de CNPJ recebe um número de CNPJ e devolve, em JSON, os dados cadastrais que a Receita Federal publica sobre aquele estabelecimento: razão social, nome fantasia, situação cadastral, atividade (CNAE), endereço, sócios, natureza jurídica, porte e opção pelo Simples Nacional e pelo MEI. Serve para preencher cadastro sem digitação, validar fornecedor ou cliente antes de faturar e enriquecer uma base de empresas.

A apipj monta essa base a partir dos dados abertos do CNPJ que a Receita Federal publica todo mês. A carga de setembro de 2026 tem 73.366.147 estabelecimentos, matrizes e filiais, ativos e baixados.

O que a API devolve

Uma consulta a GET /v1/cnpj/{cnpj} devolve um documento por estabelecimento. Os campos principais:

Datas vêm no formato AAAA-MM-DD. O que a Receita não publica vem como null: a API não inventa campo. O CPF de sócio pessoa física vem mascarado, exatamente como na base pública. A lista completa, com tipos, está na documentação.

Primeira consulta em um minuto

1. Crie uma conta grátis. A chave de API aparece na hora, sem cartão.
2. Guarde a chave numa variável de ambiente (APIPJ_KEY), nunca no código-fonte.
3. Chame a API com o cabeçalho Authorization: Bearer:

curl -s https://apipj.com.br/v1/cnpj/11378117000120 \
  -H "Authorization: Bearer $APIPJ_KEY"

import os, requests
r = requests.get("https://apipj.com.br/v1/cnpj/11378117000120",
                 headers={"Authorization": f"Bearer {os.environ['APIPJ_KEY']}"}, timeout=10)
empresa = r.json()
print(empresa["razao_social"], empresa["situacao_cadastral"]["descricao"])

const r = await fetch('https://apipj.com.br/v1/cnpj/11378117000120', {
  headers: { Authorization: `Bearer ${process.env.APIPJ_KEY}` },
});
const empresa = await r.json();
console.log(empresa.razao_social, empresa.situacao_cadastral.descricao);

Trecho da resposta (formato completo):

{
  "cnpj": "11378117000120",
  "cnpj_formatado": "11.378.117/0001-20",
  "razao_social": "LEADS2B S/A",
  "situacao_cadastral": { "codigo": "02", "descricao": "ATIVA", "data": "2009-11-24" },
  "cnae_principal": { "codigo": "6311900", "descricao": "Tratamento de dados, provedores de serviços de aplicação e serviços de hospedagem na internet" },
  "endereco": {
    "tipo_logradouro": "RUA", "logradouro": "PADRE ANCHIETA", "numero": "2285",
    "bairro": "BIGORRILHO", "cep": "80730001", "uf": "PR",
    "municipio": { "codigo_rfb": "7535", "codigo_ibge": "4106902", "nome": "CURITIBA" }
  },
  "simples": { "optante": false, "data_opcao": "2009-11-24", "data_exclusao": "2019-12-31" }
}

Quer testar sem escrever código? O sandbox faz a mesma consulta no navegador e mostra os cabeçalhos de limite.

Dois formatos de resposta

• completo (padrão): documento estruturado, com código e descrição separados e datas em ISO. É o melhor para código novo.
• simplificado (?formato=simplificado): campos planos e já formatados para exibir ou gravar direto: datas DD/MM/AAAA, CNPJ e CEP com máscara, endereço e telefone em texto. Útil para planilhas, automações e integrações antigas.

Limites e planos

Toda consulta usa uma chave. O limite por minuto protege a API de rajadas; a cota mensal é o volume contratado.

Toda resposta traz X-RateLimit-Remaining e X-Quota-Remaining, então sua aplicação sabe quanto ainda pode consultar. Passou do limite por minuto, a resposta é 429 com Retry-After; acabou a cota do mês, 429 com o código quota_exceeded. Detalhes e preços atualizados em Preços.

O que esta API não substitui

• Certidão e consulta oficial em tempo real. Os dados são a carga mensal dos dados abertos da Receita. Uma alteração feita hoje aparece na próxima carga. Para prova formal de situação cadastral, use o comprovante emitido no site da Receita Federal.
• Inscrição estadual. A base pública do CNPJ não traz inscrição estadual; ela vem do cadastro de cada estado.
• Análise de crédito. Não há score, protesto nem dívida: são dados cadastrais.

Boas práticas para produção

• Valide antes de consultar. O dígito verificador se confere localmente, sem gastar cota. O guia do CNPJ alfanumérico tem a função em quatro linguagens.
• Faça cache. A base muda uma vez por mês: guardar a resposta por até 30 dias corta a maior parte das consultas repetidas.
• Trate 404 como resposta, não como erro. O CNPJ pode não existir, ou ser tão novo que ainda não está na carga do mês.
• Respeite o Retry-After quando receber 429 por limite por minuto, e não repita quando o código for quota_exceeded.
• Chame a API do seu servidor. A chave dá acesso à sua cota; no navegador ela fica exposta.

Os tutoriais mostram tudo isso em código pronto: Python, JavaScript, PHP e C#.

Perguntas frequentes

De onde vêm os dados e com que frequência são atualizados?

Dos dados abertos do CNPJ publicados pela Receita Federal, carregados uma vez por mês. O mês em uso aparece em atualizado_em em cada resposta e em Status. A metodologia está em Sobre.

A API aceita CNPJ alfanumérico?

Sim. Desde 31/07/2026 a Receita emite CNPJ com letras nas 12 primeiras posições. A API valida e consulta os dois formatos, com ou sem máscara, em maiúsculas ou minúsculas. Veja o guia do CNPJ alfanumérico.

O endereço traz o código IBGE do município?

Traz. endereco.municipio.codigo_ibge tem os 7 dígitos que a NFS-e pede, e codigo_rfb tem o código de 4 dígitos da própria Receita. Só estabelecimentos no exterior vêm sem IBGE.

Posso consultar sem cadastro?

A validação de formato e dígito (GET /v1/valida/{cnpj}) é aberta. A consulta de dados exige uma chave, que é grátis: assim cada uso tem limite e ninguém esgota a API dos outros.

E os dados de sócios, a LGPD permite?

São dados pessoais de acesso público, publicados pela própria Receita, e a API os devolve como estão na base, com o CPF mascarado. A base legal, a finalidade e o canal para o titular pedir a supressão estão na política de privacidade.