GET /v1/cnpjs/{cnpj}

GET /v1/cnpjs/{cnpj} devolve uma empresa pelo CNPJ, com ou sem pontuação, numérico ou alfanumérico; na URL, a barra vai como %2F ou sai junto com a pontuação. O parâmetro profile escolhe entre basic (1 crédito), o cadastro da Receita Federal, e full (6 créditos), que acrescenta contatos, sócios e regime tributário. Disponível em todos os planos, inclusive no Free.

O que retorna

Os sinais has_* do basic dizem se o full teria contato para mostrar, o que permite decidir se vale pagar os 6 créditos. Cada campo, com tipo, nulabilidade e tabela de códigos, está em Campos da resposta.

Parâmetros

Exemplo de requisição

# basic (1 crédito)
curl "https://api.cnpj.ia.br/v1/cnpjs/00000000000191" \
  -H "Authorization: Bearer $CNPJIA_KEY"

# full (6 créditos)
curl "https://api.cnpj.ia.br/v1/cnpjs/00000000000191?profile=full" \
  -H "Authorization: Bearer $CNPJIA_KEY"

import os, requests

def consulta(cnpj: str, profile: str = "basic") -> dict:
    r = requests.get(
        f"https://api.cnpj.ia.br/v1/cnpjs/{cnpj}",
        params={"profile": profile},
        headers={"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

empresa = consulta("00000000000191", "full")
print(empresa["data"]["situacao_cadastral"]["descricao"])

async function consulta(cnpj, profile = "basic") {
  const url = new URL(`https://api.cnpj.ia.br/v1/cnpjs/${cnpj}`);
  url.searchParams.set("profile", profile);
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.CNPJIA_KEY}` },
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

const { data, meta } = await consulta("00000000000191", "full");
console.log(data.situacao_cadastral.descricao, meta.credits_charged);

Exemplo de resposta

O exemplo ilustrativo declarado no contrato para BANCO DO BRASIL SA (00.000.000/0001-91) no perfil full, completo na referência gerada, tem esta forma; abaixo, um recorte dele:

{
  "data": {
    "cnpj": "00000000000191",
    "razao_social": "BANCO DO BRASIL SA",
    "situacao_cadastral": { "codigo": "02", "descricao": "Ativa" },
    "porte": { "codigo": "05", "descricao": "Demais" },
    "endereco": { "municipio": "Brasília", "uf": "DF", "codigo_municipio_ibge": "5300108" },
    "telefones": [{ "ddd": "61", "numero": "34939002" }],
    "socios": [{ "nome": "NOME DO DIRIGENTE", "cnpj_cpf_socio": "***123456**", "qualificacao": { "codigo": "10", "descricao": "Diretor" } }],
    "faixa_faturamento": { "faixa": "Superior a R$4.800.000,00", "origem": "porte" }
  },
  "meta": {
    "request_id": "req_01J8ZK3Q9X",
    "profile": "full",
    "source": "rfb_open_data+oportunidados",
    "data_as_of": "2026-08-10",
    "suppressed": false,
    "credits_charged": 6,
    "credits_remaining": 99994,
    "credits_reset_at": "2026-10-01T00:00:00-03:00"
  }
}

Três campos de meta merecem atenção em toda integração: data_as_of é a data da base, não a data da chamada; credits_charged é o custo real, que cai para 1 crédito quando suppressed é true; request_id é o que o suporte pede.

Toda resposta traz o header X-Request-Id; se você enviar um X-Request-Id próprio com 8 a 64 caracteres de A-Z a-z 0-9 _ -, ele volta em X-Client-Request-Id. X-RateLimit-* aparece nas respostas que passaram pelo controle de requisições por conta, e X-Credits-* nas que passaram pela verificação de saldo, mesmo sem débito; a tabela completa está em Créditos, franquia e rate limit.

Erros

Nenhum erro consome crédito. A tabela completa, com a política de retentativa, está em Erros e retentativas.

Relacionados

• Referência gerada de getCnpj: parâmetros, respostas e headers direto do OpenAPI.
• Busca de empresas, quando você não tem o CNPJ e precisa achar as empresas por filtro.
• Créditos, franquia e rate limit e /precos.