API de CNPJ para onboarding de PJ

No cadastro de um cliente pessoa jurídica, a pergunta é simples: esse CNPJ existe, qual é a situação cadastral e quais dados estão registrados na Receita Federal? Uma consulta basic (1 crédito) responde com situação cadastral e sua data, matriz ou filial, razão social, nome fantasia, endereço e natureza jurídica, na base da Receita Federal de agosto/2026. CNPJ malformado ou inexistente custa 0.

O fluxo em três passos

1. Normalize e consulte

   Envie o CNPJ como o usuário digitou, com ou sem pontuação, numérico ou alfanumérico. A API normaliza e valida o dígito verificador.

   GET /v1/cnpjs/00.000.000/0001-91

2. Decida pela situação, não pelo 200

   situacao_cadastral.codigo diz se a empresa está ativa; data_situacao_cadastral e matriz_filial contextualizam. Preencha razão social e endereço do cadastro.

   data.situacao_cadastral.codigo == "02" → Ativa

3. Trate os três resultados do cadastro

   400 invalid_cnpj é formato ou dígito errado; 404 not_found é CNPJ válido que não existe; nenhum dos dois consome crédito. Só o 200 é cobrado, no peso do perfil.

   400 invalid_cnpj · 404 not_found · 200 → cobrado no peso do basic

Código pronto

import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"}

def validar_cnpj(cnpj_digitado: str) -> dict:
    cnpj = "".join(ch for ch in cnpj_digitado if ch.isalnum())  # tira pontuação: "/" quebraria a rota
    r = requests.get(f"https://api.cnpj.ia.br/v1/cnpjs/{cnpj}", headers=HEADERS, timeout=10)
    if r.status_code == 400:
        return {"ok": False, "motivo": "CNPJ inválido"}
    if r.status_code == 404:
        return {"ok": False, "motivo": "CNPJ não encontrado na base"}
    r.raise_for_status()
    d = r.json()["data"]
    return {
        "ok": d["situacao_cadastral"]["codigo"] == "02",
        "situacao": d["situacao_cadastral"]["descricao"],
        "desde": d["data_situacao_cadastral"],
        "razao_social": d["razao_social"],
        "matriz": d["matriz_filial"]["descricao"],
        "cidade": f'{d["endereco"]["municipio"]}/{d["endereco"]["uf"]}',
    }

const headers = { Authorization: `Bearer ${process.env.CNPJIA_KEY}` };

async function validarCnpj(cnpjDigitado) {
  const res = await fetch(`https://api.cnpj.ia.br/v1/cnpjs/${encodeURIComponent(cnpjDigitado)}`, { headers });
  if (res.status === 400) return { ok: false, motivo: "CNPJ inválido" };
  if (res.status === 404) return { ok: false, motivo: "CNPJ não encontrado na base" };
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const { data: d } = await res.json();
  return {
    ok: d.situacao_cadastral.codigo === "02",
    situacao: d.situacao_cadastral.descricao,
    desde: d.data_situacao_cadastral,
    razaoSocial: d.razao_social,
    matriz: d.matriz_filial.descricao,
    cidade: `${d.endereco.municipio}/${d.endereco.uf}`,
  };
}

Campos mais usados

O que muda com o CNPJ alfanumérico

Desde 2026 a Receita Federal emite CNPJs com letras nas doze primeiras posições. A API aceita o formato antigo e o novo, com ou sem pontuação, e devolve cnpj sempre normalizado. No seu cadastro, guarde como texto, aceite letras na máscara e valide o dígito verificador pelo algoritmo novo, que continua correto para os numéricos. Detalhes em CNPJ alfanumérico.

Decisões que o código deve tomar

• Ativa é 02: os demais códigos de situacao_cadastral (nula, suspensa, inapta, baixada) estão na tabela de Campos da resposta; motivo_situacao_cadastral explica o porquê.
• Filial não é erro: matriz_filial diz se o CNPJ é o estabelecimento principal; raiz_cnpj liga matriz e filiais.
• Data da base: meta.data_as_of é a foto mensal que respondeu. Uma empresa aberta este mês pode ainda não constar; trate 404 not_found como “não encontrada na base de agosto/2026”, não como inexistente.
• Sem CPF: o cadastro PJ não recebe dado de pessoa física além do quadro societário público, no perfil full, se você precisar dele.