API de consulta de CNPJ

Dados oficiais da Receita Federal do Brasil em JSON: cadastro completo, busca por nome, raiz e sócio, enriquecimento em massa e demonstrações financeiras de companhias abertas. Uma requisição, uma resposta.

REST · JSON · UTF-8 v1.0.0 Atualização mensal CNPJ alfanumérico 2026 1.500 consultas/mês grátis

Visão geral

A API da CNPGolden é REST, responde em JSON codificado em UTF-8 e usa os códigos de status HTTP convencionais. Todos os endpoints ficam sob uma única URL base:

https://api.cnpgolden.com.br/api/v1

O que dá para fazer

  • Consultar um CNPJ e receber razão social, situação cadastral, endereço, contato, CNAEs, regime tributário e quadro societário numa só chamada.
  • Buscar empresas por razão social, por raiz de CNPJ (matriz e filiais) ou pelo nome de um sócio.
  • Enriquecer bases com até 1.000 CNPJs por requisição.
  • Ler balanços de companhias abertas brasileiras (DRE, balanço patrimonial, fluxo de caixa), a partir dos dados públicos da CVM.

Versionamento

A versão faz parte do caminho (/api/v1). Campos novos podem ser adicionados às respostas a qualquer momento — trate isso como uma mudança compatível e não quebre seu parser com campos desconhecidos. Remoções ou renomeações só aconteceriam em uma /api/v2.

Rotas legadas. As URLs www.cnpgolden.com.br/api/cnpj/<cnpj>, /api/search/by-name e /api/search/bulk estão descontinuadas: hoje elas exigem X-API-Key, respondem com o header Deprecation: true e serão removidas. Migre para https://api.cnpgolden.com.br/api/v1.

Início rápido

Da conta à primeira resposta em três passos.

1. Crie uma conta gratuita

A conta é gratuita e, com o e-mail confirmado, recebe 70 créditos por mês. Criar conta.

2. Gere sua chave

Em Minha conta → API, crie uma chave. Ela começa com cnpg_live_ e é exibida uma única vez — guarde em uma variável de ambiente, nunca no código versionado.

3. Faça a primeira consulta

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Sem chave nenhuma, GET /cnpj ainda responde — limitado a 10 consultas por IP por dia. Dá para testar a integração antes de criar a conta.

Autenticação

Envie sua chave no header X-API-Key em toda requisição. Não há OAuth, nem Authorization: Bearer, nem chave por query string.

X-API-Key: cnpg_live_SUA_CHAVE_AQUI

Gerenciando chaves

  • Até 5 chaves ativas por conta — use chaves separadas por ambiente ou por serviço.
  • A chave completa aparece uma única vez, na criação. Depois só o prefixo fica visível.
  • Revogar é imediato: a chave revogada passa a responder 401 na requisição seguinte.
  • Guardamos apenas o hash SHA-256 da chave — nem nós conseguimos recuperá-la. Perdeu, gere outra.

Se estiver recebendo 429 sem explicação, confira o prefixo da chave. Uma chave malformada que não comece com cnpg_live_ não gera 401: a requisição cai no caminho anônimo e passa a valer o limite por IP (10/dia). O 401 só aparece quando a chave tem o prefixo correto mas é desconhecida ou foi revogada.

Nunca use a chave no navegador do usuário final. Ela gasta os seus créditos. Chame a API do seu servidor. (O console desta página é uma exceção consciente: a chave que você digita ali fica no seu navegador e vai direto para a API — não passa pelo nosso servidor nem é armazenada.)

Créditos, limites e cobrança

Cada chamada gasta créditos do seu saldo, com o custo fixo da tabela abaixo (lida ao vivo da configuração pública). A conta grátis recebe 70 créditos por mês com o e-mail confirmado; para mais, assine um pacote ou compre créditos avulsos.

Como o consumo é debitado

  1. Primeiro saem os créditos que vencem antes (os do mês, grátis ou da assinatura).
  2. Depois, os avulsos, que não vencem.
  3. Sem saldo, a API responde 402 com custo, saldo e faltam.

Há também um limite de chamadas por minuto: 10 na conta grátis e o do degrau na assinatura. Acima dele a API responde 429 com Retry-After.

AçãoCusto
Balanços pela API
Consulta de demonstrações financeiras (CVM) com chave de API.
1 crédito por consulta
Busca pela API
Busca por nome, raiz ou sócio com chave de API, por resultado devolvido.
1 crédito a cada 10 resultados
Consulta de CNPJ pela API
Uma consulta completa de CNPJ com chave de API.
1 crédito por consulta
Consulta em lote pela API
POST /search/bulk, por CNPJ enviado.
1 crédito a cada 100 CNPJs

Números de GET /config/publica — ver preços dos créditos.

Erros

Todos os erros usam o mesmo envelope: success: false, um error curto e legível por máquina e uma message em português para humanos.

StatusQuando aconteceO que fazer
400Parâmetro ausente, mal formatado ou fora dos limitesCorrigir a requisição; repetir não adianta
401Chave cnpg_live_ desconhecida ou revogadaConferir a chave; gerar outra se necessário
402Saldo de créditos não cobre a chamadaLer faltam na resposta e comprar créditos (só o que falta, se quiser)
403Recurso que exige conta, chamado sem chaveCriar uma conta grátis e usar a chave
404Registro inexistente na baseNão repetir — o CNPJ não existe no cadastro
429Limite de chamadas por minuto, ou cota anônima por IP (sem chave)Esperar o Retry-After e repetir com backoff
500Falha internaRepetir com backoff exponencial

Corpos de resposta reais

{
  "error": "Missing parameter",
  "message": "Parâmetro cnpj é obrigatório",
  "success": false
}
{
  "error": "Invalid CNPJ",
  "message": "CNPJ deve ter 14 caracteres alfanuméricos",
  "success": false
}
{
  "error": "Invalid parameter",
  "message": "Os parâmetros page e per_page devem ser numéricos",
  "success": false
}
{
  "error": "Invalid raiz",
  "message": "A raiz deve ter exatamente 8 caracteres alfanuméricos",
  "success": false
}
{
  "error": "Missing file",
  "message": "Arquivo TXT é obrigatório",
  "success": false
}
{
  "error": "Too many CNPJs",
  "message": "Máximo de 1000 CNPJs por consulta",
  "success": false
}
{
  "error": "Unauthorized",
  "message": "Chave de API inválida ou revogada",
  "success": false
}
{
  "acao": "api_busca",
  "custo": 3,
  "email_confirmado": true,
  "error": "Payment Required",
  "faltam": 2,
  "message": "Seus créditos não cobrem esta consulta (custa 3, saldo 1). Compre créditos em conta.cnpgolden.com.br.",
  "saldo": 1,
  "success": false
}
{
  "error": "Forbidden",
  "feature": "bulk",
  "message": "Consulta em massa (bulk) exige uma conta. Crie a sua em cnpgolden.com.br/conta/cadastrar",
  "success": false
}
{
  "error": "Too Many Requests",
  "message": "Muitas chamadas por minuto. Espere alguns segundos e tente de novo.",
  "success": false
}
{
  "error": "Too Many Requests",
  "message": "Quota gratuita diária de 10 consultas por IP atingida. Crie uma conta para continuar.",
  "success": false
}
{
  "error": "Not found",
  "message": "CNPJ não encontrado",
  "success": false
}
{
  "found": false
}
{
  "error": "Not found",
  "message": "Município não encontrado.",
  "success": false
}
{
  "error": "ranking_nao_gerado",
  "message": "O ranking por município ainda não foi gerado.",
  "success": false
}
{
  "error": "Internal server error",
  "message": "Erro interno do servidor",
  "success": false
}

O 402 traz um caminho de saída legível por máquina: os campos custo, saldo e faltam permitem montar na sua aplicação o aviso "faltam N créditos".

Paginação e limites

Os endpoints de busca aceitam per_page, limitado a 100 — valores maiores são reduzidos silenciosamente. Use has_more para saber se existem mais resultados.

O parâmetro page não funciona em todos os endpoints. Ele pagina de verdade em /search/by-socio, /search/socio/empresas e /cvm/empresas. Em /search/by-name e /search/by-raiz ele é aceito e devolvido na resposta, mas não altera o resultado — a consulta aplica LIMIT sem OFFSET. Nesses dois, trabalhe com per_page até 100 e refine o termo de busca.

Contagens

Em /search/by-raiz, total_available é a contagem real de estabelecimentos da raiz. Já em /search/by-name, tanto total quanto total_available refletem apenas o lote devolvido, não o total de correspondências na base.

Acompanhamento do saldo

A API não retorna headers X-RateLimit-*. Para acompanhar saldo, extrato e vencimentos, use Minha conta → Créditos. Trate o 402 como "sem saldo" e o 429 como limite por minuto.

Outros tetos

  • /search/bulk: 1.000 CNPJs por arquivo.
  • /search/by-socio: 5.000 registros candidatos antes do agrupamento — quando o teto é atingido, a resposta traz truncated: true.
  • /cvm/comparar: 5 companhias por chamada.
  • /cvm/empresas: página fixa de 50 itens.
  • CNAEs secundários em GET /cnpj: os 5 primeiros.

Formato do CNPJ

O CNPJ tem 14 caracteres: raiz (8) + estabelecimento (4) + dígito verificador (2). O estabelecimento 0001 identifica a matriz; qualquer outro é filial.

Nunca limpe um CNPJ com um filtro de apenas-dígitos. Desde a mudança de 2026 da Receita Federal, as 12 primeiras posições aceitam letras (0-9A-Z) e só os 2 dígitos verificadores continuam numéricos. Um replace(/\D/g, '') transformaria 12ABC34501DE35 em 1234501, e a consulta falharia. Remova apenas pontuação e converta para maiúsculas.

A API aceita qualquer máscara — 00.000.000/0001-91 e 00000000000191 são equivalentes. Letras minúsculas são convertidas automaticamente.

Dígito verificador

A API não valida o dígito verificador: ela confere apenas o formato e consulta a base. Um CNPJ bem formado mas inexistente retorna 404, e não 400. Para validar o DV antes de gastar créditos, use o validador gratuito ou o endpoint /cnpj-alfa/validar.

Testar agora

Dispare uma requisição real e veja a resposta. Sua chave fica apenas neste navegador e vai direto para api.cnpgolden.com.br — não passa pelo nosso servidor web nem é armazenada.

Só endpoints GET aparecem aqui. Para POST /search/bulk, copie o exemplo de cURL da seção do endpoint.

CNPJ

Consulta e busca no cadastro de empresas da Receita Federal (base completa de CNPJs, estabelecimentos e quadro societário).

GET /cnpj

Consultar um CNPJ

Retorna o cadastro completo de um estabelecimento: razão social, nome fantasia, situação cadastral, endereço, contato, CNAEs, regime tributário (Simples/MEI) e quadro societário — tudo em uma única requisição.

1 crédito por consulta Funciona sem chave (10/IP/dia)

Parâmetros

NomeEmTipoPadrãoDescrição
cnpj
obrigatório
query string — CNPJ com 14 caracteres. Aceita qualquer máscara — pontuação é removida e letras são convertidas para maiúsculas antes da consulta.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=00000000000191", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "data": {
    "cnpj_completo": "00000000000191",
    "cnpj_basico": "00000000",
    "cnpj_estabelecimento": "0001",
    "digito_verificador": "91",
    "identificador_matriz_filial": "1",
    "tipo_estabelecimento": "MATRIZ",
    "estabelecimentos_raiz": 5445,
    "estabelecimentos_raiz_ativos": 5402,
    "razao_social": "BANCO DO BRASIL SA",
    "nome_fantasia": "DIRECAO GERAL",
    "situacao": "02",
    "data_situacao": "20051103",
    "data_abertura": "19660801",
    "porte": "05",
    "codigo_natureza_juridica": "2038",
    "capital_social": 120000000000.0,
    "natureza_juridica": "SOCIEDADE DE ECONOMIA MISTA",
    "tipo_logradouro": "QUADRA",
    "logradouro": "SAUN QUADRA 5 LOTE B TORRES I, II E III",
    "numero": "SN",
    "complemento": "ANDAR 1 A 16 TORRE I,II,III",
    "bairro": "ASA NORTE",
    "municipio": "BRASILIA",
    "codigo_municipio": "9701",
    "uf": "DF",
    "cep": "70040912",
    "codigo_pais": "",
    "ddd1": "61",
    "telefone1": "34939002",
    "email": "[email protected]",
    "cnae_principal": "6422100",
    "atividade_principal": "Bancos multiplos, com carteira comercial",
    "cnaes_secundarias": [
      {
        "codigo": "6421200",
        "descricao": "Bancos comerciais"
      },
      {
        "codigo": "6499999",
        "descricao": "Outras atividades de servicos financeiros"
      }
    ],
    "optante_simples": "N",
    "data_opcao_simples": null,
    "optante_mei": "N",
    "data_opcao_mei": null,
    "socios": [
      {
        "nome_socio": "NOME DO ADMINISTRADOR",
        "faixa_etaria": "51 a 60 anos",
        "qualificacao": "Diretor",
        "cpf_cnpj_socio": "***456789**",
        "tipo_socio": 2,
        "cod_pais": null
      }
    ]
  },
  "timestamp": "2026-08-28T14:03:11.482913"
}

Erros possíveis

StatusSituação
400Parâmetro obrigatório ausente
400CNPJ com formato inválido
404Não encontrado
429Quota gratuita por IP atingida
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Único endpoint que responde sem chave de API, limitado a 10 consultas por IP por dia. Com chave, cada consulta gasta créditos do seu saldo.
  • Os campos situacao e porte vêm como código bruto da Receita (ex.: "02", "05") e as datas como AAAAMMDD. Os endpoints de busca devolvem esses mesmos campos já formatados — a diferença é intencional e está documentada em cada um.
  • cnaes_secundarias é truncado nos 5 primeiros códigos.
  • Não há validação de dígito verificador: um CNPJ bem formado mas inexistente retorna 404, não 400.
  • Todo campo textual ausente volta como string vazia (""), nunca null; capital_social ausente volta como 0.
  • tipo_estabelecimento (MATRIZ/FILIAL) vem do campo identificador_matriz_filial da Receita (1 = matriz, 2 = filial). Não deduza a matriz pelo sufixo 0001: empresa que muda de sede rebaixa o 0001 original a filial e promove outro estabelecimento a matriz.
  • estabelecimentos_raiz e estabelecimentos_raiz_ativos contam todos os estabelecimentos da mesma raiz (8 primeiros caracteres), inclusive o consultado. São recalculados a cada carga da base; para listá-los, use GET /search/by-raiz.
GET /search/by-name

Buscar empresas por razão social

Busca estabelecimentos cuja razão social contenha o termo informado (correspondência parcial, sem distinção de maiúsculas).

1 crédito a cada 10 resultados

Parâmetros

NomeEmTipoPadrãoDescrição
nome
obrigatório
query string — Termo de busca. Mínimo 3 e máximo 200 caracteres. Os caracteres %, _ e \ são escapados.
apenas_ativas
opcional
query boolean true Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page
opcional
query integer 1 Aceito e ecoado na resposta, mas SEM EFEITO neste endpoint — a consulta usa LIMIT sem OFFSET. Use per_page para ampliar o resultado (máx. 100). Ver a seção Paginação.
per_page
opcional
query integer 100 Itens por página. Limitado a 100 — valores maiores são reduzidos.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/search/by-name?nome=MAGAZINE+LUIZA&per_page=20"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/search/by-name?nome=MAGAZINE+LUIZA&per_page=20",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/search/by-name?nome=MAGAZINE+LUIZA&per_page=20", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/search/by-name?nome=MAGAZINE+LUIZA&per_page=20");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/search/by-name?nome=MAGAZINE+LUIZA&per_page=20", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "cnpj": "60746948000112",
      "cnpj_formatado": "60.746.948/0001-12",
      "razao_social": "BANCO BRADESCO S.A.",
      "nome_fantasia": "BRADESCO",
      "situacao": "02",
      "data_situacao": "03/11/2005",
      "uf": "SP",
      "municipio": "OSASCO",
      "porte": "GRANDE",
      "tipo_estabelecimento": "MATRIZ",
      "cnae_principal": "6422100",
      "cnae_descricao": "Bancos multiplos, com carteira comercial",
      "data_abertura": "10/09/1943"
    }
  ],
  "total": 1,
  "total_available": 1,
  "has_more": true,
  "apenas_ativas": true,
  "page": 1,
  "per_page": 1,
  "timestamp": "2026-08-28T14:03:11.482913"
}

Erros possíveis

StatusSituação
400Parâmetro inválido
400Parâmetro obrigatório ausente
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • page não pagina aqui (ver seção Paginação). Use per_page até 100.
  • total e total_available são iguais a len(data) — refletem o lote devolvido, não a contagem total de correspondências na base. Para saber se há mais resultados, use has_more.
  • per_page na resposta é a quantidade efetivamente devolvida, que pode ser menor que a solicitada.
  • Aqui porte vem por extenso (MICRO, PEQUENO, GRANDE, NÃO INFORMADO) e as datas em DD/MM/AAAA — diferente de GET /cnpj.
GET /search/by-raiz

Listar estabelecimentos de uma raiz de CNPJ

Retorna matriz e filiais que compartilham a mesma raiz de 8 caracteres — a forma de mapear toda a rede de um grupo empresarial.

1 crédito a cada 10 resultados

Parâmetros

NomeEmTipoPadrãoDescrição
raiz
obrigatório
query string — Raiz do CNPJ: exatamente 8 caracteres alfanuméricos. Um CNPJ completo de 14 caracteres é rejeitado — envie apenas os 8 primeiros.
apenas_ativas
opcional
query boolean false Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page
opcional
query integer 1 Aceito e ecoado na resposta, mas SEM EFEITO neste endpoint — a consulta usa LIMIT sem OFFSET. Use per_page para ampliar o resultado (máx. 100). Ver a seção Paginação.
per_page
opcional
query integer 100 Itens por página. Limitado a 100 — valores maiores são reduzidos.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/search/by-raiz?raiz=60746948"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/search/by-raiz?raiz=60746948",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/search/by-raiz?raiz=60746948", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/search/by-raiz?raiz=60746948");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/search/by-raiz?raiz=60746948", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "cnpj": "60746948000112",
      "cnpj_formatado": "60.746.948/0001-12",
      "razao_social": "BANCO BRADESCO S.A.",
      "nome_fantasia": "BRADESCO",
      "situacao": "02",
      "data_situacao": "03/11/2005",
      "uf": "SP",
      "municipio": "OSASCO",
      "porte": "GRANDE",
      "tipo_estabelecimento": "MATRIZ",
      "cnae_principal": "6422100",
      "cnae_descricao": "Bancos multiplos, com carteira comercial",
      "data_abertura": "10/09/1943"
    }
  ],
  "total": 1,
  "total_available": 4821,
  "has_more": true,
  "apenas_ativas": false,
  "page": 1,
  "per_page": 1,
  "raiz": "60746948",
  "timestamp": "2026-08-28T14:03:11.482913"
}

Erros possíveis

StatusSituação
400Raiz inválida
400Parâmetro inválido
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • page não pagina aqui (ver seção Paginação).
  • Diferente de by-name, aqui total_available é a contagem real de estabelecimentos da raiz.
  • has_more compara com o valor fixo 100, não com o per_page enviado.
GET /search/by-socio

Buscar sócios por nome

Localiza pessoas físicas ou jurídicas no quadro societário e informa em quantas empresas cada uma aparece. Use o par nome + doc do resultado para abrir a lista de empresas em /search/socio/empresas.

1 crédito a cada 10 resultados

Parâmetros

NomeEmTipoPadrãoDescrição
nome
obrigatório
query string — Nome do sócio. Mínimo 3 e máximo 200 caracteres. Espaços viram curingas: Maria Silva busca %MARIA%SILVA%.
apenas_ativas
opcional
query boolean false Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page
opcional
query integer 1 Página dos resultados. Aplicada via OFFSET neste endpoint.
per_page
opcional
query integer 100 Itens por página. Limitado a 100 — valores maiores são reduzidos.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/search/by-socio?nome=MARIA+DA+SILVA"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/search/by-socio?nome=MARIA+DA+SILVA",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/search/by-socio?nome=MARIA+DA+SILVA", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/search/by-socio?nome=MARIA+DA+SILVA");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/search/by-socio?nome=MARIA+DA+SILVA", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "nome": "MARIA DA SILVA",
      "doc": "***456789**",
      "doc_display": "***4567****",
      "tipo_socio": 2,
      "tipo_socio_desc": "PF",
      "cod_pais": null,
      "num_empresas": 7
    }
  ],
  "total": 1,
  "has_more": false,
  "truncated": false,
  "apenas_ativas": false,
  "page": 1,
  "per_page": 100,
  "timestamp": "2026-08-28T14:03:11.482913"
}

Erros possíveis

StatusSituação
400Parâmetro inválido
400Parâmetro obrigatório ausente
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Este endpoint pagina de verdade — page aplica OFFSET.
  • O conjunto de candidatos é limitado a 5.000 registros antes do agrupamento; quando esse teto é atingido a resposta traz truncated: true. Refine o nome para reduzir o conjunto.
  • Proteção de dados: para pessoa física (tipo_socio: 2), doc_display vem mascarado como ***4567****. O campo doc mantém os dígitos mascarados publicados pela Receita e é o que deve ser reenviado no drill-down.
GET /search/socio/empresas

Listar empresas de um sócio

Detalha as empresas ligadas a um sócio específico. Os valores de nome e doc devem vir exatamente como retornados por /search/by-socio — a correspondência é exata.

1 crédito a cada 10 resultados

Parâmetros

NomeEmTipoPadrãoDescrição
nome
obrigatório
query string — Nome exato do sócio (máx. 250 caracteres).
doc
opcional
query string "" Documento mascarado, exatamente como veio no campo doc de /search/by-socio (máx. 20 caracteres).
cod_pais
opcional
query integer — Código do país para desambiguar sócios estrangeiros. Precisa ser numérico.
apenas_ativas
opcional
query boolean false Quando verdadeiro, retorna apenas estabelecimentos com situação cadastral ATIVA (código 02).
page
opcional
query integer 1 Página dos resultados. Aplicada via OFFSET neste endpoint.
per_page
opcional
query integer 100 Itens por página. Limitado a 100 — valores maiores são reduzidos.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/search/socio/empresas?nome=MARIA+DA+SILVA&doc=%2A%2A%2A456789%2A%2A"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/search/socio/empresas?nome=MARIA+DA+SILVA&doc=%2A%2A%2A456789%2A%2A",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/search/socio/empresas?nome=MARIA+DA+SILVA&doc=%2A%2A%2A456789%2A%2A", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/search/socio/empresas?nome=MARIA+DA+SILVA&doc=%2A%2A%2A456789%2A%2A");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/search/socio/empresas?nome=MARIA+DA+SILVA&doc=%2A%2A%2A456789%2A%2A", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "cnpj": "12345678000195",
      "cnpj_formatado": "12.345.678/0001-95",
      "razao_social": "EMPRESA EXEMPLO LTDA",
      "nome_fantasia": "EXEMPLO",
      "situacao": "02",
      "data_situacao": "15/04/2014",
      "uf": "SP",
      "municipio": "SAO PAULO",
      "porte": "PEQUENO",
      "tipo_estabelecimento": "MATRIZ",
      "cnae_principal": "6201501",
      "cnae_descricao": "Desenvolvimento de programas de computador sob encomenda",
      "qualificacao_socio": "Sócio-Administrador"
    }
  ],
  "total": 1,
  "has_more": false,
  "apenas_ativas": false,
  "page": 1,
  "per_page": 100,
  "timestamp": "2026-08-28T14:03:11.482913"
}

Erros possíveis

StatusSituação
400Parâmetro inválido
400Parâmetro obrigatório ausente
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Este endpoint pagina de verdade — page aplica OFFSET.
  • Retorna somente matrizes; filiais são omitidas.
  • Traz qualificacao_socio (o papel da pessoa na empresa) e, ao contrário de by-name, não traz data_abertura.
POST /search/bulk

Consultar até 1.000 CNPJs de uma vez

Envie um arquivo .txt com um CNPJ por linha e receba os cadastros em uma única resposta. Ideal para enriquecer bases de clientes e fornecedores.

1 crédito a cada 100 CNPJs

Parâmetros

NomeEmTipoPadrãoDescrição
file
obrigatório
formData file — Arquivo .txt, um CNPJ por linha, no máximo 1.000 CNPJs válidos. A extensão .txt é obrigatória.

Requisição

curl -X POST \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  -F "[email protected]" \
  "https://api.cnpgolden.com.br/api/v1/search/bulk"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
with open("cnpjs.txt", "rb") as f:
    r = requests.post(
        "https://api.cnpgolden.com.br/api/v1/search/bulk",
        files={"file": f}, headers=headers,
        timeout=120,
    )

r.raise_for_status()
print(r.json())
import { createReadStream } from "node:fs";

const form = new FormData();
form.set("file", await openAsBlob("cnpjs.txt"), "cnpjs.txt");

const res = await fetch("https://api.cnpgolden.com.br/api/v1/search/bulk", {
  method: "POST",
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
  body: form,
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/search/bulk");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, ["file" => new CURLFile("cnpjs.txt")]);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	arquivo, _ := os.Open("cnpjs.txt")
	defer arquivo.Close()

	var buf bytes.Buffer
	w := multipart.NewWriter(&buf)
	parte, _ := w.CreateFormFile("file", "cnpjs.txt")
	io.Copy(parte, arquivo)
	w.Close()

	req, _ := http.NewRequest("POST", "https://api.cnpgolden.com.br/api/v1/search/bulk", &buf)
	req.Header.Set("Content-Type", w.FormDataContentType())
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	corpo, _ := io.ReadAll(res.Body)
	fmt.Println(string(corpo))
}

Resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "cnpj": "00000000000191",
      "cnpj_formatado": "00.000.000/0001-91",
      "razao_social": "BANCO DO BRASIL SA",
      "nome_fantasia": "DIRECAO GERAL",
      "situacao": "02",
      "data_abertura": "19660801",
      "logradouro": "SAUN QUADRA 5 LOTE B TORRES I, II E III",
      "numero": "SN",
      "complemento": "ANDAR 1 A 16 TORRE I,II,III",
      "bairro": "ASA NORTE",
      "municipio": "BRASILIA",
      "uf": "DF",
      "cep": "70040912",
      "telefone": "(61) 3493-9002",
      "email": "[email protected]",
      "atividade_principal": "Bancos multiplos, com carteira comercial",
      "optante_simples": "N",
      "found": true
    },
    {
      "cnpj": "99999999999999",
      "cnpj_formatado": "99.999.999/9999-99",
      "found": false,
      "error": "CNPJ não encontrado"
    }
  ],
  "total": 2,
  "found": 1,
  "not_found": 1,
  "timestamp": "2026-08-28T14:03:11.482913"
}

Erros possíveis

StatusSituação
400Arquivo ausente ou inválido
400Lote acima do limite
403Recurso exige conta
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Custo sobre o total: o lote é cobrado em créditos pelo número de CNPJs válidos do arquivo, com a regra "1 crédito a cada N CNPJs" aplicada uma vez ao total (veja a tabela de custos).
  • Linhas que não resultem em exatamente 14 caracteres são descartadas em silêncio antes da contagem — elas não aparecem na resposta nem contam para o limite de 1.000.
  • Cada item traz found. Quando false, vêm apenas cnpj, cnpj_formatado, found e error.
  • data_abertura volta crua (AAAAMMDD), enquanto telefone já vem formatado — ou null se o DDD/número for inválido.
  • Comparado a GET /cnpj, o bulk não devolve socios, capital_social, porte, natureza_juridica, cnae_principal, codigo_municipio, tipo_logradouro nem os campos de MEI.
GET /municipios

Listar municípios com empresa ativa

Devolve todos os municípios do país que têm estabelecimento na base, com o código da Receita, a UF e o identificador usado nas demais rotas de município. A resposta é estável e cacheável por um dia — baixe uma vez e filtre do seu lado.

Sem chave

Requisição

curl \
  "https://api.cnpgolden.com.br/api/v1/municipios"
import requests

r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/municipios",
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/municipios");

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/municipios");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/municipios", nil)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "data": [
    {
      "codmun": "7107",
      "nome": "SAO PAULO",
      "uf": "SP",
      "slug": "sao-paulo-sp",
      "total_ativas": 2498311
    }
  ],
  "total": 5570,
  "gerado_em": "2026-10-24T03:12:44+00:00",
  "referencia_rfb": "2026-10-01",
  "timestamp": "2026-10-24T14:03:11.482913+00:00"
}

Erros possíveis

StatusSituação
503Ranking ainda não publicado
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • codmun é o código de município da Receita Federal, não o do IBGE.
  • slug é estável: uma vez publicado, não muda em recargas posteriores.
  • Depende da carga do ranking por município; antes dela a rota responde 503.
GET /municipios/{municipio}/empresas

Maiores empresas de um município

Ranking das maiores empresas de grande porte do município, por um índice que pesa 70% o número de estabelecimentos ativos no Brasil inteiro e 30% o capital social, ambos em escala logarítmica. O agrupamento é por raiz de CNPJ: matriz e filiais contam como uma empresa só. Há duas visões: visao=matriz lista só as empresas sediadas na cidade (matriz ativa lá); visao=presenca lista toda empresa com ao menos uma unidade ativa na cidade, mesmo com a matriz em outro município — e aí matriz_na_cidade vem false e matriz_municipio diz onde ela fica. Empresas com registro ativo na CVM vêm com capital_aberto: true.

1 crédito a cada 10 resultados

Parâmetros

NomeEmTipoPadrãoDescrição
municipio
obrigatório
path string — O slug ou o codmun devolvidos por GET /municipios.
visao
opcional
query string — matriz (sediadas na cidade) ou presenca (qualquer unidade ativa na cidade). Padrão: presenca.
limite
opcional
query integer — Quantas empresas devolver, de 1 a 200 (padrão 200). Valores maiores são reduzidos a 200.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/municipios/{municipio}/empresas?municipio=campinas-sp&visao=matriz"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/municipios/{municipio}/empresas?municipio=campinas-sp&visao=matriz",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/municipios/{municipio}/empresas?municipio=campinas-sp&visao=matriz", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/municipios/{municipio}/empresas?municipio=campinas-sp&visao=matriz");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/municipios/{municipio}/empresas?municipio=campinas-sp&visao=matriz", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "visao": "presenca",
  "municipio": {
    "codmun": "6001",
    "nome": "CAMPINAS",
    "uf": "SP",
    "slug": "campinas-sp",
    "total_ativas": 181402,
    "total_empresas": 154930,
    "total_matrizes": 98211
  },
  "data": [
    {
      "posicao": 1,
      "cnpj": "60746948000112",
      "cnpj_basico": "60746948",
      "razao_social": "EMPRESA EXEMPLO S.A.",
      "nome_fantasia": "EXEMPLO",
      "unidades_ativas": 1284,
      "unidades_cidade": 37,
      "capital_social": 57600000000.0,
      "porte": "05",
      "porte_descricao": "GRANDE",
      "cnae_codigo": "4711301",
      "cnae_descricao": "Comércio varejista de mercadorias em geral",
      "matriz_na_cidade": false,
      "matriz_municipio": "SAO PAULO",
      "matriz_uf": "SP",
      "indice": 81.2,
      "capital_aberto": true,
      "cd_cvm": "000001",
      "dfs_slug": "empresa-exemplo-s-a-60746948000112"
    }
  ],
  "total": 200,
  "gerado_em": "2026-10-24T03:12:44+00:00",
  "referencia_rfb": "2026-10-01",
  "timestamp": "2026-10-24T14:03:11.482913+00:00"
}

Erros possíveis

StatusSituação
400Parâmetro inválido
404Município não encontrado
503Ranking ainda não publicado
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • O teto de 200 é o tamanho do ranking materializado: não há página 2.
  • unidades_ativas conta o Brasil inteiro; unidades_cidade só o município.
  • capital_social é da empresa (raiz), em reais.
  • Só entram entidades empresariais (natureza jurídica 2xxx) de grande porte (porte 05): órgãos públicos, associações, igrejas, fundações e empresários individuais ficam fora, assim como CNPJs com remoção de dados concluída.
  • indice vai de 0 a 100: 70% ln(1+unidades)/ln(1+máximo do país) + 30% o mesmo para o capital social. Capital acima de R$ 10 bi em empresa de até 2 unidades não entra no índice (indício de erro de cadastro), mas continua em capital_social.
  • capital_aberto reflete o cadastro da CVM no momento da consulta; dfs_slug, quando presente, é o endereço da página de Balanços em /demonstracoes-financeiras/{dfs_slug}.
  • O ranking é recalculado a cada carga da Receita Federal; gerado_em diz quando foi a última vez.

Demonstrações Financeiras

Balanços de companhias abertas brasileiras a partir dos dados públicos da CVM (DFP anual e ITR trimestral). Todos os valores monetários estão em MIL R$.

GET /cvm/search

Autocompletar companhias abertas

Busca rápida por nome ou código CVM, limitada a 15 resultados. Feita para caixas de autocompletar.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
q
obrigatório
query string — Termo de busca (nome ou código CVM). Vazio devolve [].

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/search?q=banco"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/search?q=banco",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/search?q=banco", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/search?q=banco");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/search?q=banco", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

[
  {
    "cd_cvm": "001023",
    "denom_social": "BCO BRASIL S.A.",
    "cnpj": "00.000.000/0001-91",
    "setor": "Bancos"
  }
]

Erros possíveis

StatusSituação
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Responde um array puro, sem o envelope {success, data} usado nos endpoints de CNPJ.
  • Só retorna companhias que já possuem KPIs carregados.
GET /cvm/by-cnpj/{cnpj}

Descobrir o código CVM a partir do CNPJ

Ponte entre os dois domínios: informe um CNPJ e descubra se aquela empresa tem demonstrações financeiras publicadas, recebendo o cd_cvm para as demais chamadas.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
cnpj
obrigatório
path string — CNPJ completo (14) ou apenas a raiz (8). A pontuação é ignorada nos dois lados da comparação.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/by-cnpj/00000000000191"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/by-cnpj/00000000000191",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/by-cnpj/00000000000191", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/by-cnpj/00000000000191");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/by-cnpj/00000000000191", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "found": true,
  "cd_cvm": "001023",
  "denom_social": "BCO BRASIL S.A.",
  "cnpj": "00.000.000/0001-91"
}

Erros possíveis

StatusSituação
404Companhia não encontrada
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Quando não há correspondência, devolve {"found": false} com status 404.
GET /cvm/ranking

Ranking das 24 companhias mais lucrativas

Top 24 por lucro líquido no exercício anual mais recente, acompanhado de estatísticas agregadas do mercado.

1 crédito por consulta

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/ranking"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/ranking",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/ranking", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/ranking");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/ranking", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "ano_atual": 2025,
  "empresas": [
    {
      "cd_cvm": "001023",
      "denom_social": "BCO BRASIL S.A.",
      "cnpj": "00.000.000/0001-91",
      "setor": "Bancos",
      "situacao": "ATIVO",
      "lucro_liquido": 35600000,
      "receita_liquida": 164200000,
      "ano": 2025,
      "dt_refer": "2025-12-31",
      "origem": "DFP"
    }
  ],
  "stats": {
    "ano": 2025,
    "empresas_total": 712,
    "empresas_ativas": 655,
    "lucro_total": 512000000,
    "receita_total": 4870000000,
    "ativo_total": 41200000000,
    "top_setor": "Bancos",
    "top_setor_n": 48
  }
}

Erros possíveis

StatusSituação
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Valores em MIL R$. O ano é escolhido automaticamente (exercício anual mais recente com KPIs carregados).
GET /cvm/empresa/{cd_cvm}

Demonstrações completas de uma companhia

Retorna cadastro, períodos disponíveis, indicadores do período e do anterior, e todos os quadros já preenchidos (DRE, BPA, BPP, DFC, DVA, DMPL, DRA) em uma só chamada.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
cd_cvm
obrigatório
path string — Código CVM de 6 dígitos. Valores mais curtos são completados com zeros à esquerda.
origem
opcional
query string DFP DFP para o anual, ITR para o trimestral. Se não houver dados na origem pedida, a API tenta a outra automaticamente e informa qual usou no campo origem da resposta.
ano
opcional
query integer — Ano do exercício. Padrão: o mais recente disponível.
dt_refer
opcional
query string — Data de referência (AAAA-MM-DD). Ignorada se não estiver na lista dts.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023?origem=DFP"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023?origem=DFP",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023?origem=DFP", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023?origem=DFP");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023?origem=DFP", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "found": true,
  "empresa": {
    "cd_cvm": "001023",
    "cnpj": "00.000.000/0001-91",
    "denom_social": "BCO BRASIL S.A.",
    "denom_comerc": "BANCO DO BRASIL",
    "situacao": "ATIVO",
    "setor": "Bancos",
    "auditor": "KPMG AUDITORES INDEPENDENTES",
    "cnpj_auditor": "57.755.217/0001-29",
    "uf": "DF",
    "municipio": "BRASILIA"
  },
  "origem": "DFP",
  "ano": 2025,
  "anos": [
    2025,
    2024,
    2023
  ],
  "dt_refer": "2025-12-31",
  "dts": [
    "2025-12-31"
  ],
  "quadros": [
    "DRE",
    "BPA",
    "BPP",
    "DFC_MI",
    "DVA"
  ],
  "quadros_data": {
    "DRE": [
      {
        "cd_conta": "3.01",
        "ds_conta": "Receita de Venda de Bens e/ou Serviços",
        "ind_ultimo": 164200000,
        "ind_penultimo": 151900000,
        "con_ultimo": 168400000,
        "con_penultimo": 154300000,
        "dt_fim_ultimo": "2025-12-31",
        "dt_ini_ultimo": "2025-01-01",
        "dt_fim_penultimo": "2024-12-31",
        "dt_ini_penultimo": "2024-01-01",
        "nivel": 1,
        "var_ind": 8.09,
        "var_con": 9.13
      }
    ]
  },
  "indic": {
    "receita_liquida": 164200000,
    "lucro_liquido": 35600000,
    "margem_liquida": 21.68,
    "ativo_total": 2280000000
  },
  "indic_ant": {
    "receita_liquida": 151900000,
    "lucro_liquido": 33100000,
    "margem_liquida": 21.79,
    "ativo_total": 2120000000
  }
}

Erros possíveis

StatusSituação
404Companhia não encontrada
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Resposta pesada: quadros_data traz todas as linhas de todos os quadros. Para um quadro só, use /cvm/empresa/{cd_cvm}/quadro/{quadro}.
  • Cada linha tem ind_* (individual) e con_* (consolidado), nos exercícios ultimo e penultimo, com var_ind/var_con em % — null quando o período anterior é zero ou ausente.
  • nivel é a profundidade da conta no plano de contas, derivada da quantidade de pontos em cd_conta (3.01 → nível 1).
GET /cvm/empresa/{cd_cvm}/quadro/{quadro}

Um único quadro contábil

Versão enxuta do endpoint anterior: devolve apenas as linhas do quadro pedido.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
cd_cvm
obrigatório
path string — Código CVM de 6 dígitos.
quadro
obrigatório
path string — DRE (resultado), BPA (ativo), BPP (passivo), DFC_MI/DFC_MD (fluxo de caixa), DVA (valor adicionado), DMPL (mutações do PL), DRA (resultado abrangente).
origem
opcional
query string DFP Origem dos dados.
ano
obrigatório
query integer — Ano do exercício. Obrigatório.
dt_refer
obrigatório
query string — Data de referência AAAA-MM-DD. Obrigatório.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023/quadro/DRE?ano=2025&dt_refer=2025-12-31"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023/quadro/DRE?ano=2025&dt_refer=2025-12-31",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023/quadro/DRE?ano=2025&dt_refer=2025-12-31", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023/quadro/DRE?ano=2025&dt_refer=2025-12-31");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/empresa/001023/quadro/DRE?ano=2025&dt_refer=2025-12-31", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

[
  {
    "cd_conta": "3.01",
    "ds_conta": "Receita de Venda de Bens e/ou Serviços",
    "ind_ultimo": 164200000,
    "ind_penultimo": 151900000,
    "con_ultimo": 168400000,
    "con_penultimo": 154300000,
    "dt_fim_ultimo": "2025-12-31",
    "dt_ini_ultimo": "2025-01-01",
    "dt_fim_penultimo": "2024-12-31",
    "dt_ini_penultimo": "2024-01-01",
    "nivel": 1,
    "var_ind": 8.09,
    "var_con": 9.13
  }
]

Erros possíveis

StatusSituação
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Responde um array puro.
  • Sem ano e dt_refer retorna 400 {"error": "ano e dt_refer obrigatórios"}. Obtenha os valores válidos nos campos anos/dts de /cvm/empresa/{cd_cvm}.
GET /cvm/comparar

Comparar até 5 companhias

Série histórica de indicadores lado a lado, já acompanhada dos rótulos e da configuração de gráficos usada pelo site.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
empresas
obrigatório
query string — Códigos CVM separados por vírgula. Do 6º em diante são ignorados.
origem
opcional
query string DFP Origem dos dados.
natureza
opcional
query string con con para consolidado, ind para individual.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/comparar?empresas=001023%2C906&natureza=con"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/comparar?empresas=001023%2C906&natureza=con",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/comparar?empresas=001023%2C906&natureza=con", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/comparar?empresas=001023%2C906&natureza=con");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/comparar?empresas=001023%2C906&natureza=con", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "origem": "DFP",
  "natureza": "con",
  "dados": [
    {
      "empresa": {
        "cd_cvm": "001023",
        "cnpj": "00.000.000/0001-91",
        "denom_social": "BCO BRASIL S.A.",
        "denom_comerc": "BANCO DO BRASIL",
        "situacao": "ATIVO",
        "setor": "Bancos",
        "auditor": "KPMG AUDITORES INDEPENDENTES",
        "cnpj_auditor": "57.755.217/0001-29",
        "uf": "DF",
        "municipio": "BRASILIA"
      },
      "serie": [
        {
          "ano": 2025,
          "dt_refer": "2025-12-31",
          "receita_liquida": 164200000,
          "lucro_liquido": 35600000,
          "margem_liquida": 21.68
        }
      ]
    }
  ],
  "labels": {
    "receita_liquida": "Receita líquida",
    "lucro_liquido": "Lucro líquido"
  },
  "monetarios": [
    "receita_liquida",
    "lucro_liquido",
    "ativo_total"
  ],
  "charts": [
    "receita_liquida",
    "lucro_liquido",
    "margem_liquida"
  ]
}

Erros possíveis

StatusSituação
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Códigos CVM inexistentes são silenciosamente omitidos de dados — compare o tamanho do array com o que você enviou.
GET /cvm/empresas

Listar e filtrar companhias abertas

Catálogo paginado com filtros por setor, UF e município, ordenável por qualquer indicador. Retorna também as facetas para montar filtros na sua interface.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
page
opcional
query integer 1 Página. Pagina de verdade (OFFSET).
q
opcional
query string — Termo livre (nome ou CNPJ).
setor
opcional
query string — Setor exato, como listado em facets.setores.
uf
opcional
query string — UF de 2 letras.
municipio
opcional
query string — Município exato. As opções só aparecem em facets.municipios quando uf é informada.
order_by
opcional
query string lucro_liquido Campo de ordenação. Valor inválido volta ao padrão.
order_dir
opcional
query string desc Direção da ordenação.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/empresas?setor=Bancos&order_by=lucro_liquido&order_dir=desc"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/empresas?setor=Bancos&order_by=lucro_liquido&order_dir=desc",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/empresas?setor=Bancos&order_by=lucro_liquido&order_dir=desc", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/empresas?setor=Bancos&order_by=lucro_liquido&order_dir=desc");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/empresas?setor=Bancos&order_by=lucro_liquido&order_dir=desc", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "rows": [
    {
      "cd_cvm": "001023",
      "denom_social": "BCO BRASIL S.A.",
      "cnpj": "00.000.000/0001-91",
      "setor": "Bancos",
      "situacao": "ATIVO",
      "uf": "DF",
      "municipio": "BRASILIA",
      "receita_liquida": 164200000,
      "ebitda": null,
      "lucro_liquido": 35600000,
      "ativo_total": 2280000000,
      "margem_liquida": 21.68,
      "ano": 2025,
      "origem": "DFP"
    }
  ],
  "total": 712,
  "page": 1,
  "page_size": 50,
  "pages": 15,
  "facets": {
    "ufs": [
      "AL",
      "AM",
      "BA",
      "CE",
      "DF",
      "ES",
      "GO",
      "MG",
      "PR",
      "RJ",
      "RS",
      "SC",
      "SP"
    ],
    "setores": [
      "Bancos",
      "Energia Elétrica",
      "Petróleo e Gás",
      "Varejo"
    ],
    "municipios": []
  }
}

Erros possíveis

StatusSituação
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • page_size é fixo em 50 e não pode ser alterado; use pages para saber quantas páginas existem.
GET /cvm/setores

Agregados por setor

Receita, lucro e ativo somados por setor, com drill-down opcional para as empresas de um setor.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
setor
opcional
query string — Quando informado, empresas traz as companhias desse setor. Sem ele, empresas volta vazio.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/setores?setor=Bancos"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/setores?setor=Bancos",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/setores?setor=Bancos", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/setores?setor=Bancos");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/setores?setor=Bancos", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "setores": [
    {
      "setor": "Bancos",
      "empresas": 48,
      "lucro_total": 128000000,
      "receita_total": 940000000,
      "ativo_total": 18400000000
    }
  ],
  "drill": "",
  "empresas": []
}

Erros possíveis

StatusSituação
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Companhias sem setor são agrupadas em (Não informado).
GET /cvm/auditorias

Agregados por auditoria independente

Participação de mercado das auditorias independentes: quantas companhias cada uma audita e o volume financeiro sob sua responsabilidade.

1 crédito por consulta

Parâmetros

NomeEmTipoPadrãoDescrição
auditor
opcional
query string — Quando informado, empresas traz as companhias auditadas por essa firma.

Requisição

curl \
  -H "X-API-Key: cnpg_live_SUA_CHAVE_AQUI" \
  "https://api.cnpgolden.com.br/api/v1/cvm/auditorias"
import requests

headers = {"X-API-Key": "cnpg_live_SUA_CHAVE_AQUI"}
r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/cvm/auditorias",
    headers=headers,
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/cvm/auditorias", {
  headers: { "X-API-Key": "cnpg_live_SUA_CHAVE_AQUI" },
});

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/cvm/auditorias");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: cnpg_live_SUA_CHAVE_AQUI']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/cvm/auditorias", nil)
	req.Header.Set("X-API-Key", "cnpg_live_SUA_CHAVE_AQUI")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "auditores": [
    {
      "auditor": "KPMG AUDITORES INDEPENDENTES",
      "empresas": 141,
      "n_setores": 22,
      "receita_total": 1180000000,
      "ebitda_total": 210000000,
      "lucro_total": 96000000,
      "ativo_total": 9400000000,
      "patrimonio_total": 1830000000
    }
  ],
  "ano_atual": 2025,
  "drill": "",
  "empresas": []
}

Erros possíveis

StatusSituação
401Chave inválida ou revogada
402Saldo de créditos não cobre a chamada
429Limite de chamadas por minuto
500Erro interno

Notas

  • Companhias sem auditor identificado caem em (Não informado).

Utilitários

Endpoints públicos de apoio: saúde do serviço, data da última carga da base e preços em créditos. Não exigem chave.

GET /health

Verificar disponibilidade da API

Sonda leve para monitoramento. Não exige chave e não gasta créditos.

Sem chave

Requisição

curl \
  "https://api.cnpgolden.com.br/api/v1/health"
import requests

r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/health",
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/health");

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/health");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/health", nil)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "status": "ok",
  "timestamp": "2026-08-28T14:03:11.482913",
  "version": "2.0-simplified"
}
GET /database/last-update

Data da última carga da base

Informa a data do arquivo da Receita Federal atualmente carregado. Use para decidir quando revalidar seu cache.

Sem chave

Requisição

curl \
  "https://api.cnpgolden.com.br/api/v1/database/last-update"
import requests

r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/database/last-update",
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/database/last-update");

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/database/last-update");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/database/last-update", nil)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "data": {
    "last_update": "12/08/2026",
    "last_update_raw": "20260812"
  },
  "timestamp": "2026-08-28T14:03:11.482913"
}

Erros possíveis

StatusSituação
404Não encontrado
500Erro interno

Notas

  • A Receita Federal publica a base mensalmente.
GET /config/publica

Preços e limites em créditos

Os números do modelo de créditos: o custo de cada ação, os pacotes de assinatura (créditos por mês, preço mensal e anual, limite por minuto) e as regras (créditos grátis do mês, avulso, validade). A página de preços do site lê exatamente daqui.

Sem chave

Requisição

curl \
  "https://api.cnpgolden.com.br/api/v1/config/publica"
import requests

r = requests.get(
    "https://api.cnpgolden.com.br/api/v1/config/publica",
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://api.cnpgolden.com.br/api/v1/config/publica");

console.log(await res.json());
<?php
$ch = curl_init("https://api.cnpgolden.com.br/api/v1/config/publica");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.cnpgolden.com.br/api/v1/config/publica", nil)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "success": true,
  "limites": {
    "visitante_dia": 30,
    "conta_dia": 300,
    "api_sem_chave_dia": 10
  },
  "creditos": {
    "em_vigor": true,
    "config": {
      "creditos_gratis_mes": 70,
      "desconto_anual_pct": 10,
      "avulso_minimo_reais": 9.9,
      "limite_minuto_gratis": 10
    },
    "degraus": [
      {
        "id": 1,
        "creditos_mes": 1000,
        "preco_mensal": 16.9,
        "preco_anual": 181.9,
        "limite_minuto": 60,
        "destaque": false
      }
    ],
    "custos": [
      {
        "acao": "api_consulta",
        "nome": "Consulta de CNPJ pela API",
        "creditos": 1,
        "por_unidades": 1,
        "unidade": "consulta",
        "descricao": "..."
      }
    ]
  }
}

Erros possíveis

StatusSituação
500Erro interno

Notas

  • Custo de uma ação = teto(quantidade ÷ por_unidades) × creditos.

CNPJ Alfanumérico

Gerador, validador e calculadora de dígito verificador do novo CNPJ alfanumérico (Receita Federal, vigência 2026). Gratuito e sem chave — atenção: roda em www.cnpgolden.com.br e usa um envelope de resposta diferente.

GET /cnpj-alfa/gerar

Gerar CNPJs alfanuméricos fictícios

Gera CNPJs no novo formato alfanumérico com dígito verificador correto, para testar seus sistemas antes da vigência de 2026. Os números são fictícios e não correspondem a empresas reais.

Sem chave Host: www.cnpgolden.com.br

Parâmetros

NomeEmTipoPadrãoDescrição
quantidade
opcional
query integer 1 Quantos gerar, de 1 a 100.
raiz
opcional
query string — Fixa os 8 primeiros caracteres.
estabelecimento
opcional
query string — Fixa os 4 caracteres do estabelecimento (ex.: 0001).
com_razao_social
opcional
query boolean false Quando verdadeiro, cada item vira um objeto com razão social fictícia; caso contrário cnpjs é uma lista de strings.

Requisição

curl \
  "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/gerar?quantidade=2&com_razao_social=true"
import requests

r = requests.get(
    "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/gerar?quantidade=2&com_razao_social=true",
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://www.cnpgolden.com.br/api/v1/cnpj-alfa/gerar?quantidade=2&com_razao_social=true");

console.log(await res.json());
<?php
$ch = curl_init("https://www.cnpgolden.com.br/api/v1/cnpj-alfa/gerar?quantidade=2&com_razao_social=true");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/gerar?quantidade=2&com_razao_social=true", nil)

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "sucesso": true,
  "quantidade": 2,
  "cnpjs": [
    {
      "cnpj": "12ABC34501DE35",
      "cnpj_formatado": "12.ABC.345/01DE-35",
      "razao_social": "COMERCIO EXEMPLO LTDA"
    },
    {
      "cnpj": "A1B2C3D40001F7",
      "cnpj_formatado": "A1.B2C.3D4/0001-F7",
      "razao_social": "SERVICOS MODELO ME"
    }
  ]
}

Notas

  • Servido por www.cnpgolden.com.br, não por api.cnpgolden.com.br.
  • Envelope diferente: sucesso/erro, e não success/error.
POST /cnpj-alfa/validar

Validar CNPJs alfanuméricos

Confere o dígito verificador de um ou vários CNPJs. O algoritmo é um superconjunto estrito do numérico: CNPJs antigos são validados exatamente como antes.

Sem chave Host: www.cnpgolden.com.br

Parâmetros

NomeEmTipoPadrãoDescrição
cnpj
opcional
body string — Um CNPJ. Use este ou cnpjs.
cnpjs
opcional
body array — Lista de até 100 CNPJs.

Requisição

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"cnpjs": ["12.ABC.345/01DE-35"]}' \
  "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/validar"
import requests

r = requests.post(
    "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/validar",
    json={"cnpjs": ["12.ABC.345/01DE-35"]},
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://www.cnpgolden.com.br/api/v1/cnpj-alfa/validar", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"cnpjs": ["12.ABC.345/01DE-35"]}),
});

console.log(await res.json());
<?php
$ch = curl_init("https://www.cnpgolden.com.br/api/v1/cnpj-alfa/validar");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["cnpjs" => ["12.ABC.345/01DE-35"]]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	corpo := strings.NewReader("{\"cnpjs\": [\"12.ABC.345/01DE-35\"]}")

	req, _ := http.NewRequest("POST", "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/validar", corpo)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "sucesso": true,
  "quantidade": 1,
  "resultados": [
    {
      "valido": true,
      "motivo": "",
      "cnpj_informado": "12.ABC.345/01DE-35",
      "cnpj_limpo": "12ABC34501DE35",
      "cnpj_formatado": "12.ABC.345/01DE-35",
      "base": "12ABC34501DE",
      "dv_informado": "35",
      "dv_correto": "35"
    }
  ]
}

Notas

  • Envelope sucesso/erro. Servido por www.cnpgolden.com.br.
POST /cnpj-alfa/dv

Calcular o dígito verificador

A partir das 12 primeiras posições, calcula os 2 dígitos verificadores e devolve o CNPJ completo.

Sem chave Host: www.cnpgolden.com.br

Parâmetros

NomeEmTipoPadrãoDescrição
base
opcional
body string — Uma base de 12 caracteres. Use este ou bases.
bases
opcional
body array — Lista de até 100 bases de 12 caracteres.

Requisição

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"bases": ["12ABC34501DE"]}' \
  "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/dv"
import requests

r = requests.post(
    "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/dv",
    json={"bases": ["12ABC34501DE"]},
    timeout=30,
)

r.raise_for_status()
print(r.json())
const res = await fetch("https://www.cnpgolden.com.br/api/v1/cnpj-alfa/dv", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"bases": ["12ABC34501DE"]}),
});

console.log(await res.json());
<?php
$ch = curl_init("https://www.cnpgolden.com.br/api/v1/cnpj-alfa/dv");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["bases" => ["12ABC34501DE"]]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$resposta = curl_exec($ch);
curl_close($ch);

$dados = json_decode($resposta, true);
print_r($dados);
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	corpo := strings.NewReader("{\"bases\": [\"12ABC34501DE\"]}")

	req, _ := http.NewRequest("POST", "https://www.cnpgolden.com.br/api/v1/cnpj-alfa/dv", corpo)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	dados, _ := io.ReadAll(res.Body)
	fmt.Println(string(dados))
}

Resposta — 200 OK

{
  "sucesso": true,
  "quantidade": 1,
  "resultados": [
    {
      "base": "12ABC34501DE",
      "dv": "35",
      "cnpj_completo": "12ABC34501DE35",
      "cnpj_formatado": "12.ABC.345/01DE-35",
      "valido": true,
      "motivo": ""
    }
  ]
}

Notas

  • Envelope sucesso/erro. Servido por www.cnpgolden.com.br.

Dicionário de campos

Alguns campos vêm com os códigos originais da Receita Federal. As tabelas abaixo traduzem os mais usados.

Situação cadastral (situacao)

CódigoSignificado
01Nula
02Ativa
03Suspensa
04Inapta
08Baixada

Porte da empresa (porte)

CódigoSignificado
00Não informado
01Micro empresa
03Empresa de pequeno porte
05Empresa de grande porte (demais)

Tipo de sócio (tipo_socio)

CódigoSignificado
1Pessoa jurídica
2Pessoa física
3Estrangeiro

O formato varia entre endpoints — isso é intencional e documentado. Em GET /cnpj, situacao e porte vêm como código bruto e as datas como AAAAMMDD. Nos endpoints de busca, o porte vem por extenso e as datas em DD/MM/AAAA. Em /search/bulk, data_abertura volta crua mas telefone já vem formatado. Confira a seção do endpoint que você usa.

Valores monetários

Em GET /cnpj, capital_social está em reais. Nos endpoints de demonstrações financeiras, todos os valores estão em MIL R$ — um lucro_liquido de 35600000 significa R$ 35,6 bilhões.

Perguntas frequentes

Como consultar um CNPJ via API?

Faça um GET para https://api.cnpgolden.com.br/api/v1/cnpj?cnpj=… com sua chave no header X-API-Key. A resposta traz o cadastro completo em JSON. Sem chave, o mesmo endpoint responde até 10 vezes por IP por dia.

Existe uma API de CNPJ gratuita?

Sim. A conta é gratuita, sem cartão de crédito, e recebe 70 créditos por mês com o e-mail confirmado (1 crédito por consulta de CNPJ).

De onde vêm os dados?

Dos arquivos de dados abertos do CNPJ publicados pela Receita Federal do Brasil, cobrindo todos os estabelecimentos ativos e inativos. A carga é atualizada mensalmente; GET /database/last-update informa a data do arquivo em uso.

A API suporta o CNPJ alfanumérico de 2026?

Sim, em todos os endpoints. Veja a seção de formato para a armadilha mais comum na hora de limpar a entrada.

Como consultar vários CNPJs de uma vez?

Com POST /search/bulk: um arquivo .txt, um CNPJ por linha, até 1.000 por requisição, cobrado em créditos sobre o total do arquivo.

Existe spec OpenAPI ou coleção do Postman?

A spec OpenAPI 3.1 está em /openapi.json e importa direto no Postman, Insomnia ou geradores de SDK. Há também um espelho em Markdown em /api-docs.md.

Posso usar a chave no frontend?

Não. A chave gasta os seus créditos — chame a API a partir do seu servidor e exponha só o que sua aplicação precisa.

Preciso de volume maior ou SLA?

Para alto volume, faturamento por nota fiscal ou integração dedicada, fale com o time comercial.

Versionamento e mudanças

A versão vive no caminho da URL. Enquanto /api/v1 existir, nenhum campo será removido ou renomeado.

  • Compatível (pode acontecer a qualquer momento): novos campos nas respostas, novos endpoints, novos parâmetros opcionais. Seu parser deve ignorar o que não conhece.
  • Incompatível (só em uma /api/v2): remoção ou renomeação de campos, mudança de tipo, mudança no significado de um código.

A base da Receita Federal é recarregada mensalmente. Durante a recarga, consultas continuam respondendo com os dados do ciclo anterior.

Comece com 1.500 consultas por mês

Plano gratuito, sem cartão de crédito. Gere sua chave e faça a primeira requisição em menos de cinco minutos.

Criar conta grátis Ver planos