# Radar CNPJ — referência completa da API

> Gerada do catálogo em https://www.radar-cnpj.com · build `a22fcc58`
> 64 endpoints · 38 estruturas
> Índice curto: https://www.radar-cnpj.com/llms.txt · Spec: https://www.radar-cnpj.com/openapi.json · MCP: https://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/api/auth/bootstrap").then(r => r.json());
  const r = await fetch("https://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/.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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/okf/cnpj/00000000000191.md
```

### `GET /api/`

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

- **URL:** `https://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/api/pricing
```

### `GET /api/billing`

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

- **URL:** `https://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/api/vitrine
```

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

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

- **URL:** `https://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/api/credito?usd=10'
```

### `GET /api/credito`

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

- **URL:** `https://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/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://www.radar-cnpj.com/api/credito/pix/0123456789abcdef0123456789abcdef
```

### `GET /api/credito/asaas`

Pix automático: se está disponível neste app, os pacotes em reais e o saldo que o produto vende.

- **URL:** `https://www.radar-cnpj.com/api/credito/asaas`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

- `disponivel` (boolean) — `false` quando o app não tem o Asaas configurado (use o Pix com comprovante). → ver `boolean` em **Estruturas**.
- `pacotes` (object[]) — Os pacotes de crédito (1, 5, 10 ou 25 dólares), com `brl_centavos`.
- `saldo` (object) — Quando o produto vende saldo em reais: a faixa e se a conta logada pode comprar.
- `precisa_documento` (boolean) — Se o CPF ou CNPJ de quem paga ainda é pedido. → ver `boolean` em **Estruturas**.

**Exemplo**

```sh
curl -s https://www.radar-cnpj.com/api/credito/asaas
```

### `POST /api/credito/asaas`

Gera um Pix dinâmico: JSON com `oferta` (`pacote` com `usd`, ou `saldo` com `centavos`) e o pagador.

O pagamento libera sozinho o que se comprou: o pacote vira o token `cred_…` que já vem na resposta; o saldo cai na organização da conta logada. Na primeira compra vão `documento` (CPF ou CNPJ, que segue para o gateway e não fica guardado aqui) e `nome`; `email`, `pagina` e `navegador_id` são opcionais e ficam registrados.

- **URL:** `https://www.radar-cnpj.com/api/credito/asaas`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Resposta `200`**

- `id` (string) — Id da cobrança, para acompanhar.
- `credito` (string) — No pacote: o token `cred_…`, mostrado UMA vez; vale quando o Pix cair.
- `pix` (object) — `copia_e_cola`, `imagem` (QR em PNG, data URI) e `expira_em`.
- `estado_em` (string) — Onde acompanhar o pagamento.

**Erros**

- `400` — Pacote fora da lista (1, 5, 10 ou 25), valor fora da faixa, ou CPF/CNPJ, nome ou e-mail inválido.
- `429` — A rede já gerou as cobranças do dia.
- `502` — O gateway não gerou o Pix; tente de novo.
- `503` — Pix automático indisponível neste app, ou cobranças demais esperando pagamento.

**Exemplo**

```sh
curl -s -XPOST https://www.radar-cnpj.com/api/credito/asaas -H 'content-type: application/json' -d '{"oferta":"pacote","usd":5,"documento":"000.000.000-00","nome":"Ana"}'
```

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

Estado de uma cobrança Pix automática: `pendente`, `pago`, `vencido`, `estornado` ou `falhou`.

- **URL:** `https://www.radar-cnpj.com/api/credito/asaas/:id`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Parâmetros de caminho**

- `id` (string, obrigatório) — Id da cobrança (32 hex). Ex.: `0123456789abcdef0123456789abcdef`.

**Resposta `200`**

- `estado` (string) — `pago` libera o token do pacote ou o saldo; o Pix pago depois do vencimento vale.
- `pago_em` (string) — Quando o pagamento foi confirmado, ou `null`.

**Erros**

- `404` — Cobrança desconhecida.

**Exemplo**

```sh
curl -s https://www.radar-cnpj.com/api/credito/asaas/0123456789abcdef0123456789abcdef
```

## Consulta de CNPJ e endereço

### `GET /api/consulta`

O serviço de consulta de CNPJ e endereço: a franquia grátis de hoje, o pacote avulso, os três planos e o seu saldo.

Sem credencial mostra a franquia e as ofertas; com a conta (cookie ou `X-Api-Key: mmk_…`) ou o crédito (`X-Credito`), também o saldo, que vale em todos os portais da casa (Radar CNPJ, PontoFato, EditalMD).

- **URL:** `https://www.radar-cnpj.com/api/consulta`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Query**

- `lingua` (string) — Língua das mensagens: `pt` ou `en` (padrão: a do navegador, senão inglês). Valores: `pt`, `en`.

**Resposta `200`**

Estrutura: `ConsultaServico`.

- `servico` (string) — Sempre `consulta`.
- `nome` (string) — Nome do serviço na língua pedida.
- `descricao` (string) — O que ele entrega e como se paga, numa frase.
- `gratis` (ConsultaFranquia) — A franquia de hoje para esta rede. → ver `ConsultaFranquia` em **Estruturas**.
- `ofertas` (ConsultaOferta[]) — O pacote avulso e os três planos. → ver `ConsultaOferta` em **Estruturas**.
- `saldo` (ConsultaSaldo, pode ser null) — O saldo de quem pediu; `null` sem conta nem crédito. → ver `ConsultaSaldo` em **Estruturas**.
- `como_comprar` (string) — Como comprar pela API, na língua pedida.
- `_links` (object) — `self`, `cnpj`, `cep`, `pagina` e `api_index` absolutos.

**Erros**

- `401` — Credencial apresentada e recusada.
- `503` — Serviço de conta ou de saldo fora do ar.

**Exemplo**

```sh
curl -s 'https://www.radar-cnpj.com/api/consulta?lingua=pt'
```

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

Consulta uma empresa pelo CNPJ: a ficha da Receita e onde fica o endereço dela no mapa (CNEFE/IBGE).

Uma consulta: sai da franquia grátis do dia (10 por rede) e, depois dela, do saldo da conta ou do crédito (plano ou pacote). Sem franquia nem saldo, 402 com as ofertas. Aceita o CNPJ numérico e o alfanumérico. Não encontrado, fonte fora do ar ou limite por minuto não são cobrados. O dado pessoal da ficha vem mascarado.

- **URL:** `https://www.radar-cnpj.com/api/consulta/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 ou sem pontuação (14 caracteres). Ex.: `00000000000191`.

**Query**

- `lingua` (string) — Língua das mensagens: `pt` ou `en` (padrão: a do navegador, senão inglês). Valores: `pt`, `en`.

**Headers**

- `Idempotency-Key` (string) — Chave da tentativa (até 80 caracteres): repetir a MESMA consulta com a mesma chave não desconta o saldo duas vezes.

**Resposta `200`**

Estrutura: `ConsultaCnpj`.

- `consulta` (string) — Sempre `cnpj`.
- `cnpj` (string) — CNPJ formatado.
- `empresa` (object) — A ficha da Receita: razão social, fantasia, situação, abertura, natureza, porte, capital, CNAEs, endereço, Simples/MEI e sócios; sócio pessoa física, telefones e e-mail mascarados (`mascarado: true`).
- `ponto` (ConsultaPonto, pode ser null) — O endereço no mapa; `null` quando o CEP não está no CNEFE. → ver `ConsultaPonto` em **Estruturas**.
- `uso` (ConsultaUso) — Quem pagou esta consulta. → ver `ConsultaUso` em **Estruturas**.
- `_links` (object) — `self`, `cnpj`, `cep`, `pagina` e `api_index` absolutos.

**Erros**

- `400` — CNPJ ou CEP inválido (nada é cobrado).
- `401` — Credencial apresentada e recusada: sessão encerrada ou chave de API inválida.
- `402` — Franquia grátis do dia e saldo esgotados: `error` (`franquia_esgotada` ou `saldo_esgotado`), `message`, `gratis` (com `renova_em`) e `ofertas[]` com a URL de compra, na forma de `GET /api/consulta`.
- `404` — Não existe na base (a consulta não é cobrada).
- `429` — Consultas demais neste minuto; respeite o Retry-After (a consulta não é cobrada).
- `503` — Fonte dos dados ou serviço de saldo fora do ar (a consulta não é cobrada).

**Exemplo**

```sh
curl -s 'https://www.radar-cnpj.com/api/consulta/cnpj/00000000000191?lingua=pt'
```

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

Consulta um endereço pelo CEP: os endereços com coordenada (CNEFE/IBGE) e as empresas registradas nele.

Uma consulta, paga como a do CNPJ: franquia grátis do dia, depois o saldo. Devolve até 20 endereços e até 20 empresas; o total de endereços vem em `pontos_total`.

- **URL:** `https://www.radar-cnpj.com/api/consulta/cep/:cep`
- **Auth:** `none` — Público (algumas rotas de origem podem restringir por geo BR).

**Parâmetros de caminho**

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

**Query**

- `lingua` (string) — Língua das mensagens: `pt` ou `en` (padrão: a do navegador, senão inglês). Valores: `pt`, `en`.

**Headers**

- `Idempotency-Key` (string) — Chave da tentativa (até 80 caracteres): repetir a MESMA consulta com a mesma chave não desconta o saldo duas vezes.

**Resposta `200`**

Estrutura: `ConsultaCep`.

- `consulta` (string) — Sempre `cep`.
- `cep` (string) — CEP formatado.
- `endereco` (object, pode ser null) — Resumo do CEP: unidades, edifícios, bairro, cidade, UF, código IBGE, centro (lat/lon) e espécies.
- `pontos` (object[]) — Até 20 endereços do CEP, com logradouro, número, bairro, cidade, UF, coordenada e espécie.
- `pontos_total` (int) — Quantos endereços a origem devolveu para o CEP.
- `empresas` (ConsultaEmpresasDoCep, pode ser null) — `null` quando a base de empresas não respondeu. → ver `ConsultaEmpresasDoCep` em **Estruturas**.
- `fonte` (string, pode ser null) — Crédito da fonte dos endereços.
- `uso` (ConsultaUso) — Quem pagou esta consulta. → ver `ConsultaUso` em **Estruturas**.
- `_links` (object) — `self`, `cnpj`, `cep`, `pagina` e `api_index` absolutos.

**Erros**

- `400` — CNPJ ou CEP inválido (nada é cobrado).
- `401` — Credencial apresentada e recusada: sessão encerrada ou chave de API inválida.
- `402` — Franquia grátis do dia e saldo esgotados: `error` (`franquia_esgotada` ou `saldo_esgotado`), `message`, `gratis` (com `renova_em`) e `ofertas[]` com a URL de compra, na forma de `GET /api/consulta`.
- `404` — Não existe na base (a consulta não é cobrada).
- `429` — Consultas demais neste minuto; respeite o Retry-After (a consulta não é cobrada).
- `503` — Fonte dos dados ou serviço de saldo fora do ar (a consulta não é cobrada).

**Exemplo**

```sh
curl -s 'https://www.radar-cnpj.com/api/consulta/cep/01310100?lingua=pt'
```

### `POST /api/consulta/planos/:oferta`

Compra o pacote avulso ou um dos três planos da consulta de CNPJ e endereço, para a conta ou o crédito.

O saldo fica com a conta (cookie da sessão ou `X-Api-Key: mmk_…`) ou, sem conta, com a carteira do crédito que pagou (`X-Credito`). Sem pagamento, 402 com o preço e as portas: crédito pré-pago (comprado também por Pix) ou x402. Plano soma 30 dias e a quota dele ao que já existe; o pacote vale 90 dias. Sem renovação automática.

- **URL:** `https://www.radar-cnpj.com/api/consulta/planos/:oferta`
- **Auth:** `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou header `X-Credito`). Não é conta: é portador de saldo.

**Parâmetros de caminho**

- `oferta` (string, obrigatório) — A oferta: `pacote`, `basico`, `profissional` ou `empresa`. Ex.: `basico`.

**Query**

- `lingua` (string) — Língua das mensagens: `pt` ou `en` (padrão: a do navegador, senão inglês). Valores: `pt`, `en`.
- `compra` (string) — Marca desta compra (8 a 64 caracteres `A-Za-z0-9_-`): repetir com a mesma marca não cobra de novo.

**Headers**

- `X-Credito` (string) — Token do crédito pré-pago (`cred_…`) que paga a compra.
- `X-Api-Key` (string) — Chave de API da conta (`mmk_…`): o plano fica com a conta.
- `X-PAYMENT` (string) — Pagamento x402 assinado, a partir da cotação do 402.

**Resposta `200`**

Estrutura: `ConsultaCompra`.

- `comprado` (string) — Id da oferta comprada.
- `nome` (string) — Nome da oferta na língua pedida.
- `consultas` (int) — Consultas desta compra.
- `valido_ate` (string, pode ser null) — Até quando esta compra vale (ISO).
- `saldo` (object) — `consultas` (o saldo somado depois da compra) e `dono` (`conta` ou `carteira`).
- `via` (string) — `credito` ou `x402`.
- `recibo` (string) — O recibo do pagamento (a mesma compra repetida devolve o mesmo).
- `message` (string) — Confirmação na língua pedida.
- `_links` (object) — `consulta`: o serviço, com o saldo novo.

**Erros**

- `401` — Sem conta nem crédito para o plano ficar, ou credencial recusada.
- `402` — Pagamento necessário: o preço, o crédito e o x402.
- `404` — Oferta desconhecida.
- `409` — Cobrança desligada nesta oferta: nada foi cobrado nem criado.
- `503` — Oferta sem preço configurado ou pagamento fora do ar.

**Exemplo**

```sh
curl -s -X POST 'https://www.radar-cnpj.com/api/consulta/planos/basico?compra=minha-compra-01' -H "X-Credito: $CREDITO"
```

## API access

### `GET /api/acesso`

Discover the monthly data package or inspect a private purchase.

- **URL:** `https://www.radar-cnpj.com/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://www.radar-cnpj.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://www.radar-cnpj.com/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://www.radar-cnpj.com/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`.

### `ConsultaServico`

O serviço de consulta de CNPJ e endereço neste portal.

- `servico` (string) — Sempre `consulta`.
- `nome` (string) — Nome do serviço na língua pedida.
- `descricao` (string) — O que ele entrega e como se paga, numa frase.
- `gratis` (ConsultaFranquia) — A franquia de hoje para esta rede. → ver `ConsultaFranquia` em **Estruturas**.
- `ofertas` (ConsultaOferta[]) — O pacote avulso e os três planos. → ver `ConsultaOferta` em **Estruturas**.
- `saldo` (ConsultaSaldo, pode ser null) — O saldo de quem pediu; `null` sem conta nem crédito. → ver `ConsultaSaldo` em **Estruturas**.
- `como_comprar` (string) — Como comprar pela API, na língua pedida.
- `_links` (object) — `self`, `cnpj`, `cep`, `pagina` e `api_index` absolutos.

### `ConsultaCnpj`

A ficha pública da empresa e onde fica o endereço dela.

- `consulta` (string) — Sempre `cnpj`.
- `cnpj` (string) — CNPJ formatado.
- `empresa` (object) — A ficha da Receita: razão social, fantasia, situação, abertura, natureza, porte, capital, CNAEs, endereço, Simples/MEI e sócios; sócio pessoa física, telefones e e-mail mascarados (`mascarado: true`).
- `ponto` (ConsultaPonto, pode ser null) — O endereço no mapa; `null` quando o CEP não está no CNEFE. → ver `ConsultaPonto` em **Estruturas**.
- `uso` (ConsultaUso) — Quem pagou esta consulta. → ver `ConsultaUso` em **Estruturas**.
- `_links` (object) — `self`, `cnpj`, `cep`, `pagina` e `api_index` absolutos.

### `ConsultaCep`

Os endereços de um CEP e as empresas registradas nele.

- `consulta` (string) — Sempre `cep`.
- `cep` (string) — CEP formatado.
- `endereco` (object, pode ser null) — Resumo do CEP: unidades, edifícios, bairro, cidade, UF, código IBGE, centro (lat/lon) e espécies.
- `pontos` (object[]) — Até 20 endereços do CEP, com logradouro, número, bairro, cidade, UF, coordenada e espécie.
- `pontos_total` (int) — Quantos endereços a origem devolveu para o CEP.
- `empresas` (ConsultaEmpresasDoCep, pode ser null) — `null` quando a base de empresas não respondeu. → ver `ConsultaEmpresasDoCep` em **Estruturas**.
- `fonte` (string, pode ser null) — Crédito da fonte dos endereços.
- `uso` (ConsultaUso) — Quem pagou esta consulta. → ver `ConsultaUso` em **Estruturas**.
- `_links` (object) — `self`, `cnpj`, `cep`, `pagina` e `api_index` absolutos.

### `ConsultaCompra`

O que a compra entregou.

- `comprado` (string) — Id da oferta comprada.
- `nome` (string) — Nome da oferta na língua pedida.
- `consultas` (int) — Consultas desta compra.
- `valido_ate` (string, pode ser null) — Até quando esta compra vale (ISO).
- `saldo` (object) — `consultas` (o saldo somado depois da compra) e `dono` (`conta` ou `carteira`).
- `via` (string) — `credito` ou `x402`.
- `recibo` (string) — O recibo do pagamento (a mesma compra repetida devolve o mesmo).
- `message` (string) — Confirmação na língua pedida.
- `_links` (object) — `consulta`: o serviço, com o saldo novo.

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

### `ConsultaFranquia`

As consultas grátis do dia, por rede (IP), somadas no Radar CNPJ, no PontoFato e no EditalMD.

- `por_dia` (int) — Quantas consultas saem de graça por dia.
- `restantes_hoje` (int) — Quantas ainda saem de graça hoje (dia UTC).
- `renova_em` (string, opcional) — Quando a franquia volta (ISO, virada do dia UTC).

### `ConsultaOferta`

O pacote avulso ou um dos três planos, com o preço deste portal.

- `id` (string) — `pacote`, `basico`, `profissional` ou `empresa`.
- `tipo` (string) — `pacote` (vale 90 dias) ou `plano` (30 dias; comprar de novo soma 30).
- `nome` (string) — Nome da oferta na língua pedida.
- `consultas` (int) — Consultas incluídas.
- `dias` (int) — Validade em dias, a partir da compra.
- `renovacao_automatica` (bool) — Sempre `false`: a renovação é uma compra explícita.
- `preco_usd` (string, pode ser null) — Preço em dólares (`"5.00"`); `null` quando não está à venda.
- `preco_brl` (string, pode ser null) — O mesmo preço em reais, no câmbio do Pix da casa.
- `disponivel` (bool) — `false` quando o portal não tem o preço configurado.
- `compra` (string) — URL absoluta da compra (POST).

### `ConsultaSaldo`

O saldo de quem pediu, somado entre planos e pacotes vigentes, válido em todos os portais.

- `dono` (string) — `conta` (sessão ou chave de API) ou `carteira` (crédito).
- `consultas` (int) — Consultas restantes, somadas.
- `planos` (ConsultaPlanoAtivo[]) — As compras vigentes, a que vence primeiro antes. → ver `ConsultaPlanoAtivo` em **Estruturas**.

### `ConsultaPonto`

Onde fica o endereço da empresa no CNEFE (IBGE, 2022).

- `lat` (number) — Latitude WGS84.
- `lon` (number) — Longitude WGS84.
- `precisao` (string) — `numero` (o mesmo número no CEP) ou `cep` (o centro do CEP).
- `logradouro` (string, pode ser null) — Logradouro do ponto, quando achado pelo número.
- `numero` (string, pode ser null) — Número do ponto, quando achado pelo número.
- `bairro` (string, pode ser null) — Bairro do cadastro de endereços.
- `cidade` (string, pode ser null) — Município IBGE.
- `uf` (string, pode ser null) — Sigla da UF.
- `cep` (string, pode ser null) — CEP formatado.
- `fonte` (string, pode ser null) — Crédito da fonte dos endereços.

### `ConsultaUso`

Quem pagou esta consulta.

- `via` (string) — `gratis` (franquia do dia) ou `saldo` (plano ou pacote).
- `restantes` (int, pode ser null) — Quantas restam na mesma via depois desta.

### `ConsultaEmpresasDoCep`

As empresas registradas no CEP (a primeira página).

- `itens` (object[]) — Até 20 cards: `cnpj`, `cnpjFormatted`, `razaoSocial`, `nomeFantasia`, `situacao`, `bairro` e `cnae`.
- `mais` (bool) — `true` quando o CEP tem mais empresas que as devolvidas.

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

### `ConsultaPlanoAtivo`

Um plano ou pacote vigente do dono.

- `oferta` (string) — Id da oferta comprada.
- `nome` (string) — Nome da oferta na língua pedida.
- `restantes` (int) — Consultas que ainda restam nesta compra.
- `valido_ate` (string, pode ser null) — Até quando vale (ISO).

### `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: consulta de CNPJ e endereço (`GET /api/consulta/cnpj/:cnpj`, `GET /api/consulta/cep/:cep`) — 10 por dia por rede, somadas nos portais; depois, o saldo do plano ou do pacote (válido em todos os portais).
- 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: consulta de CNPJ e endereço, Pacote avulso: 100 consultas por 90 dias, sem renovação automática (`POST /api/consulta/planos/pacote`) — **$1.00** USDC via x402.
- Pago: consulta de CNPJ e endereço, Básico: 1000 consultas por 30 dias, sem renovação automática (`POST /api/consulta/planos/basico`) — **$5.00** USDC via x402.
- Pago: consulta de CNPJ e endereço, Profissional: 3000 consultas por 30 dias, sem renovação automática (`POST /api/consulta/planos/profissional`) — **$10.00** USDC via x402.
- Pago: consulta de CNPJ e endereço, Empresa: 10000 consultas por 30 dias, sem renovação automática (`POST /api/consulta/planos/empresa`) — **$25.00** USDC via x402.
- 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://www.radar-cnpj.com/api/