Como consultar CNPJ com Python usando a API CNPJ da APIBrasil

Validar o CNPJ de um cliente ou fornecedor é uma das tarefas mais comuns em sistemas brasileiros: cadastro de empresas, emissão de nota, análise de crédito, onboarding de parceiros. Neste tutorial você vai aprender a consultar CNPJ com Python usando a API CNPJ da APIBrasil, que devolve razão social, situação cadastral, CNAE, endereço, sócios e dados do Simples Nacional em uma única chamada.

O código foi escrito seguindo a especificação publicada em doc.apibrasil.io e usa o modo de homologação, então você pode rodar quantas vezes quiser sem gastar crédito.

O que a API CNPJ devolve

A API CNPJ fica na categoria Consulta CNPJ do catálogo e custa R$ 0,04 por consulta em produção. Além da consulta por número de CNPJ, ela tem endpoints para buscar empresas por CNAE, por estado, por capital social e para listar sócios. Neste guia vamos usar a consulta por número.

Grupo de dados	Campos principais
Identificação	`cnpj`, `nome_fantasia`, `matriz_filial`
Situação	`situacao_cadastral`, `data_situacao_cadastral`, `motivo_situacao`
Atividade	`cnae_fiscal`, `cnae_fiscal_secundaria`, `data_inicio_atividades`
Endereço	`logradouro`, `numero`, `bairro`, `cep`, `uf`, `municipio`
Empresa	`empresa.razao_social`, `empresa.natureza_juridica`, `empresa.porte_empresa`, `empresa.capital_social`
Simples Nacional	`simples.opcao_simples`, `simples.opcao_mei` e datas
Quadro societário	`socios`

Pré-requisitos

Python 3.9 ou mais novo.
Um Bearer Token da APIBrasil, que você encontra em Credenciais no painel. Se ainda não tem, siga os primeiros passos na APIBrasil.

Passo 1: prepare o projeto

Crie uma pasta, um ambiente virtual e instale as bibliotecas requests (para as chamadas HTTP) e python-dotenv (para ler o token do arquivo .env):

mkdir consulta-cnpj && cd consulta-cnpj
python3 -m venv .venv
source .venv/bin/activate   # no Windows: .venv\Scripts\activate
pip install requests python-dotenv

Terminal criando ambiente virtual Python e instalando requests para consultar CNPJ — Ambiente virtual criado e biblioteca <code>requests</code> instalada.

Crie um arquivo .env com o token e o modo de homologação ligado:

APIBRASIL_TOKEN=seu_token_aqui
APIBRASIL_HOMOLOG=true

Não esqueça de adicionar .env ao .gitignore.

Passo 2: entenda a chamada

A API CNPJ recebe um POST no endereço abaixo, com o tipo da consulta e o número do CNPJ no corpo:

POST https://gateway.apibrasil.io/api/v2/dados/cnpj/credits
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "tipo": "cnpj",
  "cnpj": "44.959.669/0001-80",
  "homolog": true
}

O CNPJ pode ir com ou sem pontuação no exemplo do catálogo. Mesmo assim, é boa prática limpar a máscara antes de enviar, e é isso que o nosso código vai fazer.

Passo 3: escreva o cliente em Python

Crie o arquivo consulta_cnpj.py:

import os
import re
import sys
import time

import requests
from dotenv import load_dotenv

load_dotenv()

URL = "https://gateway.apibrasil.io/api/v2/dados/cnpj/credits"
TOKEN = os.environ["APIBRASIL_TOKEN"]
HOMOLOG = os.getenv("APIBRASIL_HOMOLOG", "true").lower() == "true"


class SaldoInsuficiente(Exception):
    pass


class ErroAPIBrasil(Exception):
    pass


def valor_br(texto):
    """Converte "105,660" ou "0.19" em float."""
    if texto is None:
        return 0.0
    texto = str(texto).strip()
    if "," in texto:
        texto = texto.replace(".", "").replace(",", ".")
    return float(texto)


def consultar_cnpj(cnpj, tentativas=3):
    cnpj = re.sub(r"\D", "", cnpj)
    if len(cnpj) != 14:
        raise ValueError("CNPJ deve ter 14 dígitos")

    corpo = {"tipo": "cnpj", "cnpj": cnpj, "homolog": HOMOLOG}
    cabecalhos = {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    }

    for tentativa in range(1, tentativas + 1):
        try:
            resp = requests.post(URL, json=corpo, headers=cabecalhos, timeout=120)
        except requests.Timeout:
            if tentativa == tentativas:
                raise
            time.sleep(2 ** tentativa)
            continue

        if resp.status_code == 402:
            raise SaldoInsuficiente("Saldo insuficiente: recarregue a conta.")
        if resp.status_code >= 500 and tentativa < tentativas:
            time.sleep(2 ** tentativa)
            continue
        if resp.status_code >= 400:
            raise ErroAPIBrasil(f"HTTP {resp.status_code}: {resp.text[:200]}")

        corpo_resp = resp.json()
        # O erro pode vir com HTTP 200: confira sempre o campo error.
        if corpo_resp.get("error"):
            raise ErroAPIBrasil(corpo_resp.get("message", "Erro na consulta"))
        return corpo_resp

    raise ErroAPIBrasil("Não foi possível concluir a consulta")


if __name__ == "__main__":
    resposta = consultar_cnpj(sys.argv[1])
    empresa = resposta["data"]["cnpj"]

    print("Razão social .....", empresa["empresa"]["razao_social"])
    print("Nome fantasia ....", empresa["nome_fantasia"])
    print("Situação .........", empresa["situacao_cadastral"])
    print("CNAE principal ...", empresa["cnae_fiscal"])
    print("Custo ............ R$", resposta["tax"])
    print("Saldo restante ... R$", valor_br(resposta["balance"]))

Os pontos mais importantes do código:

Limpeza do CNPJ: a expressão \D remove pontos, barra e hífen.
Duas verificações: primeiro o status HTTP, depois o campo error do corpo. A APIBrasil pode devolver um erro com HTTP 200.
Retry só quando faz sentido: tempo esgotado e erros 5xx são repetidos com espera crescente. Erros 4xx não, porque repetir uma chamada errada continua cobrando.
402 separado: saldo insuficiente é um erro terminal e precisa de ação humana.
valor_br: balance e tax chegam como texto no formato brasileiro, e o separador varia entre APIs.

Passo 4: rode o script

python consulta_cnpj.py 44.959.669/0001-80

Saída do script Python mostrando razão social, situação cadastral e CNAE do CNPJ consultado — O script imprime os principais dados da empresa e o custo da consulta.

Interpretando a situação cadastral

O campo situacao_cadastral vem como código, no padrão da Receita Federal:

Código	Situação
01	Nula
02	Ativa
03	Suspensa
04	Inapta
08	Baixada

Na prática, para liberar um cadastro, a regra mais comum é aceitar só 02 (Ativa) e mandar os demais casos para revisão manual.

Boas práticas para usar em produção

Cache: dados cadastrais mudam pouco. Guardar o resultado por alguns dias evita pagar duas vezes pela mesma consulta.
Homologação nos testes: deixe APIBRASIL_HOMOLOG=true no ambiente de desenvolvimento e na esteira de CI.
Log de custo: registre tax e balance de cada chamada para acompanhar o gasto.
Validação local antes: confira os dígitos verificadores do CNPJ antes de chamar a API e evite consultas inúteis.

Perguntas frequentes

Consigo buscar empresas por CNAE ou por estado?

Sim. A mesma API tem endpoints para buscar CNPJs por CNAE, por UF e por faixa de capital social, além de um endpoint para listar sócios. Os corpos de cada um estão na página da API CNPJ em doc.apibrasil.io.