cnpj.ia.br
docs · base agosto/2026Atualizado em

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

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 
curl "https://api.cnpj.ia.br/v1/cnpjs/00000000000191?profile=full" \
  -H "Authorization: Bearer $CNPJIA_KEY"
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 
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
$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 
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 
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 
{
  "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 e todos os campos em Campos da resposta.

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 
curl "https://api.cnpj.ia.br/v1/usage" \
  -H "Authorization: Bearer $CNPJIA_KEY"

Próximos passos

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.