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

# Início rápido

> Do zero a uma empresa enriquecida em uma chamada.

## 1. Autentique

```bash theme={"dark"}
curl https://brain.pandoragraph.com/api/v1/cobertura \
  -H "Authorization: Bearer pk_sua_chave"
```

<Note>
  A chave pertence à organização. Guardamos apenas o hash — se você perder a
  chave, não há como recuperá-la: emitimos outra e revogamos a antiga.
</Note>

Chave ausente e chave inválida devolvem o **mesmo** `401`. É deliberado:
distinguir os dois entregaria informação a quem está tentando adivinhar.

## 2. Resolva o nome em um id

```bash theme={"dark"}
curl "https://brain.pandoragraph.com/api/v1/busca?termo=construtora exemplo" \
  -H "Authorization: Bearer pk_sua_chave"
```

Se o nome casar com mais de uma empresa você recebe `409` com as opções, e cada
opção já traz o `id` que você reenvia. Nós não escolhemos por você.

<Tip>
  Se você já tem o CNPJ, pule esta etapa. O id aceita `00.000.000/0001-91`,
  `00000000000191` ou `00000000` — todos chegam na mesma empresa.
</Tip>

## 3. Enriqueça em uma chamada

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

<CodeGroup>
  ```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
    }
  }
  ```

  ```python Python theme={"dark"}
  import requests

  r = requests.get(
      "https://brain.pandoragraph.com/api/v1/entidades/00000000",
      params={"incluir": "socios,endereco,sancoes"},
      headers={"Authorization": f"Bearer {CHAVE}"},
      timeout=10,
  )
  r.raise_for_status()
  d = r.json()["dado"]

  contratos = d["contratos"]
  if not contratos["conferido"]:
      # as bases discordaram: use como aproximado, não some com outros números
      ...
  ```

  ```typescript TypeScript theme={"dark"}
  const r = await fetch(
    "https://brain.pandoragraph.com/api/v1/entidades/00000000?incluir=socios,endereco",
    { headers: { Authorization: `Bearer ${chave}` } },
  );
  if (r.status === 503) throw new Error("base indisponível — NÃO grave como ausência");
  const { dado, avisos } = await r.json();
  ```
</CodeGroup>

## 4. Leia com cuidado o que parece óbvio

<Warning>
  `vizinhos: 417` **não** quer dizer fachada. Esse caso é real e medido: 417
  empresas no mesmo endereço, `comSocioComum: 0` e `comContratoPublico: 0` — é
  escritório de contabilidade.

  O que merece atenção é vizinho que **repete sócio** ou que **toca dinheiro
  público**, não a contagem.
</Warning>

## Latência e lote

| `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 é dez vezes mais lento. A resposta traz o cabeçalho
`X-Latencia-Estimada-Ms` para você dimensionar lotes sem descobrir isso em
produção.

| custo     | teto por minuto |
| --------- | --------------- |
| grafo     | 600             |
| ontologia | 60              |

Ao estourar, `429` com `Retry-After`.