cnpjob 1.0.0

SDK oficial para a API cnpj/ob — consulta CNPJ, sócios, CNAE e mais

cnpjob

SDK oficial Python para a API cnpj/ob — consulte qualquer CNPJ diretamente da Receita Federal com uma linha de código.

Instalação

pip install cnpjob

Início rápido

from cnpjob import CNPJob

client = CNPJob('SUA_API_KEY')

empresa = client.lookup('12.345.678/0001-00')
print(empresa['razao_social'])  # EMPRESA EXEMPLO LTDA

Obtenha sua API key gratuita em app.cnpjob.com.br

---

Métodos

lookup(cnpj)

Consulta completa de uma empresa pelo CNPJ. Aceita qualquer formato (com ou sem máscara).

empresa = client.lookup('12.345.678/0001-00')

print(empresa['razao_social'])        # EMPRESA EXEMPLO LTDA
print(empresa['nome_fantasia'])       # Empresa Exemplo
print(empresa['situacao_cadastral'])  # ATIVA
print(empresa['data_abertura'])       # 2010-03-15
print(empresa['endereco']['municipio'])  # São Paulo
print(empresa['socios'])             # [{'nome': ..., 'qualificacao': ...}]

batch(cnpjs)

Consulta múltiplos CNPJs em uma única requisição (até 10 por chamada).

resultado = client.batch([
    '12345678000100',
    '33000167000101',
    '60701190000104',
])

for empresa in resultado['results']:
    print(empresa['cnpj'], empresa['razao_social'])

validate(cnpj)

Valida o formato e os dígitos verificadores de um CNPJ. Não consome cota.

result = client.validate('12.345.678/0001-00')
print(result['valid'])  # True ou False

---

Resposta completa

{
    "cnpj": "12345678000100",
    "razao_social": "EMPRESA EXEMPLO LTDA",
    "nome_fantasia": "Empresa Exemplo",
    "situacao_cadastral": "ATIVA",
    "data_abertura": "2010-03-15",
    "natureza_juridica": "Sociedade Empresária Limitada",
    "porte": "MICRO EMPRESA",
    "capital_social": 10000.00,
    "endereco": {
        "logradouro": "Rua das Flores",
        "numero": "100",
        "complemento": "Sala 1",
        "bairro": "Centro",
        "municipio": "São Paulo",
        "uf": "SP",
        "cep": "01310-100"
    },
    "atividade_principal": {
        "codigo": "6201-5/01",
        "descricao": "Desenvolvimento de programas de computador sob encomenda"
    },
    "socios": [
        {
            "nome": "JOÃO DA SILVA",
            "qualificacao": "Sócio-Administrador",
            "pais_origem": "Brasil"
        }
    ]
}

---

Tratamento de erros

from cnpjob import CNPJob

client = CNPJob('SUA_API_KEY')

try:
    empresa = client.lookup('00000000000000')
except Exception as e:
    print(e)
    # "CNPJ não encontrado"      → HTTP 404
    # "Limite de requisições"    → HTTP 429 (upgrade de plano)
    # "Chave de API inválida"    → HTTP 401

Código	Causa
401	API key inválida ou ausente
403	IP bloqueado pela allowlist
404	CNPJ não encontrado
429	Limite de requisições atingido

---

Uso com Django / FastAPI

# Django view
from cnpjob import CNPJob
from django.http import JsonResponse

client = CNPJob(settings.CNPJOB_API_KEY)

def consulta_cnpj(request, cnpj):
    empresa = client.lookup(cnpj)
    return JsonResponse(empresa)

# FastAPI endpoint
from cnpjob import CNPJob
from fastapi import FastAPI

app = FastAPI()
client = CNPJob('SUA_API_KEY')

@app.get('/empresa/{cnpj}')
def get_empresa(cnpj: str):
    return client.lookup(cnpj)

---

Opções avançadas

client = CNPJob(
    api_key='SUA_API_KEY',
    base_url='https://api.cnpjob.com.br/api',  # padrão
)

---

Compatibilidade

• Python 3.7+
• Django, Flask, FastAPI
• Scripts avulsos e notebooks Jupyter

Dependência única: requests

---

Planos

Plano	Req/dia	Req/min	Preço
Free	10	2	Grátis
Pro	10.000	60	R$ 99/mês
Business	100.000	300	R$ 299/mês

Ver todos os planos →

---

Links

• Documentação completa
• Portal do desenvolvedor
• Issues & suporte

Licença

MIT