---
title: "GET /v1/cnpjs/{cnpj}"
description: "Consulta uma empresa pelo CNPJ nos perfis basic ou full: cadastro, endereço, situação, Simples e MEI; no full, telefones, e-mail, site, sócios sem CPF, regime tributário e faixa de faturamento derivada do porte."
canonical: "https://cnpj.ia.br/docs/consulta-cnpj"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# GET /v1/cnpjs/{cnpj}

Consulta uma empresa pelo CNPJ nos perfis basic ou full: cadastro, endereço, situação, Simples e MEI; no full, telefones, e-mail, site, sócios sem CPF, regime tributário e faixa de faturamento derivada do porte.

`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](https://cnpj.ia.br/docs/campos).

## 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

```bash
# 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

```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

```javascript
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](https://cnpj.ia.br/docs/referencia/get-cnpj), tem esta forma; abaixo, um recorte dele:

```json
{
  "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](https://cnpj.ia.br/docs/erros-e-retentativas).

## Relacionados

- [Referência gerada de `getCnpj`](https://cnpj.ia.br/docs/referencia/get-cnpj): parâmetros, respostas e headers direto do OpenAPI.
- [Busca de empresas](https://cnpj.ia.br/docs/busca-empresas), quando você não tem o CNPJ e precisa achar as empresas por filtro.
- [Créditos, franquia e rate limit](https://cnpj.ia.br/docs/creditos-e-limites) e [`/precos`](https://cnpj.ia.br/precos).

## Perguntas frequentes

**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.