# PontoFato — referência completa da API

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

> Referência completa. Fonte: CNEFE 2022 no c3.

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


## Endpoints

## Descoberta

### `GET /okf/:arquivo`

Bundle OKF (Open Knowledge Format v0.1): markdown com frontmatter para o agente ler o produto inteiro sem parsear HTML.

- **URL:** `https://pontofato.com/okf/:arquivo`
- **Auth:** `none` — não declarada

**Parâmetros de caminho**

- `arquivo` (string, obrigatório) — `index.md`, `sobre.md`, `api.md` ou `faq.md`. Ex.: `index.md`.

**Resposta `200`**

`text/markdown`. Comece por `/okf/index.md`, que lista o bundle.

**Erros**

- `404` — Arquivo fora do bundle.

**Exemplo**

```sh
curl -s https://pontofato.com/okf/index.md
```

### `GET /.well-known/:arquivo`

Descoberta de máquina antes da home: `api-catalog` (RFC 9727, linkset com a API e o MCP), `security.txt` (RFC 9116) e `mcp-registry-auth` (chave do registro oficial de MCP).

- **URL:** `https://pontofato.com/.well-known/:arquivo`
- **Auth:** `none` — não declarada

**Parâmetros de caminho**

- `arquivo` (string, obrigatório) — `api-catalog`, `security.txt`, `mcp-registry-auth` ou `apis.json`. Ex.: `api-catalog`.

**Resposta `200`**

`application/linkset+json` no api-catalog; `text/plain` nos outros dois.

**Erros**

- `404` — Nome fora dos quatro publicados.

**Exemplo**

```sh
curl -s https://pontofato.com/.well-known/api-catalog
```

### `GET /apis.json`

APIs.json (apisjson.org, 0.19): o índice que o APIs.io colhe — a API, o MCP, OpenAPI, guia e bundle OKF num arquivo só. Também em `/.well-known/apis.json`.

- **URL:** `https://pontofato.com/apis.json`
- **Auth:** `none` — não declarada

**Resposta `200`**

`application/json` no formato APIs.json 0.19: `apis[]` com `baseURL`, `humanURL` e `properties[]`.

**Exemplo**

```sh
curl -s https://pontofato.com/apis.json
```

### `GET /api/`

Índice auto-descrito: cada rota, o que cobra e como plugar o MCP.

- **URL:** `https://pontofato.com/api/`
- **Auth:** `none` — não declarada

**Resposta `200`**

- `name` (string) — Nome do produto.
- `description` (string) — O que o produto faz.
- `build` (string) — Commit publicado.
- `base_url` (string) — Origem em que esta API está servindo.
- `docs` (object) — Links para llms.txt, OpenAPI, MCP e a UI.
- `endpoints` (object[]) — Catálogo de endpoints.
- `mcp_tools` (string[]) — Tools do MCP.

### `GET /api/health`

Saúde da origem sqlite e cobertura por UF.

- **URL:** `https://pontofato.com/api/health`
- **Auth:** `none` — não declarada

**Resposta `200`**

Estrutura: `Saude`.

- `ok` (bool) — `true` quando há pelo menos uma UF no disco.
- `origem` (string) — `sqlite` ou `indisponivel`.
- `cobertura` (Cobertura) — UFs presentes. → ver `Cobertura` em **Estruturas**.
- `pontos` (int) — Soma de linhas nas UFs montadas.
- `build` (string) — Commit publicado neste Worker (`BUILD`).

**Erros**

- `503` — Nenhuma UF montada na origem.

**Exemplo**

```sh
curl -s https://pontofato.com/api/health
```

### `POST /mcp`

MCP Streamable HTTP — as tools deste catálogo, despachadas neste mesmo Worker.

- **URL:** `https://pontofato.com/mcp`
- **Auth:** `none` — não declarada

**Resposta `200`**

JSON-RPC 2.0 (`initialize`, `tools/list`, `tools/call`).

**Exemplo**

```sh
curl -s -XPOST https://pontofato.com/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Lugar

### `GET /api/cep/:cep`

Pontos CNEFE de um CEP, com lat/lon IBGE — não é chute de mapa.

- **URL:** `https://pontofato.com/api/cep/:cep`
- **Auth:** `none` — não declarada

**Parâmetros de caminho**

- `cep` (string, obrigatório) — 8 dígitos, com ou sem hífen. Ex.: `70040010`.

**Resposta `200`**

Estrutura: `Cep`.

- `cep` (string) — CEP formatado `NNNNN-NNN`.
- `pontos` (Ponto[]) — Endereços distintos neste CEP (teto na origem). → ver `Ponto` em **Estruturas**.
- `resumo` (Resumo) — Unidades, edifícios, espécies, bairro, cidade, UF e centroide. → ver `Resumo` em **Estruturas**.
- `fonte` (string) — Sempre `cnefe-2022` neste produto.
- `cobertura` (Cobertura) — UFs ingeridas agora. → ver `Cobertura` em **Estruturas**.
- `_links` (object) — `self`, `empresas` e `unidades` absolutos.

**Erros**

- `400` — CEP inválido (tamanho ou `00000000`).
- `404` — CEP bem-formado fora da base; `cobertura` diz quais UFs já existem.
- `503` — Origem sqlite fora.

**Exemplo**

```sh
curl -s https://pontofato.com/api/cep/70040010
```

### `GET /api/cep/:cep/unidades`

Unidades CNEFE de um CEP, com complemento, espécie e id — paginado.

O lookup do CEP agrupa por logradouro+número. Esta rota devolve cada unidade (apartamento, loja) com o fato CNEFE. Sem `logradouro`/`numero`, pagina o CEP inteiro.

- **URL:** `https://pontofato.com/api/cep/:cep/unidades`
- **Auth:** `none` — não declarada

**Parâmetros de caminho**

- `cep` (string, obrigatório) — 8 dígitos, com ou sem hífen. Ex.: `71940000`.

**Query**

- `logradouro` (string) — Logradouro exatamente como no lookup (tipo + nome).
- `numero` (string) — Número do edifício no CNEFE.
- `limit` (int) — Itens por página, teto 50. Padrão: `50`.
- `offset` (int) — Deslocamento 0-based. Padrão: `0`.

**Resposta `200`**

Estrutura: `Unidades`.

- `cep` (string) — CEP formatado.
- `items` (Ponto[]) — Unidades desta página (complemento, espécie, id CNEFE). → ver `Ponto` em **Estruturas**.
- `total` (int) — Quantas unidades batem o filtro.
- `limit` (int) — Teto desta página.
- `offset` (int) — Deslocamento pedido.
- `hasMore` (bool) — `true` se ainda há unidade depois desta página.
- `cobertura` (Cobertura) — UFs ingeridas agora. → ver `Cobertura` em **Estruturas**.
- `_links` (object) — `self` desta página e `cep` do lookup.

**Erros**

- `400` — CEP inválido.
- `404` — CEP fora da malha, ou o logradouro+número não existe nele.

**Exemplo**

```sh
curl -s 'https://pontofato.com/api/cep/71940000/unidades?logradouro=RUA%20BURITI&numero=6'
```

### `GET /api/proximo`

Ponto CNEFE mais perto de um par lat/lon. Sem default para (0,0).

Ausente ou vazio NÃO vira zero. `(0,0)` é o golfo da Guiné e só entra se a pessoa mandou.

- **URL:** `https://pontofato.com/api/proximo`
- **Auth:** `none` — não declarada

**Query**

- `lat` (number, obrigatório) — Latitude WGS84, −90 a 90. Ex.: `-15.7897`.
- `lon` (number, obrigatório) — Longitude WGS84, −180 a 180. Ex.: `-47.8793`.

**Resposta `200`**

Estrutura: `Proximo`.

- `logradouro` (string) — Logradouro do ponto.
- `bairro` (string) — Localidade.
- `cidade` (string) — Município.
- `uf` (string) — Sigla da unidade da federação.
- `cep` (string) — CEP formatado.
- `lat` (number) — Latitude.
- `lon` (number) — Longitude.
- `numero` (string, pode ser null) — Número no logradouro.
- `complemento` (string, pode ser null) — Complemento CNEFE, se houver.
- `ibge` (string, pode ser null) — Código IBGE do município.
- `especie` (string, pode ser null) — Código da espécie CNEFE.
- `especie_label` (string, pode ser null) — Rótulo IBGE da espécie.
- `setor` (string, pode ser null) — Setor censitário.
- `estabelecimento` (string, pode ser null) — Nome do estabelecimento, se a espécie tiver.
- `nv_geo` (string, pode ser null) — Nível de geocodificação.
- `nv_geo_label` (string, pode ser null) — O que o nível de geo significa.
- `id_cnefe` (string, pode ser null) — `COD_UNICO_ENDERECO`.
- `distancia_m` (int) — Distância aproximada em metros.

**Erros**

- `400` — `lat` ou `lon` ausentes ou fora da faixa.
- `404` — Nada na cobertura perto do ponto.

**Exemplo**

```sh
curl -s 'https://pontofato.com/api/proximo?lat=-15.7897&lon=-47.8793'
```

### `GET /api/buscar`

Busca textual de logradouro (FTS5), com UF e cidade opcionais.

- **URL:** `https://pontofato.com/api/buscar`
- **Auth:** `none` — não declarada

**Query**

- `q` (string, obrigatório) — Termo com 3+ caracteres. Ex.: `paulista`.
- `uf` (string) — Restringe a uma UF. Ex.: `SP`.
- `cidade` (string) — Trecho do município.

**Resposta `200`**

Estrutura: `PaginaPonto`.

- `items` (Ponto[]) — Resultados (teto 50). → ver `Ponto` em **Estruturas**.
- `total` (int) — Quantos vieram nesta página.

**Erros**

- `400` — Termo curto demais.

**Exemplo**

```sh
curl -s 'https://pontofato.com/api/buscar?q=paulista&uf=SP'
```

### `GET /api/empresas`

Estabelecimentos da Receita neste CEP (join no c3, teto 50).

- **URL:** `https://pontofato.com/api/empresas`
- **Auth:** `none` — não declarada

**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.
- `503` — API de CNPJ indisponível.

**Exemplo**

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

### `GET /api/raio`

CEPs a N metros de um ponto, com distância e quantos endereços CNEFE cada um tem — raio em metros, não bairro em texto.

- **URL:** `https://pontofato.com/api/raio`
- **Auth:** `none` — não declarada

**Query**

- `cep` (string) — Centro = média dos pontos deste CEP. Alternativa a lat/lon. Ex.: `01310100`.
- `lat` (number) — Latitude do centro, se não vier `cep`.
- `lon` (number) — Longitude do centro, se não vier `cep`.
- `raio` (int) — Raio em metros, 1 a 2000. Padrão: `500`. Ex.: `800`.

**Resposta `200`**

Estrutura: `Raio`.

- `centro` (object) — `lat`, `lon` e, quando o centro veio de CEP, `cep` formatado.
- `raio_m` (int) — Raio usado, em metros.
- `total_pontos` (int) — Endereços CNEFE dentro do raio, somando os CEPs devolvidos.
- `ceps` (CepNoRaio[]) — Até 300 CEPs, ordenados por distância. → ver `CepNoRaio` em **Estruturas**.
- `truncado` (bool) — `true` se havia mais de 300 CEPs no raio — diminua o raio.
- `fonte` (string) — Sempre `cnefe-2022`.
- `_links` (object) — `self` e `vizinhanca` com o mesmo centro e raio.

**Erros**

- `400` — Sem centro (`cep` ou `lat`+`lon`), CEP inválido, coordenada inválida ou raio fora de 1–2000.
- `404` — CEP fora da malha, ou nenhum ponto CNEFE no raio; `cobertura` diz quais UFs existem.
- `503` — Origem sqlite fora.

**Exemplo**

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

### `GET /api/vizinhanca`

Empresas ativas, abertas e baixadas num raio em metros, por CNAE, com as aberturas mais recentes e a distância de cada uma — o CNEFE dá o raio, a Receita dá o fato.

- **URL:** `https://pontofato.com/api/vizinhanca`
- **Auth:** `credito` — não declarada

**Query**

- `cep` (string) — Centro = média dos pontos deste CEP. Alternativa a lat/lon. Ex.: `01310100`.
- `lat` (number) — Latitude do centro, se não vier `cep`.
- `lon` (number) — Longitude do centro, se não vier `cep`.
- `raio` (int) — Raio em metros, 1 a 2000. Padrão: `500`. Ex.: `800`.
- `cnae` (string) — Prefixo de CNAE: divisão (2 dígitos), classe (5) ou subclasse (7). Ex.: `56`.
- `desde` (string) — Data ISO para “abriu/baixou desde”. Padrão: 90 dias antes da data da base (`base.dump_date`). Ex.: `2026-02-01`.

**Resposta `200`**

Estrutura: `Vizinhanca`.

- `centro` (object) — `lat`, `lon` e `cep` quando o centro veio de CEP.
- `raio_m` (int) — Raio usado, em metros.
- `ceps` (int) — Quantos CEPs entraram na conta (teto 300).
- `truncado` (bool) — `true` se o raio tinha mais de 300 CEPs.
- `desde` (string) — Data ISO de corte para abertas/baixadas.
- `base` (object) — `dump_date`: data do dump da Receita carregado — a janela padrão conta a partir dela.
- `cnae` (string, pode ser null) — Prefixo de CNAE aplicado, se houve.
- `empresas` (object) — `total`, `ativas`, `abertas_desde`, `baixadas_desde` (nulos quando `lenta`).
- `por_cnae` (ContagemCnae[]) — As 20 subclasses com mais ativas. → ver `ContagemCnae` em **Estruturas**.
- `amostra_abertas` (Abertura[]) — As 50 aberturas mais recentes, com distância. → ver `Abertura` em **Estruturas**.
- `lenta` (bool) — `true` quando alguma contagem estourou o teto de tempo e veio nula.
- `fonte` (string) — Sempre `cnefe-2022 + receita`.
- `_links` (object) — `self` e `raio` com o mesmo centro.

**Erros**

- `400` — Centro ausente, CEP/coordenada/raio inválidos, `cnae` fora de 2/5/7 dígitos ou `desde` fora de 1900–hoje.
- `402` — Cota diária grátis esgotada: pague $0.05 por x402 (`accepts[]`) ou mande crédito pré-pago (`Authorization: Bearer cred_…`).
- `404` — CEP fora da malha ou nenhum ponto no raio.
- `503` — Origem sqlite ou API de CNPJ fora.

**Exemplo**

```sh
curl -s 'https://pontofato.com/api/vizinhanca?cep=01310100&raio=800&cnae=56'
```

## Geo

### `GET /api/local`

Cidade/UF de quem chama, pela borda Cloudflare. Sem cache.

- **URL:** `https://pontofato.com/api/local`
- **Auth:** `none` — não declarada

**Resposta `200`**

Estrutura: `Local`.

- `cidade` (string, pode ser null) — Cidade que a borda atribuiu ao IP.
- `uf` (string, pode ser null) — Região/UF da borda.
- `pais` (string, pode ser null) — País ISO.
- `cep` (string, pode ser null) — CEP aproximado da borda, se houver.

## Contato

### `POST /api/contact`

Contato: humano com Turnstile (grátis) ou agente com x402 $0.10.

- **URL:** `https://pontofato.com/api/contact`
- **Auth:** `none` — não declarada

**Corpo** (`application/json`)

- `name` (string, obrigatório) — Nome (alias `nome`).
- `email` (string, obrigatório) — E-mail de resposta.
- `message` (string, obrigatório) — Mensagem (alias `mensagem`).
- `form_ts` (int) — Epoch ms de quando o form abriu (2s–12h).

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando a mensagem foi aceita.
- `path` (string) — Caminho: humano com captcha ou agente pago.

**Erros**

- `400` — Validação.
- `402` — Agente: pague $0.10 e repita com X-PAYMENT.
- `403` — Turnstile inválido.

**Exemplo**

```sh
curl -s -XPOST https://pontofato.com/api/contact -H 'content-type: application/json' -d '{"name":"Agent","email":"a@example.com","message":"hello from agent path","form_ts":0}'
```

## Operação

### `GET /api/metrics`

Métricas dos últimos 7 dias para o painel do operador; com o token, inclui os pagamentos.

Sem credencial devolve o uso real da API: movimentos de crédito da casa por dia, com `produto` separando o PontoFato dos outros produtos no banco compartilhado. Visitas da interface não são contadas aqui — quem mede visita é o GA e a borda CF. Com `METRICS_TOKEN` em Bearer acrescenta `payments` — só x402 liquidado em Base mainnet.

- **URL:** `https://pontofato.com/api/metrics`
- **Auth:** `none` — não declarada

**Headers**

- `Authorization` (string) — `Bearer <METRICS_TOKEN>` para incluir o bloco financeiro; token errado é 401.

**Resposta `200`**

Estrutura: `Metricas`.

- `app` (string) — Nome do produto.
- `today` (string) — Dia de referência (UTC, AAAA-MM-DD).
- `today_visits` (int) — Zero neste produto: visitas são medidas pelo GA e pela borda CF.
- `today_contacts` (int, opcional) — Mensagens de contato hoje. Só com `METRICS_TOKEN`: contato não sai sem token.
- `days` (object[]) — Um registro por dia da janela, com as contagens de cada métrica.
- `usage` (object) — `creditos`: movimentos de crédito do PontoFato por dia — chamadas pagas da API, x402 ou crédito, com `produto` filtrando o que é da casa.
- `accounts` (object) — Sem contas neste produto: objeto vazio.
- `financeiro` (object, opcional) — Agregado do dia: `hoje_usd`, `hoje_count`, `rede`. Só com `METRICS_TOKEN`: dinheiro não sai sem token; a série completa é `payments`.
- `payments` (object, opcional) — Resumo financeiro do x402; só com METRICS_TOKEN.

**Erros**

- `401` — Token de operador errado.
- `503` — Worker sem METRICS_TOKEN configurado.

**Exemplo**

```sh
curl -s https://pontofato.com/api/metrics -H "Authorization: Bearer $METRICS_TOKEN"
```

## Crédito

### `POST /api/credito`

Recarrega crédito pré-pago: paga uma vez com x402 e recebe o token que desconta em qualquer API da casa.

- **URL:** `https://pontofato.com/api/credito`
- **Auth:** `none` — não declarada

**Query**

- `usd` (int, obrigatório) — Pacote: 1, 5, 10 ou 25 dólares.

**Resposta `200`**

- `token` (string) — Token portador do saldo (`cred_…`). Mostrado UMA vez — não há como recuperá-lo.
- `saldo_usd` (string) — Saldo creditado.
- `guarde` (string) — Aviso de que o token é o portador do crédito.
- `usar` (string) — Como apresentar o token nas rotas pagas.
- `saldo_em` (string) — Onde consultar saldo e extrato.

**Erros**

- `400` — Pacote fora da lista (1, 5, 10 ou 25).
- `402` — Sem pagamento — o corpo traz `accepts[]` do x402.

**Exemplo**

```sh
curl -s -XPOST 'https://pontofato.com/api/credito?usd=10'
```

### `GET /api/credito`

Saldo e extrato do crédito — as últimas movimentações, sem devolver o token.

- **URL:** `https://pontofato.com/api/credito`
- **Auth:** `credito` — não declarada

**Resposta `200`**

- `saldo_micros` (int) — Saldo em micro-dólares (1e-6 USD).
- `saldo_usd` (string) — Saldo formatado.
- `criado_em` (string) — Quando o crédito foi aberto.
- `movimentos` (object[]) — Entradas e saídas recentes, com produto e recurso.

**Erros**

- `401` — Sem token ou token desconhecido.

**Exemplo**

```sh
curl -s https://pontofato.com/api/credito -H 'Authorization: Bearer cred_…'
```

## Estruturas

### `Saude`

Se a origem sqlite está no ar e o quanto da malha já foi ingerida.

- `ok` (bool) — `true` quando há pelo menos uma UF no disco.
- `origem` (string) — `sqlite` ou `indisponivel`.
- `cobertura` (Cobertura) — UFs presentes. → ver `Cobertura` em **Estruturas**.
- `pontos` (int) — Soma de linhas nas UFs montadas.
- `build` (string) — Commit publicado neste Worker (`BUILD`).

### `Cep`

Pontos CNEFE de um CEP, com resumo e cobertura.

- `cep` (string) — CEP formatado `NNNNN-NNN`.
- `pontos` (Ponto[]) — Endereços distintos neste CEP (teto na origem). → ver `Ponto` em **Estruturas**.
- `resumo` (Resumo) — Unidades, edifícios, espécies, bairro, cidade, UF e centroide. → ver `Resumo` em **Estruturas**.
- `fonte` (string) — Sempre `cnefe-2022` neste produto.
- `cobertura` (Cobertura) — UFs ingeridas agora. → ver `Cobertura` em **Estruturas**.
- `_links` (object) — `self`, `empresas` e `unidades` absolutos.

### `Unidades`

Unidades CNEFE de um CEP (ou de um logradouro+número), paginadas.

- `cep` (string) — CEP formatado.
- `items` (Ponto[]) — Unidades desta página (complemento, espécie, id CNEFE). → ver `Ponto` em **Estruturas**.
- `total` (int) — Quantas unidades batem o filtro.
- `limit` (int) — Teto desta página.
- `offset` (int) — Deslocamento pedido.
- `hasMore` (bool) — `true` se ainda há unidade depois desta página.
- `cobertura` (Cobertura) — UFs ingeridas agora. → ver `Cobertura` em **Estruturas**.
- `_links` (object) — `self` desta página e `cep` do lookup.

### `Proximo`

Ponto CNEFE mais perto do par lat/lon.

- `logradouro` (string) — Logradouro do ponto.
- `bairro` (string) — Localidade.
- `cidade` (string) — Município.
- `uf` (string) — Sigla da unidade da federação.
- `cep` (string) — CEP formatado.
- `lat` (number) — Latitude.
- `lon` (number) — Longitude.
- `numero` (string, pode ser null) — Número no logradouro.
- `complemento` (string, pode ser null) — Complemento CNEFE, se houver.
- `ibge` (string, pode ser null) — Código IBGE do município.
- `especie` (string, pode ser null) — Código da espécie CNEFE.
- `especie_label` (string, pode ser null) — Rótulo IBGE da espécie.
- `setor` (string, pode ser null) — Setor censitário.
- `estabelecimento` (string, pode ser null) — Nome do estabelecimento, se a espécie tiver.
- `nv_geo` (string, pode ser null) — Nível de geocodificação.
- `nv_geo_label` (string, pode ser null) — O que o nível de geo significa.
- `id_cnefe` (string, pode ser null) — `COD_UNICO_ENDERECO`.
- `distancia_m` (int) — Distância aproximada em metros.

### `PaginaPonto`

Lista paginada de pontos.

- `items` (Ponto[]) — Resultados (teto 50). → ver `Ponto` em **Estruturas**.
- `total` (int) — Quantos vieram nesta página.

### `Empresas`

Estabelecimentos da Receita neste CEP, via api-cnpj no c3.

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

### `Raio`

CEPs a N metros de um ponto, do mais perto ao mais longe.

- `centro` (object) — `lat`, `lon` e, quando o centro veio de CEP, `cep` formatado.
- `raio_m` (int) — Raio usado, em metros.
- `total_pontos` (int) — Endereços CNEFE dentro do raio, somando os CEPs devolvidos.
- `ceps` (CepNoRaio[]) — Até 300 CEPs, ordenados por distância. → ver `CepNoRaio` em **Estruturas**.
- `truncado` (bool) — `true` se havia mais de 300 CEPs no raio — diminua o raio.
- `fonte` (string) — Sempre `cnefe-2022`.
- `_links` (object) — `self` e `vizinhanca` com o mesmo centro e raio.

### `Vizinhanca`

O que a Receita sabe sobre os CEPs dentro do raio: contagens, classes e aberturas recentes.

- `centro` (object) — `lat`, `lon` e `cep` quando o centro veio de CEP.
- `raio_m` (int) — Raio usado, em metros.
- `ceps` (int) — Quantos CEPs entraram na conta (teto 300).
- `truncado` (bool) — `true` se o raio tinha mais de 300 CEPs.
- `desde` (string) — Data ISO de corte para abertas/baixadas.
- `base` (object) — `dump_date`: data do dump da Receita carregado — a janela padrão conta a partir dela.
- `cnae` (string, pode ser null) — Prefixo de CNAE aplicado, se houve.
- `empresas` (object) — `total`, `ativas`, `abertas_desde`, `baixadas_desde` (nulos quando `lenta`).
- `por_cnae` (ContagemCnae[]) — As 20 subclasses com mais ativas. → ver `ContagemCnae` em **Estruturas**.
- `amostra_abertas` (Abertura[]) — As 50 aberturas mais recentes, com distância. → ver `Abertura` em **Estruturas**.
- `lenta` (bool) — `true` quando alguma contagem estourou o teto de tempo e veio nula.
- `fonte` (string) — Sempre `cnefe-2022 + receita`.
- `_links` (object) — `self` e `raio` com o mesmo centro.

### `Local`

Geo de borda do visitante (Cloudflare). Nunca é cacheado.

- `cidade` (string, pode ser null) — Cidade que a borda atribuiu ao IP.
- `uf` (string, pode ser null) — Região/UF da borda.
- `pais` (string, pode ser null) — País ISO.
- `cep` (string, pode ser null) — CEP aproximado da borda, se houver.

### `Metricas`

Painel de 7 dias do operador. `payments` só aparece com o token e só em Base mainnet.

- `app` (string) — Nome do produto.
- `today` (string) — Dia de referência (UTC, AAAA-MM-DD).
- `today_visits` (int) — Zero neste produto: visitas são medidas pelo GA e pela borda CF.
- `today_contacts` (int, opcional) — Mensagens de contato hoje. Só com `METRICS_TOKEN`: contato não sai sem token.
- `days` (object[]) — Um registro por dia da janela, com as contagens de cada métrica.
- `usage` (object) — `creditos`: movimentos de crédito do PontoFato por dia — chamadas pagas da API, x402 ou crédito, com `produto` filtrando o que é da casa.
- `accounts` (object) — Sem contas neste produto: objeto vazio.
- `financeiro` (object, opcional) — Agregado do dia: `hoje_usd`, `hoje_count`, `rede`. Só com `METRICS_TOKEN`: dinheiro não sai sem token; a série completa é `payments`.
- `payments` (object, opcional) — Resumo financeiro do x402; só com METRICS_TOKEN.

### `Cobertura`

Quais UFs já têm sqlite na origem.

- `ufs` (string[]) — Siglas presentes no disco, em ordem.
- `completa` (bool) — `true` só com as 27 UFs.

### `Ponto`

Um endereço CNEFE: número, coordenada IBGE e o fato que veio no CSV.

- `cep` (string, pode ser null) — CEP formatado da unidade ou do edifício.
- `logradouro` (string) — Tipo + nome do logradouro, já juntados.
- `numero` (string, pode ser null) — Número no logradouro.
- `complemento` (string, pode ser null) — Complementos do CNEFE, se houver.
- `bairro` (string) — Localidade/bairro no cadastro.
- `cidade` (string) — Município IBGE.
- `uf` (string) — Sigla da unidade da federação.
- `lat` (number, pode ser null) — Latitude WGS84 do ponto.
- `lon` (number, pode ser null) — Longitude WGS84 do ponto.
- `ibge` (string, pode ser null) — Código IBGE do município.
- `especie` (string, pode ser null) — Código da espécie CNEFE (`1`–`8`).
- `especie_label` (string, pode ser null) — Rótulo IBGE da espécie.
- `tipo_edificacao` (string, pode ser null) — Casa, apartamento, vila — `COD_TIPO_ESPECIE`.
- `tipo_edificacao_codigo` (string, pode ser null) — Código `101`–`104`.
- `estabelecimento` (string, pode ser null) — Nome do estabelecimento, quando a espécie tem.
- `estabelecimentos` (string[], pode ser null) — Nomes distintos no edifício (amostra).
- `especies` (EspecieContagem[], pode ser null) — Mistura de espécies neste logradouro+número. → ver `EspecieContagem` em **Estruturas**.
- `setor` (string, pode ser null) — Setor censitário.
- `distrito` (string, pode ser null) — Código de distrito IBGE.
- `subdistrito` (string, pode ser null) — Código de subdistrito IBGE.
- `quadra` (string, pode ser null) — Número da quadra no setor.
- `face` (string, pode ser null) — Número da face da quadra.
- `nv_geo` (string, pode ser null) — Nível de geocodificação (`1`–`6`).
- `nv_geo_label` (string, pode ser null) — O que o nível de geo significa.
- `finalidade` (string, pode ser null) — Residencial, não residencial, misto ou indeterminado.
- `indicador_estab` (string, pode ser null) — Único ou múltiplo estabelecimento no endereço.
- `indicador_const` (string, pode ser null) — Único ou múltiplo em construção/reforma.
- `id_cnefe` (string, pode ser null) — `COD_UNICO_ENDERECO` da unidade (só no detalhe).
- `tipo_logradouro` (string, pode ser null) — Tipo (RUA, AVENIDA…).
- `titulo_logradouro` (string, pode ser null) — Título (DOUTOR…), se houver.
- `nome_logradouro` (string, pode ser null) — Nome do logradouro sem o tipo.
- `modificador` (string, pode ser null) — Modificador do número (SN, KM…).
- `unidades` (int) — Quantas unidades CNEFE neste logradouro+número (apartamentos, salas).
- `complementos` (int, pode ser null) — Complementos distintos no edifício.
- `_links` (object, pode ser null) — `unidades` absoluto para o detalhe paginado.
- `_origem` (string) — UF do sqlite que respondeu.

### `Resumo`

Síntese do CEP: quantos pontos, quantos edifícios, onde fica.

- `address_count` (int) — Unidades CNEFE no CEP (não é o número de prédios).
- `edificios` (int) — Logradouro+número distintos no CEP.
- `bairro` (string) — Bairro mais frequente na amostra.
- `cidade` (string) — Município IBGE.
- `uf` (string) — Sigla da unidade da federação.
- `ibge` (string, pode ser null) — Código IBGE do município.
- `lat` (number, pode ser null) — Latitude média dos edifícios devolvidos.
- `lon` (number, pode ser null) — Longitude média dos edifícios devolvidos.
- `especies` (EspecieContagem[]) — Unidades por espécie no CEP inteiro. → ver `EspecieContagem` em **Estruturas**.

### `Empresa`

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

- `cnpj` (string) — 14 dígitos, sem máscara.
- `cnpjFormatted` (string) — CNPJ com pontuação.
- `razaoSocial` (string, pode ser null) — Razão social na Receita.
- `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 da Receita.
- `bairro` (string, pode ser null) — Bairro do estabelecimento.
- `cnae` (object, pode ser null) — `codigo` e `descricao` da atividade principal.

### `CepNoRaio`

Um CEP dentro do raio: quantos pontos CNEFE dele caem no círculo e a que distância começa.

- `cep` (string) — CEP formatado `NNNNN-NNN`.
- `cep8` (string) — CEP com 8 dígitos, pronto para `/api/empresas` e `/api/cep`.
- `uf` (string) — UF do sqlite que respondeu.
- `pontos` (int) — Endereços CNEFE deste CEP dentro do raio.
- `distancia_m` (int) — Distância do centro ao ponto mais perto deste CEP, em metros.
- `lat` (number) — Latitude média dos pontos deste CEP no raio.
- `lon` (number) — Longitude média dos pontos deste CEP no raio.

### `ContagemCnae`

Uma classe de CNAE no raio.

- `cnae` (int) — Subclasse CNAE (7 dígitos).
- `descricao` (string, pode ser null) — Descrição oficial da subclasse.
- `ativas` (int) — Estabelecimentos ativos neste CNAE no raio.
- `abertas_desde` (int) — Dos ativos, quantos abriram desde `desde`.

### `Abertura`

Um estabelecimento aberto desde `desde`, sem contato e sem sócio.

- `cnpj` (string) — 14 dígitos.
- `cnpjFormatted` (string) — CNPJ com pontuação.
- `nome` (string, pode ser null) — Nome fantasia ou, na falta, razão social.
- `razaoSocial` (string, pode ser null) — Razão social.
- `nomeFantasia` (string, pode ser null) — Nome fantasia declarado na Receita, quando a empresa tem um.
- `cnae` (object, pode ser null) — `codigo` e `descricao` da atividade principal.
- `dataInicio` (string) — Data de início de atividade, ISO.
- `endereco` (object) — `tipoLogradouro`, `logradouro`, `numero`, `bairro`, `cep` formatado.
- `distancia_m` (int, pode ser null) — Distância do centro ao CEP deste estabelecimento.

### `EspecieContagem`

Quantas unidades CNEFE de uma espécie no recorte.

- `codigo` (string, pode ser null) — Código IBGE da espécie (`1`–`8`).
- `label` (string, pode ser null) — Rótulo: domicílio particular, ensino, saúde…
- `n` (int) — Quantas unidades nesta espécie.