Quando vale pedir o perfil full?

Quando você precisa de telefone, e-mail, site, sócios ou regime tributário. Se só precisa validar cadastro, situação e endereço, o basic resolve por uma fração do custo. Os sinais has_phone, has_email e has_website do basic dizem se o full teria contato para mostrar.

A consulta devolve o CPF dos sócios?

Não, em nenhum perfil, nem na busca, nem no MCP. O quadro societário traz nome, qualificação, data de entrada, país e faixa etária de cada sócio, e o nome e a qualificação do representante legal quando houver.

O que significa `meta.suppressed: true`?

Que a empresa tem um pedido de remoção de contatos ativo. A resposta vem sem telefones, e-mail, site, contatos extras e sócios, e a chamada custa o preço do basic mesmo quando você pediu full.

Um 404 consome crédito?

Não. Nenhum erro consome crédito: só respostas 200 são cobradas. Um CNPJ com formato válido que não está na base responde 404 not_found e o saldo fica igual.

Os dados são da Receita Federal ou da Oportunidados?

O cadastro vem dos dados abertos da Receita Federal, atualizados mensalmente; meta.source identifica a origem e meta.data_as_of a data da base. Contatos extras e site vêm de enriquecimento da Oportunidados, e a faixa de faturamento é derivada do porte declarado, não uma estimativa.

Consulta por CNPJ · Docs cnpj.ia.br

GET /v1/cnpjs/{cnpj} devolve uma empresa pelo CNPJ, com ou sem pontuação, numérico ou alfanumérico. 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

Perfil	Créditos	Conteúdo
`basic`	1	Identificação, matriz ou filial, situação cadastral e motivo, situação especial, natureza jurídica, porte, capital social, CNAE principal e secundários, endereço com códigos SIAFI e IBGE, Simples e MEI, e os sinais `has_email`, `has_phone`, `has_mobile_phone` e `has_website`
`full`	6	Tudo do `basic` mais telefones, e-mail, site, contatos extras, sócios (sem CPF), regime tributário, faixa de faturamento derivada do porte e faixa de funcionários

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

Onde	Nome	Tipo	Obrigatório	Descrição
path	`cnpj`	string	sim	14 caracteres após normalização; aceita `00000000000191`, `00.000.000/0001-91` e o formato alfanumérico
query	`profile`	`basic` ou `full`	não	Padrão `basic`

Exemplo de requisição

curl

# 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/00.000.000/0001-91?profile=full" \
  -H "Authorization: Bearer $CNPJIA_KEY"

Python

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"])

Node

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", "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-01",
    "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.

Erros

Status	Código	Quando
400	`invalid_cnpj`	Formato ou dígito verificador inválido
401	`invalid_api_key`, `key_expired`	Chave ausente, revogada ou vencida
402	`quota_exceeded`	Franquia e pacotes esgotados; o header `X-Credits-Reset` diz quando renova
403	`payment_required`	Cobrança em atraso além da carência
404	`not_found`	CNPJ válido que não existe na base, ou empresa com remoção total
429	`rate_limited`	Requisições por minuto da conta excedidas; respeite `Retry-After`
503	`maintenance`	Janela de atualização da base; respeite `Retry-After`
504	`upstream_timeout`	Tempo limite na consulta; nada é cobrado e a chamada pode ser repetida

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.