# Radar CNPJ — referência completa da API

> Gerada do catálogo em https://exf.ia.br · build `1c0a45eb`
> 57 endpoints · 27 estruturas
> Índice curto: https://exf.ia.br/llms.txt · Spec: https://exf.ia.br/openapi.json · MCP: https://exf.ia.br/mcp

> Pesquise empresas por atividade e lugar; consulte fichas e acompanhe mudanças.

## 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://exf.ia.br/llms-full.txt?prefix=/api/` devolve só aquele ramo.

## Autenticação

- `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.
- `none` — Público (algumas rotas de origem podem restringir por geo BR).
- `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.
- `token` — Token de operador `METRICS_TOKEN` em `Authorization: Bearer`.

## 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://exf.ia.br/api/auth/bootstrap`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/api/account/profile`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```js
await fetch("https://exf.ia.br/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://exf.ia.br/api/account/avatar`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**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://exf.ia.br/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://exf.ia.br/api/me`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Resposta `200`**

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

**Erros**

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

**Exemplo**

```js
await fetch("https://exf.ia.br/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://exf.ia.br/api/auth/logout`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**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://exf.ia.br";
  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://exf.ia.br/api/account/keys`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**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://exf.ia.br/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://exf.ia.br/api/account/keys/create`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**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://exf.ia.br/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://exf.ia.br/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://exf.ia.br/api/account/keys/revoke`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**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://exf.ia.br/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://exf.ia.br/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://exf.ia.br/okf/:arquivo`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/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://exf.ia.br/.well-known/:arquivo`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/.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://exf.ia.br/apis.json`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

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

**Exemplo**

```sh
curl -s https://exf.ia.br/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://exf.ia.br/agent.json`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

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

**Exemplo**

```sh
curl -s https://exf.ia.br/agent.json
```

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

O mesmo registro que a API responde, em markdown OKF: `cnpj` (Empresa por CNPJ, na base da Receita). Via de acesso para quem já tem o id, não catálogo.

- **URL:** `https://exf.ia.br/okf/:tipo/:id.md`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Parâmetros de caminho**

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

**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://exf.ia.br/okf/cnpj/00000000000191.md
```

### `GET /api/`

Índice da API, com operações, formatos, autenticação e limites.

- **URL:** `https://exf.ia.br/api/`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

- `name` (string) — Nome do produto.
- `description` (string) — O que o produto faz, em uma frase.
- `build` (string) — Commit publicado.
- `base_url` (string) — Origem em que esta API está servindo.
- `origin_api` (string) — Endereço público da API de dados do produto.
- `docs` (object) — Links para llms.txt, llms-full.txt, openapi.json, MCP e a UI.
- `conventions` (object) — Formato de erro, CORS, x402 e a regra de paridade UI↔API.
- `auth` (object) — Cada modo de autenticação e como obtê-lo.
- `endpoints` (object[]) — Todo endpoint com método, caminho, auth, URL absoluta e o que devolve.
- `quota` (object) — O que é grátis, o que custa e como pagar.
- `mcp` (object) — Endereço e transporte do servidor MCP.
- `mcp_tools` (string[]) — Nome de cada tool do MCP.
- `quickstart` (string[]) — As chamadas que levam da ideia à lista de empresas.

### `GET /api/health`

Disponibilidade e data de referência dos registros.

`import.dump_date` informa a data de referência e `import.counts` traz as contagens disponíveis. A consulta não confirma mudanças em tempo real.

- **URL:** `https://exf.ia.br/api/health`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

Estrutura: `SaudeOrigem`.

- `ok` (bool) — Sempre `true` quando a origem responde.
- `service` (string) — Qual serviço respondeu.
- `db` (string) — Estado do banco: `up` ou o motivo de não estar.
- `import` (object) — `dump_date`, `loaded_at` e as contagens por tabela — é a idade real do dado.

### `POST /mcp`

Servidor MCP por HTTP (Streamable HTTP, JSON-RPC 2.0) — pluga no cliente sem instalar nada.

As tools são as operações deste mesmo catálogo; o MCP não tem backend próprio. `GET /mcp` devolve o cartão do servidor.

- **URL:** `https://exf.ia.br/mcp`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).
- Credencial vai nos headers de sempre (X-Guest-Token, Authorization, X-PAYMENT) e é repassada à API.
- Cota estourada chega como 402 com accepts[] dentro do resultado da tool — pague e repita.

**Resposta `200`**

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

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/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://exf.ia.br/api/pricing`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/api/pricing
```

### `GET /api/billing`

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

- **URL:** `https://exf.ia.br/api/billing`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/api/billing
```

## Avaliar ideia

### `POST /api/avaliar`

Descreva uma atividade e um lugar para consultar as empresas registradas nesse recorte.

É o primeiro produto da home. Devolve o CNAE a que a ideia foi mapeada, quantas empresas ativas, abertas e baixadas existem no recorte, como elas se formalizam e uma leitura honesta disso. **Não inventa volume de busca** e não promete demanda: `ficha.limites` diz o que os números não dizem. Renda passiva isto não é.

- **URL:** `https://exf.ia.br/api/avaliar`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

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

- `texto` (string, obrigatório) — A ideia em 3 a 400 caracteres.
- `uf` (string) — Hint de estado; só entra se a IA não resolver o lugar sozinha. Ex.: `SP`.
- `municipio` (int) — Hint de município (código IBGE); mesma regra do `uf`.

**Exemplo de corpo**

```json
{
  "texto": "padaria em Campinas",
  "uf": "SP",
  "municipio": 6291
}
```

**Resposta `200`**

Estrutura: `Avaliacao`.

- `ok` (bool) — Sempre `true` quando a avaliação saiu.
- `texto` (string) — A ideia como você a escreveu.
- `cnae` (string, pode ser null) — CNAE a que a ideia foi mapeada.
- `fonte_cnae` (string) — Como o CNAE foi determinado: pela IA ou pelo hint que você mandou.
- `filtros` (object[]) — Os filtros normalizados que a avaliação aplicou — dá para reusar em `GET /api/busca`.
- `ficha` (FichaOferta) — O retrato da oferta formal e a leitura honesta dela. → ver `FichaOferta` em **Estruturas**.

**Erros**

- `400` — Texto fora de 3–400 caracteres, ou corpo que não é JSON.
- `405` — Só POST nesta rota.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/avaliar -H 'content-type: application/json' -d '{"texto":"padaria em Campinas"}'
```

## Consulta

### `GET /api/cnpj/:cnpj`

A ficha cadastral de uma empresa, pelos 14 dígitos do CNPJ, com o dado pessoal mascarado.

Nome de sócio pessoa física (`LUIS F. R. P.`), telefones e e-mail vêm mascarados, com `data.mascarado: true`; sócio empresa vem inteiro. O dado completo sai por `POST /api/revelar/:cnpj`. A resposta pode ser reutilizada por até 6 horas; confira a data de referência dos registros.

- **URL:** `https://exf.ia.br/api/cnpj/:cnpj`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Parâmetros de caminho**

- `cnpj` (string, obrigatório) — CNPJ com 14 dígitos, sem pontuação. Ex.: `00000000000191`.

**Resposta `200`**

Estrutura: `FichaCnpj`.

- `ok` (bool) — Sempre `true` quando o CNPJ existe na base.
- `data` (object) — O cadastro: identificação, endereço, contato, sócios, CNAEs, Simples e situação. Com `mascarado: true`, o nome de sócio pessoa física sai como `LUIS F. R. P.` (sem documento) e `contato` mostra só parte dos telefones e do e-mail.

**Erros**

- `400` — CNPJ que não tem 14 dígitos.
- `404` — CNPJ não existe na base.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/cnpj/00000000000191
```

### `POST /api/revelar/:cnpj`

Revela o dado pessoal da ficha — nomes dos sócios, telefones e e-mail sem máscara. Pago por empresa.

Custa US$ 0,10 por empresa: desconta do crédito pré-pago (`Authorization: Bearer cred_…`) ou paga só esta revelação com x402 (`X-PAYMENT`). O mesmo código de crédito revendo a mesma empresa no mesmo dia (horário de Brasília) não paga de novo; o x402 avulso cobra cada revelação. CNPJ inexistente ou consulta que falha não cobra nada. A resposta não vai para cache.

- **URL:** `https://exf.ia.br/api/revelar/:cnpj`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.

**Parâmetros de caminho**

- `cnpj` (string, obrigatório) — CNPJ com 14 dígitos, sem pontuação. Ex.: `00000000000191`.

**Headers**

- `authorization` (string) — `Bearer cred_…`, o token do crédito pré-pago. Sem ele (e sem `X-PAYMENT`), a resposta é o 402 do x402.
- `x-payment` (string) — Pagamento x402 assinado (base64), para pagar só esta revelação.

**Resposta `200`**

Estrutura: `FichaRevelada`.

- `ok` (bool) — Sempre `true` quando a revelação foi entregue.
- `data` (object) — O mesmo cadastro de `GET /api/cnpj/:cnpj`, com `socios[].nome`, `socios[].documento` e `contato` inteiros e `mascarado: false`.
- `cobranca` (object) — `via` (`credito`, `x402` ou `gratis`), `preco_usd`, `saldo_usd` (só no crédito) e `repetido` (`true` quando o mesmo código de crédito já tinha revelado esta empresa hoje e nada foi cobrado).

**Erros**

- `400` — CNPJ que não tem 14 dígitos.
- `401` — Token de crédito desconhecido.
- `402` — Sem pagamento ou com saldo insuficiente: o corpo traz `accepts[]` do x402 e como recarregar o crédito.
- `404` — CNPJ não existe na base.
- `502` — A consulta falhou; nada foi cobrado.
- `503` — Revelação fora do ar; nada foi cobrado.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/revelar/00000000000191 -H "Authorization: Bearer $CREDITO"
```

### `GET /api/busca`

Busca empresas por termo e/ou filtros avançados, paginada.

Exige termo OU pelo menos um filtro — varrer 71 milhões de estabelecimentos sem recorte não é uma busca, é um dump.

- **URL:** `https://exf.ia.br/api/busca`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Query**

- `q` (string) — Termo de busca, entre 2 e 120 caracteres. Ex.: `padaria`.
- `f` (string) — Filtros avançados em JSON (CNAE, situação, porte, data de abertura). Ex.: `{"uf":"SP"}`.
- `tipo` (string) — Que campo o termo procura: `nome` (razão social, o padrão), `fantasia`, `socio`, `telefone` (com DDD, 10 ou 11 dígitos), `endereco` ou `cnae`. Ex.: `telefone`.
- `uf` (string) — Restringe a uma unidade da federação. Ex.: `SP`.
- `page` (int) — Página, começando em 0. Padrão: `0`.
- `pageSize` (int) — Resultados por página, de 1 a 50. Padrão: `20`.

**Resposta `200`**

Estrutura: `PaginaDeBusca`.

- `ok` (bool) — Sempre `true` quando a busca rodou.
- `page` (int) — Página devolvida, começando em 0.
- `pageSize` (int) — Quantos resultados por página.
- `hasMore` (bool) — Se existe página seguinte.
- `results` (Empresa[]) — As empresas desta página. → ver `Empresa` em **Estruturas**.

**Erros**

- `400` — `busca_vazia` (sem termo nem filtro), `termo_invalido` (fora de 2–120) ou `filtros_invalidos`.

**Exemplo**

```sh
curl -s 'https://exf.ia.br/api/busca?q=padaria&uf=SP&pageSize=5'
```

### `GET /api/export`

Exporta o resultado da busca em CSV ou JSON, com os mesmos filtros dela.

Duas formas na mesma rota. Com `format=json` a resposta é o envelope descrito abaixo — é o que um agente usa. Com `format=csv` (o padrão) vem o arquivo: content-type e content-disposition são repassados da origem, para o browser baixar direto do link. `capped` avisa quando o export bateu no teto e não trouxe tudo.

- **URL:** `https://exf.ia.br/api/export`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Query**

- `q` (string) — Termo de busca, entre 2 e 120 caracteres. Ex.: `padaria`.
- `f` (string) — Filtros avançados em JSON (CNAE, situação, porte, data de abertura). Ex.: `{"uf":"SP"}`.
- `tipo` (string) — Que campo o termo procura: `nome` (razão social, o padrão), `fantasia`, `socio`, `telefone` (com DDD, 10 ou 11 dígitos), `endereco` ou `cnae`. Ex.: `telefone`.
- `uf` (string) — Restringe a uma unidade da federação. Ex.: `SP`.
- `format` (string) — Formato do arquivo. Padrão: `csv`. Valores: `csv`, `json`.

**Resposta `200`**

Estrutura: `Export`.

- `ok` (bool) — Sempre `true` quando o export saiu.
- `count` (int) — Quantas empresas o arquivo traz.
- `capped` (bool) — `true` quando o export bateu no teto da origem e não trouxe tudo — o número acima não é o total do filtro.
- `results` (Empresa[]) — As empresas exportadas. → ver `Empresa` em **Estruturas**.

**Erros**

- `400` — `formato_invalido`, ou os mesmos erros de `GET /api/busca`.

**Exemplo**

```sh
curl -s 'https://exf.ia.br/api/export?q=padaria&uf=SP&format=json'
```

### `GET /api/sugerir`

Autocomplete de empresas e termos, para montar a lista enquanto a pessoa digita.

Não conta como visita nas métricas — senão o painel mediria tecla, não gente.

- **URL:** `https://exf.ia.br/api/sugerir`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Query**

- `q` (string, obrigatório) — O que já foi digitado. Ex.: `padar`.
- `limit` (int) — Quantas sugestões devolver, de 1 a 50. Padrão: `10`.

**Resposta `200`**

Estrutura: `ListaSugestao`.

- `ok` (bool) — Sempre `true`.
- `results` (object[]) — As sugestões, cada uma com o texto e o que ela identifica.

**Erros**

- `400` — `q` ausente ou curto demais.

**Exemplo**

```sh
curl -s 'https://exf.ia.br/api/sugerir?q=padar&limit=5'
```

### `GET /api/ref`

Vocabulários oficiais para montar seletor: CNAE, município e natureza jurídica.

Ou você busca por texto (`q`) ou resolve códigos que já tem (`codigos`) — `codigos` ganha quando os dois vêm.

- **URL:** `https://exf.ia.br/api/ref`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Query**

- `tipo` (string, obrigatório) — Qual vocabulário consultar. Valores: `cnae`, `municipio`, `natureza`.
- `q` (string) — Texto a procurar no vocabulário, até 60 caracteres. Ex.: `padaria`.
- `codigos` (string) — Códigos separados por vírgula, para resolver os nomes deles. Ex.: `4721102,4712100`.

**Resposta `200`**

Estrutura: `ListaReferencia`.

- `ok` (bool) — Sempre `true`.
- `results` (ItemReferencia[]) — Os itens que casam com a consulta. → ver `ItemReferencia` em **Estruturas**.

**Erros**

- `400` — `tipo` ausente ou fora da lista.

**Exemplo**

```sh
curl -s 'https://exf.ia.br/api/ref?tipo=cnae&q=padaria'
```

## IA

### `POST /api/ia`

Transforma um texto livre nos filtros normalizados que a busca aceita.

Caminho síncrono: leva de 18 a 20 segundos. Quando estoura o tempo, use `POST /api/ia/jobs`.

- **URL:** `https://exf.ia.br/api/ia`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

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

- `texto` (string, obrigatório) — A descrição em linguagem natural do que você procura.

**Exemplo de corpo**

```json
{
  "texto": "padarias em SP com MEI"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando a IA respondeu.
- `filtros` (object[]) — Os filtros normalizados, prontos para virar o `f` de `GET /api/busca`.

**Erros**

- `400` — Texto ausente ou fora do tamanho aceito.
- `504` — O caminho síncrono estourou — enfileire em `POST /api/ia/jobs`.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/ia -H 'content-type: application/json' -d '{"texto":"padarias em SP com MEI"}'
```

### `POST /api/ia/jobs`

Enfileira a mesma tradução de texto para filtros, quando a síncrona não cabe no tempo.

- **URL:** `https://exf.ia.br/api/ia/jobs`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

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

- `texto` (string, obrigatório) — A descrição em linguagem natural do que você procura.

**Exemplo de corpo**

```json
{
  "texto": "padarias em SP com MEI"
}
```

**Resposta `200`**

- `job_id` (string) — ID do trabalho, para consultar em `GET /api/ia/jobs/:id`.
- `eta` (int) — Estimativa de segundos até ficar pronto.

**Erros**

- `400` — Texto ausente ou fora do tamanho aceito.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/ia/jobs -H 'content-type: application/json' -d '{"texto":"padarias em SP com MEI"}'
```

### `GET /api/ia/jobs/:id`

Consulta o trabalho de IA enfileirado; quando pronto, devolve os filtros.

- **URL:** `https://exf.ia.br/api/ia/jobs/:id`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Parâmetros de caminho**

- `id` (string, obrigatório) — ID do trabalho, vindo de `POST /api/ia/jobs`. Ex.: `9f3c2b1d7a4e58b0`.

**Resposta `200`**

- `status` (string) — Estado do trabalho.
- `filtros` (object[], opcional) — Os filtros normalizados; só quando `status` é `done`.

**Erros**

- `404` — Trabalho não existe ou já expirou.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/ia/jobs/JOB_ID
```

## Geo

### `GET /api/local`

Cidade e UF aproximadas de quem está chamando.

Nunca é cacheada: cache aqui entregaria o lugar de outra pessoa.

- **URL:** `https://exf.ia.br/api/local`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

Estrutura: `Local`.

- `ok` (bool) — Sempre `true`.
- `cidade` (string, pode ser null) — Cidade detectada.
- `uf` (string, pode ser null) — Unidade da federação detectada.
- `cep` (string, pode ser null) — CEP aproximado da borda.
- `pais` (string, pode ser null) — País detectado, ISO 3166-1 alpha-2.
- `fonte` (string) — De onde veio a detecção.

### `GET /api/municipio-proximo`

Município de um par de coordenadas, com o bairro quando disponível.

Também nunca é cacheada. Coordenada ausente ou vazia NÃO vira zero — (0,0) é um lugar de verdade, no golfo da Guiné.

- **URL:** `https://exf.ia.br/api/municipio-proximo`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Query**

- `lat` (number, obrigatório) — Latitude, entre -90 e 90. Ex.: `-23.55`.
- `lon` (number, obrigatório) — Longitude, entre -180 e 180. Ex.: `-46.63`.

**Resposta `200`**

Estrutura: `MunicipioProximo`.

- `ok` (bool) — Sempre `true`.
- `municipio` (object) — `codigo` (da Receita; `null` sem par de nome), `descricao`, `uf` e `km` — 0 dentro do contorno; fora de todos (praia, mar, GPS impreciso), a distância até o contorno mais próximo, até 50 km.
- `bairro` (string, opcional) — Bairro mais próximo, quando existe.
- `cep` (string, opcional) — CEP mais próximo, quando existe.
- `bairro_km` (number, opcional) — Distância até o endereço de referência, em km.

**Erros**

- `400` — `lat` ou `lon` ausentes ou fora da faixa.
- `404` — `fora_do_brasil`: nenhum município brasileiro contém o ponto nem fica a até 50 km dele.
- `503` — `sem_malha`: a base de contornos dos municípios está indisponível.

**Exemplo**

```sh
curl -s 'https://exf.ia.br/api/municipio-proximo?lat=-23.55&lon=-46.63'
```

## Monitoramento

### `POST /api/guest`

Cria ou recupera o visitante temporário deste navegador.

A biblioteca global assina o token e limita a emissão por rede; o cookie HttpOnly vale só neste domínio.

- **URL:** `https://exf.ia.br/api/guest`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

- `guest_token` (string) — Token assinado do visitante.

**Erros**

- `429` — guest_rate_limited
- `503` — auth_unavailable

### `POST /api/auth/claim`

Vincula à conta as vigias feitas neste navegador.

A SDK valida sessão e token, transfere as vigias na origem e as vagas compradas no crédito global.

- **URL:** `https://exf.ia.br/api/auth/claim`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Resposta `200`**

- `ok` (bool) — true quando todas as vigias passaram para a conta.

**Erros**

- `401` — Sessão da conta ausente ou vencida.
- `409` — unknown_guest
- `503` — product_claim_pending

**Exemplo**

```sh
await MMConta.fetch(new URL("https://exf.ia.br/api/auth/claim").pathname, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" })
```

### `GET /api/me/monitor/watches`

Os CNPJs que você acompanha, com a cota aplicada (grátis + vagas compradas).

Quem confere a cota é a origem (`api.radar-cnpj.com`), dentro da transação; o Worker calcula quanto você tem (10 grátis + as vagas em vigor) e manda junto. Watch além da cota vem com `suspensa: true` e não gera e-mail.

- **URL:** `https://exf.ia.br/api/me/monitor/watches`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Headers**

- `Authorization` (string) — Agente: `Bearer rd_…` (visitante), `Bearer mmk_…` (conta) ou `Bearer cred_…` (carteira). No navegador vale o cookie temporário ou o da conta; escrita com a conta leva `X-CSRF-Token`.

**Resposta `200`**

Estrutura: `Watches`.

- `ok` (bool) — Sempre `true`.
- `watches` (object[]) — Um item por CNPJ acompanhado; `suspensa: true` quando está além da cota.
- `quota` (int) — Quantos monitores você pode ter agora: grátis + vagas em vigor.
- `base` (int) — Quantos são grátis.
- `pagos` (int) — Vagas compradas e em vigor (30 dias cada).
- `used` (int) — Quantos estão ativos.
- `suspensas` (int) — Quantos ficaram além da cota — não geram alerta até a cota voltar.

**Erros**

- `401` — Sem visitante, conta ou carteira válida: `nao_logado`; chave recusada: `invalid_api_key`.
- `503` — A conta não respondeu agora.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/me/monitor/watches -H "Authorization: Bearer $CREDITO"
```

### `POST /api/me/monitor/watch`

Passa a acompanhar um CNPJ. Os 10 primeiros são grátis; cada vaga a mais, US$ 0,50 por 30 dias.

Estourou a cota: **402 com `accepts[]`** (x402) — ou, com token de crédito, o débito direto do saldo. Pague e repita a mesma chamada com `X-PAYMENT`; a vaga fica no `direito` global e a watch entra.

- **URL:** `https://exf.ia.br/api/me/monitor/watch`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Headers**

- `Authorization` (string) — Agente: `Bearer rd_…` (visitante), `Bearer mmk_…` (conta) ou `Bearer cred_…` (carteira). No navegador vale o cookie temporário ou o da conta; escrita com a conta leva `X-CSRF-Token`.

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

- `cnpj` (string, obrigatório) — CNPJ a acompanhar, 14 dígitos sem pontuação.

**Exemplo de corpo**

```json
{
  "cnpj": "00000000000000"
}
```

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `400` — CNPJ que não tem 14 dígitos.
- `401` — Sem visitante, conta ou carteira válida: `nao_logado`; chave recusada: `invalid_api_key`.
- `402` — Cota estourada. A resposta traz `accepts[]` (x402, USDC na Base): pague e repita a mesma chamada com `X-PAYMENT`.
- `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta vinda de outra origem ou sem `X-CSRF-Token`.
- `503` — A conta não respondeu agora.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/me/monitor/watch -H "Authorization: Bearer $CREDITO" -H 'content-type: application/json' -d '{"cnpj":"00000000000191"}'
```

### `DELETE /api/me/monitor/watch/:cnpj`

Para de acompanhar um CNPJ. A chave é o próprio CNPJ, não um id.

- **URL:** `https://exf.ia.br/api/me/monitor/watch/:cnpj`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Parâmetros de caminho**

- `cnpj` (string, obrigatório) — CNPJ a deixar de acompanhar, 14 dígitos sem pontuação. Ex.: `00000000000191`.

**Headers**

- `Authorization` (string) — Agente: `Bearer rd_…` (visitante), `Bearer mmk_…` (conta) ou `Bearer cred_…` (carteira). No navegador vale o cookie temporário ou o da conta; escrita com a conta leva `X-CSRF-Token`.

**Resposta `200`**

Estrutura: `Ok`.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

**Erros**

- `401` — Sem visitante, conta ou carteira válida: `nao_logado`; chave recusada: `invalid_api_key`.
- `403` — `invalid_origin` / `invalid_csrf`: escrita com o cookie da conta vinda de outra origem ou sem `X-CSRF-Token`.
- `404` — Este CNPJ não está sendo acompanhado por você.

**Exemplo**

```sh
curl -s -XDELETE https://exf.ia.br/api/me/monitor/watch/00000000000191 -H "Authorization: Bearer $CREDITO"
```

### `GET /api/me/monitor/alerts`

Os alertas gerados para os CNPJs que você acompanha.

`retidos` conta os alertas de watches suspensas (fora da cota): voltam a aparecer quando a cota volta. Conta com e-mail verificado recebe os alertas também por e-mail; carteira de agente, só aqui.

- **URL:** `https://exf.ia.br/api/me/monitor/alerts`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Headers**

- `Authorization` (string) — Agente: `Bearer rd_…` (visitante), `Bearer mmk_…` (conta) ou `Bearer cred_…` (carteira). No navegador vale o cookie temporário ou o da conta; escrita com a conta leva `X-CSRF-Token`.

**Resposta `200`**

Estrutura: `Alertas`.

- `ok` (bool) — Sempre `true`.
- `alerts` (object[]) — Um item por alteração detectada num CNPJ acompanhado.
- `retidos` (int) — Quantos alertas são de monitores suspensos (além da cota) — voltam quando a cota voltar.

**Erros**

- `401` — Sem visitante, conta ou carteira válida: `nao_logado`; chave recusada: `invalid_api_key`.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/me/monitor/alerts -H "Authorization: Bearer $CREDITO"
```

### `GET /api/monitor/changes/:cnpj`

O histórico de alterações cadastrais de um CNPJ.

É o que o monitoramento observa: cada linha diz o que mudou, de que valor para qual, e quando. O nome de sócio sai mascarado.

- **URL:** `https://exf.ia.br/api/monitor/changes/:cnpj`
- **Auth:** `session` — A conta global: Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. O monitoramento (`/api/me/monitor/*`, `/api/monitor/changes/:cnpj`) é da conta; agente sem conta usa o crédito global em `Authorization: Bearer cred_…` (ou `X-Credito`), e a carteira vira a dona dos monitores.

**Parâmetros de caminho**

- `cnpj` (string, obrigatório) — CNPJ a consultar, 14 dígitos sem pontuação. Ex.: `00000000000191`.

**Headers**

- `Authorization` (string) — Agente: `Bearer rd_…` (visitante), `Bearer mmk_…` (conta) ou `Bearer cred_…` (carteira). No navegador vale o cookie temporário ou o da conta; escrita com a conta leva `X-CSRF-Token`.

**Resposta `200`**

Estrutura: `HistoricoCnpj`.

- `ok` (bool) — Sempre `true`.
- `cnpj` (string) — CNPJ consultado, só dígitos.
- `cnpjFormatted` (string) — O mesmo CNPJ com pontuação.
- `changes` (object[]) — Uma entrada por alteração observada, com o campo, o valor anterior e a data.

**Erros**

- `401` — Sem visitante, conta ou carteira válida: `nao_logado`; chave recusada: `invalid_api_key`.
- `404` — CNPJ sem histórico ou fora da base.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/monitor/changes/00000000000191 -H "Authorization: Bearer $CREDITO"
```

## Contato

### `POST /api/contato`

O mesmo contato de `/api/contact`, com o nome da rota em português.

Uma rota para dúvida e para proposta de patrocínio, parceria ou anúncio (`tipo`, com os espaços de `GET /api/partners`). Sem captcha, sem conta, sem pagamento. Uma mensagem a cada 10 segundos por rede: a que chega antes espera a vez e sai — sem erro. A mensagem chega à equipe por e-mail, com o `email` como endereço de resposta.

- **URL:** `https://exf.ia.br/api/contato`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

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

- `name` (string, obrigatório) — Como chamar quem escreve (alias `nome`).
- `email` (string, obrigatório) — Para onde responder.
- `message` (string, obrigatório) — O que você quer dizer (alias `mensagem`).
- `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`.

**Exemplo de corpo**

```json
{
  "name": "Agente",
  "email": "agent@example.com",
  "message": "olá, sou um agente"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando a mensagem foi aceita.

**Erros**

- `400` — Validação: o `code` diz o campo.
- `503` — O contato não está configurado neste servidor.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/contact -H 'content-type: application/json' -d '{"name":"Agente","email":"agent@example.com","message":"olá, sou um agente"}'
```

### `POST /api/contact`

Fale com quem faz o produto — de graça, para pessoa e agente.

Uma rota para dúvida e para proposta de patrocínio, parceria ou anúncio (`tipo`, com os espaços de `GET /api/partners`). Sem captcha, sem conta, sem pagamento. Uma mensagem a cada 10 segundos por rede: a que chega antes espera a vez e sai — sem erro. A mensagem chega à equipe por e-mail, com o `email` como endereço de resposta.

- **URL:** `https://exf.ia.br/api/contact`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

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

- `name` (string, obrigatório) — Como chamar quem escreve (alias `nome`).
- `email` (string, obrigatório) — Para onde responder.
- `message` (string, obrigatório) — O que você quer dizer (alias `mensagem`).
- `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`.

**Exemplo de corpo**

```json
{
  "name": "Agente",
  "email": "agent@example.com",
  "message": "olá, sou um agente"
}
```

**Resposta `200`**

- `ok` (bool) — Sempre `true` quando a mensagem foi aceita.

**Erros**

- `400` — Validação: o `code` diz o campo.
- `503` — O contato não está configurado neste servidor.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/contact -H 'content-type: application/json' -d '{"name":"Agente","email":"agent@example.com","message":"olá, sou um agente"}'
```

### `GET /api/metrics`

Métricas operacionais: sem token, visitas de hoje e uso; com o token do operador, a série de 7 dias.

Conta visitantes distintos e **não** conta autocomplete — senão o painel mediria tecla, não gente. Sem `Authorization` devolve só `app`, `today_visits` e `usage`, com 5 min de cache na borda — é o que a linha de estado do rodapé lê, como nos outros produtos. Com `Bearer METRICS_TOKEN`, a resposta completa da origem (`days`), sem cache.

- **URL:** `https://exf.ia.br/api/metrics`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Headers**

- `Authorization` (string) — `Bearer <METRICS_TOKEN>`, só para a série completa do operador.

**Resposta `200`**

Estrutura: `Metricas`.

- `app` (string) — Nome do produto.
- `today_visits` (int) — Visitantes distintos hoje — não conta autocomplete.
- `days` (object[], opcional) — Um registro por dia da janela. Só com `METRICS_TOKEN`.
- `usage` (object) — Uso por recurso — aqui, `queries`.

**Erros**

- `401` — Token do operador errado.
- `503` — Sem os secrets configurados no ambiente.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/metrics -H "Authorization: Bearer $METRICS_TOKEN"
```

## 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://exf.ia.br/api/erro-cliente`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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; número, hash e token no caminho são guardados como `:id`.
- `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.
- `build` (string) — Build da página que relatou (a `<meta name="build">`), até 64 letras, dígitos, `.`, `_` ou `-`; é ele que data a falha.

**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://exf.ia.br/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://exf.ia.br/api/pagamento/aberto`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

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

A interface relata os passos da visita (funil de conversão). Agentes não devem chamar.

Lote da mesma origem, enviado pela própria página: páginas vistas, engajamento, oferta à vista, clique em comprar, janela de pagamento, pagamento enviado ou aceito. Guarda o id aleatório do navegador, o caminho sem query, o host de quem mandou a pessoa e as utm; nunca IP, e-mail ou conta. Não grava banco: uma linha por lote no diário do dia, com teto. Robô declarado e smoke ficam de fora.

- **URL:** `https://exf.ia.br/api/funil`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Headers**

- `Origin` (string) — A origem da página, idêntica à desta rota.
- `Content-Type` (string, obrigatório) — `application/json` ou `text/plain`.

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

- `v` (number, obrigatório) — Versão do lote: `1`.
- `vid` (string, obrigatório) — Id aleatório deste navegador (UUID v4).
- `sid` (string, obrigatório) — Id da sessão (30 min sem atividade encerram).
- `sn` (number, obrigatório) — Número da sessão deste navegador.
- `pv` (string, obrigatório) — Id da página vista.
- `e` (object[], obrigatório) — Até 40 eventos `{ t, n, p? }` do vocabulário do funil.

**Resposta `202`**

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

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/funil -H 'content-type: text/plain' -H 'x-mm-smoke: 1' -d '{"v":1,"vid":"0f8b9c1e-2a3b-4c5d-8e6f-7a8b9c0d1e2f","sid":"s1abcdefgh","sn":1,"pv":"p1abcdefgh","e":[{"t":0,"n":"pagina"}]}'
```

### `GET /api/funil/arquivos`

Operador: os dias do diário do funil guardados neste app, com o tamanho de cada um.

- **URL:** `https://exf.ia.br/api/funil/arquivos`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Headers**

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

**Resposta `200`**

- `v` (number) — Versão do lote guardado.
- `produto` (string) — O produto.
- `teto` (object) — `bytesDia` e `dias` guardados.
- `dias` (object[]) — `{ dia, bytes }`, do mais velho ao de hoje.

**Erros**

- `401` — Unauthorized
- `503` — Not configured

**Exemplo**

```sh
curl -s https://exf.ia.br/api/funil/arquivos -H "Authorization: Bearer $METRICS_TOKEN"
```

### `GET /api/funil/arquivo`

Operador: um pedaço de um dia do diário do funil, em NDJSON, a partir de um byte.

Até 4 MiB por resposta, cortados na última linha inteira. `X-MM-Funil-Proximo` diz de onde pedir o resto; `X-MM-Funil-Tamanho`, o tamanho do dia agora.

- **URL:** `https://exf.ia.br/api/funil/arquivo`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Query**

- `dia` (string, obrigatório) — O dia, `AAAA-MM-DD` (UTC).
- `desde` (number) — O byte de onde ler; `0` no começo.

**Headers**

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

**Resposta `200`**

Linhas JSON, uma por lote guardado.

**Erros**

- `400` — Invalid parameters
- `401` — Unauthorized
- `503` — Not configured

**Exemplo**

```sh
curl -s "https://exf.ia.br/api/funil/arquivo?dia=2026-09-27&desde=0" -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://exf.ia.br/api/vitrine`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/api/vitrine
```

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

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

- **URL:** `https://exf.ia.br/api/vitrine/operador`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/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://exf.ia.br/api/vitrine/painel`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/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://exf.ia.br/api/vitrine/cursores`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/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://exf.ia.br/api/partners`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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`, livre: uma mensagem a cada 10 s por rede), `campos` (os obrigatórios), `campos_proposta` (os opcionais da proposta, com os valores aceitos de cada um), `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://exf.ia.br/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://exf.ia.br/api/credito`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/api/credito?usd=10'
```

### `GET /api/credito`

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

- **URL:** `https://exf.ia.br/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://exf.ia.br/api/credito -H 'Authorization: Bearer cred_…'
```

### `GET /api/credito/pix`

Crédito por Pix: a chave, o câmbio fixo, os pacotes em reais e o que o comprovante aceita.

- **URL:** `https://exf.ia.br/api/credito/pix`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

- `chave` (string) — A chave Pix que recebe o pagamento.
- `brl_por_usd` (number) — Câmbio fixo usado nos pacotes.
- `pacotes` (object[]) — Os pacotes (1, 5, 10 ou 25 dólares), cada um com `brl_centavos` e `copia_e_cola` (o Pix copia e cola do valor, o mesmo texto do QR: o app do banco já vem com o valor).
- `comprovante` (object) — Tipos aceitos (foto ou PDF) e o tamanho máximo, em bytes.
- `liberacao` (string) — `manual`: o dono confere o Pix e libera.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/credito/pix
```

### `POST /api/credito/pix`

Pede crédito pago por Pix: multipart com `usd`, `comprovante` (foto ou PDF até 2 MB) e `email`; o resto é opcional.

O código de crédito sai na resposta e passa a valer quando o dono confere o Pix e libera (manual, em geral no mesmo dia). O `email` é obrigatório: é por ele que o dono fala com a pessoa. Opcionais: `nome`, `pagina` (a página de onde pediu, até 2.000 caracteres) e o que a pessoa comprava quando recebeu o 402 — `recurso` (até 2.000), `descricao` (até 300) e `preco_usd` (decimal, ex. `0.50`); e `navegador_id` (UUID que liga os pedidos do mesmo navegador). Tudo o que chega fica registrado no pedido — o comprovante inclusive —, com a conta logada (conferida pelo cookie da sessão), a rede e o navegador de quem pediu.

- **URL:** `https://exf.ia.br/api/credito/pix`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

- `id` (string) — Id do pedido, para acompanhar.
- `estado` (string) — `pendente` até a decisão.
- `credito` (string) — O token `cred_…`, mostrado UMA vez; vale depois da liberação.
- `estado_em` (string) — Onde acompanhar o pedido.

**Erros**

- `400` — Pacote fora da lista (1, 5, 10 ou 25), sem comprovante ou sem e-mail válido.
- `413` — Comprovante acima de 2 MB.
- `415` — Comprovante que não é foto (JPEG, PNG, WebP) nem PDF.
- `429` — A rede já mandou os pedidos do dia.
- `502` — O e-mail ao dono não saiu: o pedido fica registrado como `falhou`; mande de novo.
- `503` — Fila de conferência cheia, ou Pix indisponível neste app.

**Exemplo**

```sh
curl -s -XPOST https://exf.ia.br/api/credito/pix -F usd=5 -F email=voce@empresa.com.br -F comprovante=@pix.pdf
```

### `GET /api/credito/pix/:id`

Estado de um pedido de crédito por Pix: `pendente`, `liberado`, `recusado` ou `falhou`.

- **URL:** `https://exf.ia.br/api/credito/pix/:id`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id do pedido (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `estado` (string) — `pendente`, `liberado`, `recusado` ou `falhou` (o e-mail ao dono não saiu; mande de novo).
- `usd` (int) — O pacote pedido.
- `decidido_em` (string) — Quando o dono decidiu, ou `null`.

**Erros**

- `404` — Pedido desconhecido.

**Exemplo**

```sh
curl -s https://exf.ia.br/api/credito/pix/0123456789abcdef0123456789abcdef
```

## API access

### `GET /api/acesso`

Discover the monthly data package or inspect a private purchase.

- **URL:** `https://exf.ia.br/api/acesso`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/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://exf.ia.br/api/acesso`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**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://exf.ia.br/api/acesso" -H "X-API-Pass: $API_PASS"
```

## Estruturas

### `SaudeOrigem`

Disponibilidade do serviço e data de referência dos dados.

- `ok` (bool) — Sempre `true` quando a origem responde.
- `service` (string) — Qual serviço respondeu.
- `db` (string) — Estado do banco: `up` ou o motivo de não estar.
- `import` (object) — `dump_date`, `loaded_at` e as contagens por tabela — é a idade real do dado.

### `Avaliacao`

Leitura da oferta formal de empresas para uma atividade e região.

- `ok` (bool) — Sempre `true` quando a avaliação saiu.
- `texto` (string) — A ideia como você a escreveu.
- `cnae` (string, pode ser null) — CNAE a que a ideia foi mapeada.
- `fonte_cnae` (string) — Como o CNAE foi determinado: pela IA ou pelo hint que você mandou.
- `filtros` (object[]) — Os filtros normalizados que a avaliação aplicou — dá para reusar em `GET /api/busca`.
- `ficha` (FichaOferta) — O retrato da oferta formal e a leitura honesta dela. → ver `FichaOferta` em **Estruturas**.

### `FichaCnpj`

A ficha cadastral de uma empresa, com o dado pessoal mascarado.

- `ok` (bool) — Sempre `true` quando o CNPJ existe na base.
- `data` (object) — O cadastro: identificação, endereço, contato, sócios, CNAEs, Simples e situação. Com `mascarado: true`, o nome de sócio pessoa física sai como `LUIS F. R. P.` (sem documento) e `contato` mostra só parte dos telefones e do e-mail.

### `FichaRevelada`

A ficha com o dado pessoal sem máscara, e o que a revelação custou.

- `ok` (bool) — Sempre `true` quando a revelação foi entregue.
- `data` (object) — O mesmo cadastro de `GET /api/cnpj/:cnpj`, com `socios[].nome`, `socios[].documento` e `contato` inteiros e `mascarado: false`.
- `cobranca` (object) — `via` (`credito`, `x402` ou `gratis`), `preco_usd`, `saldo_usd` (só no crédito) e `repetido` (`true` quando o mesmo código de crédito já tinha revelado esta empresa hoje e nada foi cobrado).

### `PaginaDeBusca`

Página da busca. Paginação por `page`/`pageSize`, e `hasMore` no lugar de um total — contar 71 milhões de estabelecimentos a cada busca não muda decisão nenhuma.

- `ok` (bool) — Sempre `true` quando a busca rodou.
- `page` (int) — Página devolvida, começando em 0.
- `pageSize` (int) — Quantos resultados por página.
- `hasMore` (bool) — Se existe página seguinte.
- `results` (Empresa[]) — As empresas desta página. → ver `Empresa` em **Estruturas**.

### `Export`

O envelope de `GET /api/export?format=json`. Com `format=csv` a rota devolve o arquivo, não este objeto.

- `ok` (bool) — Sempre `true` quando o export saiu.
- `count` (int) — Quantas empresas o arquivo traz.
- `capped` (bool) — `true` quando o export bateu no teto da origem e não trouxe tudo — o número acima não é o total do filtro.
- `results` (Empresa[]) — As empresas exportadas. → ver `Empresa` em **Estruturas**.

### `ListaSugestao`

Sugestões de autocomplete — o suficiente para montar a lista enquanto a pessoa digita.

- `ok` (bool) — Sempre `true`.
- `results` (object[]) — As sugestões, cada uma com o texto e o que ela identifica.

### `ListaReferencia`

Itens de um vocabulário oficial (CNAE, município, natureza jurídica) para montar seletor.

- `ok` (bool) — Sempre `true`.
- `results` (ItemReferencia[]) — Os itens que casam com a consulta. → ver `ItemReferencia` em **Estruturas**.

### `Local`

Localização aproximada do visitante. Nunca é cacheado: cache aqui daria o lugar de outra pessoa.

- `ok` (bool) — Sempre `true`.
- `cidade` (string, pode ser null) — Cidade detectada.
- `uf` (string, pode ser null) — Unidade da federação detectada.
- `cep` (string, pode ser null) — CEP aproximado da borda.
- `pais` (string, pode ser null) — País detectado, ISO 3166-1 alpha-2.
- `fonte` (string) — De onde veio a detecção.

### `MunicipioProximo`

O município que contém o ponto e o bairro mais próximo, quando disponível.

- `ok` (bool) — Sempre `true`.
- `municipio` (object) — `codigo` (da Receita; `null` sem par de nome), `descricao`, `uf` e `km` — 0 dentro do contorno; fora de todos (praia, mar, GPS impreciso), a distância até o contorno mais próximo, até 50 km.
- `bairro` (string, opcional) — Bairro mais próximo, quando existe.
- `cep` (string, opcional) — CEP mais próximo, quando existe.
- `bairro_km` (number, opcional) — Distância até o endereço de referência, em km.

### `Watches`

Os CNPJs que você acompanha (conta ou carteira de crédito), com a cota que a ORIGEM aplica.

- `ok` (bool) — Sempre `true`.
- `watches` (object[]) — Um item por CNPJ acompanhado; `suspensa: true` quando está além da cota.
- `quota` (int) — Quantos monitores você pode ter agora: grátis + vagas em vigor.
- `base` (int) — Quantos são grátis.
- `pagos` (int) — Vagas compradas e em vigor (30 dias cada).
- `used` (int) — Quantos estão ativos.
- `suspensas` (int) — Quantos ficaram além da cota — não geram alerta até a cota voltar.

### `Ok`

Confirmação de escrita que não tem corpo próprio a devolver.

- `ok` (bool) — Sempre `true` — a falha vem como status 4xx/5xx, não como `ok:false`.

### `Alertas`

Os alertas gerados para os CNPJs que você acompanha.

- `ok` (bool) — Sempre `true`.
- `alerts` (object[]) — Um item por alteração detectada num CNPJ acompanhado.
- `retidos` (int) — Quantos alertas são de monitores suspensos (além da cota) — voltam quando a cota voltar.

### `HistoricoCnpj`

O que mudou no cadastro de um CNPJ ao longo do tempo — é o que o monitoramento observa.

- `ok` (bool) — Sempre `true`.
- `cnpj` (string) — CNPJ consultado, só dígitos.
- `cnpjFormatted` (string) — O mesmo CNPJ com pontuação.
- `changes` (object[]) — Uma entrada por alteração observada, com o campo, o valor anterior e a data.

### `Metricas`

Métricas operacionais da origem, 7 dias. Sem token vêm só `app`, `today_visits` e `usage`; `days` exige `METRICS_TOKEN`.

- `app` (string) — Nome do produto.
- `today_visits` (int) — Visitantes distintos hoje — não conta autocomplete.
- `days` (object[], opcional) — Um registro por dia da janela. Só com `METRICS_TOKEN`.
- `usage` (object) — Uso por recurso — aqui, `queries`.

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

### `FichaOferta`

Quantas empresas já fazem isso, como elas se formalizam e o que esses números não dizem.

- `mapeou_cnae` (bool) — Se deu para mapear a ideia num CNAE. Sem isso, os números abaixo não valem.
- `oferta` (object) — Empresas ativas, abertas e baixadas no recorte.
- `formalizacao` (object) — Como essas empresas se formalizam: MEI, Simples, porte.
- `leitura` (string[]) — O que os números sugerem, em frases — sem promessa de demanda.
- `limites` (string[]) — O que estes dados NÃO dizem. Não há volume de busca aqui, e renda passiva isto não é.
- `passivo` (object, pode ser null) — Sinais de risco no recorte, quando existem.

### `Empresa`

Uma empresa no resultado de busca. É o recorte da origem, não o cadastro inteiro.

- `cnpj` (string) — CNPJ só com dígitos, 14 posições.
- `cnpjFormatted` (string) — O mesmo CNPJ com pontuação, para mostrar a uma pessoa.
- `razaoSocial` (string) — Razão social registrada.
- `nomeFantasia` (string, pode ser null) — Nome fantasia, quando declarado.
- `situacao` (string) — Situação cadastral: ativa, baixada, suspensa, inapta, nula.
- `uf` (string, pode ser null) — Unidade da federação do estabelecimento.
- `municipio` (string, pode ser null) — Município do estabelecimento.
- `bairro` (string, pode ser null) — Bairro do estabelecimento.
- `cnae` (string, pode ser null) — CNAE principal do estabelecimento.

### `ItemReferencia`

Um item de vocabulário oficial: o código que a Receita usa e o nome dele.

- `codigo` (int) — Código oficial, ex. `4721102` para padaria.
- `descricao` (string) — Nome do código por extenso.

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

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

- [Empresas por CNPJ](https://api.radar-cnpj.com/empresas/index.json): Estabelecimentos ativos por estado, município e atividade (CNAE), com ficha pública por CNPJ. UF → município → atividade (CNAE) → estabelecimentos → ficha por CNPJ. [HTML](https://api.radar-cnpj.com/empresas/) · [llms.txt](https://api.radar-cnpj.com/empresas/llms.txt) · [OKF](https://api.radar-cnpj.com/empresas/okf/index.md)
- [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)


## Cota

- Grátis: avaliar ideia (`POST /api/avaliar`) — sem cota.
- Grátis: consulta e busca de CNPJ — sem cota (cache de borda 6h).
- Grátis: monitoramento de CNPJ — 10 watches por sessão (a cota vem da origem: `quota` em `GET /api/me/monitor/watches`).
- Pago: 1,000 basic reads across /empresas, /enderecos and /licitacoes, valid for 30 days; availability and purchase: GET/POST /api/acesso; no automatic renewal — **$1.00** USDC via x402.
- Pago: watch de monitoramento além dos 10 da sessão, por 30 dias — **$0.50** USDC via x402.
- Pago: revelação de sócios, telefones e e-mail de uma empresa — **$0.10** USDC via x402.

- **Sem cobrar agora**: revelar_dados, monitor_vaga. Chame direto — não vem 402. O preço acima é o de tabela e volta a valer sem aviso.

Estourou a franquia → **402** com `accepts[]` (x402, USDC na Base). Pague e repita a mesma chamada com `X-PAYMENT`.

Números em vigor: https://exf.ia.br/api/