Tutoriais

Como consultar CNPJ em Python, sem instalar nada

Com urllib.request e json, da biblioteca padrão, o Python consulta o CNPJ em cnpj.wortic.com e traz a ficha da Receita Federal, sem cadastro e sem chave.

Por Equipe Wortic 4 min de leitura
Mãos digitando em um notebook ao lado de uma xícara de café, em uma mesa de madeira

Para consultar um CNPJ em Python, abra https://cnpj.wortic.com/cnpj/{numero} com urllib.request e leia o JSON com json.load. Não precisa instalar nada, nem cadastro nem chave: a biblioteca padrão do Python já basta. A API é a da Wortic, gratuita, com os dados abertos do CNPJ publicados pela Receita Federal e 60 consultas por minuto por IP.

A função completa

Esta função foi testada contra a API em produção no Python 3.10 e no 3.15, com todos os avisos ligados (-W error). Ela trata o limite e devolve a mensagem de erro da própria API:

import json
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import urlopen

API = "https://cnpj.wortic.com/cnpj/"


def consultar_cnpj(cnpj: str) -> dict:
    try:
        with urlopen(API + quote(cnpj, safe=""), timeout=10) as resposta:
            return json.load(resposta)
    except HTTPError as erro:
        with erro:
            if erro.code == 429:
                espera = erro.headers.get("retry-after", "60")
                raise RuntimeError(f"Limite: tente em {espera} s") from erro
            raise RuntimeError(json.load(erro)["erro"]["mensagem"]) from erro


empresa = consultar_cnpj("37.853.407/0001-71")
print(empresa["razao_social"], empresa["situacao"]["descricao"])

O with erro: fecha a resposta de erro depois de lida. Sem ele, o Python 3.15 avisa que um recurso ficou aberto. O quote(cnpj, safe="") protege o endereço quando alguém digita o CNPJ com barra.

O que volta na ficha

Razão social, nome fantasia, situação na Receita com a data de início, abertura, atividade principal e secundárias (CNAE), natureza jurídica, porte, capital social, Simples, MEI, endereço com o código IBGE da cidade, telefone e e-mail públicos. O CNPJ pode ir com ou sem pontuação, e o formato alfanumérico, com letras, também é aceito.

CNPJ com dígito errado volta 400 com cnpj_invalido. CNPJ válido que não está na base volta 404 com nao_encontrado. A função transforma os dois em RuntimeError com a mensagem da API, pronta para mostrar a quem digitou.

Enriquecer uma planilha de CNPJs

Para uma lista, consulte um CNPJ por segundo e guarde cada resposta: assim a conta fica longe do limite de 60 por minuto, e o mesmo CNPJ nunca é consultado duas vezes. Confira os dígitos antes de chamar a API, para não gastar consulta com número digitado errado. O guia de enriquecer planilha da API mostra a regra completa.

Com requests ou httpx o código fica igual: um GET no mesmo endereço e a leitura do JSON. A API responde a qualquer cliente HTTP, do script no terminal ao Django, ao FastAPI e ao Flask.

Usar no Django, no FastAPI e no Flask

Chame a função na view ou na rota que salva o cliente e guarde a resposta no cache do framework por um dia. A ficha de uma empresa muda pouco, e a segunda consulta do mesmo CNPJ não precisa sair do seu servidor. Quando passar a usar a chave do plano, guarde-a numa variável de ambiente e mande no cabeçalho x-api-key; nunca ponha a chave no código.

O que a ficha não diz

A base mostra o cadastro que a empresa declarou à Receita Federal. Ela não traz faturamento, número de funcionários nem dívidas, e nenhum desses números deve ser deduzido dela no seu sistema.

Volume maior e busca avançada

Quem assina a Wortic recebe 1 milhão de consultas por mês em cada API. A mesma chave libera a busca de empresas por atividade, estado, cidade, porte, capital, data de abertura e raio em quilômetros, com resposta em JSON, planilha CSV ou jsonW. O jsonW tem SDK para Python a partir do 3.10: grava as fichas num arquivo e acha um CNPJ em menos de um milissegundo.

Perguntas frequentes

Preciso instalar o requests para consultar CNPJ em Python?

Não. A biblioteca padrão já basta: urllib.request faz o GET e json.load lê a resposta. Com requests ou httpx o código fica igual.

Em quais versões do Python o exemplo funciona?

Foi testado no Python 3.10 e no 3.15 contra a API em produção, com todos os avisos ligados.

Como consultar uma lista grande de CNPJs?

Uma consulta por segundo, sem repetir CNPJ e conferindo os dígitos antes. Para volume maior, a assinatura Wortic dá 1 milhão de consultas por mês.

Fontes

Conheça: API de CNPJ grátis da Wortic.

Imagem: Foto de Pixabay no Pexels (https://www.pexels.com/license/).

Quer isso funcionando na sua empresa?

Um consultor da Wortic olha o seu caso e mostra o caminho, sem compromisso.

Falar com um consultor

Equipe editorial

Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.

  • Automacao com IA
  • Gestao empresarial
  • CRM
  • ERP
  • Marketing digital

Isso funcionando no seu negócio.

Um consultor mostra o sistema do seu ramo, com a IA dentro.