---
title: "Primeira consulta em cinco minutos"
description: "Crie a chave, faça a primeira consulta por CNPJ, leia a resposta e confira o uso. Exemplos em curl, Python, Node, PHP, Ruby, Go e n8n."
canonical: "https://cnpj.ia.br/docs/inicio-rapido"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

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

# Primeira consulta em cinco minutos

Crie a chave, faça a primeira consulta por CNPJ, leia a resposta e confira o uso. Exemplos em curl, Python, Node, PHP, Ruby, Go e n8n.

Uma chave, uma chamada HTTP e um JSON com os dados da empresa e a data da base. A chave é criada em [app.cnpj.ia.br](https://app.cnpj.ia.br) e vai no header `Authorization`. O exemplo abaixo consulta o CNPJ 00.000.000/0001-91 (BANCO DO BRASIL SA), uma instituição pública, no perfil `full`, que custa 6 créditos.

## 1. Crie a chave

Entre em [app.cnpj.ia.br](https://app.cnpj.ia.br) com e-mail e senha, ou com GitHub ou Google. A chave aparece uma única vez: copie e guarde num gerenciador de segredos ou numa variável de ambiente. Ela nasce com 15 créditos; verificar o e-mail libera os 60 créditos mensais do plano Free.

> **Nunca exponha a chave**
>
> Não coloque a chave em URL, em código versionado nem em um frontend. Quem tem a chave gasta os seus créditos. Se vazou, revogue no portal e crie outra: o efeito na API é imediato.

## 2. Faça a primeira consulta

Guarde a chave em `CNPJIA_KEY` e rode um dos exemplos. Todos fazem a mesma coisa: `GET /v1/cnpjs/{cnpj}` com `profile=full`.

#### curl

```bash
curl "https://api.cnpj.ia.br/v1/cnpjs/00000000000191?profile=full" \
  -H "Authorization: Bearer $CNPJIA_KEY"
```

#### Python

```python
import os, requests

r = requests.get(
    "https://api.cnpj.ia.br/v1/cnpjs/00000000000191",
    params={"profile": "full"},
    headers={"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"},
    timeout=10,
)
r.raise_for_status()
body = r.json()
print(body["data"]["razao_social"], body["meta"]["data_as_of"])
```

#### Node

```javascript
const res = await fetch(
  "https://api.cnpj.ia.br/v1/cnpjs/00000000000191?profile=full",
  { headers: { Authorization: `Bearer ${process.env.CNPJIA_KEY}` } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { data, meta } = await res.json();
console.log(data.razao_social, meta.data_as_of);
```

#### PHP

```php
<?php
$ch = curl_init("https://api.cnpj.ia.br/v1/cnpjs/00000000000191?profile=full");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CNPJIA_KEY")],
]);
$body = json_decode(curl_exec($ch), true);
echo $body["data"]["razao_social"], " ", $body["meta"]["data_as_of"];
```

#### Ruby

```ruby
require "net/http"
require "json"

uri = URI("https://api.cnpj.ia.br/v1/cnpjs/00000000000191?profile=full")
req = Net::HTTP::Get.new(uri, "Authorization" => "Bearer #{ENV.fetch('CNPJIA_KEY')}")
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
body = JSON.parse(res.body)
puts body["data"]["razao_social"], body["meta"]["data_as_of"]
```

#### Go

```go
req, _ := http.NewRequest("GET",
    "https://api.cnpj.ia.br/v1/cnpjs/00000000000191?profile=full", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("CNPJIA_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer res.Body.Close()
var body struct {
    Data struct{ RazaoSocial string `json:"razao_social"` } `json:"data"`
    Meta struct{ DataAsOf string `json:"data_as_of"` }     `json:"meta"`
}
json.NewDecoder(res.Body).Decode(&body)
fmt.Println(body.Data.RazaoSocial, body.Meta.DataAsOf)
```

#### n8n

```json
{
  "node": "HTTP Request",
  "method": "GET",
  "url": "https://api.cnpj.ia.br/v1/cnpjs/{{ $json.cnpj }}",
  "queryParameters": { "profile": "full" },
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "headerAuth": { "name": "Authorization", "value": "Bearer <sua chave, guardada como credencial>" }
}
```

O CNPJ pode ir com ou sem pontuação. O perfil `basic` (1 crédito) traz o cadastro; o `full` (6 créditos) acrescenta telefones, e-mail, site, sócios e regime tributário. Os dois perfis estão descritos em [Consulta por CNPJ](https://cnpj.ia.br/docs/consulta-cnpj) e todos os campos em [Campos da resposta](https://cnpj.ia.br/docs/campos).

## 3. Leia a resposta

A resposta tem dois objetos. `data` traz os campos do perfil pedido; `meta` diz o que aconteceu com a chamada:

- `meta.data_as_of`: a data da base da Receita Federal que respondeu. A base é mensal; nenhum campo reflete o instante da chamada.
- `meta.credits_charged` e `meta.credits_remaining`: o que esta chamada custou e o que sobra na franquia.
- `meta.request_id`: o identificador para citar num pedido de suporte.
- `meta.suppressed`: `true` quando a empresa tem pedido de remoção de contatos ativo. Nesse caso os campos de contato e os sócios são omitidos e a chamada custa 1 crédito, mesmo em `full`.

Ausência de dado é `null`, nunca chave omitida. Os mesmos valores viajam nos headers `X-Credits-Charged`, `X-Credits-Remaining` e `X-Request-Id`.

## 4. Confira o uso

`GET /v1/usage` custa 0 créditos e devolve franquia, consumo do ciclo, pacotes, data do reset e o limite de requisições por minuto do seu plano.

#### curl

```bash
curl "https://api.cnpj.ia.br/v1/usage" \
  -H "Authorization: Bearer $CNPJIA_KEY"
```

## Próximos passos

- Precisa de listas de empresas por filtro? [Busca de empresas](https://cnpj.ia.br/docs/busca-empresas), disponível a partir do plano Starter.
- Vai usar com um agente? O [servidor MCP](https://cnpj.ia.br/docs/mcp) usa a mesma chave.
- Quer entender a cobrança antes de escalar? [Créditos, franquia e rate limit](https://cnpj.ia.br/docs/creditos-e-limites).

## Perguntas frequentes

**Preciso de cartão de crédito para criar a chave?**

Não. O plano Free é criado só com e-mail e senha, ou com GitHub ou Google. Dados fiscais e forma de pagamento só entram quando você assina um plano pago; pacotes avulsos são para assinantes.

**Por que a chave começa com menos créditos do que o plano Free anuncia?**

A chave nasce com um saldo de ativação para a primeira chamada funcionar antes de você verificar o e-mail. A verificação libera a franquia mensal inteira do Free. Os dois números estão em `/precos` e em `GET /v1/usage`.

**Posso usar a chave no frontend do meu site?**

Não. A chave identifica a sua conta e gasta os seus créditos; num frontend qualquer visitante a copia. Chame a API do seu backend, de uma função serverless ou de um fluxo n8n. Os únicos endpoints sem chave são `GET /v1/status` e `GET /v1/demo`, e só eles aceitam CORS.

**O CNPJ precisa ir formatado?**

Não. A API aceita `00000000000191` e `00.000.000/0001-91` e normaliza antes de consultar. Formato ou dígito verificador inválido devolve `400 invalid_cnpj`, sem custo.

**A primeira consulta funciona com qualquer CNPJ?**

Sim, com qualquer CNPJ registrado na Receita Federal. Os exemplos das docs usam instituições públicas, como o Banco do Brasil, porque o contato institucional delas é público por lei. Para testar sem chave, `GET /v1/demo?cnpj=` serve uma lista fixa de CNPJs públicos.