Documentação da cnpjob API

Acesse dados de 67 milhões de empresas, 70 milhões de estabelecimentos e 27 milhões de sócios diretamente da Receita Federal — em tempo real, com latência < 100ms.

REST API JSON Dados RF oficiais 67M empresas

Base URL https://api.cnpjob.com.br

💡

Todos os endpoints de dados retornam JSON. Inclua o header Accept: application/json nas suas requisições. A API usa HTTPS obrigatoriamente em produção.

Quickstart — 60 segundos

bash — cURL

# 1. Registre sua conta e obtenha uma API key em cnpjob.com.br

# 2. Consulte um CNPJ
curl https://api.cnpjob.com.br/cnpj/33000167000101 \
  -H "X-API-Key: cnjb_live_SUA_CHAVE"

javascript — fetch

const res = await fetch('https://api.cnpjob.com.br/cnpj/33000167000101', {
  headers: { 'X-API-Key': 'cnjb_live_SUA_CHAVE' }
});
const empresa = await res.json();
console.log(empresa.razao_social); // "PETROLEO BRASILEIRO S A"

python — requests

import requests

res = requests.get(
    'https://api.cnpjob.com.br/cnpj/33000167000101',
    headers={'X-API-Key': 'cnjb_live_SUA_CHAVE'}
)
empresa = res.json()
print(empresa['razao_social'])  # "PETROLEO BRASILEIRO S A"

🔑 Segurança

Autenticação

A API usa API Keys transmitidas via header HTTP. Nunca exponha sua chave em código client-side ou repositórios públicos.

Header obrigatório

http

GET /cnpj/33000167000101 HTTP/1.1
Host: api.cnpjob.com.br
X-API-Key: cnjb_live_SUA_CHAVE
Accept: application/json

⚠️

Requisições sem o header X-API-Key retornam 401 Unauthorized. Chaves inativas ou inválidas também retornam 401.

Gerenciando sua API Key

Ação	Como fazer
Criar chave	Dashboard → "Gerar nova chave" (exibida uma única vez)
Revogar chave	Gerar nova chave revoga automaticamente a anterior
Ver prefixo	Dashboard → seção "Minha API Key" (ex: `cnjb_live_ab12...`)
Verificar uso	Dashboard → seção "Uso"

✅

A chave completa é exibida apenas no momento da criação. O sistema armazena somente o hash SHA-256. Guarde em variável de ambiente (CNPJOB_API_KEY=cnjb_live_...).

⚡ Limites

Rate Limiting

Limites são aplicados por API key usando contadores atômicos no Redis. Dois janelas independentes: por minuto e por dia.

Free

R$0

para sempre

10 req / dia

2 req / minuto

10 itens / página

Pro

R$99

por mês

10.000 req / dia

60 req / minuto

100 itens / página

Business

R$349

por mês

100.000 req / dia

300 req / minuto

1.000 itens / página

Headers de resposta

Todas as respostas de endpoints autenticados incluem os headers abaixo:

X-RateLimit-Limit-Minute

Limite de requisições por minuto do seu plano

X-RateLimit-Limit-Day

Limite diário do seu plano

X-RateLimit-Remaining-Minute

Requisições restantes no minuto atual

X-RateLimit-Remaining-Day

Requisições restantes no dia atual

⚠️

Ao exceder o limite por minuto ou diário, a API retorna 429 Too Many Requests. O contador de minuto reseta após 60s e o diário à meia-noite UTC.

resposta 429

{
  "error": "Limite de 2 req/min atingido. Aguarde 1 minuto."
}

🚨 Respostas

Códigos de erro

Todos os erros retornam JSON com campo error descritivo.

Status	Significado	Causa comum
`400`	Bad Request	CNPJ inválido, parâmetro ausente
`401`	Unauthorized	API key ausente ou inválida
`402`	Payment Required	Plano expirado — renove a assinatura
`403`	Forbidden	Endpoint requer plano superior (Pro/Business)
`404`	Not Found	CNPJ não encontrado na base RF
`429`	Too Many Requests	Limite de req/min ou req/dia atingido
`500`	Internal Server Error	Erro inesperado — contate o suporte
`503`	Service Unavailable	Serviço temporariamente indisponível

exemplo de erro 403

{
  "error": "Este endpoint requer o plano pro ou superior. Faça upgrade em cnpjob.com.br."
}

📋 Sem autenticação

Planos disponíveis

Lista os planos ativos com limites e preços. Útil para exibir opções de upgrade na sua aplicação.

GET /plans Lista planos ativos ▾

Resposta 200

json

[
  {
    "id": 1,
    "name": "Free",
    "slug": "free",
    "price_brl": "0.00",
    "req_per_day": 10,
    "req_per_min": 2,
    "max_page_size": 10,
    "has_checkout": false
  },
  {
    "id": 2,
    "name": "Pro",
    "slug": "pro",
    "price_brl": "99.90",
    "req_per_day": 10000,
    "req_per_min": 60,
    "max_page_size": 100,
    "has_checkout": true
  }
]

📋 Sem autenticação

CNAEs

Lista e consulta atividades econômicas da Classificação Nacional de Atividades Econômicas (CNAE).

GET /cnae Lista todos os CNAEs ▾

Resposta 200

json

[
  { "codigo": "0111301", "descricao": "Cultivo de arroz" },
  { "codigo": "0111302", "descricao": "Cultivo de milho" }
]

GET /cnae/:codigo Detalhes de um CNAE + empresas ▾

🔒

Requer API Key + plano Pro ou superior.

Parâmetros

Parâmetro	Tipo	Descrição
`codigo`	path	Código CNAE (ex: `6201501`)
`limit`	query	Resultados por página (padrão: 20, máx: conforme plano)
`offset`	query	Paginação (padrão: 0)

📋 Sem autenticação

Municípios

GET /municipios Lista todos os municípios ▾

json

[
  { "codigo": "7107", "nome": "SAO PAULO", "uf": "SP" }
]

GET /municipios/:uf Municípios por estado ▾

Parâmetros

Parâmetro	Tipo	Exemplo
`uf`	path	`SP`, `RJ`, `MG`...

🏢 Dados de empresa

Consulta por CNPJ

Retorna dados completos de uma empresa: razão social, situação, endereço, CNAE, sócios, capital social e mais — direto da Receita Federal.

GET /cnpj/:cnpj Dados completos da empresa ▾

✅

Disponível no plano Free. Aceita CNPJ com ou sem formatação (33.000.167/0001-01 ou 33000167000101).

Parâmetros

Parâmetro	Tipo	Descrição
`cnpj`	path	CNPJ com 14 dígitos (formatado ou não)

Exemplo de requisição

bash

curl https://api.cnpjob.com.br/cnpj/33000167000101 \
  -H "X-API-Key: cnjb_live_SUA_CHAVE"

Resposta 200

json

{
  "cnpj": "33.000.167/0001-01",
  "razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
  "nome_fantasia": "PETROBRAS",
  "situacao_cadastral": "Ativa",
  "data_situacao": "2005-11-17",
  "data_abertura": "1966-09-28",
  "porte": "Grande",
  "natureza_juridica": "Sociedade de Economia Mista",
  "capital_social": 205431960490.52,
  "cnae_principal": {
    "codigo": "0600301",
    "descricao": "Extração de petróleo e gás natural"
  },
  "cnaes_secundarios": [
    { "codigo": "1921700", "descricao": "Fabricação de produtos do refino de petróleo" }
  ],
  "endereco": {
    "logradouro": "AV REPUBLICA DO CHILE",
    "numero": "65",
    "complemento": "ANDAR 1 A 22",
    "bairro": "CENTRO",
    "municipio": "RIO DE JANEIRO",
    "uf": "RJ",
    "cep": "20031912"
  },
  "telefone": "2135985678",
  "email": "relacionamento@petrobras.com.br",
  "socios": [
    {
      "nome": "MAGDA MARIA DE REGINA CHAMBRIARD",
      "qualificacao": "Presidente",
      "tipo": "Pessoa Física",
      "cpf_representante": null
    }
  ]
}

👥 Societário

Quadro societário

Retorna o quadro de sócios e administradores (QSA) de um CNPJ com qualificações e percentuais.

GET /cnpj/:cnpj/socios Sócios de um CNPJ ▾

✅

Disponível no plano Free.

Exemplo de requisição

bash

curl https://api.cnpjob.com.br/cnpj/33000167000101/socios \
  -H "X-API-Key: cnjb_live_SUA_CHAVE"

Resposta 200

json

[
  {
    "nome": "MAGDA MARIA DE REGINA CHAMBRIARD",
    "cpf_cnpj": "***355***-**",
    "qualificacao": "Presidente",
    "tipo": "Pessoa Física",
    "data_entrada": "2023-06-21"
  }
]

🏭 Filiais

Estabelecimentos

Lista todas as filiais e estabelecimentos de um CNPJ raiz, com endereços e situações individuais.

GET /cnpj/:cnpj/estabelecimentos Filiais de um CNPJ ▾

🔒

Requer plano Pro ou superior.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`cnpj`	path	—	CNPJ (14 dígitos)
`limit`	query	20	Itens por página (máx conforme plano)
`offset`	query	0	Posição inicial para paginação

Resposta 200

json

{
  "total": 48,
  "data": [
    {
      "cnpj": "33.000.167/0001-01",
      "nome_fantasia": "PETROBRAS - MATRIZ",
      "situacao": "Ativa",
      "tipo": "Matriz",
      "uf": "RJ",
      "municipio": "RIO DE JANEIRO"
    }
  ]
}

🔍 Busca textual

Busca por razão social

Busca empresas por nome usando similaridade trigram (pg_trgm). Suporta termos parciais e nomes incompletos.

GET /empresa/busca Busca por nome da empresa ▾

🔒

Requer plano Pro ou superior.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`q`	query	✅ Sim	Termo de busca (mín. 3 caracteres)
`uf`	query	Não	Filtrar por estado (ex: `SP`)
`limit`	query	Não	Resultados (padrão: 20)
`offset`	query	Não	Paginação

Exemplo

bash

curl "https://api.cnpjob.com.br/empresa/busca?q=petrobras&uf=RJ&limit=5" \
  -H "X-API-Key: cnjb_live_SUA_CHAVE"

Resposta 200

json

[
  {
    "cnpj": "33.000.167/0001-01",
    "razao_social": "PETROLEO BRASILEIRO S A PETROBRAS",
    "situacao": "Ativa",
    "uf": "RJ",
    "municipio": "RIO DE JANEIRO",
    "cnae_principal": "0600301"
  }
]

🔎 Filtros avançados

Busca com filtros

Filtra empresas por CNAE, UF, município e situação cadastral. Ideal para prospecção e enriquecimento de leads.

GET /empresas Filtra empresas por critérios ▾

🔒

Requer plano Pro ou superior. Ao menos um filtro é obrigatório.

Parâmetros

Parâmetro	Tipo	Exemplo	Descrição
`cnae`	query	`6201501`	Código CNAE principal
`uf`	query	`SP`	Sigla do estado
`municipio`	query	`7107`	Código do município RF
`situacao`	query	`2`	Situação cadastral: `2`=Ativa, `8`=Baixada, `3`=Suspensa
`limit`	query	`50`	Resultados por página
`offset`	query	`0`	Paginação

Exemplo — empresas de TI ativas em São Paulo

bash

curl "https://api.cnpjob.com.br/empresas?cnae=6201501&uf=SP&situacao=2&limit=50" \
  -H "X-API-Key: cnjb_live_SUA_CHAVE"

🔍 Busca por sócio

Empresas por sócio

Descobre todas as empresas onde um CPF ou CNPJ figura como sócio ou administrador.

GET /socio/busca Empresas de um sócio ▾

🔒

Requer plano Pro ou superior.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`cpf_cnpj`	query	✅ Sim	CPF (11 dígitos) ou CNPJ (14 dígitos) do sócio
`limit`	query	Não	Resultados por página (padrão: 20)
`offset`	query	Não	Paginação

Exemplo

bash

curl "https://api.cnpjob.com.br/socio/busca?cpf_cnpj=12345678901" \
  -H "X-API-Key: cnjb_live_SUA_CHAVE"

Resposta 200

json

[
  {
    "cnpj": "12.345.678/0001-90",
    "razao_social": "EMPRESA EXEMPLO LTDA",
    "situacao": "Ativa",
    "nome_socio": "FULANO DE TAL",
    "qualificacao": "Sócio-Administrador"
  }
]