Como consultar CNPJ via API no Python.
Aprenda a consultar CNPJ via API no Python com requests: código pronto, leitura do JSON, tratamento de erros e boas práticas. API de CNPJ grátis, sem chave e sem cadastro.
Por que usar a API do openCNPJ no Python
Python é a escolha natural para automações, análise de dados e integrações. Em poucas linhas, você consulta o CNPJ de uma empresa e recebe razão social, endereço, CNAE e sócios em um dicionário pronto para usar no pandas, no Django ou em um script.
- Grátis, sem chave de acesso e sem cadastro.
- Resposta em JSON com razão social, situação cadastral, endereço, CNAEs, sócios e Simples Nacional.
- Aceita o CNPJ numérico e o novo CNPJ alfanumérico.
- Limite de 10 requisições por segundo por IP.
O que você precisa
Python 3.8 ou superior e a biblioteca requests (pip install requests).
Consultar um CNPJ no Python
O endpoint é GET https://api.opencnpj.com.br/cnpj/{cnpj}. Envie o CNPJ com 14 caracteres, sem pontos, barra ou hífen. O exemplo abaixo consulta o CNPJ 06.990.590/0001-23:
import requests
cnpj = "06990590000123"
resposta = requests.get(f"https://api.opencnpj.com.br/cnpj/{cnpj}", timeout=10)
resposta.raise_for_status()
empresa = resposta.json()
print(empresa["razao_social"])
print(empresa["estabelecimento"]["situacao_cadastral"])Requer a biblioteca requests (pip install requests).
Remover a máscara do CNPJ
Se o CNPJ vem formatado (06.990.590/0001-23) de um formulário, banco de dados ou planilha, limpe a pontuação antes de montar a URL. A mesma regra funciona para o CNPJ alfanumérico:
import re
def limpar_cnpj(cnpj: str) -> str:
return re.sub(r"[^0-9A-Za-z]", "", cnpj).upper()
cnpj = limpar_cnpj("06.990.590/0001-23") # "06990590000123"
Campos mais usados da resposta
| Campo | Conteúdo |
|---|---|
razao_social | Nome empresarial |
estabelecimento.nome_fantasia | Nome fantasia |
estabelecimento.situacao_cadastral | Ativa, Suspensa, Inapta, Baixada ou Nula |
estabelecimento.atividade_principal | CNAE principal, com código e descrição |
estabelecimento.cidade.nome e estabelecimento.estado.sigla | Município e UF |
estabelecimento.cep, logradouro, numero, bairro | Endereço |
simples.simples e simples.mei | Opção pelo Simples Nacional e MEI |
socios | Quadro de sócios e administradores |
A lista completa de campos está na documentação da API.
Tratando erros
Verifique o status HTTP antes de ler o JSON. Python: use resposta.status_code.
| Status | O que significa | O que fazer |
|---|---|---|
200 | CNPJ encontrado | Ler o JSON |
400 | Formato de CNPJ inválido | Conferir os 14 caracteres |
404 | CNPJ não encontrado na base | Informar ao usuário |
429 | Limite de requisições excedido | Aguardar e tentar de novo |
500 | Erro interno | Tentar novamente mais tarde |
Os erros também vêm em JSON, com os campos status, titulo e detalhes.
Boas práticas
- Defina um timeout na requisição, por exemplo com o parâmetro
timeout=do requests. - Guarde o resultado em cache se o mesmo CNPJ for consultado com frequência.
- Em processamentos em lote, respeite o limite de 10 requisições por segundo.
- Os dados refletem a base pública mais recente processada e não substituem certidões oficiais.
Perguntas frequentes
A API de CNPJ do openCNPJ é gratuita?
Sim, 100% grátis. Não há chave de acesso nem cadastro. O limite é de 10 requisições por segundo por IP.
Dá para consultar CNPJ em Python sem instalar o requests?
Sim, com a biblioteca padrão: json.load(urllib.request.urlopen("https://api.opencnpj.com.br/cnpj/06990590000123", timeout=10)). Para status diferentes de 200, o urllib lança HTTPError.
Como consultar uma lista de CNPJs de uma planilha?
Leia a coluna com o pandas, limpe a máscara de cada CNPJ e faça as chamadas em sequência, respeitando o limite de 10 requisições por segundo (por exemplo, com time.sleep(0.1) entre as chamadas).
De onde vêm os dados do CNPJ?
Dos dados abertos do CNPJ publicados pela Receita Federal, complementados por bases públicas. Os dados podem ter defasagem e não substituem certidões oficiais. Veja a origem dos dados.