# PontoFato — referência completa da API

> Gerada do catálogo em https://pontofato.com · build `dev`
> 1 endpoints · 2 estruturas · fatia `/api/empresas`
> Índice curto: https://pontofato.com/llms.txt · Spec: https://pontofato.com/openapi.json · MCP: https://pontofato.com/mcp

> Referência completa para consultar endereços, empresas no CEP e vizinhança.

- [Também disponível na PayAPI Market](https://payapi.market/api/pontofato)
## Serviços grátis e pagos

- [Franquias e preços vigentes](https://pontofato.com/api/pricing)
- [Meios e condições de pagamento](https://pontofato.com/api/billing)
- [Primeira chamada e recuperação de pagamento](https://pontofato.com/skill.md)


## Como ler

- Cada endpoint traz caminho, auth, parâmetros, corpo, estrutura da resposta, erros e uma chamada que roda.
- `Pagina<Canal>` é referência: os campos estão em **Estruturas**, no fim, uma vez só.
- `(opcional)` num campo quer dizer que ele pode não vir; `(pode ser null)` quer dizer que vem com valor nulo.
- Fatie o que precisa: `https://pontofato.com/llms-full.txt?prefix=/api/` devolve só aquele ramo.

## Autenticação

- `none` — Público.
- `token` — Token de operador `METRICS_TOKEN` em `Authorization: Bearer` (métricas).
- `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`.
- `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

## Endpoints

## Lugar

### `GET /api/empresas`

Empresas registradas neste CEP, até 50 por página.

- **URL:** `https://pontofato.com/api/empresas`
- **Auth:** `none` — Público.

**Query**

- `cep` (string, obrigatório) — 8 dígitos, com ou sem hífen. Ex.: `01310100`.
- `page` (int) — Página 0-based da origem CNPJ (50 por página). Padrão: `0`.

**Resposta `200`**

Estrutura: `Empresas`.

- `items` (Empresa[]) — Cards da origem CNPJ (teto 50 por página). → ver `Empresa` em **Estruturas**.
- `total` (int) — Tamanho desta página, ou total se a origem mandar.
- `hasMore` (bool) — `true` quando a origem tem mais estabelecimentos além do teto.
- `page` (int) — Página 0-based pedida à origem.

**Erros**

- `400` — CEP inválido.
- `429` — Limite de consultas desta rede atingido. Tente novamente em um minuto.
- `503` — API de CNPJ indisponível.

**Exemplo**

```sh
curl -s 'https://pontofato.com/api/empresas?cep=01310100'
```

## Estruturas

### `Empresas`

Empresas registradas neste CEP.

- `items` (Empresa[]) — Cards da origem CNPJ (teto 50 por página). → ver `Empresa` em **Estruturas**.
- `total` (int) — Tamanho desta página, ou total se a origem mandar.
- `hasMore` (bool) — `true` quando a origem tem mais estabelecimentos além do teto.
- `page` (int) — Página 0-based pedida à origem.

### `Empresa`

Card da busca por CEP na origem CNPJ — não é a ficha completa do Radar.

- `cnpj` (string) — 14 caracteres (dígitos ou alfanumérico), sem máscara.
- `cnpjFormatted` (string) — CNPJ com pontuação.
- `razaoSocial` (string, pode ser null) — Razão social cadastrada.
- `nomeFantasia` (string, pode ser null) — Nome fantasia, se houver.
- `situacao` (object, pode ser null) — `codigo` numérico e `label` (Ativa, Inapta, Baixada…).
- `uf` (string, pode ser null) — UF do estabelecimento.
- `municipio` (string, pode ser null) — Município cadastrado.
- `bairro` (string, pode ser null) — Bairro do estabelecimento.
- `cnae` (object, pode ser null) — `codigo` e `descricao` da atividade principal.