Consulta CNPJ via API REST: Tutorial Node.js, Python e cURL (2026)

Consultar CNPJ via API é uma chamada HTTP que retorna em segundos a razão social, situação cadastral, CNAE, endereço, capital social e quadro societário (QSA) de uma empresa diretamente da base da Receita Federal. Substitui consultas manuais no portal solucoes.receita.fazenda.gov.br — que exigem captcha e travam frequentemente — por uma única requisição programática integrável ao seu ERP, sistema de cadastro ou pipeline de compliance.

Este guia mostra o tutorial completo da API FiscalAPI com exemplos em cURL, Node.js e Python, quando faz sentido automatizar, estratégia de cache, e por que CNPJ raramente é suficiente sozinho — você quase sempre vai querer cruzar com Inscrição Estadual e certidões negativas.

Por que automatizar consulta de CNPJ#

Validar CNPJ manualmente no portal da Receita Federal:

• 1 consulta por vez, com captcha.
• Sem busca por filiais — você precisa do CNPJ completo (14 dígitos).
• Sem retorno estruturado — copia e cola manual em planilha.
• Indisponibilidade frequente em horário comercial.

Os cenários onde automação se paga rapidamente:

1. Cadastro de fornecedor/cliente em ERP — validar antes do cadastro evita NF-e contra empresas baixadas.
2. Onboarding de marketplace — Mercado Livre, Magalu, Amazon Marketplace exigem CNPJ ativo para liberar o seller.
3. Due diligence de M&A — validar quadro societário, CNAE, situação cadastral em uma carteira de targets.
4. Compliance recorrente — checar mensalmente fornecedores ativos contra mudanças de status.
5. Fintechs e crédito B2B — análise de crédito automatizada precisa de dados estruturados, não PDF.

Tutorial — primeira consulta em 5 minutos#

1. Criar conta + gerar API key#

Acesse fiscalapi.com.br, assine o plano apropriado (a partir de R$ 19,99/mês) e gere a chave em Configurações → API Keys. Os planos:

Cada consulta CNPJ conta como 1 consulta. Quem cruza CNPJ + IE + CND consome múltiplas consultas por documento — dimensionar o plano de acordo.

2. Endpoint REST#

GET https://api.fiscalapi.com.br/api/consultar-cnpj?cnpj={cnpj}
Headers: Authorization: Bearer {API_KEY}

Parâmetros:

3. cURL#

curl -X GET "https://api.fiscalapi.com.br/api/consultar-cnpj?cnpj=12345678000199" \
  -H "Authorization: Bearer SUA_API_KEY"

Resposta:

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cnpj": "12345678000199",
  "cached": false,
  "source_status": {
    "status": "success",
    "error_code": "",
    "error_message": ""
  },
  "result": {
    "razao_social": "AGROPECUARIA BOA VISTA LTDA",
    "nome_fantasia": "FAZENDA BOA VISTA",
    "situacao_cadastral": "ATIVA",
    "data_situacao_cadastral": "2010-05-20",
    "cnae_principal_codigo": "0151-2/01",
    "cnae_principal_descricao": "CRIACAO DE BOVINOS PARA CORTE",
    "cnaes_secundarios": [
      { "codigo": "0111-3/01", "descricao": "CULTIVO DE ARROZ" }
    ],
    "natureza_juridica": "206-2 - Sociedade Empresaria Limitada",
    "capital_social": "500000.00",
    "endereco": {
      "logradouro": "ROD BR-364 KM 28",
      "numero": "S/N",
      "bairro": "ZONA RURAL",
      "municipio": "CUIABA",
      "uf": "MT",
      "cep": "78000-000"
    },
    "qsa": [
      { "nome": "JOAO DA SILVA", "qualificacao": "Socio-Administrador" }
    ],
    "porte": "PEQUENO PORTE"
  }
}

4. Node.js#

async function consultarCNPJ(cnpj) {
  const url = new URL("https://api.fiscalapi.com.br/api/consultar-cnpj");
  url.searchParams.set("cnpj", cnpj);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.FISCALAPI_KEY}` },
  });

  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error}: ${data.message}`);

  if (data.result?.situacao_cadastral !== "ATIVA") {
    console.warn(`CNPJ irregular: ${data.result?.situacao_cadastral}`);
  }
  return data.result;
}

5. Python#

import os
import requests

def consultar_cnpj(cnpj: str) -> dict:
    r = requests.get(
        "https://api.fiscalapi.com.br/api/consultar-cnpj",
        params={"cnpj": cnpj},
        headers={"Authorization": f"Bearer {os.environ['FISCALAPI_KEY']}"},
        timeout=15,
    )
    r.raise_for_status()
    return r.json()

resp = consultar_cnpj("12345678000199")
if resp["result"]["situacao_cadastral"] != "ATIVA":
    raise ValueError(f"CNPJ irregular: {resp['result']['situacao_cadastral']}")

Campos da resposta — o que cada um significa#

Cruzando CNPJ com Inscrição Estadual#

A consulta CNPJ retorna endereco.uf da matriz. Para validar a operação fiscal completa:

1. Consulta CNPJ → recupera UF.
2. Consulta IE no estado dessa UF → confirma se está habilitada para emitir NF-e.
3. (Opcional) Consulta CND estadual → confirma regularidade fiscal.

Esse pipeline é o padrão para due diligence fiscal antes de fechar contrato. Detalhes da etapa 2 no guia de consulta de Inscrição Estadual e o tutorial específico de API em Consulta de IE via API.

Estratégia de cache#

O campo cached na resposta indica se o resultado veio do cache interno da FiscalAPI.

Recomendações de TTL no seu lado (cache próprio):

Tratamento de erros#

A API CNPJ retorna no formato:

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": "ERRO_INTERNO",
  "message": "Erro interno do servidor"
}

Códigos comuns:

Quando source_status.status for diferente de "success", o result pode vir vazio — sempre checar antes de acessar campos.

Boas práticas#

1. Normalize o CNPJ. Aceite formatado e não formatado no seu front. Remova pontos, barras e traços antes de chamar a API.

2. Valide dígito verificador antes da chamada. Algoritmo de validação CNPJ é público e simples; economiza cota.

3. Não armazene a API key no front-end. Toda chamada deve passar pelo seu backend.

4. Log estruturado. Salve request_id, cached e timestamp. Suporte da FiscalAPI consegue rastrear pelo request_id.

5. Combo certidões. Para um workflow completo de validação (CNPJ + IE + CND estadual + CND federal + CNDT + CRF FGTS), use o endpoint /api/certidoes-todas, que consolida tudo em uma chamada — economiza latência se você precisa de várias certidões para o mesmo documento.

6. Não confunda CNPJ com IE. CNPJ é federal e único (válido em todo o Brasil). IE é estadual e empresa pode ter mais de uma (uma por estado de operação). Misturar os dois em um único campo de banco vira bug silencioso.

Comparativo de provedores#

A escolha entre provedores depende do volume, dos dados extras necessários e do quão crítica é a integração. Critérios típicos:

A FiscalAPI integra todas as consultas (CNPJ, IE, CND estadual/federal, CNDT, CRF FGTS, CADIN, Lista Suja, IBAMA, CAR, CCIR) sob a mesma chave e o mesmo dashboard, voltado para o agronegócio brasileiro e fornecedores de empresas reguladas.

Perguntas frequentes#

A consulta de CNPJ é em tempo real? A API consulta a Receita Federal e retorna o dado mais atualizado disponível. A Receita atualiza a base periodicamente (a cada 45 dias ou menos para empresas ativas), então "tempo real" significa o snapshot mais recente que a Receita publicou.

Posso consultar CPF da mesma forma? Não. Consulta de CPF tem regras de privacidade distintas e exige login GovBR para o próprio titular. O que você consulta com CPF na FiscalAPI é Inscrição Estadual de produtor rural (que é informação pública porque ele é contribuinte do ICMS). Detalhes no guia de consulta de IE de produtor rural.

Como descobrir filiais de uma empresa? A consulta CNPJ retorna dados do CNPJ específico que você consultou (14 dígitos). A Receita identifica matriz pelo final 0001 no CNPJ base + 2 dígitos verificadores. Filiais têm o mesmo radical (8 dígitos iniciais) com sufixo diferente. Para listar todas as filiais, você precisa iterar os sufixos ou usar uma base de dados de CNPJs (CNPJBase pública da Receita).

Existe limite de QSA exposto? A Receita Federal pode restringir parte do QSA em alguns períodos por questões judiciais ou cadastrais. Quando isso acontece, a API retorna qsa: [] mesmo para empresas grandes.

Como interpretar "ATIVA NÃO REGULAR"? Esse status aparece em alguns provedores como sinônimo de "ATIVA com pendência". A FiscalAPI retorna o status bruto na data_situacao_cadastral — interprete junto com situacao_cadastral. Empresa com ATIVA recente (< 30 dias) que era BAIXADA antes merece atenção.

Posso usar a API para validar pré-NF-e? Sim. O recomendado é cruzar CNPJ + IE no pré-envio. Se o destinatário tem CNPJ ativo mas IE irregular no estado da operação, a NF-e é rejeitada com código 215. Veja consulta de IE via API para tratar essa parte.

Próximo passo#

Conheça os planos da FiscalAPI e teste no dashboard sem código antes de integrar. Documentação técnica em docs.fiscalapi.com.br.

Se sua operação envolve produtores rurais, fornecedores agro ou validação de IE em múltiplos estados, comece pelo pillar de Inscrição Estadual — CNPJ sozinho não cobre o caso de uso.

Artigos relacionados#

• Como Consultar Inscrição Estadual em 2026: Guia Definitivo
• Consulta de Inscrição Estadual via API: Tutorial Completo
• Como integrar a API FiscalAPI em 5 minutos
• Por que sua consulta de CNPJ está desatualizada (e como obter o dado ao vivo)
• Consulta SINTEGRA: como consultar a Inscrição Estadual nos 27 estados