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

# Entidades

> A ficha completa, com expansão sob demanda. É onde mora o produto.

<ParamField path="id" type="string" required>
  CNPJ em qualquer formato — `00.000.000/0001-91`, `00000000000191` ou
  `00000000` — ou um id de pessoa devolvido por outra chamada.

  Você nunca precisa saber como chaveamos internamente: mandar a raiz ou o
  estabelecimento chega na mesma empresa. Quando você manda o CNPJ completo, a
  gente entende que a filial importa e usa ela nas expansões.
</ParamField>

<ParamField query="incluir" type="string">
  Lista separada por vírgula: `socios`, `endereco`, `doacoes`, `sancoes`.
  Expansão desconhecida é ignorada, não quebra a chamada.
</ParamField>

```bash theme={"dark"}
curl "https://brain.pandoragraph.com/api/v1/entidades/00000000?incluir=socios,endereco" \
  -H "Authorization: Bearer pk_sua_chave"
```

```json theme={"dark"}
{
  "dado": {
    "id": "00000000",
    "tipo": "empresa",
    "nome": "BANCO DO BRASIL SA",
    "estabelecimentos": {
      "valor": 7902,
      "conferido": false,
      "procedencia": "grafo"
    },
    "contratos": {
      "valor": 276,
      "conferido": false,
      "procedencia": "grafo"
    },
    "valorEmContratos": {
      "valor": 3469461623.9800043,
      "conferido": true,
      "procedencia": "ontologia"
    },
    "socios": [
      {
        "id": "***000000**::PESSOA EXEMPLO",
        "nome": "PESSOA EXEMPLO",
        "papel": "consta no QSA"
      }
    ],
    "endereco": {
      "estabelecimento": "00000000000191",
      "vizinhos": 13,
      "comSocioComum": 3,
      "comContratoPublico": 0
    }
  },
  "avisos": [
    "mesmo endereço é indício, não vínculo…"
  ],
  "fonte": {
    "atualizadoEm": "2026-08-06",
    "cacheSegundos": 3600
  }
}
```

## Expansões e custo

| `incluir=` | fonte         | latência típica |
| ---------- | ------------- | --------------- |
| `socios`   | grafo         | \~300 ms        |
| `endereco` | grafo         | \~500 ms        |
| `doacoes`  | grafo         | \~400 ms        |
| `sancoes`  | **ontologia** | **\~3 s**       |

`sancoes` varre outra base e conta no teto de 60/min em vez de 600/min. A
resposta traz `X-Latencia-Estimada-Ms` para você dimensionar lotes.

## Como ler `endereco`

<Warning>
  `vizinhos` sozinho não indica nada. Caso real e medido: 417 empresas no mesmo
  endereço, com `comSocioComum: 0` e `comContratoPublico: 0` — é escritório de
  contabilidade.

  O sinal está nos outros dois campos: vizinho que **repete sócio** ou que **toca
  dinheiro público**. Prédio comercial acende a contagem e zera os dois.
</Warning>

## Como ler `socios`

<Note>
  Constar no quadro societário é o que o registro afirma — não é titularidade, não
  é controle. O casamento é por nome, com CPF mascarado na origem, então homônimo
  é possível.
</Note>

## Como ler `sancoes`

Cada linha traz `evidencia`, e a forma carrega a diferença antes da palavra:

<div style={{display:'flex',flexDirection:'column',gap:'0.75rem',margin:'1.25rem 0'}}>
  <div style={{display:'flex',alignItems:'center',gap:'0.75rem'}}>
    <span className="selo selo-decisao">decisão</span>
    <span>uma autoridade decidiu e publicou. É fato, e é publicável.</span>
  </div>

  <div style={{display:'flex',alignItems:'center',gap:'0.75rem'}}>
    <span className="selo selo-acusacao">acusação</span>
    <span>a empresa é ré num processo. <strong>Não é prova de nada.</strong></span>
  </div>
</div>

Misturar os dois é como uma lista de suspeitos vira difamação. Se o seu sistema
exibe esse dado, exiba o campo junto.

## Ficha de pessoa

`GET /api/v1/entidades/***000000**::NOME` devolve sociedades, candidaturas e
mandato.

<Warning>
  **Todo acesso a ficha de pessoa é registrado** com a chave que pediu. Se não
  conseguirmos gravar o registro, a consulta é recusada com `503` — não existe
  caminho de leitura sem rastro.
</Warning>

Uma pessoa sem vínculo devolve `200` com listas vazias. Nunca `404`: "não achei
nada sobre ela" é resposta, "não existe essa pessoa" seria conclusão.