GET /v1/cnpjs/{cnpj}

Retorna o perfil basic (1 crédito) ou full (6 créditos) de uma empresa. Aceita CNPJ numérico ou alfanumérico, com ou sem pontuação.

Créditos

perfil basic · 1 crédito perfil full · 6 créditos

Parâmetros

Respostas

200 OK

Empresa encontrada. Se houver pedido de remoção ativo, meta.suppressed é true, os campos de contato e sócios são omitidos e a cobrança é de 1 crédito.

{
  "data": {
    "cnpj": "00000000669822",
    "raiz_cnpj": "00000000",
    "razao_social": "BANCO DO BRASIL SA",
    "nome_fantasia": "TIRADENTES / BNC (SP)",
    "matriz_filial": {
      "codigo": "2",
      "descricao": "Filial"
    },
    "n_filiais": 0,
    "data_inicio_atividade": "2009-04-16",
    "situacao_cadastral": {
      "codigo": "02",
      "descricao": "Ativa"
    },
    "data_situacao_cadastral": "2009-04-16",
    "motivo_situacao_cadastral": {
      "codigo": "00",
      "descricao": "Sem motivo"
    },
    "situacao_especial": null,
    "data_situacao_especial": null,
    "natureza_juridica": {
      "codigo": "2038",
      "descricao": "Sociedade de Economia Mista"
    },
    "porte": {
      "codigo": "05",
      "descricao": "Demais"
    },
    "capital_social": 120000000000,
    "cnae_fiscal": {
      "codigo": "6422100",
      "descricao": "Bancos múltiplos, com carteira comercial"
    },
    "cnaes_secundarios": [
      {
        "codigo": "6499999",
        "descricao": "Outras atividades de serviços financeiros não especificadas anteriormente"
      }
    ],
    "endereco": {
      "tipo_logradouro": "AVENIDA",
      "logradouro": "TIRADENTES",
      "numero": "451",
      "complemento": null,
      "bairro": "Luz",
      "cep": "01101010",
      "municipio": "São Paulo",
      "codigo_municipio_ibge": "3550308",
      "codigo_municipio_siafi": "7107",
      "uf": "SP"
    },
    "simples": {
      "optante": false,
      "data_opcao": "2007-07-01",
      "data_exclusao": "2007-07-01"
    },
    "mei": {
      "optante": false,
      "data_opcao": "2009-07-01",
      "data_exclusao": "2009-07-01"
    },
    "has_email": false,
    "has_website": false,
    "has_phone": false,
    "has_mobile_phone": false
  },
  "meta": {
    "request_id": "req_01J8ZK3Q9X",
    "profile": "basic",
    "source": "rfb_open_data+oportunidados",
    "data_as_of": "2026-09-01",
    "suppressed": false,
    "credits_charged": 1,
    "credits_remaining": 59,
    "credits_reset_at": "2026-10-01T00:00:00-03:00"
  }
}

400 Requisição inválida

CNPJ inválido (formato ou dígito) ou profile diferente de basic/full.

{
  "error": {
    "code": "invalid_cnpj",
    "message": "O CNPJ informado é inválido. Confira os caracteres e o dígito verificador.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#invalid_cnpj"
  }
}

401 Não autorizado

Chave ausente, desconhecida, revogada ou expirada.

{
  "error": {
    "code": "invalid_api_key",
    "message": "Chave de API ausente ou inválida.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#invalid_api_key"
  }
}

402 Pagamento necessário

Franquia e pacotes esgotados. Header X-Credits-Reset.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Créditos insuficientes para esta operação. Aguarde a renovação ou adquira mais créditos.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#quota_exceeded"
  }
}

403 Proibido

Conta com billing_state blocked (payment_required). insufficient_plan não se aplica à consulta por CNPJ.

{
  "error": {
    "code": "payment_required",
    "message": "Sua conta está com pagamento pendente. Regularize para continuar usando a API.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#payment_required"
  }
}

404 Não encontrado

CNPJ válido ausente na base, ou API desligada (CNPJIA_API_ENABLED diferente de on).

{
  "error": {
    "code": "not_found",
    "message": "Recurso não encontrado.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": false,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#not_found"
  }
}

429 Excesso de requisições

Requisições por minuto da conta excedidas. Header Retry-After. Sem X-RateLimit-* quando o limite atingido é o de requisições sem chave por IP.

{
  "error": {
    "code": "rate_limited",
    "message": "Limite de requisições excedido. Tente novamente em instantes.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#rate_limited"
  }
}

500 Erro interno

Erro não previsto. retryable: true; a operação não é cobrada. Se houve liquidação, o estorno é tentado e pode ficar pendente de retentativa ou recuperação manual. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta; X-Credits-* presentes quando passou pela verificação de saldo (mesmo sem débito). Ausentes quando a falha é anterior (por exemplo, ao consultar o estado da base).

{
  "error": {
    "code": "internal_error",
    "message": "Erro interno. Tente novamente; se persistir, fale com o suporte.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#internal_error"
  }
}

503 Serviço indisponível

Janela mensal de atualização da base. Header Retry-After.

{
  "error": {
    "code": "maintenance",
    "message": "A base está em manutenção. Tente novamente em instantes.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#maintenance"
  }
}

504 Tempo esgotado

Timeout de consulta. retryable: true; nada é cobrado. X-RateLimit-* presentes quando a requisição passou pelo controle de requisições por conta; X-Credits-* presentes quando passou pela verificação de saldo (mesmo sem débito). Ausentes quando a falha é anterior (por exemplo, ao consultar o estado da base).

{
  "error": {
    "code": "upstream_timeout",
    "message": "A operação demorou mais que o esperado. Tente novamente.",
    "request_id": "req_01J8ZK3Q9X",
    "retryable": true,
    "docs_url": "https://cnpj.ia.br/docs/erros-e-retentativas#upstream_timeout"
  }
}

Ferramenta MCP

No servidor MCP oficial esta operação é a ferramenta consultar_cnpj, com a mesma chave e os mesmos créditos da API.

Exemplo

curl -s "https://api.cnpj.ia.br/v1/cnpjs/00000000000191" \
  -H "Authorization: Bearer $CNPJIA_KEY"