Início rápido

1. Crie uma chave

Entre em brain.pandoragraph.com, abra Organização → Chaves da API, dê um nome à chave e escolha:

Cadastro de empresas (Aurora) para catálogo, ficha e histórico;
Acesso completo para incluir também quadro societário e as demais fontes.

A chave completa aparece uma vez. Guarde-a num gerenciador de segredos:

export BRAIN_API_KEY="pk_sua_chave"

Não coloque a chave no navegador, no Git ou em logs. A Pandora guarda apenas o hash; se perder a chave, revogue-a e emita outra.

2. Leia a primeira página do catálogo

curl "https://brain.pandoragraph.com/api/v1/empresas?limite=100" \
  -H "Authorization: Bearer $BRAIN_API_KEY"

A resposta contém até 100 empresas, o snapshot consultado e a paginação:

{
  "dado": {
    "total": 100,
    "itens": [
      {
        "id": "00000000",
        "cnpjBasico": "00000000",
        "razaoSocial": "BANCO DO BRASIL SA",
        "capitalSocial": 120000000000,
        "porte": "05",
        "primeiraAparicao": "2025-11-16",
        "ultimaAparicao": "2026-07-12"
      }
    ],
    "pagina": {
      "limite": 100,
      "temMais": true,
      "proximoCursor": "cursor_opaco"
    }
  },
  "fonte": { "atualizadoEm": "2026-07-12", "cacheSegundos": 3600 },
  "fontes": {
    "aurora": { "estado": "ok", "snapshotId": "...", "completo": true }
  }
}

Use proximoCursor sem interpretá-lo e repita os mesmos parâmetros:

curl "https://brain.pandoragraph.com/api/v1/empresas?limite=100&cursor=$CURSOR" \
  -H "Authorization: Bearer $BRAIN_API_KEY"

3. Consulte uma empresa pelo CNPJ

curl "https://brain.pandoragraph.com/api/v1/entidades/00.000.000/0001-91" \
  -H "Authorization: Bearer $BRAIN_API_KEY"

A resposta Aurora-first traz cadastroAurora completo. O id aceita CNPJ com ou sem pontuação, raiz de 8 dígitos ou estabelecimento de 14 dígitos. Para obter o QSA, a chave precisa do escopo socios:read:

curl "https://brain.pandoragraph.com/api/v1/empresas/00000000/socios?modo=vigentes" \
  -H "Authorization: Bearer $BRAIN_API_KEY"

4. Selecione um perfil

curl "https://brain.pandoragraph.com/api/v1/empresas?cnae=6612603&comex=true&capitalMin=1000000&limite=100" \
  -H "Authorization: Bearer $BRAIN_API_KEY"

O endpoint entrega atributos cadastrais, não uma avaliação de potencial comercial. Capital social é o valor declarado no cadastro da Receita; não é patrimônio nem faturamento.

Erros que a integração deve tratar

status	`erro`	ação
`401`	`chave_invalida`	confira ou rotacione a chave
`403`	`escopo_insuficiente`	emita uma chave com o acesso necessário
`409`	`cursor_snapshot_expirado`	reinicie a paginação sem cursor
`429`	`limite_excedido`	respeite `Retry-After` e reduza concorrência
`503`	`fonte_indisponivel`	tente novamente; não grave como “não existe”

Todas as respostas trazem X-Request-Id. Envie também um id próprio de 8 a 80 caracteres em X-Request-Id para correlacionar seus logs. Dados cadastrais usam Cache-Control: private; respostas com pessoas usam private, no-store.

Exemplo em Python

import os
import requests

base = "https://brain.pandoragraph.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['BRAIN_API_KEY']}"}
cursor = None

while True:
    params = {"limite": 100}
    if cursor:
        params["cursor"] = cursor

    r = requests.get(f"{base}/empresas", params=params, headers=headers, timeout=30)
    r.raise_for_status()
    pagina = r.json()["dado"]

    for empresa in pagina["itens"]:
        processar(empresa)

    cursor = pagina["pagina"]["proximoCursor"]
    if not cursor:
        break

Começar

Endpoints

1. Crie uma chave

2. Leia a primeira página do catálogo

3. Consulte uma empresa pelo CNPJ

4. Selecione um perfil

Erros que a integração deve tratar

Exemplo em Python

​1. Crie uma chave

​2. Leia a primeira página do catálogo

​3. Consulte uma empresa pelo CNPJ

​4. Selecione um perfil

​Erros que a integração deve tratar

​Exemplo em Python

1. Crie uma chave

2. Leia a primeira página do catálogo

3. Consulte uma empresa pelo CNPJ

4. Selecione um perfil

Erros que a integração deve tratar

Exemplo em Python