> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pandoragraph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Empresas

> Percorra o cadastro Aurora inteiro ou selecione empresas por CNAE e comércio exterior.

Este endpoint tem dois modos. Sem `cnae` e `comex`, ele percorre o catálogo
completo da Aurora em ordem estável de raiz do CNPJ. Com um desses filtros, ele
seleciona o perfil no grafo e devolve o cadastro completo hidratado pela Aurora.

É preciso criar no Brain uma chave com o acesso **Cadastro de empresas
(Aurora)**, que inclui o escopo `aurora:read`.

## Catálogo completo

```bash theme={"dark"}
curl "https://brain.pandoragraph.com/api/v1/empresas?limite=100" \
  -H "Authorization: Bearer $BRAIN_API_KEY"
```

```json theme={"dark"}
{
  "dado": {
    "total": 100,
    "itens": [
      {
        "id": "00000000",
        "versaoId": "emp_v1_...",
        "cnpjBasico": "00000000",
        "razaoSocial": "BANCO DO BRASIL SA",
        "naturezaJuridica": "2038",
        "qualificacaoResponsavel": "10",
        "capitalSocial": 120000000000,
        "capitalSocialTexto": "120000000000",
        "porte": "05",
        "enteFederativo": null,
        "primeiraAparicao": "2025-11-16",
        "ultimaAparicao": "2026-07-12"
      }
    ],
    "pagina": {
      "limite": 100,
      "temMais": true,
      "proximoCursor": "cursor_opaco"
    }
  },
  "avisos": [
    "capitalSocialTexto é a representação textual do double precision armazenado; não é patrimônio nem faturamento"
  ],
  "fonte": { "atualizadoEm": "2026-07-12", "cacheSegundos": 3600 },
  "fontes": {
    "aurora": { "estado": "ok", "snapshotId": "...", "completo": true }
  }
}
```

Envie o cursor sem alterá-lo e mantenha os mesmos filtros:

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

<Note>
  O cursor é opaco, pertence à organização e preserva o snapshot da primeira
  página. Se esse snapshot sair da retenção, a API devolve `409
      cursor_snapshot_expirado`; reinicie sem cursor.
</Note>

## Perfil por CNAE e comércio exterior

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

<ParamField query="cnae" type="string">
  Um ou mais CNAEs de sete dígitos, separados por vírgula. Mais de um significa
  que a empresa pode corresponder a qualquer um deles.
</ParamField>

<ParamField query="comex" type="boolean">
  `true` exige estabelecimento com comércio exterior. `false` não filtra.
</ParamField>

<ParamField query="capitalMin" type="number">
  Capital social cadastral mínimo. Só pode ser usado junto de `cnae` ou `comex`;
  não é patrimônio, faturamento nem estimativa de tamanho.
</ParamField>

<ParamField query="limite" type="integer" default="25">
  De `1` a `100`. A resposta pode trazer menos itens e ainda ter `temMais:
      true`; continue pelo cursor.
</ParamField>

## Histórico cadastral

```bash theme={"dark"}
curl "https://brain.pandoragraph.com/api/v1/empresas/00000000/historico?limite=100" \
  -H "Authorization: Bearer $BRAIN_API_KEY"
```

Cada item usa o mesmo formato cadastral do catálogo. `primeiraAparicao` e
`ultimaAparicao` descrevem em quais cargas a versão foi observada; não são,
necessariamente, datas jurídicas de início e fim.

## Quadro societário

```bash theme={"dark"}
curl "https://brain.pandoragraph.com/api/v1/empresas/00000000/socios?modo=vigentes&limite=100" \
  -H "Authorization: Bearer $BRAIN_API_KEY"
```

`modo=vigentes` devolve as linhas presentes na carga do snapshot. Use
`modo=historico` para todas as versões conhecidas. Esta rota exige também
`socios:read`, registra o acesso e responde com `Cache-Control: private,
no-store`.

<Warning>
  `vigente` significa “presente na carga observada”, não uma data formal de
  saída. Constar no QSA não prova controle ou titularidade, e nomes iguais podem
  ser pessoas diferentes.
</Warning>

## Limites e cache

Consultas Aurora têm teto distribuído de 300 unidades por minuto por
organização e por chave. QSA custa duas unidades. Também há limite de quatro
consultas Aurora simultâneas por organização. Ao exceder, a API responde `429`
e `Retry-After: 60`.

Respostas cadastrais usam cache privado por uma hora e variam por
`Authorization`. Respostas com pessoas usam `private, no-store`.