# PontoFato — referência completa da API

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

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

## 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://staging.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 header `X-Credito`). Não é conta: é portador de saldo.
- `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

## Endpoints

## Conta

### `GET /api/auth/bootstrap`

Prepara o navegador para entrar na conta global.

Define cookie HttpOnly restrito ao host. CSRF vinculado à sessão atual. Sem CORS.

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

**Resposta `200`**

- `csrf` (string) — X-CSRF-Token
- `context` (string) — Opaque view context, also in X-MM-Context; not a credential / contexto opaco da vista, não é credencial.

**Erros**

- `400` — invalid_request
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved

### `GET /api/account/profile`

Consulta seu perfil global.

Lê preferências atuais da conta. Altere-as na página da conta; produtos não mantêm perfil autoritativo separado.

- **URL:** `https://staging.pontofato.com/api/account/profile`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

{profile:{name,locale,timeZone,theme,revision}}

**Erros**

- `401` — invalid_session
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.pontofato.com/api/account/profile", {credentials: "same-origin"}).then(r => r.json());
```

### `GET /api/account/avatar`

Consulta sua foto de perfil global.

WebP privado de até 64 KiB, sem cache. Altere-o na conta. Não aceita ID de usuário ou URL de objeto.

- **URL:** `https://staging.pontofato.com/api/account/avatar`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

image/webp; Cache-Control: no-store

**Erros**

- `401` — invalid_session
- `404` — not_found: no photo / sem foto
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.pontofato.com/api/account/avatar", {credentials: "same-origin"}).then(r => {if (!r.ok) throw new Error("HTTP " + r.status); return r.blob();});
```

### `GET /api/me`

Lê a conta global atual neste produto.

- **URL:** `https://staging.pontofato.com/api/me`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

{user:{identityId,sessionId,productId,audience,authTime,methods,mfaState}}

**Erros**

- `401` — invalid_session
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.pontofato.com/api/me", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/auth/logout`

Revoga esta sessão do produto.

Exige bootstrap/CSRF deste navegador e sessão. As sessões de outros produtos permanecem ativas.

- **URL:** `https://staging.pontofato.com/api/auth/logout`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_request
- `403` — invalid_origin / invalid_csrf
- `503` — auth_unavailable: a sessão anterior é preservada / the previous session is preserved

**Exemplo**

```js
// Execute no console da página do produto / Run in the product page console.
(async () => {
  const origin = "https://staging.pontofato.com";
  const {csrf} = await fetch(origin + "/api/auth/bootstrap").then(r => r.json());
  const r = await fetch(origin + "/api/auth/logout", {
    method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({})
  });
  if (!r.ok) throw new Error("Auth HTTP " + r.status);
  return r.json();
})();
```

### `GET /api/account/keys`

Lista suas chaves de API neste produto.

Nunca devolve a chave: nome, 4 últimos caracteres, organização, criação, último uso (por hora) e se ainda vale.

- **URL:** `https://staging.pontofato.com/api/account/keys`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

**Resposta `200`**

- `keys` (object[]) — `id`, `name`, `organizationId`, `last4`, `createdAt`, `lastUsedAt`, `revokedAt`, `active` (false quando revogada ou parada por troca de senha / encerrar todos os acessos).

**Erros**

- `401` — invalid_session
- `503` — auth_unavailable

**Exemplo**

```js
await fetch("https://staging.pontofato.com/api/account/keys", {credentials: "same-origin"}).then(r => r.json());
```

### `POST /api/account/keys/create`

Cria uma chave de API para agentes e scripts.

Exige entrada nos últimos 5 minutos; a de organização também exige segundo fator na sessão e o papel de dona/administradora com o produto ligado. No máximo 10 chaves vivas por conta e produto. A chave (`secret`) volta UMA vez.

- **URL:** `https://staging.pontofato.com/api/account/keys/create`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

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

- `name` (string, obrigatório) — Até 60 caracteres.
- `organizationId` (string, obrigatório) — `null` para chave da conta.

**Exemplo de corpo**

```json
{
  "name": "agent",
  "organizationId": null
}
```

**Resposta `200`**

- `key` (object) — `id`, `name`, `organizationId`, `last4`, `createdAt`.
- `secret` (string) — `mmk_…`, mostrada uma vez.

**Erros**

- `400` — invalid_key_name / invalid_organization
- `401` — invalid_session / reauth_required
- `403` — invalid_origin / invalid_csrf / organization_forbidden / organization_mfa_required
- `409` — key_limit_reached
- `503` — auth_unavailable

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://staging.pontofato.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.pontofato.com/api/account/keys/create", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({name: "agent", organizationId: null})});
  return r.json();
})();
```

### `POST /api/account/keys/revoke`

Revoga uma das suas chaves de API.

Para a chave na hora. Repetir não faz mal.

- **URL:** `https://staging.pontofato.com/api/account/keys/revoke`
- **Auth:** `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token.

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

- `id` (string, obrigatório) — O `id` da chave.

**Exemplo de corpo**

```json
{
  "id": "…"
}
```

**Resposta `200`**

- `ok` (bool) — true

**Erros**

- `400` — invalid_key_id
- `401` — invalid_session
- `403` — invalid_origin / invalid_csrf
- `404` — key_not_found
- `503` — auth_unavailable

**Exemplo**

```js
(async () => {
  const {csrf} = await fetch("https://staging.pontofato.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://staging.pontofato.com/api/account/keys/revoke", {method: "POST", credentials: "same-origin",
    headers: {"Content-Type": "application/json", "X-CSRF-Token": csrf},
    body: JSON.stringify({id: "…"})});
  return r.json();
})();
```

## 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://staging.pontofato.com/okf/:arquivo`
- **Auth:** `none` — Público.

**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://staging.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), `x402` (manifesto de pagamento: rede, carteira e rotas que cobram), `agent-card.json` (identidade do agente: ferramentas MCP e portas de descoberta; também em `/agent.json`) e `mcp-registry-auth` (chave do registro oficial de MCP).

- **URL:** `https://staging.pontofato.com/.well-known/:arquivo`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

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

**Resposta `200`**

`application/linkset+json` no api-catalog; `application/json` no x402, no agent-card.json e no apis.json; `text/plain` nos outros dois.

**Erros**

- `404` — Nome fora dos seis publicados.

**Exemplo**

```sh
curl -s https://staging.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://staging.pontofato.com/apis.json`
- **Auth:** `none` — Público.

**Resposta `200`**

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

**Exemplo**

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

### `GET /agent.json`

Cartão do agente: identidade, quem opera, documentação, o endpoint MCP e as ferramentas que ele serve. Mesmo documento de `/.well-known/agent-card.json`.

- **URL:** `https://staging.pontofato.com/agent.json`
- **Auth:** `none` — Público.

**Resposta `200`**

`application/json`: `name`, `provider`, `protocol` (`mcp`), `interfaces[]` e `skills[]`.

**Exemplo**

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

### `GET /okf/:tipo/:id.md`

O mesmo registro que a API responde, em markdown OKF: `cep` (Endereço do CEP — referência 2022). Via de acesso para quem já tem o id, não catálogo.

- **URL:** `https://staging.pontofato.com/okf/:tipo/:id.md`
- **Auth:** `none` — Público.

**Parâmetros de caminho**

- `tipo` (string, obrigatório) — Um de: `cep`. Ex.: `cep`.
- `id` (string, obrigatório) — O id do registro, como a API o aceita. Ex.: `01310100`.

**Resposta `200`**

`text/markdown` com frontmatter OKF; `resource` aponta o JSON equivalente. Sem `.md` responde 301 para o canônico.

**Erros**

- `404` — Id fora da base, em markdown.

**Exemplo**

```sh
curl -s https://staging.pontofato.com/okf/cep/01310100.md
```

### `GET /api/`

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

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

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

Disponibilidade do serviço e cobertura por UF.

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

**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` — Cobertura indisponível.

**Exemplo**

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

### `POST /mcp`

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

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

**Resposta `200`**

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

**Exemplo**

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

### `GET /api/pricing`

Preços vigentes e franquias gratuitas.

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

**Resposta `200`**

- `product` (string) — Product name.
- `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → ver `PaymentQuota` em **Estruturas**.
- `pricing` (string) — Absolute URL of the current price list.
- `billing` (string) — Absolute URL of payment discovery or the existing billing summary.
- `api_index` (string) — Absolute URL of the API catalog.

**Erros**

- `405` — Use GET ou HEAD.

**Exemplo**

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

### `GET /api/billing`

Descoberta pública de pagamento e crédito pré-pago.

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

**Resposta `200`**

- `product` (string) — Product name.
- `quota` (PaymentQuota) — Public allowances and current list prices; not personal usage. → ver `PaymentQuota` em **Estruturas**.
- `pricing` (string) — Absolute URL of the current price list.
- `billing` (string) — Absolute URL of payment discovery or the existing billing summary.
- `api_index` (string) — Absolute URL of the API catalog.
- `payment` (PaymentX402) — Public x402 configuration; pay_to=null means not configured. → ver `PaymentX402` em **Estruturas**.
- `credit` (PaymentCredit) — Prepaid credit entry point. Never contains a balance or token. → ver `PaymentCredit` em **Estruturas**.

**Erros**

- `405` — Use GET ou HEAD.

**Exemplo**

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

## Lugar

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

Endereços de um CEP, com latitude e longitude.

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

**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) — Identificação e crédito da referência dos endereços.
- `cobertura` (Cobertura) — UFs disponíveis nesta consulta. → 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` — Consulta temporariamente indisponível.

**Exemplo**

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

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

Unidades de um CEP, com complemento, tipo e identificador — paginado.

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

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

**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 resultado.
- `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, identificador). → 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 disponíveis nesta consulta. → 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://staging.pontofato.com/api/cep/71940000/unidades?logradouro=RUA%20BURITI&numero=6'
```

### `GET /api/proximo`

Endereço 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://staging.pontofato.com/api/proximo`
- **Auth:** `none` — Público.

**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, 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://staging.pontofato.com/api/proximo?lat=-15.7897&lon=-47.8793'
```

### `GET /api/buscar`

Busca textual de logradouro, com UF e cidade opcionais.

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

**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://staging.pontofato.com/api/buscar?q=paulista&uf=SP'
```

### `GET /api/empresas`

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

- **URL:** `https://staging.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.
- `503` — API de CNPJ indisponível.

**Exemplo**

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

### `GET /api/raio`

CEPs a N metros de um ponto, com distância e quantidade de endereços dentro do raio.

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

**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 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) — Identificação e crédito da referência dos endereços.
- `_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 endereço no raio; `cobertura` diz quais UFs existem.
- `503` — Consulta temporariamente indisponível.

**Exemplo**

```sh
curl -s 'https://staging.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.

Consulte quota.free_now no índice: quando inclui vizinhanca ou *, a operação não cobra nem exige crédito. Com cobrança ativa, a franquia diária vem antes da tarifa por consulta.

- **URL:** `https://staging.pontofato.com/api/vizinhanca`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.

**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 de referência dos registros — 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) — Identificação e crédito das referências utilizadas.
- `_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` — Somente com cobrança ativa e franquia esgotada: use a cotação x402 (`accepts[]`) ou crédito pré-pago (`Authorization: Bearer cred_…`).
- `404` — CEP fora da malha ou nenhum ponto no raio.
- `503` — Consulta temporariamente indisponível.

**Exemplo**

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

## Geo

### `GET /api/local`

Cidade/UF aproximadas de quem chama. Sem cache.

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

**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://staging.pontofato.com/api/contact`
- **Auth:** `none` — Público.

**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 formulário abriu (2 s–12 h). Só o caminho humano exige.
- `tipo` (string) — Proposta: `patrocinio`, `parceria` ou `anuncio`. Liga os campos abaixo.
- `empresa` (string) — Quem propõe, quando é empresa.
- `site` (string) — Site de quem propõe.
- `orcamento` (string) — `ate_100`, `100_500`, `500_2000`, `2000_mais` ou `a_combinar`.
- `espaco` (string[]) — Ids de placement de `GET /api/partners`, até 6.
- `duracao` (string) — Dias de exposição: `30`, `90` ou `365`.
- `pagamento` (string) — `usdc`, `deposito` ou `a_combinar`.

**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://staging.pontofato.com/api/contact -H 'content-type: application/json' -d '{"name":"Agent","email":"a@example.com","message":"hello from agent path"}'
```

## Operação

### `POST /api/erro-cliente`

Relato de erro do navegador, enviado pela própria interface. Agente não precisa chamar.

A interface relata sozinha erro de JS, promessa rejeitada, script/CSS que não carregou e bloqueio de CSP — uma vez por sessão — e o app relata falha tratada por `window.mmErro.relata`. O servidor valida o envelope, redige credencial, e-mail e telefone, junta repetições da mesma falha por minuto e registra um evento operacional; nada é gravado em banco. Não guarda IP, cookie, query nem o User-Agent inteiro. Responde 204 sempre, inclusive para relato inválido.

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

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

- `code` (string, obrigatório) — Código da falha, `UI-` + letras/dígitos (`UI-JS-001` erro global, `UI-PROMESSA-001`, `UI-RECURSO-001`, `UI-CSP-001`, `UI-APP-001` relato do app).
- `phase` (string, obrigatório) — Fase em que quebrou, minúsculas: `global`, `promessa`, `script`, `carregar_lista`…
- `path` (string) — Caminho da página aberta, sem query.
- `message` (string) — Mensagem do erro, até 2000 caracteres.
- `stack` (string) — Stack trace, até 12000 caracteres.
- `source` (string) — Script de origem; só o caminho é guardado.
- `line` (int) — Linha no script de origem.
- `column` (int) — Coluna no script de origem.
- `visivel` (bool) — Se a aba estava visível quando quebrou.

**Exemplo de corpo**

```json
{
  "code": "UI-APP-001",
  "phase": "carregar_lista",
  "path": "/",
  "message": "lista 500"
}
```

**Resposta `200`**

204 sem corpo, sempre — relato inválido, repetido ou acima do teto também recebe 204.

**Exemplo**

```sh
curl -s -XPOST https://staging.pontofato.com/api/erro-cliente -H 'content-type: application/json' -d '{"code":"UI-APP-001","phase":"carregar_lista","path":"/","message":"lista 500"}'
```

### `POST /api/pagamento/aberto`

A interface relata que exibiu uma cobrança. Agentes não devem chamar.

Relato sem corpo, da mesma origem, enviado automaticamente quando uma cobrança fica visível. Não inicia pagamento, não concede acesso e não recebe identidade ou credencial. Não grava banco por relato. Conta eventos, não pessoas únicas. O painel privado do operador separa pedidos de pagamento da API e aberturas da interface por dia UTC; os dois números podem se sobrepor.

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

**Headers**

- `Origin` (string, obrigatório) — A origem da página, idêntica à desta rota.
- `Sec-Fetch-Site` (string, obrigatório) — `same-origin`, definido pelo navegador.
- `X-MM-Payment-View` (string, obrigatório) — `1`, definido pelo componente comum.

**Resposta `202`**

202 sem corpo se aceito; 204 se ignorado. Sempre no-store.

### `POST /api/visit`

Ping da interface que soma a visita do dia. Agente não precisa chamar.

A página manda ao primeiro sinal humano (toque, tecla ou clique), uma vez por página. Smoke não conta: `X-MM-Smoke`, User-Agent `mm-smoke` ou `smoke: true` no corpo voltam `counted: false`.

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

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

- `p` (string) — Caminho da página visitada.
- `smoke` (bool) — `true` marca a chamada como teste e ela não entra na conta.

**Exemplo de corpo**

```json
{
  "p": "/"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true`.
- `counted` (bool) — Se a visita entrou na conta do dia.
- `reason` (string, opcional) — Por que não contou, quando `counted` é `false`.

**Exemplo**

```sh
curl -s -XPOST https://staging.pontofato.com/api/visit -H 'content-type: application/json' -d '{"p":"/","smoke":true}'
```

### `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 vêm do `POST /api/visit`, o ping ao primeiro sinal humano, em `today_visits` e em `days[].visits`. Com `METRICS_TOKEN` em Bearer acrescenta `payments` — só x402 liquidado em Base mainnet.

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

**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) — Visitas da interface hoje: pings de `POST /api/visit`, um por página ao primeiro sinal humano.
- `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://staging.pontofato.com/api/metrics -H "Authorization: Bearer $METRICS_TOKEN"
```

## Números públicos

### `GET /api/vitrine`

Os números públicos do produto: tráfego, agentes, uso e confiabilidade, sem dinheiro.

Projeção publicada de hora em hora pelo coletor da casa, arredondada a dois dígitos significativos; `null` é medição ausente, nunca zero. Cache de 15 minutos com ETag (`If-None-Match` → 304). Não há como enviar números por esta rota: a publicação é do coletor, com token próprio.

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

**Resposta `200`**

- `v` (int) — Versão do contrato (1).
- `produto` (string) — Id do produto.
- `publicado` (bool) — `false` antes da primeira publicação do coletor; aí só estas cinco chaves vêm.
- `atualizado_em` (string, pode ser null) — Quando o coletor publicou (ISO 8601).
- `stale` (bool) — `true` quando a projeção tem mais de 26 h.
- `nome` (string, opcional) — Nome do produto.
- `desde` (string, opcional, pode ser null) — Dia a partir do qual a série vale.
- `fuso` (string, opcional) — Fuso dos dias (`UTC`).
- `hoje` (object, opcional) — O dia de hoje: páginas por classe (pessoa, IA, bot), chamadas de API por classe, leituras das superfícies de máquina e uso do produto.
- `dias` (object[], opcional) — Até 31 dias, o mais antigo primeiro: `dia`, `paginas`, `api`, `api_ia`, `maquina`, `visitantes`, `uso`.
- `janelas` (object, opcional) — Somas de 7 e 30 dias (`d7`, `d30`).
- `visitantes` (object, opcional) — Visitantes únicos na borda em 7 dias.
- `pessoas` (object, opcional, pode ser null) — GA4 quando há: usuários, sessões, países, aparelhos e quem chegou de IA.
- `agentes` (object, opcional) — Os agentes de IA e os bots que mais leem, 7 dias.
- `superficies` (object, opcional) — Leituras de OKF, llms, well-known, OpenAPI e MCP em 7 dias.
- `mcp` (object, opcional) — Chamadas MCP em 7 dias.
- `uso` (object, opcional) — Uso real do produto por recurso: rótulo, hoje, 7 e 30 dias.
- `contas` (object, opcional, pode ser null) — Usuários e convidados.
- `confiabilidade` (object, opcional) — Percentual de pedidos sem 5xx em 7 dias e o build no ar.
- `catalogo` (object, opcional, pode ser null) — Tamanho do acervo, quando o produto tem um.
- `apoio` (object, opcional) — Impressões e cliques por patrocinador, quando houver.

**Exemplo**

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

### `GET /api/vitrine/operador`

O documento completo do produto no painel do operador — só com o token do operador.

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

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>` — a classe operador.

**Resposta `200`**

- `produto` (string) — Id do produto.
- `atualizado_em` (string, pode ser null) — Quando o coletor publicou.
- `operador` (object, pode ser null) — O documento completo do coletor, com o que a projeção pública não carrega.

**Erros**

- `401` — Sem token, token errado ou token de outra classe.
- `503` — Worker sem `METRICS_TOKEN` ou sem o control plane.

**Exemplo**

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

### `GET /api/vitrine/painel`

O painel da casa inteira, na forma que o gm lê — só com o token do operador.

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

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>` — a classe operador.

**Resposta `200`**

- `apps` (object[]) — Um documento do operador por produto, em ordem de id.
- `updated` (string, opcional) — Quando o coletor fechou a rodada.
- `totals` (object, opcional) — Os totais da casa.

**Erros**

- `401` — Sem token, token errado ou token de outra classe.
- `503` — Worker sem `METRICS_TOKEN` ou sem o control plane.

**Exemplo**

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

### `GET /api/vitrine/cursores`

O cursor de erro resolvido por produto (`borda`, `cli`) — só com o token do operador.

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

**Headers**

- `Authorization` (string, obrigatório) — `Bearer <METRICS_TOKEN>` — a classe operador.

**Resposta `200`**

JSON: `{ [produto]: { borda?: ISO, cli?: ISO } }`; vazio é `{}`.

**Erros**

- `401` — Sem token, token errado ou token de outra classe.
- `503` — Worker sem `METRICS_TOKEN` ou sem o control plane.

**Exemplo**

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

## Parceria

### `GET /api/partners`

Parceria, patrocínio e anúncio: os espaços do produto com preço sugerido, os números públicos ao lado e como propor.

Informação sob consulta, sem ativação: espaços do catálogo da casa com preço em USD por 30 dias (90 e 365 dias com desconto), patrocinadores em vigor, recorte de `/api/vitrine`, carteira da casa (USDC na Base) e o caminho de contato — depósito, PIX ou fatura são combinados na resposta. Cache de 1 hora.

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

**Resposta `200`**

- `status` (string) — `sob_consulta`: informação e proposta, sem ativação nem cobrança.
- `produto` (string) — Nome do produto.
- `idioma` (string) — Idioma dos textos (o do produto).
- `titulo` (string) — Título da oferta.
- `descricao` (string) — Uma frase sobre a oferta.
- `publico` (string) — Quem usa o produto — o público que o patrocinador alcança.
- `modalidades` (object[]) — `{ id, nome }`: patrocinio, parceria, anuncio.
- `placements` (object[]) — Os espaços do produto: `id`, `nome`, `onde`, `formato`, `exclusivo`, `medicao`, `price_usd_30d` (sugestão; `null` é sob consulta), `exposure[{ dias, price_usd }]` para 30, 90 e 365 dias, `disponivel`.
- `house_bundle` (object) — O pacote da casa: rodapé e menção para agentes nos dez produtos, com desconto.
- `parcerias` (string[]) — Ideias de parceria que o produto aceita discutir.
- `current_sponsors` (object[]) — Patrocinadores em vigor: `id`, `nome`, `url`, `frase`, `espacos`, `ate`.
- `stats` (object) — Recorte dos números públicos (`hoje`, `janelas`, `agentes`, `confiabilidade`) e o `link` para `/api/vitrine`; `publicado: false` antes da primeira publicação.
- `payment` (object) — Como pagar: `rede`, `chain_id`, `ativo`, `pay_to`, `eip681` (a carteira da casa, quando declarada), `alternativas` e a `nota` — depósito, PIX ou fatura pela resposta.
- `contact` (object) — `email`, `form_url`, `api_url` (`POST /api/contact` onde há handler), `campos` (os obrigatórios), `campos_proposta` (os opcionais da proposta, com os valores aceitos de cada um), `price_agent_usd`, `message_template`, `instructions`.
- `politica` (object) — Rótulo do espaço, setores recusados, pagamento adiantado, prazos.
- `_links` (object) — `self`, `stats`, `page` (`null` até a página existir), `contact`, `casa` (o mesmo caminho nos dez produtos).

**Exemplo**

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

## 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://staging.pontofato.com/api/credito`
- **Auth:** `none` — Público.

**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://staging.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://staging.pontofato.com/api/credito`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.

**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://staging.pontofato.com/api/credito -H 'Authorization: Bearer cred_…'
```

## API access

### `GET /api/acesso`

Discover the monthly data package or inspect a private purchase.

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

**Headers**

- `X-API-Pass` (string) — Private pass: api_<32 random hex>_<64 random hex>. Save before buying.

**Resposta `200`**

Estrutura: `ApiAccess`.

- `offer` (ApiAccessOffer) — Current offer and payment instructions. → ver `ApiAccessOffer` em **Estruturas**.
- `enabled` (bool, opcional) — Present in public discovery; false means no purchases.
- `id` (string, opcional) — Purchase ID; not a credential.
- `status` (string, opcional) — paid, unpaid or pending.
- `granted_credits` (int, opcional) — Original grant, not remaining usage.
- `expires_at` (string, opcional, pode ser null) — ISO expiry, 30 days after purchase.
- `receipt` (string, opcional, pode ser null) — Confirmed payment receipt.
- `via` (string, opcional, pode ser null) — x402, credito or gated homolog.
- `message` (string, opcional) — Next action in the requested language.

**Erros**

- `400` — Invalid pass.
- `404` — Unknown purchase or wrong owner.
- `503` — Purchases disabled.

**Exemplo**

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

### `POST /api/acesso`

Buy 1000 basic data reads for US$1, valid for 30 days.

Same pass in retries recovers the same purchase. No automatic renewal. OCR, AI, documents and delivery keep their own tariffs. Send X-API-Pass on eligible data reads; remaining credits come in X-API-Credits-Remaining.

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

**Headers**

- `X-API-Pass` (string, obrigatório) — Private pass: api_<32 random hex>_<64 random hex>. Save before buying.
- `X-Credito` (string) — Existing prepaid credit token; alternative to x402.
- `Authorization` (string) — Bearer cred_… alternative to X-Credito.
- `X-PAYMENT` (string) — Signed x402 authorization from the 402 quote, maximum 16 KiB.
- `PAYMENT-SIGNATURE` (string) — Alternative name for X-PAYMENT.
- `X-API-Transaction` (string) — Confirmed Base transaction hash for reconciliation with the original pass and signed payment. Never creates another charge.

**Resposta `200`**

Estrutura: `ApiAccess`.

- `offer` (ApiAccessOffer) — Current offer and payment instructions. → ver `ApiAccessOffer` em **Estruturas**.
- `enabled` (bool, opcional) — Present in public discovery; false means no purchases.
- `id` (string, opcional) — Purchase ID; not a credential.
- `status` (string, opcional) — paid, unpaid or pending.
- `granted_credits` (int, opcional) — Original grant, not remaining usage.
- `expires_at` (string, opcional, pode ser null) — ISO expiry, 30 days after purchase.
- `receipt` (string, opcional, pode ser null) — Confirmed payment receipt.
- `via` (string, opcional, pode ser null) — x402, credito or gated homolog.
- `message` (string, opcional) — Next action in the requested language.

**Erros**

- `400` — Missing or invalid pass/payment.
- `401` — Invalid prepaid credit.
- `402` — Payment required: x402 accepts[] and prepaid-credit instructions.
- `409` — Payment pending; retain the same pass and do not pay again.
- `429` — Purchase attempt limit; respect Retry-After.
- `503` — Payment unavailable or pending reconciliation.

**Exemplo**

```sh
curl -s -X POST "https://staging.pontofato.com/api/acesso" -H "X-API-Pass: $API_PASS"
```

## Estruturas

### `Saude`

Disponibilidade da consulta e cobertura atual.

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

Endereços 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) — Identificação e crédito da referência dos endereços.
- `cobertura` (Cobertura) — UFs disponíveis nesta consulta. → ver `Cobertura` em **Estruturas**.
- `_links` (object) — `self`, `empresas` e `unidades` absolutos.

### `Unidades`

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

- `cep` (string) — CEP formatado.
- `items` (Ponto[]) — Unidades desta página (complemento, espécie, identificador). → 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 disponíveis nesta consulta. → ver `Cobertura` em **Estruturas**.
- `_links` (object) — `self` desta página e `cep` do lookup.

### `Proximo`

Endereço 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, 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`

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.

### `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 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) — Identificação e crédito da referência dos endereços.
- `_links` (object) — `self` e `vizinhanca` com o mesmo centro e raio.

### `Vizinhanca`

Empresas nos CEPs dentro do raio: contagens, atividades 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 de referência dos registros — 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) — Identificação e crédito das referências utilizadas.
- `_links` (object) — `self` e `raio` com o mesmo centro.

### `Local`

Localização aproximada do visitante. Nunca é cacheada.

- `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) — Visitas da interface hoje: pings de `POST /api/visit`, um por página ao primeiro sinal humano.
- `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.

### `ApiAccess`

- `offer` (ApiAccessOffer) — Current offer and payment instructions. → ver `ApiAccessOffer` em **Estruturas**.
- `enabled` (bool, opcional) — Present in public discovery; false means no purchases.
- `id` (string, opcional) — Purchase ID; not a credential.
- `status` (string, opcional) — paid, unpaid or pending.
- `granted_credits` (int, opcional) — Original grant, not remaining usage.
- `expires_at` (string, opcional, pode ser null) — ISO expiry, 30 days after purchase.
- `receipt` (string, opcional, pode ser null) — Confirmed payment receipt.
- `via` (string, opcional, pode ser null) — x402, credito or gated homolog.
- `message` (string, opcional) — Next action in the requested language.

### `PaymentQuota`

- `free` (PaymentFree[]) — Free allowances and their windows. → ver `PaymentFree` em **Estruturas**.
- `paid` (PaymentPrice[]) — List prices in USD. The operation's 402 is the payable quote. → ver `PaymentPrice` em **Estruturas**.
- `how_to_pay` (string) — Payment instructions and availability restrictions.
- `live` (string, pode ser null) — Authoritative product quota endpoint.
- `free_now` (string[], opcional) — SKUs temporarily free despite their list price.
- `trial` (PaymentTrial, opcional) — Registration trial, when offered. → ver `PaymentTrial` em **Estruturas**.

### `PaymentX402`

x402 payment configuration in force. Comes from `planPublic` and is the same across the products.

- `provider` (string) — Always `x402` — the only billing protocol accepted.
- `mode` (string) — Seller mode: `live` charges for real, `dev` lets calls through unpaid.
- `network` (string) — USDC network: `base` in production, `base-sepolia` in staging.
- `chain_id` (int) — EVM chain ID of the network above, so the wallet signs on the right chain.
- `pay_to` (string, pode ser null) — Address that receives the payment.
- `homolog` (bool) — Staging seam on: the loop can be closed without spending USDC.
- `dev` (bool) — Development mode: the 402 is simulated.
- `dev_gate` (bool) — A homologation credential is configured; this grants no access.
- `gratis` (string[], opcional) — Temporarily free SKUs.
- `facilitator` (string) — URL of the facilitator that verifies and settles the payment.
- `asset` (string) — Accepted currency — always `USDC`.
- `asset_address` (string) — USDC contract on the network above.
- `faucet` (string, pode ser null) — Test-USDC faucet; only on base-sepolia.
- `wallets` (object) — Links to wallets that speak x402 (metamask, coinbase, base_app).

### `PaymentCredit`

- `url` (string) — POST to purchase credit; GET with X-Credito to inspect its balance.
- `header` (string) — Header for a previously issued credit token: X-Credito.

### `Cobertura`

Quais UFs estão disponíveis para consulta.

- `ufs` (string[]) — Siglas disponíveis, em ordem.
- `completa` (bool) — `true` só com as 27 UFs.

### `Ponto`

Um endereço com número, coordenadas e características disponíveis.

- `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 endereço, 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 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 de referência do resultado.

### `Resumo`

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

- `address_count` (int) — Unidades 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 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.

### `CepNoRaio`

Um CEP dentro do raio: quantos endereços 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 de referência do resultado.
- `pontos` (int) — Endereços 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 cadastrado, quando disponível.
- `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.

### `ApiAccessOffer`

- `id` (string) — Package identifier.
- `price_usd` (number) — Price in USD.
- `credits` (int) — Basic reads included.
- `days` (int) — Validity after payment, in days.
- `auto_renew` (bool) — False: the client explicitly buys another package.
- `unit` (string) — basic_data_read; one page of up to 20 metadata records.
- `products` (string[]) — Data indexes sharing the same package.
- `purchase` (string) — Absolute purchase URL.
- `method` (string) — HTTP method for the explicit package purchase: POST.
- `status` (string) — GET with X-API-Pass checks the private purchase status.
- `header` (string) — X-API-Pass.
- `payment_methods` (string[]) — x402 or prepaid_credit.
- `instructions` (string) — Generate and retain the pass before payment.
- `generate_pass` (string) — JavaScript example using cryptographic randomness.
- `client` (string, pode ser null) — Auditable ES module client; orchestrates purchase and data retry with caller-owned wallet and durable state.
- `guide` (string, pode ser null) — Client setup, explicit budget, recovery and data value.
- `workflow` (ApiAccessWorkflow) — Machine-readable purchase and recovery contract. → ver `ApiAccessWorkflow` em **Estruturas**.
- `evaluation` (object, pode ser null) — Free evaluation: register URL, X-Agent-Pass header, 1,000 reads per product, 30 days, no renewal. Registration grants independent quotas on the three indexes; preserve the credential.

### `PaymentFree`

- `o_que` (string) — Operation or allowance.
- `limite` (string) — Allowance and eligibility.
- `janela` (string, pode ser null) — Reset window, when applicable.

### `PaymentPrice`

- `o_que` (string) — Operation and billing unit.
- `price_usd` (number) — Current list price in USD.

### `PaymentTrial`

- `days` (int) — Trial duration in days.
- `how` (string) — Eligibility and activation steps.

### `EspecieContagem`

Quantas unidades 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.

### `ApiAccessWorkflow`

- `version` (int) — Workflow version.
- `kind` (string) — package_then_retry: buy at purchase, then retry the original data URL.
- `purchase_requires_authority` (bool) — The client needs an explicit spending budget.
- `retry_same_pass` (bool) — Persist the pass and original signed proof before submitting.
- `on_unknown_payment` (string) — Query the purchase or reconcile the original proof; never sign again automatically.


## Acervos públicos de dados

Explore endereços e compras por lugar e abra os registros de que precisa. Até 20 itens por página, em formatos prontos para pessoas e agentes. Confira a cobertura e a data de referência antes de usar um resultado. Cada produto informa suas opções de acesso.

- [CEPs e endereços](https://api.pontofato.com/enderecos/index.json): Encontre endereços por lugar, com coordenadas e referência de 2022. Não certifica CEP vigente. UF → município → bairro/localidade → rua → endereços. [HTML](https://api.pontofato.com/enderecos/) · [llms.txt](https://api.pontofato.com/enderecos/llms.txt) · [OKF](https://api.pontofato.com/enderecos/okf/index.md)
- [Editais e compras públicas](https://api.editalmd.com/licitacoes/index.json): Encontre compras públicas por lugar e período. Consulte documentos e opções de leitura no EditalMD. Modalidade → UF → ano → mês → dia → município → compras. [HTML](https://api.editalmd.com/licitacoes/) · [llms.txt](https://api.editalmd.com/licitacoes/llms.txt) · [OKF](https://api.editalmd.com/licitacoes/okf/index.md)