# Radar CNPJ — referência completa da API

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

> Avalia ideia de negócio contra a oferta formal da Receita; consulta e monitora CNPJ.
> Este Worker é proxy fino: o dado mora em api.radar-cnpj.com.

## 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://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` — Monitoramento anônimo: header `x-radar-session` com o uuid de `POST /api/monitor/session`. Não há login — quem tem o uuid é o dono da sessão, então trate como segredo.
- `token` — Token de operador `METRICS_TOKEN` em `Authorization: Bearer`.

## Endpoints

## Descoberta

### `GET /okf/:arquivo`

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

- **URL:** `https://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://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) e `mcp-registry-auth` (chave do registro oficial de MCP).

- **URL:** `https://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`, `mcp-registry-auth` ou `apis.json`. Ex.: `api-catalog`.

**Resposta `200`**

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

**Erros**

- `404` — Nome fora dos quatro publicados.

**Exemplo**

```sh
curl -s https://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://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://radar-cnpj.com/apis.json
```

### `GET /api/`

Índice auto-descrito de toda a superfície deste Worker, com a origem declarada.

- **URL:** `https://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) — A API de dados por trás deste proxy — é lá que o dado mora.
- `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`

Saúde da origem e a idade do dado: de quando é o dump da Receita e o que ele tem.

`import.dump_date` é a data do dump da Receita e `import.counts` traz a contagem por tabela — é onde se descobre que o dado tem semanas, não minutos.

- **URL:** `https://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://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://radar-cnpj.com/mcp -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Avaliar ideia

### `POST /api/avaliar`

Cola uma ideia de negócio em texto e recebe a ficha da oferta formal na Receita.

É 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://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://radar-cnpj.com/api/avaliar -H 'content-type: application/json' -d '{"texto":"padaria em Campinas"}'
```

## Consulta

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

A ficha cadastral completa de uma empresa, pelos 14 dígitos do CNPJ.

Cacheada na borda por 6 horas — o dump da Receita não muda em minutos.

- **URL:** `https://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 completo: identificação, endereço, sócios, CNAEs, Simples e situação.

**Erros**

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

**Exemplo**

```sh
curl -s https://radar-cnpj.com/api/cnpj/00000000000191
```

### `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://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, quando não é busca livre.
- `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://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://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, quando não é busca livre.
- `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://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://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://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://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://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://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://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://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://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://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`.

**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://radar-cnpj.com/api/ia/jobs/JOB_ID
```

## Geo

### `GET /api/local`

Cidade e UF de quem está chamando, pela borda da Cloudflare.

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

- **URL:** `https://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`

O município do IBGE mais próximo de um par de coordenadas, com o bairro do CNEFE.

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

- **URL:** `https://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`, `descricao`, `uf` e `km` — a distância até o centro do município.
- `bairro` (object, opcional) — Bairro do CNEFE mais próximo, quando existe.
- `cep` (string, opcional) — CEP mais próximo, quando existe.

**Erros**

- `400` — `lat` ou `lon` ausentes ou fora da faixa.

**Exemplo**

```sh
curl -s 'https://radar-cnpj.com/api/municipio-proximo?lat=-23.55&lon=-46.63'
```

## Monitoramento

### `POST /api/monitor/session`

Cria uma sessão anônima de monitoramento e devolve o uuid dela.

Não pede e-mail nem senha. O uuid vai no header `x-radar-session` de todas as outras rotas de monitor.

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

**Resposta `200`**

Estrutura: `Sessao`.

- `session_id` (string) — UUID a mandar no header `x-radar-session` nas rotas de monitor.

**Exemplo**

```sh
curl -s -XPOST https://radar-cnpj.com/api/monitor/session
```

### `PUT /api/monitor/session/email`

Cadastra o e-mail que vai receber os alertas desta sessão.

Sem e-mail confirmado os alertas continuam sendo gerados, mas ficam retidos — aparecem em `retidos` de `GET /api/me/monitor/alerts`.

- **URL:** `https://radar-cnpj.com/api/monitor/session/email`
- **Auth:** `session` — Monitoramento anônimo: header `x-radar-session` com o uuid de `POST /api/monitor/session`. Não há login — quem tem o uuid é o dono da sessão, então trate como segredo.

**Headers**

- `x-radar-session` (string, obrigatório) — UUID da sessão, vindo de `POST /api/monitor/session`.

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

- `email` (string, obrigatório) — Endereço que vai receber os alertas.

**Exemplo de corpo**

```json
{
  "email": "a@example.com"
}
```

**Resposta `200`**

Estrutura: `Ok`.

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

**Erros**

- `400` — E-mail ausente ou malformado.
- `401` — Header `x-radar-session` ausente ou desconhecido.

**Exemplo**

```sh
curl -s -XPUT https://radar-cnpj.com/api/monitor/session/email -H "x-radar-session: $SESSAO" -H 'content-type: application/json' -d '{"email":"a@example.com"}'
```

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

Os CNPJs que esta sessão acompanha, com a cota aplicada pela origem.

Quem decide a cota é a origem (`api.radar-cnpj.com`), que tem banco e transação — este Worker só reage ao 402 dela. Por isso `quota` e `plan` vêm na resposta, e não de uma variável local.

- **URL:** `https://radar-cnpj.com/api/me/monitor/watches`
- **Auth:** `session` — Monitoramento anônimo: header `x-radar-session` com o uuid de `POST /api/monitor/session`. Não há login — quem tem o uuid é o dono da sessão, então trate como segredo.

**Headers**

- `x-radar-session` (string, obrigatório) — UUID da sessão de monitoramento.

**Resposta `200`**

Estrutura: `Watches`.

- `ok` (bool) — Sempre `true`.
- `watches` (object[]) — Um item por CNPJ acompanhado.
- `plan` (string) — Plano em vigor para a sessão, decidido pela origem.
- `quota` (int) — Quantos watches a sessão pode ter.
- `used` (int) — Quantos já estão em uso.
- `suspensas` (object[]) — Watches suspensos e por quê.

**Erros**

- `401` — Header `x-radar-session` ausente ou desconhecido.

**Exemplo**

```sh
curl -s https://radar-cnpj.com/api/me/monitor/watches -H "x-radar-session: $SESSAO"
```

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

Passa a acompanhar um CNPJ. Os primeiros 10 da sessão são grátis; a partir daí, x402 por 30 dias.

Quem cobra é a origem: ela responde **402 com `accepts[]`** e este Worker repassa. Pague e repita a mesma chamada com `X-PAYMENT`.

- **URL:** `https://radar-cnpj.com/api/me/monitor/watch`
- **Auth:** `session` — Monitoramento anônimo: header `x-radar-session` com o uuid de `POST /api/monitor/session`. Não há login — quem tem o uuid é o dono da sessão, então trate como segredo.

**Headers**

- `x-radar-session` (string, obrigatório) — UUID da sessão de monitoramento.

**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` — Sessão ausente ou desconhecida.
- `402` — Cota estourada. A resposta traz `accepts[]` (x402, USDC na Base): pague e repita a mesma chamada com `X-PAYMENT`.

**Exemplo**

```sh
curl -s -XPOST https://radar-cnpj.com/api/me/monitor/watch -H "x-radar-session: $SESSAO" -H "X-PAYMENT: $PAGAMENTO" -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://radar-cnpj.com/api/me/monitor/watch/:cnpj`
- **Auth:** `session` — Monitoramento anônimo: header `x-radar-session` com o uuid de `POST /api/monitor/session`. Não há login — quem tem o uuid é o dono da sessão, então trate como segredo.

**Parâmetros de caminho**

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

**Headers**

- `x-radar-session` (string, obrigatório) — UUID da sessão de monitoramento.

**Resposta `200`**

Estrutura: `Ok`.

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

**Erros**

- `401` — Sessão ausente ou desconhecida.
- `404` — Este CNPJ não está sendo acompanhado por esta sessão.

**Exemplo**

```sh
curl -s -XDELETE https://radar-cnpj.com/api/me/monitor/watch/00000000000191 -H "x-radar-session: $SESSAO"
```

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

Os alertas gerados para os CNPJs que esta sessão acompanha.

`retidos` traz o que existe e não foi entregue — normalmente por não haver e-mail confirmado na sessão.

- **URL:** `https://radar-cnpj.com/api/me/monitor/alerts`
- **Auth:** `session` — Monitoramento anônimo: header `x-radar-session` com o uuid de `POST /api/monitor/session`. Não há login — quem tem o uuid é o dono da sessão, então trate como segredo.

**Headers**

- `x-radar-session` (string, obrigatório) — UUID da sessão de monitoramento.

**Resposta `200`**

Estrutura: `Alertas`.

- `ok` (bool) — Sempre `true`.
- `alerts` (object[]) — Um item por alteração detectada num CNPJ acompanhado.
- `retidos` (object[]) — Alertas que existem mas não foram entregues — normalmente por falta de e-mail confirmado.

**Erros**

- `401` — Sessão ausente ou desconhecida.

**Exemplo**

```sh
curl -s https://radar-cnpj.com/api/me/monitor/alerts -H "x-radar-session: $SESSAO"
```

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

- **URL:** `https://radar-cnpj.com/api/monitor/changes/:cnpj`
- **Auth:** `session` — Monitoramento anônimo: header `x-radar-session` com o uuid de `POST /api/monitor/session`. Não há login — quem tem o uuid é o dono da sessão, então trate como segredo.

**Parâmetros de caminho**

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

**Headers**

- `x-radar-session` (string, obrigatório) — UUID da sessão de monitoramento.

**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` — Sessão ausente ou desconhecida.
- `404` — CNPJ sem histórico ou fora da base.

**Exemplo**

```sh
curl -s https://radar-cnpj.com/api/monitor/changes/00000000000191 -H "x-radar-session: $SESSAO"
```

## Contato

### `POST /api/contato`

Fala com o suporte: humano resolve Turnstile, agente paga $0.10 em x402.

O primeiro envio de agente é livre; depois o backoff é 60s dobrando até o teto de 1 hora, informado em `Retry-After`. `POST /api/contact` é o mesmo recurso com os campos em inglês.

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

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

- `nome` (string, obrigatório) — Como chamar quem escreveu.
- `email` (string, obrigatório) — Para onde responder.
- `mensagem` (string, obrigatório) — O que você quer dizer.
- `aberto_em` (int) — Momento em que o formulário abriu; é anti-robô do caminho humano.
- `turnstile` (string) — Resposta do Turnstile; presente só no caminho humano.

**Exemplo de corpo**

```json
{
  "nome": "…",
  "email": "a@example.com",
  "mensagem": "…",
  "aberto_em": 0,
  "turnstile": "(humano)"
}
```

**Resposta `200`**

Estrutura: `Ok`.

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

**Erros**

- `400` — Campo obrigatório faltando.
- `402` — Cota estourada. A resposta traz `accepts[]` (x402, USDC na Base): pague e repita a mesma chamada com `X-PAYMENT`.
- `429` — Backoff de agente: espere o `Retry-After`.

**Exemplo**

```sh
curl -s -XPOST https://radar-cnpj.com/api/contato -H "X-PAYMENT: $PAGAMENTO" -H 'content-type: application/json' -d '{"nome":"Agente","email":"a@example.com","mensagem":"Olá"}'
```

### `POST /api/contact`

O mesmo contato de `/api/contato`, com os nomes de campo em inglês.

Existe porque agente que chegou pelo `llms.txt` de outro produto do mesmo dono já sabe mandar `name`/`email`/`message`. Mesmo backoff, mesmo preço.

- **URL:** `https://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 escreveu.
- `email` (string, obrigatório) — Para onde responder.
- `message` (string, obrigatório) — O que você quer dizer.
- `form_ts` (int) — Momento em que o formulário abriu; é anti-robô do caminho humano.

**Exemplo de corpo**

```json
{
  "name": "…",
  "email": "…",
  "message": "…",
  "form_ts": 0
}
```

**Resposta `200`**

Estrutura: `Ok`.

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

**Erros**

- `400` — Campo obrigatório faltando.
- `402` — Cota estourada. A resposta traz `accepts[]` (x402, USDC na Base): pague e repita a mesma chamada com `X-PAYMENT`.
- `429` — Backoff de agente: espere o `Retry-After`.

**Exemplo**

```sh
curl -s -XPOST https://radar-cnpj.com/api/contact -H "X-PAYMENT: $PAGAMENTO" -H 'content-type: application/json' -d '{"name":"Agente","email":"a@example.com","message":"Olá"}'
```

### `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`, `accounts`), sem cache.

- **URL:** `https://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[]) — Um registro por dia da janela.
- `usage` (object) — Uso por recurso — aqui, `queries`.
- `accounts` (object) — Sessões de monitoramento existentes.

**Erros**

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

**Exemplo**

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

## Crédito

### `POST /api/credito`

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

- **URL:** `https://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://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://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://radar-cnpj.com/api/credito -H 'Authorization: Bearer cred_…'
```

## Estruturas

### `SaudeOrigem`

Saúde da origem e a idade do dado. É aqui que se vê de quando é o dump da Receita.

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

A leitura de uma ideia de negócio contra a oferta formal da Receita. É o primeiro produto da home.

- `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, repassada da origem. `data` é o cadastro da Receita como ela o entrega — o formato é contrato da origem, não deste Worker.

- `ok` (bool) — Sempre `true` quando o CNPJ existe na base.
- `data` (object) — O cadastro completo: identificação, endereço, sócios, CNAEs, Simples e situação.

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

Onde o visitante está, segundo a borda da Cloudflare. 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 do IBGE mais próximo de um par de coordenadas, e o bairro do CNEFE quando dá para dizer.

- `ok` (bool) — Sempre `true`.
- `municipio` (object) — `codigo`, `descricao`, `uf` e `km` — a distância até o centro do município.
- `bairro` (object, opcional) — Bairro do CNEFE mais próximo, quando existe.
- `cep` (string, opcional) — CEP mais próximo, quando existe.

### `Sessao`

A sessão anônima de monitoramento. Não tem login: o uuid É a identidade, e quem o tem vê os watches.

- `session_id` (string) — UUID a mandar no header `x-radar-session` nas rotas de monitor.

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

### `Watches`

Os CNPJs que esta sessão acompanha, com a cota que a ORIGEM aplica — não este Worker.

- `ok` (bool) — Sempre `true`.
- `watches` (object[]) — Um item por CNPJ acompanhado.
- `plan` (string) — Plano em vigor para a sessão, decidido pela origem.
- `quota` (int) — Quantos watches a sessão pode ter.
- `used` (int) — Quantos já estão em uso.
- `suspensas` (object[]) — Watches suspensos e por quê.

### `Alertas`

Os alertas gerados para os watches desta sessão.

- `ok` (bool) — Sempre `true`.
- `alerts` (object[]) — Um item por alteração detectada num CNPJ acompanhado.
- `retidos` (object[]) — Alertas que existem mas não foram entregues — normalmente por falta de e-mail confirmado.

### `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` e `accounts` exigem `METRICS_TOKEN`.

- `app` (string) — Nome do produto.
- `today_visits` (int) — Visitantes distintos hoje — não conta autocomplete.
- `days` (object[]) — Um registro por dia da janela.
- `usage` (object) — Uso por recurso — aqui, `queries`.
- `accounts` (object) — Sessões de monitoramento existentes.

### `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, direto da Receita.
- `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 na Receita.
- `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.


## Cota

- Grátis: avaliar ideia (`POST /api/avaliar`) — sem cota.
- Grátis: consulta e busca de CNPJ — sem cota (cache de borda 6h).
- Grátis: monitoramento de CNPJ — 10 watches por sessão (a cota vem da origem: `quota` em `GET /api/me/monitor/watches`).
- Pago: watch de monitoramento além dos 10 da sessão, por 30 dias — **$0.50** USDC via x402.
- Pago: contato de agente — **$0.10** USDC via x402.

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

Números em vigor: https://radar-cnpj.com/api/