# API Asender — documentação completa

Este arquivo é a documentação INTEIRA da API aberta, em texto puro: convenções,
guias e todas as 612 operações, com o que cada uma faz, o que recebe e o que
devolve.

Ele existe porque um agente não navega — precisa do contexto todo de uma vez.
A versão navegável para pessoas está em https://developers.asender.net; cada API tem a
sua página em https://developers.asender.net/apis/<slug>.html.
Especificação OpenAPI unificada: https://developers.asender.net/openapi.json
Dúvidas de uso do produto (não de integração): https://developers.asender.net

Cada ferramenta é um sistema à parte, com endereço próprio. Elas compartilham a
identidade (a mesma credencial vale nas superfícies da conta) e se integram entre
si, mas falham separadamente: uma fora do ar não derruba as outras.

APIs:
  https://api.crm.asender.net        CRM  -> /apis/crm.html
  https://api.mail.asender.net       E-mail  -> /apis/mail.html
  https://auth.asender.net           Identidade (OIDC / OAuth 2.1)  -> /apis/auth.html
  https://api.pages.asender.net      Páginas  -> /apis/pages.html
  https://api.asender.net            Plataforma  -> /apis/platform.html
  (interno)                          Atendimento [em breve]  -> /apis/atendimento.html
  (interno)                          E-mail Marketing [em breve]  -> /apis/emailmarketing.html
  (interno)                          Push [em breve]  -> /apis/push.html
  (interno)                          SMS [em breve]  -> /apis/sns.html
  (interno)                          WhatsApp [em breve]  -> /apis/zapify.html



==============================================================================
# GUIA: Integrações: todos os meios
==============================================================================

Este é o mapa de **todos os meios de integrar com a Asender**. Para cada um: para que serve,
quando usar, como autenticar, onde fica e qual guia aprofunda. Se você ainda não sabe qual
usar, vá direto para a [tabela de decisão](#quero-x-use-y).

A Asender é um conjunto de ferramentas independentes (e-mail, CRM, páginas, mensageria,
atendimento) sob uma identidade só. Cada ferramenta tem a API dela num endereço próprio;
uma **API pública da plataforma** reúne o envio de mensagens e a leitura de dados. Uma
ferramenta fora do ar não derruba as outras.

## Visão rápida

| Meio | Para que serve | Autenticação | Endereço |
| --- | --- | --- | --- |
| [API REST pública](#api-rest-publica) | Enviar e-mail, SMS, WhatsApp, push, Telegram; ler leads, campanhas, mensagens, analytics | API key `sk_live_`/`sk_test_` com escopos; token de app OAuth (só leitura) | `https://api.asender.net/v1` |
| [API de E-mail](#api-de-e-mail) | Caixas, domínios e envio a partir de uma caixa | API key `sk_…` | `https://api.mail.asender.net` |
| [API do CRM](#api-do-crm) | Operar o CRM como o painel faz | Sessão do usuário | `https://api.crm.asender.net` |
| [API de Páginas](#api-de-paginas) | Criar e publicar páginas, formulários, enviar leads | API key com escopos `pages:*`/`forms:*`; sessão | `https://api.pages.asender.net` |
| [Entrar com Asender](#entrar-com-asender-oauth) | Login de usuários Asender no seu app e leitura de dados com consentimento | OAuth 2.1 + PKCE | `https://auth.asender.net` |
| [Servidor MCP](#servidor-mcp) | Agentes de IA operando a conta | OAuth (token de app, com registro automático do cliente) ou chave `sk_*` | `https://api.asender.net/mcp` |
| [Webhooks](#webhooks) | Ser avisado de eventos no seu sistema | Assinatura v1 (`Asender-Signature`) | seu endpoint |
| [SMTP e IMAP](#smtp-e-imap) | Clientes de e-mail e sistemas legados | Senha de aplicativo | hosts no guia |
| [No navegador](#no-navegador) | Formulário, pixel, chat e Web Push no seu site | Chaves públicas do navegador (nunca `sk_`) | `https://sites.asender.net` |
| [Domínios e DNS](#dominios-e-dns) | Enviar e publicar no seu domínio | Conta com acesso ao DNS | seu provedor DNS |
| [Conversões e conectores](#conversoes-e-conectores) | Meta/Google/TikTok; Kommo; HTTP próprio | Credenciais do destino | painel |
| [Para agentes de IA](#para-agentes-de-ia) | Documentação em texto puro e OpenAPI | pública | `https://developers.asender.net` |

---

## API REST pública

**Para que serve.** É a porta de integração de máquina da plataforma. Dois grupos de rotas:

- **Enviar mensagens**, de servidor para servidor:
  `POST /v1/emails/send` e `/v1/emails/batch` (até 500), `POST /v1/sms/send`,
  `POST /v1/whatsapp/send`, `POST /v1/push/send`, `POST /v1/telegram/send`,
  `POST /v1/whatsweb/send` (WhatsApp pelo aparelho) e `POST /v1/telegramconta/send`
  (Telegram pela conta). Também `GET /v1/senders` (de quais endereços sua chave pode enviar).
- **Ler dados** da conta: `/v1/leads`, `/v1/forms` (e envios), `/v1/conversions`,
  `/v1/campaigns` e `/v1/reports/email/*`, `/v1/messaging/*` (SMS, WhatsApp, push),
  `/v1/analytics/*`, `/v1/conversations`, `/v1/journeys`, mais `/v1/emails` (histórico),
  `/v1/account`, `/v1/account/usage` e `/v1/logs` (o log das suas próprias requisições).

**Quando usar.** Seu backend dispara mensagens transacionais ou de campanha, ou sincroniza
leads e métricas para outro sistema.

**Autenticação.** `Authorization: Bearer sk_live_…` (produção) ou `sk_test_…` (teste). Cada
chave tem **escopos** (`email:send`, `sms:send`, `leads:read`, `campaigns:read`…); rota fora do
escopo responde `403`. Um app OAuth de terceiro também chama as rotas de **leitura**, com o
consentimento do usuário. A chave **nunca** vai para o navegador.

```bash
curl -X POST 'https://api.asender.net/v1/emails/send' \
  -H 'Authorization: Bearer sk_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 5b0c4d1e-8a3f-4e7b-9c21-aa17c2f0e001' \
  -d '{
    "Source": "avisos@seudominio.com.br",
    "Destination": { "ToAddresses": ["cliente@example.com"] },
    "Message": { "Subject": { "Data": "Seu código" }, "Body": { "Text": { "Data": "Código: 123456" } } }
  }'
```

**Guias.** [Referência da Plataforma](../apis/platform.html) · [Convenções](convencoes.html)
(formato, erros, paginação, idempotência, limites) · [Chaves de API e escopos](chaves-de-api.html).

---

## API de E-mail

**Para que serve.** Administrar domínios e caixas de e-mail corporativo, ler e enviar mensagens
de uma caixa, rascunhos, contatos e assinatura.

**Quando usar.** Você precisa enviar **a partir de uma caixa que existe** (ou construir um cliente
de e-mail sobre a plataforma). Para e-mail transacional de qualquer endereço de um domínio
verificado (por exemplo, código de verificação), use `POST /v1/emails/send` da API pública,
acima — não exige criar caixa.

**Autenticação.** API key `Authorization: Bearer sk_…`. Escopo de administração: `mail:admin`.

**Endereço.** `https://api.mail.asender.net` — envelope de erro `{ "error", "message" }`.

**Guias.** [API de E-mail](../apis/mail.html) · [Domínios e DNS](dominios.html) · [SMTP e IMAP](smtp-imap.html).

---

## API do CRM

**Para que serve.** Contatos, estágios, segmentos, jornadas, alertas e destinos de lead.

**Quando usar.** Você está construindo uma interface que opera o CRM **como usuário logado**.
A API do CRM é uma superfície de **sessão**: **não aceita API key**. Integração
máquina-a-máquina com dados de CRM passa pela API pública: leitura de contatos em
`GET /v1/leads`, jornadas em `GET /v1/journeys` e conversões em `GET /v1/conversions`, com os
escopos `leads:read`, `journeys:read` e `conversions:read`.

**Autenticação.** Sessão OIDC do usuário (`Authorization: Bearer <token>`) e o cabeçalho
`X-Asender-Tenant` com a conta em que opera.

**Endereço.** `https://api.crm.asender.net` — envelope de erro `{ "erro": "…" }`.

**Guia.** [API do CRM](../apis/crm.html).

---

## API de Páginas

**Para que serve.** Criar, editar e publicar páginas e formulários, mídia, domínios e redirects;
ler a analytics do que foi publicado; **enviar leads** de um sistema seu para um formulário.

**Quando usar.** Automatizar a construção de páginas (inclusive por agentes de IA) ou capturar
leads de um backend próprio.

**Autenticação.** Três públicos: sessão do usuário (construtor), **API key** com escopo
(`pages:read`, `pages:write`, `pages:publish`, `forms:read`, `forms:write`) para integração de
servidor, e credenciais públicas do navegador (formulário embutido, pixel).

**Endereço.** `https://api.pages.asender.net` (a página publicada e o runtime ficam em
`https://sites.asender.net`) — envelope de erro `{ "erro": "…" }` na autoria.

**Guias.** [API de Páginas](../apis/pages.html) · [O JSON do documento v2](pages-documento-v2.html).

---

## Entrar com Asender (OAuth)

**Para que serve.** Seu app identifica um usuário Asender e, com o consentimento dele, lê dados
da conta pela API pública, com escopos mínimos (somente leitura).

**Quando usar.** Você tem um produto de terceiro (site, SaaS, ferramenta interna) e quer "Entrar
com Asender", ou precisa de acesso delegado a dados de clientes sem pedir a chave de API deles.

**Autenticação.** Authorization Code com **PKCE `S256` obrigatório**, cliente confidencial
(`client_secret_basic`), `redirect_uri` exata. Endpoints no discovery:
`https://auth.asender.net/.well-known/openid-configuration`. O token resultante chama a API
pública como `Authorization: Bearer <access_token>`.

**Cadastro do app.** Você mesmo cadastra e gerencia o app no **Portal de Aplicativos** do painel
(`admin.asender.net`, em Desenvolvedores > Aplicativos): credenciais, escopos, testadores e pedido
de revisão à equipe Asender. O guia de [Aplicativos](aplicativos.html) descreve o painel, o ciclo de
vida (desenvolvimento, revisão, publicado) e o selo Verificado.

**Guias.** [Entrar com Asender](entrar-com-asender.html) (fluxo completo, erros e exemplo de
código) · [Identidade (OIDC / OAuth 2.1)](../apis/auth.html).

---

## Servidor MCP

**Para que serve.** Conectar assistentes e agentes de IA (que falam o Model Context Protocol)
diretamente à sua conta Asender, como ferramentas.

**Quando usar.** Você quer que um agente consulte dados ou execute ações sem escrever um
cliente HTTP.

**Autenticação.** OAuth: o cliente MCP se registra sozinho em `auth.asender.net` (CIMD ou DCR),
o usuário autoriza na tela de consentimento e o agente apresenta o token no servidor MCP. Também
vale uma chave de API `sk_*` no header `Authorization`. O registro automático está em
[Aplicativos](aplicativos.html#clientes-registrados-automaticamente-mcp).

**Endereço.** `https://api.asender.net/mcp`. Somente leitura nesta fase. Veja o guia de
[MCP](mcp.html).

---

## Webhooks

**Para que serve.** A Asender chama o **seu endpoint** quando algo acontece (um e-mail ou SMS com
resultado, um lead novo, uma submissão de formulário, uma entrega do conector), e recebe webhooks de
provedores (status de mensagem, pagamento).

**Quando usar.** Você prefere ser avisado a ficar consultando a API (polling). Para ler o que
mudou desde a última vez, combine com `updated_after` nas rotas de dados da API pública.

**Autenticação.** Todos os emissores usam o formato **Asender Webhook v1**: `Asender-Signature:
t=<unix>,v1=<hex>` (HMAC-SHA256 sobre `"<t>.<corpo cru>"`, tolerância de 300 s), mais
`Asender-Webhook-Id` (deduplicação) e `Asender-Event`. **Verifique a assinatura sobre o corpo cru**
antes de confiar no conteúdo. Os cabeçalhos antigos saem em 2027-04-20. Endpoints de eventos da
conta: `/v1/webhooks` com chave de escopo `webhooks:manage`.

**Guia.** [Webhooks](webhooks.html) traz o formato v1, um verificador em Node, Python, Go e PHP, o
cadastro de cada emissor, as tentativas e como tratar duplicatas.

---

## SMTP e IMAP

**Para que serve.** Usar a caixa Asender de um cliente de e-mail (Thunderbird, Outlook, celular) ou
enviar de um sistema legado que só fala SMTP.

**Quando usar.** O software não consegue chamar HTTP, ou o usuário final quer o e-mail no app
de sempre.

**Autenticação.** **Senha de aplicativo** (uma por dispositivo ou sistema, revogável), nunca a senha
da conta. O DNS do domínio publica o autoconfig para que os clientes se configurem sozinhos.

**Guia.** [SMTP e IMAP](smtp-imap.html) (hosts, portas, senhas de aplicativo) e
[Domínios e DNS](dominios.html).

---

## No navegador

**Para que serve.** O que roda no site do **visitante**: formulário de captura (embed por
`<script>` ou HTML), pixel de analytics e de conversão, chat, Web Push e o SDK JavaScript
`@asender/pages-sdk`.

**Quando usar.** Você quer capturar leads, medir visitas ou assinar notificações no seu site, sem
backend próprio.

**Autenticação.** Credenciais **públicas**, restritas por origem e por escopo mínimo: o token do
formulário/pixel (embutido na página) e a chave `pk_push_…`, que só registra inscrição de Web
Push. **A chave `sk_…` nunca vai ao navegador.** Para enviar lead de um servidor seu, use a API de
Páginas com chave.

**Guia.** [No navegador](navegador.html).

---

## Domínios e DNS

**Para que serve.** Provar a posse e apontar o seu domínio: SPF, DKIM e DMARC para enviar e-mail;
CNAME/A para publicar páginas. O botão "Conectar com Cloudflare" usa **Domain Connect** e aplica os
registros por você, com a sua autorização.

**Quando usar.** Antes do primeiro envio com o seu domínio, ou ao publicar uma página nele.

**Guia.** [Domínios e DNS](dominios.html).

---

## Conversões e conectores

**Para que serve.** Devolver conversões de marketing para Meta, Google Ads e TikTok (API de
conversão, com deduplicação por `eventID`) e **entregar leads** a sistemas externos: Kommo e um
destino HTTP próprio.

**Quando usar.** Você quer otimizar campanhas de anúncio com a conversão real, ou encaminhar cada
lead capturado para o seu CRM/ERP.

**Autenticação.** Credenciais do destino (token do provedor, URL do seu endpoint), cadastradas no
painel e guardadas só no servidor.

**Guia.** [Conversões e conectores](conversoes-e-conectores.html).

---

## Para agentes de IA

**Para que serve.** Dar a um agente o contexto completo da API sem ele navegar página a página.

- [`llms.txt`](../llms.txt): índice curto, no padrão que os agentes procuram na raiz do domínio.
- [`llms-full.txt`](../llms-full.txt): toda a documentação (guias, operações e schemas) em um arquivo de texto.
- [`openapi.json`](../openapi.json) e [`openapi.yaml`](../openapi.yaml): OpenAPI 3.1 unificada da API
  pública; cada API também tem a sua em `apis/<api>.openapi.yaml`.

Para o agente **operar** a conta (e não só ler a documentação), use o [servidor MCP](#servidor-mcp).

---

## Quero X, use Y

| Quero… | Use | Autenticação |
| --- | --- | --- |
| Enviar um e-mail transacional ou código de verificação do meu backend | [API pública](#api-rest-publica): `POST /v1/emails/send` | API key, escopo `email:send` |
| Enviar muitos e-mails numa chamada | `POST /v1/emails/batch` (até 500) | API key, `email:send` |
| Enviar SMS, WhatsApp ou push | `POST /v1/sms/send`, `/v1/whatsapp/send`, `/v1/push/send` | API key, `sms:send`, `whatsapp:send`, `push:send` |
| Enviar de uma caixa de e-mail corporativa | [API de E-mail](#api-de-e-mail) | API key |
| Ler leads e contatos para o meu sistema | `GET /v1/leads` (use `updated_after`) | API key `leads:read` ou app OAuth |
| Ler campanhas e relatórios | `GET /v1/campaigns`, `/v1/reports/email/*`, `/v1/messaging/*` | API key `campaigns:read`/`messaging:read` |
| Saber o que mudou sem ficar consultando | [Webhooks](#webhooks) + `updated_after` | assinatura v1 do webhook |
| Pôr "Entrar com Asender" no meu produto | [OAuth](#entrar-com-asender-oauth) | OAuth 2.1 + PKCE |
| Cadastrar e gerir o meu app OAuth sozinho | [Portal de Aplicativos](aplicativos.html) no painel | sessão no painel (owner ou admin) |
| Deixar um agente de IA operar a conta | [Servidor MCP](#servidor-mcp) | OAuth ou chave `sk_*` |
| Dar a um agente a documentação inteira | [`llms-full.txt`](../llms-full.txt) e [`openapi.json`](../openapi.json) | pública |
| Capturar leads no meu site | [Formulário embutido ou SDK](#no-navegador) | credencial pública da página |
| Enviar um lead do meu servidor para um formulário | [API de Páginas](#api-de-paginas) | API key `forms:write` |
| Medir visitas e conversões da página | [Pixel](#no-navegador) | token do pixel |
| Pedir permissão de notificação no site | [Web Push](#no-navegador) | chave `pk_push_` |
| Criar ou publicar páginas por código ou por IA | [API de Páginas](#api-de-paginas) | API key `pages:*` |
| Usar a caixa no Thunderbird, Outlook ou celular | [SMTP e IMAP](#smtp-e-imap) | senha de aplicativo |
| Mandar a conversão para Meta, Google ou TikTok | [Conversões e conectores](#conversoes-e-conectores) | credencial do destino |
| Entregar cada lead ao Kommo ou ao meu endpoint | [Conectores](#conversoes-e-conectores) | credencial do destino |
| Configurar SPF/DKIM/DMARC do meu domínio | [Domínios e DNS](#dominios-e-dns) | acesso ao DNS |
| Operar o CRM numa interface minha | [API do CRM](#api-do-crm) | sessão do usuário (sem API key) |

## Antes de integrar

- **Escolha a credencial mais restrita que resolve.** Chave de servidor com o menor conjunto de
  escopos, ou token OAuth de leitura; nunca a chave no navegador. Ver [chaves de API](chaves-de-api.html).
- **Cada API tem o seu envelope de erro.** Não reaproveite o parser de uma em outra:
  veja as [convenções](convencoes.html#dois-envelopes-de-erro).
- **O que está "planejado" ou "em implantação" nesta página ainda não é contrato.** Só o que a
  referência de cada API lista é estável.



==============================================================================
# GUIA: Chaves de API e escopos
==============================================================================

# Chaves de API

A chave de API é a credencial que o **seu servidor** usa para falar com a API da
Asender: enviar e-mail, SMS, push e WhatsApp, e ler os dados da sua conta. Este
guia mostra como criar e usar uma chave, quais escopos existem, como mantê-la
segura e quando, em vez de uma chave, você deve usar um **app OAuth**.

- **Base da API:** `https://api.asender.net`
- **Formato:** `sk_live_…` ou `sk_test_…`, enviada em `Authorization: Bearer`
- **Onde criar:** painel de administração da conta, em **Chaves de API**

## Chave de API ou app OAuth: qual usar

| | **Chave de API** | **App OAuth** ("Entrar com Asender") |
| --- | --- | --- |
| Para quê | integração da **sua própria conta**, de servidor para servidor | um app que age em nome de **usuários de outras contas** |
| Quem autoriza | você, ao criar a chave | cada usuário, na tela de consentimento |
| Credencial | `sk_live_…` / `sk_test_…`, longa e estática | token de acesso de vida curta, renovado por refresh |
| Pode enviar mensagens | **sim** (escopos `*:send`) | **não**: só leitura |
| Pode ler dados | sim | sim, só o que o usuário concedeu |
| Revogação | você revoga a chave no painel | o usuário revoga o acesso do app, ou o app é bloqueado |

Regra prática: se o código roda **no seu servidor e age na sua conta** (disparar
um código de verificação, importar relatórios para o seu BI), use **chave de API**.
Se você vai oferecer um produto que **outras pessoas conectam à conta delas**, use
**app OAuth**: veja o [guia Entrar com Asender](https://developers.asender.net/guias/entrar-com-asender.html).
Não distribua a sua chave a clientes seus para "conectarem" a conta deles; é o
caso de uso do app OAuth.

## Criar uma chave

1. Entre no painel de administração da conta
   (`https://admin.asender.net/t/<conta>/api-keys`). Criar, editar e revogar
   chaves exige permissão de administração da conta.
2. Dê um **nome** que diga onde a chave é usada (por exemplo `site-checkout`).
3. Escolha o **modo** (`live` ou `test`; veja [abaixo](#live-e-test)) e marque
   **só os escopos** de que a integração precisa. Nasce marcado apenas
   `email:send`.
4. Clique em **Criar chave**. O segredo completo aparece **uma única vez**:
   copie e guarde num cofre ou no gerenciador de segredos do seu servidor. A
   Asender guarda só um hash; se você perder, revogue e crie outra.

Depois disso a lista mostra, para cada chave, o nome, o **prefixo** (por exemplo
`sk_live_ab12`, só para você reconhecê-la), o modo, os escopos, a data de criação e
o último uso (data e IP de origem).

Quem automatiza a emissão pode usar a API de sessão da plataforma
(`POST https://api.asender.net/api/tenants/{id}/api-keys`, com `name`, `scopes` e
opcionalmente `mode`); veja o [guia da API Platform](https://developers.asender.net/apis/platform.html).

## Usar a chave

```bash
curl -X POST 'https://api.asender.net/v1/emails/send' \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1042-confirmacao' \
  -d '{
    "Source": "contato@empresa.com.br",
    "Destination": { "ToAddresses": ["cliente@exemplo.test"] },
    "Message": { "Subject": { "Data": "Pedido confirmado" }, "Body": { "Text": { "Data": "Obrigado!" } } }
  }'
```

A mesma chave vale nas APIs de produto (por exemplo `api.mail.asender.net`,
`api.pages.asender.net`), conforme os escopos. Só o header `Authorization: Bearer`
é aceito; `X-Api-Key` e `?api_key=` respondem `401`.

## Escopos

Todo escopo tem o formato `<recurso>:<ação>`. **Chave sem escopo não funciona**:
a emissão sem escopos, ou com um valor fora desta tabela, é recusada com `400` (a
resposta traz a lista válida), e uma chave antiga sem escopo do catálogo recebe
`403 InsufficientScope` em toda rota. Cada rota exige exatamente um escopo.

### Envio

| escopo | o que permite |
| --- | --- |
| `email:send` | enviar e-mail (`POST /v1/emails/send` e `/v1/emails/batch`) e listar remetentes válidos (`GET /v1/senders`) |
| `sms:send` | enviar SMS (`POST /v1/sms/send`) |
| `push:send` | enviar notificações push (`POST /v1/push/send`) |
| `push:devices` | registrar e listar dispositivos de push (`/v1/push/devices`) |
| `whatsapp:send` | enviar WhatsApp oficial, por texto ou template (`POST /v1/whatsapp/send`) |
| `telegram:send` | enviar mensagem por bot do Telegram (`POST /v1/telegram/send`) |
| `whatsweb:send` | enviar WhatsApp por sessão, canal não oficial (`POST /v1/whatsweb/send`) |
| `telegramconta:send` | enviar pela conta pessoal do Telegram, canal não oficial (`POST /v1/telegramconta/send`) |

### Leitura

| escopo | o que permite |
| --- | --- |
| `email:read` | consultar mensagens de e-mail enviadas (`GET /v1/emails`, `/v1/emails/{id}`) |
| `account:read` | ler o consumo da conta (`GET /v1/account/usage`) |
| `logs:read` | ler o log das requisições feitas com as chaves da conta, com corpos redigidos (`GET /v1/logs`) |
| `leads:read` | listar e consultar contatos (leads) do CRM |
| `leads:write` | criar e atualizar contatos (leads) do CRM (`POST /v1/leads`, `PATCH /v1/leads/{id}`); só chave, nunca app OAuth; não inclui leitura. Também libera as ferramentas `asender_leads_create` e `asender_leads_update` do MCP |
| `conversions:read` | consultar conversões e o status das entregas às plataformas de anúncio |
| `analytics:read` | métricas de páginas e formulários |
| `campaigns:read` | campanhas de e-mail marketing e relatórios |
| `messaging:read` | mensagens e relatórios de SMS, WhatsApp e push |
| `conversations:read` | conversas e mensagens do atendimento |
| `journeys:read` | jornadas de automação do CRM |
| `webhooks:manage` | cadastrar, listar, alterar, apagar e testar os endpoints de webhook da conta (`/v1/webhooks`); só chave, nunca app OAuth |
| `dns:read` | ler zonas, registros e o histórico de DNS da conta (`GET /v1/dns/*`); só chave, nunca app OAuth |
| `dns:write` | criar, alterar e apagar registros de DNS (`POST`/`PATCH`/`DELETE /v1/dns/zones/{zona}/records`); só chave; não inclui leitura |
| `forms:read` | listar formulários e seus envios |

### Administração e conteúdo

| escopo | o que permite |
| --- | --- |
| `mail:admin` | criar e listar domínios e caixas do e-mail da conta. Não lê mensagens nem envia |
| `forms:write` | criar, editar e apagar formulários e enviar leads (em `api.pages.asender.net`) |
| `pages:read` | ler páginas, versões, rascunhos, SEO, domínios e mídia (em `api.pages.asender.net`) |
| `pages:write` | criar e editar páginas, salvar versões, importar, duplicar, mudar de domínio e enviar mídia. **Não publica** |
| `pages:publish` | publicar e despublicar páginas: a ação que o público enxerga, por isso é um escopo separado |

`GET /v1/account` (dados básicos da conta) aceita qualquer chave válida. O detalhe
rota a rota está no [guia da API Platform](https://developers.asender.net/apis/platform.html).

> **Painel e catálogo.** A API aceita os 28 escopos acima na emissão. Hoje a tela de
> criação do painel ainda não lista os escopos de canal não oficial (`telegram:send`,
> `whatsweb:send`, `telegramconta:send`); para uma chave com eles, emita pela API de
> sessão (`POST /api/tenants/{id}/api-keys`), com o escopo no corpo.

## Boas práticas

- **Uma chave por integração.** Se uma vazar, você revoga só ela, sem derrubar o
  resto. O nome da chave e o "último uso" mostram qual integração é qual.
- **O mínimo de escopos.** Um serviço que só dispara códigos de verificação precisa
  de `email:send` e nada mais. Uma chave de relatórios não deve ter `*:send`.
  Escopos de leitura e de envio raramente pertencem à mesma chave.
- **Só no servidor.** Nunca em JavaScript de navegador, em app mobile, em
  repositório, em log, em tela ou em chat. O que vai para o navegador não é
  segredo. As rotas de envio de push, WhatsApp, Telegram e canais não oficiais
  recusam chave de servidor usada de um navegador (`403 ServerKeyInBrowser`).
- **Variável de ambiente ou cofre.** Leia de `ASENDER_API_KEY` (ou do gerenciador
  de segredos), nunca do código-fonte. Não imprima a chave em log de erro.
- **Rotação.** Crie a chave nova, publique-a no seu ambiente, confirme o tráfego
  pelo "último uso" e **revogue a antiga**. Faça isso em intervalos regulares e
  sempre que alguém com acesso sair da equipe.
- **Idempotência nos envios.** Mande `Idempotency-Key` em todo envio que pode ser
  repetido por retry, para um retry não duplicar a mensagem nem a cobrança.
- **Respeite o rate limit.** O teto padrão é de 100 requisições por segundo, por
  chave; em `429`, espere o `Retry-After`. Veja o
  [guia da API Platform](https://developers.asender.net/apis/platform.html#rate-limits-v1).
- **Audite pelo log.** Com `logs:read`, `GET /v1/logs` mostra o que cada chave
  mandou e o que a API respondeu, com segredos e conteúdo redigidos.

## Revogar e alterar

Na lista de chaves, **Revogar** invalida a chave. Também é possível renomear uma
chave e trocar os seus escopos sem mudar o segredo. Como a API guarda a validação
em cache por pouco tempo, uma revogação ou troca de escopos passa a valer **em até
60 segundos**. Depois disso a chave revogada recebe `401`.

Se você suspeita de vazamento: revogue primeiro, investigue depois (o log da API
e o "último uso" dizem de onde veio o tráfego) e emita uma chave nova.

## Live e test

Ao criar a chave você escolhe o modo: **produção** (`sk_live_…`, o padrão) ou
**teste** (`sk_test_…`). Hoje a diferença é **só o rótulo**: o modo aparece no
painel e nos logs da API (filtro `mode`), e serve para separar o tráfego de
desenvolvimento do de produção. Não existe sandbox: uma chave `sk_test_` tem os
mesmos escopos e o mesmo rate limit, e a API não trata o envio feito com ela de
forma diferente. **Não use uma chave de teste para "ensaiar" envio a clientes
reais.** Um sandbox de verdade é **planejado**.

## Chave pública de site (`pk_push_`)

Para registrar visitantes do seu site para **web push**, o navegador não pode usar
uma chave `sk_…`. Existe uma chave própria para isso:

- formato `pk_push_…`, **pública** (vai no HTML do site, no snippet de push);
- é gerada no painel, na tela de push, junto do `manifest.json`, do service worker
  e do snippet já preenchidos, e fica **atrelada às origens** do site que você
  declara;
- só abre **uma** rota, `POST /v1/push/site/devices`, que registra a inscrição de
  web push do visitante. Não envia nada, não lê nada;
- é limitada por volume (por IP e por chave), porque, como toda chave de navegador,
  ela pode ser vista por qualquer visitante.

Ela não substitui a chave de API: para **enviar** o push, o seu servidor usa uma
chave `sk_…` com `push:send`. Veja o guia do
[navegador](https://developers.asender.net/guias/navegador.html) e a
[API Platform](https://developers.asender.net/apis/platform.html#push-e-dispositivos).

## Erros comuns

| resposta | causa | o que fazer |
| --- | --- | --- |
| `401 AuthorizationError` | chave ausente, errada, revogada ou expirada; ou enviada por `X-Api-Key`/`?api_key=` | confira o header `Authorization: Bearer` e se a chave está ativa |
| `403 InsufficientScope` | a chave não tem o escopo da rota (a mensagem nomeia o escopo) | crie uma chave com o escopo mínimo necessário |
| `403 ServerKeyInBrowser` | chave `sk_…` usada a partir de um navegador | chame do seu servidor; para web push use a chave `pk_push_…` |
| `400 ValidationError` na criação | `scopes` ausente, vazio ou com valor fora do catálogo | use só os escopos desta página |
| `429 Throttling` | passou do teto de requisições | espere o `Retry-After` e use backoff |

## Próximos passos

- [API Platform](https://developers.asender.net/apis/platform.html): todas as rotas, escopos e erros.
- [Entrar com Asender](https://developers.asender.net/guias/entrar-com-asender.html): apps que agem em nome de usuários de outras contas.
- [Aplicativos](https://developers.asender.net/guias/aplicativos.html): cadastrar e publicar o seu app OAuth no painel.
- [Webhooks](https://developers.asender.net/guias/webhooks.html): receber eventos em vez de consultar.
- Servidor MCP, em `https://api.asender.net/mcp`: veja o [guia MCP](https://developers.asender.net/guias/mcp.html).



==============================================================================
# GUIA: Webhooks
==============================================================================

# Webhooks de saída

Este guia descreve o que o Asender **envia** para o seu servidor por HTTP: o
formato de cada chamada, como conferir a assinatura, o que acontece quando o seu
endpoint falha e como tornar o seu receptor seguro. Ele descreve o que o código
faz **hoje**; o que ainda não existe aparece como "planejado" (veja a
[última seção](#planejado)).

> **Um formato só: Asender Webhook v1.** Os quatro emissores do Asender
> (eventos da conta, CRM, formulários do Páginas e conector de Integrações)
> enviam os mesmos três cabeçalhos — `Asender-Webhook-Id`, `Asender-Event` e
> `Asender-Signature` — e **um único verificador serve a todos**. Implemente o
> v1 e ignore os cabeçalhos antigos: eles continuam sendo enviados só até
> **2027-04-20** (veja [Formatos antigos](#formatos-antigos-descontinuados)).

## Visão geral

| # | Emissor | Eventos que envia (`Asender-Event`) | Onde se cadastra |
| --- | --- | --- | --- |
| 1 | **Eventos da conta** (e-mail, SMS, WhatsApp, push, Mail) | `email.queued`, `email.failed`, `sms.sent`, `sms.failed`, `whatsapp.sent`, `whatsapp.failed`, `push.delivered`, `push.failed`, `mail.sent`, `mail.received`, e `webhook.test` no teste | **API pública** `/v1/webhooks`, com chave de API de escopo `webhooks:manage` ([como usar](#api-v1-webhooks)) |
| 2 | **Destinos de lead do CRM** | `crm.lead.captured` (lead novo) e `crm.teste` (botão **Testar**) | painel de Marketing, tela **Integrações → Nova integração** |
| 3 | **Destino "webhook" de formulário** (Páginas) | `form.submitted` (cada submissão aceita) | editor do formulário, em **Destinos → Webhook** |
| 4 | **Conector "API própria / CRM próprio"** (Integrações) | `connector.delivery` (um lead de formulário entregue à sua API) | painel de Admin, tela **Integrações** |

Pontos comuns aos quatro:

- O método é `POST` com corpo JSON (o conector do item 4 também aceita os métodos `PUT`/`PATCH`
  e formulário `application/x-www-form-urlencoded`, veja a [seção 4](#4-conector-api-propria-crm-proprio-integracoes)).
- **Responda `2xx` rápido** e processe depois. Qualquer outra resposta, ou o estouro
  do prazo, é falha e gera nova tentativa (a política exata de cada emissor está em
  [Retentativas](#retentativas-e-prazos)).
- **A entrega é "ao menos uma vez".** O mesmo evento pode chegar mais de uma vez.
  Seu receptor precisa ser idempotente: [deduplique por `Asender-Webhook-Id`](#idempotencia).
- **A assinatura é calculada sobre os bytes exatos do corpo.** Leia o corpo cru,
  confira a assinatura e só então interprete o JSON.
- **Sem segredo, sem assinatura.** Os emissores 2, 3 e 4 têm segredo opcional: sem
  ele a entrega sai **sem** `Asender-Signature` (configure sempre um segredo). O
  emissor 1 não entrega a endpoint sem segredo — o segredo é sempre gerado pelo Asender.

---

## O formato v1

### Cabeçalhos

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json` (o conector 4 também pode enviar `application/x-www-form-urlencoded`) |
| `Asender-Webhook-Id` | id da entrega, **o mesmo em todas as tentativas** da mesma entrega. É opaco: trate como texto, sem interpretar o formato |
| `Asender-Event` | o tipo do evento (veja a tabela da [visão geral](#visao-geral)) |
| `Asender-Signature` | `t=<unix>,v1=<hex>` — presente só quando há segredo |

Sem prefixo `X-`, de acordo com a RFC 6648.

### Como a assinatura é calculada

```
conteudo_assinado = "<t>" + "." + <corpo cru, byte a byte>
v1                = hex minúsculo( HMAC-SHA256( segredo, conteudo_assinado ) )
Asender-Signature = "t=<t>,v1=<v1>"
```

- `t` é o horário da tentativa em **segundos Unix (UTC)**, em decimal. **Cada tentativa
  é assinada de novo** com o `t` da própria tentativa; só o `Asender-Webhook-Id` é estável.
- O segredo entra como a **string** que você guardou (`whsec_…` no emissor 1), sem
  decodificar nada.
- **Tolerância de 300 segundos** (5 minutos): recuse a entrega se `|agora − t| > 300`.
  Como cada tentativa leva um `t` novo, a janela não atrapalha as retentativas.
- **Vários `v1=` na rotação.** O valor pode trazer mais de um `v1=` (por exemplo
  `t=1792485815,v1=aaa…,v1=bbb…`), cada um calculado com um segredo diferente, para que
  você troque o segredo sem janela de falha. Aceite a entrega se **qualquer** `v1=`
  conferir com o segredo que você tem. Os verificadores abaixo já fazem isso. Hoje os
  emissores enviam um único `v1=`; o endpoint de rotação ainda é [planejado](#planejado).
- Compare **em tempo constante** (nunca com `==`) e sobre o corpo **cru**: reserializar
  o JSON antes de conferir quebra a assinatura.

Exemplo (segredo `whsec_exemplo`, corpo `{"ok":true}`):

```
Asender-Webhook-Id: whd_8f3a2c1d4e5b6a7988776655aabbccdd
Asender-Event: email.failed
Asender-Signature: t=1792485815,v1=<hex de 64 caracteres>
```

### Regras do receptor

1. Leia o corpo como **bytes crus**, antes de parsear o JSON.
2. Confira a assinatura (tempo constante) e a tolerância. Se falhar, responda `401` **sem
   processar** nada.
3. Deduplique por `Asender-Webhook-Id`, na mesma transação em que grava o efeito.
4. Responda `2xx` só depois de gravar o evento; o trabalho pesado vem depois.

---

## Verificadores (v1)

Um verificador por linguagem. Cada um recebe o segredo, os cabeçalhos **com nomes em
minúsculas** e o corpo cru, e devolve verdadeiro só se há um `t` dentro da tolerância e
algum `v1` confere. Eles foram executados contra assinaturas geradas pelo mesmo algoritmo
dos emissores, com corpo adulterado, segredo errado, `t` velho, `t` futuro, cabeçalho
ausente e vários `v1=` na rotação.

### Node.js

```js
import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCIA_S = 300; // 5 minutos

// h: cabeçalhos com nomes em minúsculas (req.headers do Node já vem assim).
// corpo: Buffer com os bytes CRUS do request. agora: segundos Unix.
export function verificarAssinaturaV1(segredo, h, corpo, agora = Date.now() / 1000) {
  let t = null;
  const v1s = [];
  for (const parte of (h["asender-signature"] ?? "").split(",")) {
    const i = parte.indexOf("=");
    if (i < 0) continue;
    const k = parte.slice(0, i).trim();
    const v = parte.slice(i + 1).trim();
    if (k === "t") t = v;
    else if (k === "v1") v1s.push(v);
  }
  if (t === null || !/^\d+$/.test(t) || v1s.length === 0) return false;
  if (Math.abs(agora - Number(t)) > TOLERANCIA_S) return false;
  const esperado = createHmac("sha256", segredo).update(`${t}.`).update(corpo).digest();
  return v1s.some((v) => {
    const recebido = Buffer.from(v, "hex");
    return recebido.length === esperado.length && timingSafeEqual(esperado, recebido);
  });
}
```

Uso com o servidor HTTP nativo (o corpo cru é o `Buffer` acumulado):

```js
import http from "node:http";
import { verificarAssinaturaV1 } from "./verificacao.mjs";

http.createServer(async (req, res) => {
  const pedacos = [];
  for await (const p of req) pedacos.push(p);
  const corpo = Buffer.concat(pedacos); // bytes crus
  if (!verificarAssinaturaV1(process.env.WEBHOOK_SEGREDO, req.headers, corpo)) {
    res.writeHead(401).end();
    return;
  }
  const id = req.headers["asender-webhook-id"]; // chave de deduplicação
  const evento = JSON.parse(corpo.toString("utf8")); // só depois de conferir
  // grave (id, evento) com restrição de unicidade em id e responda rápido
  res.writeHead(204).end();
}).listen(3000);
```

### Python

```python
import hashlib
import hmac
import re
import time

TOLERANCIA_S = 300  # 5 minutos


def verificar_assinatura_v1(segredo: str, h: dict, corpo: bytes, agora=None) -> bool:
    """h: cabeçalhos com nomes em minúsculas. corpo: bytes CRUS, antes de qualquer json.loads."""
    agora = time.time() if agora is None else agora
    t, v1s = None, []
    for parte in h.get("asender-signature", "").split(","):
        k, sep, v = parte.strip().partition("=")
        if not sep:
            continue
        if k == "t":
            t = v
        elif k == "v1":
            v1s.append(v)
    if t is None or not re.fullmatch(r"[0-9]+", t) or not v1s:
        return False
    if abs(agora - int(t)) > TOLERANCIA_S:
        return False
    esperado = hmac.new(segredo.encode(), t.encode() + b"." + corpo, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(esperado.encode(), v.lower().encode()) for v in v1s)
```

Uso com o servidor da biblioteca padrão:

```python
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

from verificacao import verificar_assinatura_v1


class Receptor(BaseHTTPRequestHandler):
    def do_POST(self):
        corpo = self.rfile.read(int(self.headers.get("Content-Length", 0)))  # bytes crus
        h = {k.lower(): v for k, v in self.headers.items()}
        if not verificar_assinatura_v1(os.environ["WEBHOOK_SEGREDO"], h, corpo):
            self.send_response(401)
            self.end_headers()
            return
        webhook_id = h.get("asender-webhook-id")  # chave de deduplicação
        # json.loads(corpo) só depois de conferir; grave (webhook_id, evento) e responda rápido
        self.send_response(204)
        self.end_headers()


HTTPServer(("", 3000), Receptor).serve_forever()
```

### Go

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

const toleranciaS = 300 // 5 minutos

// VerificarAssinaturaV1 confere o Asender-Signature (t=<unix>,v1=<hex>[,v1=<hex>]).
// h: cabeçalhos com nomes em minúsculas. corpo: os bytes CRUS do request.
func VerificarAssinaturaV1(segredo string, h map[string]string, corpo []byte, agora time.Time) bool {
	var ts string
	var v1s []string
	for _, parte := range strings.Split(h["asender-signature"], ",") {
		k, v, ok := strings.Cut(strings.TrimSpace(parte), "=")
		if !ok {
			continue
		}
		switch k {
		case "t":
			ts = v
		case "v1":
			v1s = append(v1s, v)
		}
	}
	t, err := strconv.ParseInt(ts, 10, 64)
	if err != nil || len(v1s) == 0 {
		return false
	}
	if d := agora.Unix() - t; d > toleranciaS || d < -toleranciaS {
		return false
	}
	m := hmac.New(sha256.New, []byte(segredo))
	m.Write([]byte(ts + "."))
	m.Write(corpo)
	esperado := m.Sum(nil)
	for _, v := range v1s {
		if recebido, err := hex.DecodeString(v); err == nil && hmac.Equal(esperado, recebido) {
			return true
		}
	}
	return false
}
```

Uso com `net/http` (lembre-se de passar os cabeçalhos com nomes em minúsculas):

```go
func receptor(w http.ResponseWriter, r *http.Request) {
	corpo, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20)) // bytes crus
	if err != nil {
		http.Error(w, "corpo inválido", http.StatusBadRequest)
		return
	}
	h := map[string]string{}
	for k := range r.Header {
		h[strings.ToLower(k)] = r.Header.Get(k)
	}
	if !VerificarAssinaturaV1(os.Getenv("WEBHOOK_SEGREDO"), h, corpo, time.Now()) {
		http.Error(w, "assinatura inválida", http.StatusUnauthorized)
		return
	}
	id := h["asender-webhook-id"] // chave de deduplicação
	_ = id                        // grave (id, evento) com unicidade em id; decodifique o JSON só agora
	w.WriteHeader(http.StatusNoContent)
}
```

### PHP

Requer PHP 8.0 ou superior.

```php
<?php
const TOLERANCIA_S = 300; // 5 minutos

// $h: cabeçalhos com nomes em minúsculas. $corpo: os bytes CRUS (file_get_contents('php://input')).
function verificar_assinatura_v1(string $segredo, array $h, string $corpo, ?int $agora = null): bool {
    $agora ??= time();
    $t = null;
    $v1s = [];
    foreach (explode(',', $h['asender-signature'] ?? '') as $parte) {
        [$k, $v] = array_pad(explode('=', trim($parte), 2), 2, null);
        if ($v === null) {
            continue;
        }
        if ($k === 't') {
            $t = $v;
        } elseif ($k === 'v1') {
            $v1s[] = $v;
        }
    }
    if ($t === null || !ctype_digit($t) || $v1s === []) {
        return false;
    }
    if (abs($agora - (int) $t) > TOLERANCIA_S) {
        return false;
    }
    $esperado = hash_hmac('sha256', $t . '.' . $corpo, $segredo);
    foreach ($v1s as $v) {
        if (hash_equals($esperado, strtolower($v))) {
            return true;
        }
    }
    return false;
}
```

Uso (o corpo cru vem de `php://input`; o PHP expõe os cabeçalhos em `$_SERVER`):

```php
$corpo = file_get_contents('php://input');
$h = [
    'asender-signature' => $_SERVER['HTTP_ASENDER_SIGNATURE'] ?? '',
    'asender-webhook-id' => $_SERVER['HTTP_ASENDER_WEBHOOK_ID'] ?? '',
];
if (!verificar_assinatura_v1(getenv('WEBHOOK_SEGREDO'), $h, $corpo)) {
    http_response_code(401);
    exit;
}
$evento = json_decode($corpo, true); // só depois de conferir
// grave ($h['asender-webhook-id'], $evento) com unicidade no id
http_response_code(204);
```

---

## 1. Eventos da conta

Notificam o resultado do processamento de uma mensagem enviada pela sua conta:
e-mail, SMS, WhatsApp, push e a caixa do Asender Mail. É o emissor com cadastro
pela **API pública**, tipos de evento e filtro por tipo.

### Cadastro

Pela API pública (`/v1/webhooks`, chave com o escopo `webhooks:manage`; veja
[API `/v1/webhooks`](#api-v1-webhooks)) ou pelo painel em `admin.asender.net` →
Desenvolvedores → **Webhooks** (admin ou dono da conta). O segredo (`whsec_…`) é gerado pelo Asender e mostrado **uma única vez**,
na criação. Endpoint **sem segredo não recebe entrega**.

### Tipos de evento

O corpo é o evento como o serviço de origem o publicou, e o tipo vem em
`event_type` (e em `Asender-Event`). Hoje os serviços publicam:

| Tipo | Origem | Campos além do envelope |
| --- | --- | --- |
| `email.queued` | e-mail de marketing aceito pelo relay | `relay_status`, `relay_body` |
| `email.failed` | e-mail de marketing recusado de forma definitiva | `error_code`, `detail` |
| `sms.sent`, `sms.failed` | SMS | `provider_message_id`, `segments` / `error_code`, `detail` |
| `whatsapp.sent`, `whatsapp.failed` | WhatsApp | `provider_message_id` / `error_code`, `detail` |
| `push.delivered`, `push.failed` | push | `provider_message_id` / `error_code`, `detail` |
| `mail.sent`, `mail.received` | caixa do Asender Mail | `data` com `from`, `to`, `subject` (enviado) ou `from`, `subject`, `mailbox_id` (recebido) |
| `webhook.test` | só quando **você** aciona `POST /v1/webhooks/{id}/test` | `data` com `test` e `endpoint_id` |

Não existe `email.delivered` nem `email.opened`/`clicked`/`bounced` neste emissor
hoje. Eventos de uso interno (prefixo `interno.`) **nunca** são entregues a
webhook de cliente. `webhook.test` não é assinável: ele só chega quando você pede o teste.

Ao cadastrar um endpoint, a lista de eventos (`Events`, de 1 a 32 itens, sem repetição)
aceita padrões: `*` (tudo), uma família com ponto e asterisco (`email.*`, `sms.*`,
`whatsapp.*`, `push.*`, `mail.*`) ou o tipo exato (`email.failed`).

### Exemplo de corpo (`email.failed`)

```json
{
  "detail": "mailbox unavailable",
  "error_code": "relay_5xx_550",
  "event_type": "email.failed",
  "message_id": "msg_01JABCDEF",
  "tenant_id": "acc_01JABCDEF",
  "timestamp": "2026-10-05T14:03:11.123456789Z"
}
```

Todo evento traz `event_type`, `tenant_id` (a sua conta) e `timestamp`, e quase
sempre `message_id`. Os eventos `mail.*` trazem o horário sem frações de segundo e põem os
detalhes dentro de `data`. Trate campos desconhecidos como esperados: novos campos podem
ser acrescentados sem aviso. Por privacidade, o número de telefone do destinatário de SMS
e WhatsApp **não** vai no evento; use `message_id` para consultar a mensagem pela API
autenticada.

### `Asender-Webhook-Id`

`whd_` seguido de 32 caracteres hexadecimais. É derivado do evento e do endpoint, então é
**único por evento e por endpoint** e igual em toda retentativa. Se você rotacionar
o segredo do endpoint (apagando e recriando), as entregas que ainda estavam em retentativa
passam a levar outro id.

### Retentativa

Veja a [tabela](#retentativas-e-prazos): 6 tentativas, prazo de 15 s. Se o seu host acumular
falhas seguidas (5), as entregas para ele são adiadas por 60 segundos antes de uma nova
sonda — o evento não se perde, só espera.

---

## 2. Destinos de lead do CRM

Entregam ao seu sistema cada **lead novo** capturado pelo CRM (por exemplo, vindo
de um formulário). São os "webhooks" da tela **Integrações** do painel de
Marketing e da rota `/v1/destinos` da [API do CRM](https://developers.asender.net/apis/crm.html).

### Quando dispara

Uma vez para cada **contato novo** criado no CRM e para cada destino ativo da conta.
Uma pessoa que já existe e só tem os dados atualizados **não** gera nova entrega. Também
dispara quando você aciona o **teste** do destino.

### Onde configurar

No painel de Marketing, **Integrações → Nova integração**: nome, endereço (URL
`http` ou `https`) e segredo. Pela API (rotas de sessão do CRM, sem API key):

```bash
curl -X POST 'https://api.crm.asender.net/v1/destinos' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "nome": "Meu sistema", "url": "https://hooks.exemplo.test/asender", "segredo": "um-segredo-longo-e-aleatorio", "ativo": true }'
```

O **segredo é opcional** e escolhido por você. Ele é guardado cifrado e nunca é
devolvido (a API só informa `tem_segredo`). **Sem segredo, a entrega sai sem
assinatura** e a tela marca o destino como "Sem assinatura" — configure sempre um
segredo.

### v1 neste emissor

| Cabeçalho | Valor |
| --- | --- |
| `Asender-Webhook-Id` | o número da entrega no CRM (inteiro decimal, como texto); igual em todas as tentativas |
| `Asender-Event` | `crm.lead.captured` ou `crm.teste` |
| `Asender-Signature` | `t=<unix>,v1=<hex>`, só com segredo |

### Corpo

```json
{
  "dados": {
    "contato_id": "con_01JABCDEF",
    "criado": true,
    "ocorreu_em": "2026-10-05T14:03:11.123456Z"
  },
  "evento": "crm.lead.captured",
  "tentativa": 1
}
```

| Campo | Significado |
| --- | --- |
| `evento` | `crm.lead.captured` para lead real; `crm.teste` para o botão **Testar** |
| `dados.contato_id` | o id público do contato no CRM (use-o para consultar o contato) |
| `dados.criado` | sempre `true` nas entregas de lead real |
| `dados.ocorreu_em` | quando o lead foi capturado (RFC 3339, UTC) |
| `tentativa` | número da tentativa (1 na primeira) |

O corpo é **enxuto de propósito**: não carrega e-mail, telefone nem outro dado
pessoal do lead — só o identificador. Para obter os dados, consulte o contato no
CRM. A ordem das chaves não é garantida; confira a assinatura sobre os bytes crus.

### Como testar

Use o botão **Testar** do destino, ou a rota:

```bash
curl -X POST 'https://api.crm.asender.net/v1/destinos/<id>/testar' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <conta>'
```

A resposta é `202` com `{ "enfileiradas": 1, … }`: o teste entra na **mesma fila** das
entregas reais, com a mesma assinatura. Ele só vai para o destino que você escolheu
e chega com `"evento": "crm.teste"` e `dados` contendo `teste: true`. O resultado
(estado, código HTTP, número de tentativas e o último erro) aparece em
`GET /v1/destinos/<id>/entregas` e na própria tela.

### Integrações de conversão

A tela **Integrações** também tem **integrações de conversão** (hoje, Meta
Conversions API). Elas **não** são webhooks seus: o Asender chama a API da
plataforma de anúncios com o token que você informou, e **essa chamada não leva
`Asender-Signature`** — a plataforma de anúncios autentica pelo token dela.

---

## 3. Destino "webhook" de formulário do Pages

Cada formulário do Páginas pode ter destinos de captura (CRM, Marketing, integração
e **webhook**). O destino webhook entrega os campos enviados pelo visitante ao seu
servidor.

### Quando dispara

A cada submissão aceita do formulário. A submissão e o despacho são gravados juntos
e a entrega acontece em segundo plano: um endpoint fora do ar atrasa a notificação,
mas não a perde (até o limite de tentativas), e não atrasa a resposta ao visitante.

### Onde configurar

No editor do formulário, em **Destinos → Webhook**: URL e, opcionalmente, o segredo e
o mapa de campos (qual campo do formulário vira qual chave do JSON).

### v1 neste emissor

| Cabeçalho | Valor |
| --- | --- |
| `Asender-Webhook-Id` | id único desta entrega (`whk_…`, opaco), único por submissão e por destino; **igual em todas as tentativas** |
| `Asender-Event` | `form.submitted` |
| `Asender-Signature` | `t=<unix>,v1=<hex>`, só com segredo |

### Corpo

O corpo é um objeto plano com os campos do formulário (valores em texto), usando
como chave o **alvo do mapa de campos** (`email`, `telefone`, `nome`) ou, se o campo
não tiver alvo, o próprio nome do campo:

```json
{
  "email": "ana@test.asender.com.br",
  "nome": "Ana Teste",
  "orcamento": "5000"
}
```

Não há envelope, tipo de evento nem identificador da submissão no corpo — o
identificador está em `Asender-Webhook-Id` e o tipo em `Asender-Event`. Os campos são
dados pessoais do visitante: trate-os conforme a LGPD.

### Redirecionamento

Este emissor **não segue redirecionamentos**: um `3xx` é falha de entrega ("redirecionamento
não seguido") e é retentado como qualquer outra; cadastre a URL final e responda `2xx`
direto nela. Destino que aponta para a rede interna ou tem URL inválida é encerrado sem
retentar.

---

## 4. Conector "API própria / CRM próprio" (Integrações)

O app **API própria / CRM próprio** da plataforma de Integrações envia o lead de um
formulário do Páginas para qualquer API HTTPS que você aponte, com método,
autenticação, corpo e critério de sucesso configuráveis. É o mais flexível dos
quatro: além do v1 ele leva `Idempotency-Key` e `Traceparent`.

### Quando dispara

Para cada lead capturado por um formulário do Páginas que tenha este app como
destino. Hoje o app só aceita leads de formulários do Páginas.

### Onde configurar

No painel de Admin, tela **Integrações**, instale o app **API própria / CRM próprio**
e vincule-o como destino (tipo "integração") do formulário. Campos:

| Campo | Valores |
| --- | --- |
| URL | `https` obrigatório, com nome de host com domínio (IP literal não), sem usuário/senha; porta `443`, `8443` ou de `1024` a `65535` |
| Método | `POST` (padrão), `PUT` ou `PATCH` |
| Formato | `json` (padrão) ou `form` |
| Corpo (modelo) | modelo com `{{variáveis}}` (veja abaixo) |
| Cabeçalhos fixos | até 20, não secretos; não pode fixar `Authorization`, `Cookie`, `Idempotency-Key` nem `X-Asender-*` |
| Autenticação | `nenhuma`, `api_key` (cabeçalho — padrão `X-API-Key` — ou query `api_key`), `bearer`, `basic` ou `oauth2_client_credentials` |
| Assinar o corpo | liga o HMAC-SHA256 (o segredo precisa de pelo menos 16 caracteres; se você deixar vazio, é gerado) |
| Critério de sucesso | opcional: um caminho JSON da resposta que precisa ser igual a um valor |

O painel mostra uma **prévia** da requisição com os segredos mascarados e permite
testar a conexão antes de ativar.

### Cabeçalhos que o Asender sempre envia

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json; charset=utf-8` (ou `application/x-www-form-urlencoded`) |
| `Asender-Webhook-Id` | id da entrega (`ent_…`); **igual em todas as tentativas** |
| `Asender-Event` | `connector.delivery` |
| `Asender-Signature` | `t=<unix>,v1=<hex>`, **só se "Assinar o corpo" estiver ligado** |
| `Idempotency-Key` | o mesmo id da entrega; repasse-o à sua API se ela aceita chave de idempotência |
| `Traceparent` | contexto de rastreio W3C, estável por entrega (o trace) e específico por tentativa (o span) |
| `Authorization` / cabeçalho da chave | conforme o modo de autenticação escolhido |

### Corpo

O corpo é o **modelo que você escreveu**, renderizado com o lead. As variáveis
disponíveis são `contato.*`, `campos["…"]`, `consentimento.*`, `origem.*`,
`formulario.*`, `pagina.*`, `submissao.*`, `qualidade.*`, `entrega.*`,
`instalacao.*` e `agora`, com filtros como `|e164`, `|data_iso`, `|digitos` e
`|cortar:10`. Exemplo de modelo e do corpo resultante para o lead de exemplo do
catálogo:

```json
{
  "nome": "{{contato.nome}}",
  "email": "{{contato.email}}",
  "telefone": "{{contato.telefone|e164}}",
  "origem": "{{origem.utm_source}}",
  "formulario": "{{formulario.nome}}",
  "recebido_em": "{{submissao.recebida_em}}"
}
```

```json
{"nome":"Ana Teste","email":"ana@test.asender.com.br","telefone":"+5511999990000","origem":"google","formulario":"Fale conosco","recebido_em":"2026-10-05T14:03:11Z"}
```

O modelo é validado ao salvar (variável desconhecida ou filtro inválido são
recusados) e a saída tem teto de tamanho.

### Como o Asender classifica a resposta

Prazo de **10 segundos** por tentativa (e de **64 KB** para a resposta lida);
redirecionamentos **não** são seguidos (um `3xx` encerra a entrega com erro — cadastre
a URL final).

| Resposta | O que acontece |
| --- | --- |
| `2xx` (e critério de sucesso, se houver, atendido) | entregue |
| `2xx` com o critério de sucesso **não** atendido | erro definitivo, sem retentar |
| `408`, `425`, `429`, `5xx` (exceto `501` e `505`) e falha de rede/timeout | retenta; se vier `Retry-After` (segundos ou data), ele é respeitado até 1 h |
| `401` e `403` | a entrega pausa e a instalação passa a pedir credencial nova; não gasta tentativa |
| qualquer outro `4xx` | erro definitivo, sem retentar |

---

## API `/v1/webhooks`

Gerencia os endpoints do **emissor 1 (eventos da conta)**. Exige uma **chave de API**
com o escopo `webhooks:manage` (`Authorization: Bearer <chave>`); app OAuth de terceiros
**nunca** recebe esse escopo. A conta vem da chave, nunca da requisição. Os campos do
JSON usam PascalCase. Referência completa:
[API pública](https://developers.asender.net/apis/platform.html) e [chaves de API](chaves-de-api.html).

| Rota | O que faz |
| --- | --- |
| `GET /v1/webhooks` | lista os endpoints da conta (sem o segredo) |
| `POST /v1/webhooks` | cadastra um endpoint; devolve o **segredo uma única vez** |
| `GET /v1/webhooks/{id}` | um endpoint (de outra conta ou inexistente: `404` idêntico) |
| `PATCH /v1/webhooks/{id}` | altera `Url`, `Events` e/ou `Active` (`false` pausa as entregas); não rotaciona o segredo |
| `DELETE /v1/webhooks/{id}` | apaga o endpoint (`204`) |
| `POST /v1/webhooks/{id}/test` | envia um evento `webhook.test` assinado a **esse** endpoint |

### Criar

`Url` precisa ser `https` em produção, sem credencial nem fragmento e **sem destino
interno** (loopback, faixa privada, link-local/metadados de nuvem, `localhost`, `.local`,
`.internal`); o destino é conferido de novo, no endereço resolvido, a cada entrega.
`Events` aceita `*`, `<família>.*` ou tipos exatos do [catálogo](#tipos-de-evento).
Esta rota não guarda estado de idempotência: repetir o `POST` cria outro endpoint (em
dúvida, liste antes).

```bash
curl -X POST 'https://api.asender.net/v1/webhooks' \
  -H 'Authorization: Bearer <chave-com-webhooks:manage>' \
  -H 'Content-Type: application/json' \
  -d '{ "Url": "https://hooks.exemplo.com.br/asender", "Events": ["email.*", "sms.failed"], "Active": true }'
```

Resposta `201` (com `Cache-Control: no-store`):

```json
{
  "Id": "whk_83fcaff4b496c6e6",
  "Url": "https://hooks.exemplo.com.br/asender",
  "Events": ["email.*", "sms.failed"],
  "Active": true,
  "Secret": "whsec_0123456789abcdef…",
  "RequestId": "…"
}
```

**Guarde o `Secret` agora**: ele nunca mais é exibido. Perdeu? Apague o endpoint e crie
outro. O segredo é sempre gerado pelo Asender; não é aceito o seu. Guarde-o só no servidor
(cofre ou variável de ambiente).

### Alterar, listar e apagar

```bash
# pausar
curl -X PATCH 'https://api.asender.net/v1/webhooks/whk_83fcaff4b496c6e6' \
  -H 'Authorization: Bearer <chave>' -H 'Content-Type: application/json' \
  -d '{ "Active": false }'

# listar
curl 'https://api.asender.net/v1/webhooks' -H 'Authorization: Bearer <chave>'

# apagar
curl -X DELETE 'https://api.asender.net/v1/webhooks/whk_83fcaff4b496c6e6' \
  -H 'Authorization: Bearer <chave>'
```

### Testar

```bash
curl -X POST 'https://api.asender.net/v1/webhooks/whk_83fcaff4b496c6e6/test' \
  -H 'Authorization: Bearer <chave>'
```

Faz **um** `POST` síncrono, sem retentativa, só para o endpoint pedido (o evento
`webhook.test` não vai para os outros endpoints da conta), com os cabeçalhos v1 e os
[antigos](#formatos-antigos-descontinuados). Responde `200` sempre que o endpoint existe;
o resultado da entrega vem no corpo e o corpo da resposta do seu servidor **não** é
devolvido:

```json
{ "WebhookId": "whk_83fcaff4b496c6e6", "EventId": "evt_…", "EventType": "webhook.test",
  "Delivered": true, "StatusCode": 204, "Reason": "", "DurationMs": 87 }
```

`EventId` é o mesmo valor que chega em `Asender-Webhook-Id`. `Reason` é `""` (entregue),
`non_2xx`, `transport_error`, `destination_blocked` (destino interno) ou
`non_production_blocked` (fora de produção só vão domínios de teste, como `*.test.asender.com.br`,
`.test` e `.example`).

---

## Retentativas e prazos

| | 1. Eventos da conta | 2. CRM | 3. Formulário | 4. Conector |
| --- | --- | --- | --- | --- |
| Prazo por tentativa | 15 s | 10 s | 8 s | 10 s |
| Tentativas | 6 | 8 | 12 | 12 |
| Espera entre tentativas | 1 min, 5 min, 15 min, 1 h, 6 h | 30 s dobrando, até 32 min | 30 s dobrando, até 6 h | 30 s dobrando, até 6 h (±20%); respeita `Retry-After` até 1 h |
| Duração total aproximada | 7 h 20 min | 1 h | 14 h 30 min | 14 h 30 min |
| O que retenta | tudo que não for `2xx` | tudo que não for `2xx` | tudo que não for `2xx` | `408`, `425`, `429`, `5xx` e rede |
| Redirecionamento | não segue (`3xx` é falha) | não segue | não segue (`3xx` é falha, retentada) | não segue (erro) |
| Depois da última | descartado | `falhou` | encerrado com o erro | estado "morta" |

Os tempos são aproximados: as entregas são processadas em ciclos, então a
tentativa pode atrasar alguns segundos além do previsto. Esgotadas as tentativas,
nenhum emissor reenvia sozinho. Destino que aponta para a rede interna ou tem URL
inválida falha na hora, sem retentar. Em todos, cada tentativa é assinada de novo com
o `t` da própria tentativa.

## Como responder

- Responda **`2xx`** assim que gravar o evento; o corpo da resposta é ignorado.
- Faça o trabalho pesado **depois** de responder (fila própria). Não deixe a
  chamada esperando banco ou terceiros: estourar o prazo é falha e dispara retentativa.
- Para pedir que o Asender **pare** de retentar um evento que você não quer, responda
  `2xx` e descarte. (No conector, um `4xx` que não seja `408`, `425` ou `429` também
  encerra a entrega.)
- Se você precisa recusar por assinatura inválida, use `401`. Lembre que os
  emissores 1, 2 e 3 retentam isso; só o conector (4) trata `401` como pausa de
  credencial.

## Idempotência

**Deduplique por `Asender-Webhook-Id`**, em qualquer emissor: ele é estável entre as
tentativas da mesma entrega. Guarde-o **na mesma transação** em que grava o efeito, com
uma restrição de unicidade, e trate a violação como "já processado" (responda `2xx`).
O id é opaco: não interprete o formato, e não o compare entre emissores diferentes
(os formatos são independentes). A janela de 300 s protege contra replay; o id protege
contra duplicata.

## Segurança e rede

- **Valide a assinatura.** Não há lista de endereços IP de saída publicada nem
  estável para os webhooks; **não use IP como autenticação**. A assinatura é o único
  controle confiável. Prefira `https` no seu endpoint.
- **Segredo só no servidor.** Guarde o segredo em cofre ou variável de ambiente do
  backend, nunca em código de navegador ou repositório. Os verificadores aceitam vários
  `v1=` para que a troca de segredo seja sem janela de falha.
- **O Asender recusa destinos internos.** URLs que apontam para `localhost`,
  endereços privados (`10.x`, `192.168.x`, `172.16–31.x`) ou link-local (inclui
  `169.254.169.254`) são recusadas, em qualquer ambiente — conferindo o endereço
  que o nome resolve no momento de conectar, e não só o nome (o conjunto exato de
  faixas varia um pouco entre os emissores). Para desenvolver localmente, exponha
  o seu receptor por um túnel público (HTTPS).
- **Fora de produção nada sai para destino real.** Nos ambientes de teste e
  homologação, os emissores 1, 2 e 3 só entregam em domínios de teste (`.test`,
  `.invalid`, `.example`, `example.com`, `test.asender.com.br`); para qualquer
  outro destino a entrega não é feita, de propósito, para que dados de teste nunca
  cheguem a um sistema de verdade. O conector (4) não envia em homologação: registra
  a requisição e marca a entrega como simulada. Use um domínio de teste ao testar.
- **Limite o tamanho do corpo** que o seu receptor aceita e leia o corpo uma só vez.
- **Registre o `Asender-Webhook-Id`** (e o `Traceparent`, no conector) nos seus logs:
  facilita achar uma entrega específica quando abrir um chamado.

---

## Formatos antigos (descontinuados)

> **Sunset: 2027-04-20.** Até essa data cada emissor continua enviando os cabeçalhos
> abaixo, inalterados, **além** do v1. Depois dela eles saem (com decisão registrada à
> parte). Migre para o [v1](#o-formato-v1) antes; não escreva código novo sobre estes.

| Emissor | Cabeçalhos antigos | Assinatura antiga |
| --- | --- | --- |
| 1. Eventos da conta | `X-Asender-Event-Type` (tipo do evento), `X-Asender-Timestamp` (UTC, RFC 3339 com nanossegundos, ex. `2026-10-05T14:03:11.123456789Z`), `X-Asender-Signature` | `sha256=` + hex de `HMAC-SHA256(segredo, timestamp + "." + corpo)`, com o `timestamp` **exatamente como veio** no cabeçalho (texto RFC 3339) |
| 2. CRM | `X-Asender-Timestamp` (segundos Unix), `X-Asender-Signature` | `v1=` + hex de `HMAC-SHA256(segredo, timestamp + "." + corpo)`; ausente sem segredo |
| 3. Formulário | `X-Asender-Webhook-Id` (= `Asender-Webhook-Id`), `X-Asender-Timestamp` (segundos Unix, sempre enviado), `X-Asender-Signature-V2`, `X-Asender-Signature` | V2: `v1=` + hex de `HMAC(segredo, timestamp + "." + corpo)`. Legado: `sha256=` + hex de `HMAC(segredo, corpo)`, **sem timestamp (não protege contra replay)**. Ambos ausentes sem segredo |
| 4. Conector | `X-Asender-Entrega-Id` (= `Asender-Webhook-Id`), `X-Asender-Tentativa` (a partir de 1), `X-Asender-Assinatura` | `t=<unix>,v1=<hex>` com `HMAC(segredo, t + "." + corpo)`, **idêntico** ao `Asender-Signature`; só com "Assinar o corpo". `Idempotency-Key` e `Traceparent` não são do formato antigo e não são cobertos por este sunset |

Observações para quem ainda usa os antigos:

- A janela de tolerância recomendada é a mesma (300 s) onde há timestamp; no emissor 1 o
  `X-Asender-Timestamp` é texto RFC 3339, não segundos Unix.
- No emissor 2 a deduplicação antiga era por `dados.contato_id`; no 1, por `message_id` +
  `event_type`. Passe a usar `Asender-Webhook-Id`.
- A assinatura antiga do emissor 3 (`sha256=` só sobre o corpo) permite que uma entrega
  capturada seja reenviada para sempre e continue válida. Migre para o v1.
- Os verificadores antigos (um por emissor) saíram deste guia: a fórmula de cada um está
  na tabela acima e o caminho recomendado é migrar para o v1, cuja verificação é a mesma
  nos quatro.

---

## Planejado

> Nada desta seção existe hoje. Está descrito para você planejar a integração; datas
> e formatos podem mudar.

- **Rotação de segredo** com endpoint próprio, enviando dois `v1=` durante a transição.
  Hoje, para trocar o segredo de um endpoint da conta, crie outro endpoint e apague o antigo.
- **Novos eventos** no emissor 1, ainda não entregues por nenhum emissor:

| Evento planejado | Quando |
| --- | --- |
| `conversion.sent` | uma conversão é enviada a uma plataforma de anúncio |
| `email.delivered` | o provedor do destinatário confirma a entrega de um e-mail de marketing |
| `email.opened` | o destinatário abre um e-mail de marketing |
| `email.clicked` | o destinatário clica num link de um e-mail de marketing |
| `email.bounced` | um e-mail de marketing volta (bounce) |
| `campaign.finished` | uma campanha termina o envio |

Já existem e **não** são planejados: o lead novo (`crm.lead.captured`, emissor 2) e a
submissão de formulário (`form.submitted`, emissor 3).



==============================================================================
# GUIA: No navegador: formulário, pixel, chat e push
==============================================================================

# No navegador: formulários, pixel, chat e push

Tudo o que o Asender coloca no site do seu cliente roda no navegador do visitante: o **formulário incorporado**, o **pixel de analytics**, o **chat do atendimento** e o **Web Push**. Este guia mostra cada peça: o código para colar, o que ela envia, onde ela guarda dados no navegador e o que liberar na **Content-Security-Policy** (CSP) do seu site.

Nenhuma dessas peças usa a sua API key. O código de navegador é público: ele carrega só identificadores públicos (o id do formulário, a credencial assinada do pixel, uma chave de site `pk_`). **Nunca** cole uma chave `sk_` em página de site. Para enviar leads a partir do seu servidor, veja o [guia da API de Páginas](https://developers.asender.net/apis/pages.html).

## Hosts públicos

| Host | Para que serve |
| --- | --- |
| `https://embed.asender.net` | Formulário incorporado: `embed.js`, envio, carimbo anti-spam, eventos do funil e a consulta de endereço por CEP. É o endereço que o painel gera nos snippets novos. |
| `https://sites.asender.net` | Runtime das páginas: `pixel.js`, `/collect`, `/replay`, `chat.js` e as rotas do formulário (envio, carimbo, eventos e a consulta de endereço, `/f/{formID}/endereco`). Snippets antigos de formulário, colados com `sites.`, continuam funcionando. |
| `https://api.pages.asender.net` | Painel e API de Páginas: criar pixels e ler relatórios (exige sessão). |
| `https://api.atendimento.asender.net` | API pública do chat (`/public/v1/chat`). |
| `https://api.asender.net` | API da plataforma; recebe o registro de Web Push (`/v1/push/site/devices`). |

O domínio `asender.com.br` segue respondendo em todos esses nomes (`embed.asender.com.br`, `sites.asender.com.br` e assim por diante). Snippet já colado com ele continua valendo. Se você tem CSP, libere os dois domínios enquanto houver snippet antigo.

## 1. Formulário incorporado

### Colar em uma linha

No painel de **Páginas**, abra **Formulários**, escolha o formulário e clique em **Ver como usar**. O painel mostra o código pronto e a aba **JavaScript** é a recomendada:

```html
<script src="https://embed.asender.net/f/frm_0123456789abcdef/embed.js" async></script>
```

`frm_0123456789abcdef` é o **id do formulário** (`formID`). Ele aparece no código copiado e na URL de envio do bloco **API**, na mesma tela. O id é público: quem abre o código-fonte da sua página o vê. A proteção da conta é a lista de sites autorizados (veja abaixo), não o sigilo do id.

O `embed.js` injeta o formulário **no lugar da própria tag `<script>`**, sempre com a definição atual. Edite os campos no painel e o site passa a mostrar a versão nova em até 1 minuto, sem recolar nada. O custo é depender de JavaScript. Quem precisa do formulário sem JavaScript usa a aba **HTML completo**, que é o mesmo formulário escrito por extenso (e que fica "congelado": cada campo novo exige recolar o código).

### O que o HTML gerado contém

O `<form>` é um formulário nativo que posta direto no Asender; o JavaScript só aprimora. Os atributos que o painel escreve nele:

| Atributo | Valor | Para que serve |
| --- | --- | --- |
| `action` | `https://embed.asender.net/f/{formID}` | Para onde o envio vai. |
| `data-asender-form` | o `formID` | Identifica o formulário. É o que o pixel lê (seção 2). |
| `data-asender-carimbo` | `https://embed.asender.net/f/{formID}/carimbo` | Endereço do carimbo de tempo anti-spam. As rotas `/eventos` e `/endereco` são derivadas dele. |
| `data-asender-sucesso` | texto | Mensagem de agradecimento (a configurada no formulário; padrão "Obrigado! Recebemos seus dados."). |
| `data-asender-destino` | URL (opcional) | Para onde mandar o visitante depois do envio. |

Esses atributos são **gerados** a partir da configuração do formulário no painel (mensagem e destino pós-envio). Você muda o texto e o destino no painel, não no HTML. Na resposta do envio, o servidor manda o pós-envio atual (`pos_envio`) e o JavaScript o prefere aos atributos; os atributos são o plano B. O redirecionamento só segue destino `http://` ou `https://`.

### Como o envio funciona: `POST /f/{formID}`

Sem credencial. A conta é resolvida pelo próprio `formID`.

```bash
curl -X POST 'https://embed.asender.net/f/frm_0123456789abcdef' \
  -H 'Origin: https://www.seusite.com.br' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'nome=Fulana' \
  --data-urlencode 'email=fulana@exemplo.test' \
  --data-urlencode 'consentimento=on'
# → 200 { "ok": true, "lead_id": "…", "duplicada": false,
#         "pos_envio": { "destino": "", "mensagem": "Obrigado! Recebemos seus dados." } }
```

O que vale saber:

- **Formato do corpo.** O formulário (o JavaScript do snippet e o envio nativo) manda `application/x-www-form-urlencoded`, um par `nome=valor` por campo. Use os **nomes dos campos** como estão no formulário. Campo que o formulário não declara é descartado em silêncio, para que um snippet desatualizado ou um bot que anexa lixo não faça você perder um lead legítimo.
- **Navegação ou JSON.** Quem navega (envio nativo, `Accept: text/html`) recebe uma **página** (o agradecimento, ou um redirecionamento 303 para o destino configurado). Quem pede `Accept: application/json` recebe JSON. O snippet envia o formulário com `fetch` (urlencoded) e pede JSON na resposta.
- **Origem.** O navegador manda o cabeçalho `Origin`. Se o formulário tem a **trava de sites autorizados** ligada, só as origens da lista passam; as demais recebem **403** (`origem não autorizada para este formulário`). A trava é **opcional**: desligada, qualquer site pode embutir e postar, e o anti-spam e o limite de frequência continuam valendo. Ligue-a em **Ver como usar → Sites autorizados**: até 20 origens (esquema + host + porta, sem curinga). A comparação é exata, sem sufixo.
- **Sempre 200 para spam.** Uma submissão classificada como spam recebe **200**, igual a uma aceita. É de propósito: devolver erro ensinaria o robô a ajustar o envio até passar. Por isso, **200 não prova que virou lead**; o sinal de lead criado é o `lead_id` na resposta.
- **Validação.** Campo obrigatório vazio ou valor inválido responde **422** com o primeiro problema e a lista completa:

```json
{
  "error": { "message": "submissão recusada: [email: obrigatório]" },
  "erro": "dados inválidos",
  "campo": "email",
  "motivo": "obrigatório",
  "motivos": ["email: obrigatório"]
}
```

| Status | Quando |
| --- | --- |
| 200 | Aceito, deduplicado ou descartado como spam (`ok: true`). |
| 403 | Origem fora da lista de sites autorizados do formulário. |
| 404 | Formulário inexistente. |
| 422 | Dado inválido ou campo obrigatório ausente (corpo acima). |
| 502 / 503 | Falha nossa ao registrar ou ao resolver o formulário; tente de novo. |

### Consentimento (LGPD)

Se o formulário **exige consentimento**, o HTML inclui uma caixa `consentimento` obrigatória, com o texto de aceite que você configurou no formulário. O servidor confere: sem a caixa marcada o envio é recusado com **422** (`consentimento: obrigatório`). A decisão de consentimento e o texto aceito acompanham o lead até o CRM. Se você monta o HTML à mão, mande o campo `consentimento` com qualquer valor não vazio **somente** quando a pessoa marcou a caixa.

### Anti-spam

Todo formulário gerado leva um campo-isca oculto (`_asender_website`, que deve ficar vazio) e dois campos de sinal (`_asender_carimbo` e `_asender_interacao`). Ao carregar, o script pede `GET /f/{formID}/carimbo`, que devolve `{"carimbo": "…"}`: o instante assinado em que o formulário foi aberto. Preencher rápido demais, sem interação, ou tocar na isca soma pontos de suspeita. Não há CAPTCHA. O servidor só descarta quando a soma passa do corte, e um sinal sozinho quase nunca descarta. Sem JavaScript os sinais vão vazios e o servidor os trata como "não medidos".

### Preenchimento de endereço por CEP

Se o formulário tem o bloco de endereço, o script consulta `GET /f/{formID}/endereco?pais=BR&cep=01310100` e preenche estado, cidade, bairro e rua. A rota só atende formulários que têm endereço e países que eles aceitam; responde 404 (CEP ou campo inexistente), 422 (país ou CEP inválido), 429 (muitas consultas) ou 503. Nenhuma dessas respostas trava o formulário: o visitante digita o endereço à mão.

> O host `embed.asender.net` também encaminha `/f/{formID}/endereco`, então o preenchimento por CEP funciona com o snippet apontando para ele. Em instalação cuja borda ainda não recebeu essa atualização, o endereço cai em modo manual.

### Eventos no navegador

O formulário dispara eventos que você pode escutar na sua página.

| Evento | Onde dispara | `detail` |
| --- | --- | --- |
| `asender:submissao` | No `<form>`, subindo (bubbles) até `document` | `{ id, formulario_id }` |
| `asender:enviado` | No `<form>` | `{}` |
| `asender:erro` | No `<form>` | `{ campo }` (nome do campo com problema, ou vazio) |

`asender:submissao` sai depois de um envio aceito via `fetch` que devolveu `lead_id`, e **antes** de qualquer redirecionamento. Spam e respostas sem `lead_id` não disparam o evento. O mesmo valor fica em `window.asenderSubmissao`. O `id` é o mesmo identificador que o servidor usa como `event_id` ao reportar a conversão às APIs de anúncio (Meta, Google Ads, TikTok). Por isso você **deduplica** o pixel do navegador com a conversão do servidor usando esse `id` como `eventID`:

```html
<script>
  document.addEventListener("asender:submissao", function (e) {
    // Meta Pixel: mesmo event_id que o servidor manda à API de Conversões
    fbq("track", "Lead", {}, { eventID: e.detail.id });
  });
</script>
```

`asender:enviado` e `asender:erro` não sobem até `document`; escute no próprio formulário (`form.addEventListener(...)`). No envio nativo (sem JavaScript) a página não fica aberta, então nenhum desses eventos acontece.

## 2. Pixel de analytics

O pixel mede o comportamento na página: visita, rolagem, cliques, formulário visto, iniciado e enviado, tempo na página e saída. Ele é opcional; o formulário incorporado funciona e é contado sem ele (veja "Formulário sem pixel").

### Criar e instalar

1. No painel de Páginas, abra **Analytics → Pontos de coleta** e crie um ponto de coleta (o pixel). Na API, `POST https://api.pages.asender.net/v1/pixels` (com sessão) devolve o `snippet` pronto.
2. Em **Domínios autorizados** do pixel, cadastre o domínio do seu site (por exemplo `www.seusite.com.br`). Enquanto ele não estiver na lista, o navegador do visitante recebe **403** e nenhum evento sai.
3. Cole o snippet antes de `</head>`.

Num site que não é do Asender, o snippet deve ficar assim:

```html
<script src="https://sites.asender.net/pixel.js"
        data-lz="<credencial-assinada>"
        data-lz-collect="https://sites.asender.net/collect"
        data-lz-replay="1"
        data-lz-replay-url="https://sites.asender.net/replay"
        async></script>
```

> **Endereço absoluto.** O snippet que o painel e a API (`POST /v1/pixels`) geram já traz `src`, `data-lz-collect` e `data-lz-replay-url` com o endereço público do runtime. Se você colou um snippet **antigo**, com `src="/pixel.js"` relativo, ele aponta para o seu próprio domínio e não carrega: troque pelo snippet acima ou gere o código de novo. Como reforço, o `pixel.js` também aceita `data-base` (a origem do runtime) e, sem ele, usa a origem do próprio `src` para `/collect` e `/replay`. Em páginas publicadas pelo próprio Asender nada disso é necessário.

| Atributo | Para que serve |
| --- | --- |
| `data-lz` | A credencial assinada do ponto de coleta (identifica conta e pixel; não é segredo). Sem ela o script não faz nada. |
| `data-lz-collect` | Endereço de `/collect`. Padrão: `/collect` na origem do `src` do script (ou de `data-base`). |
| `data-lz-replay` | `1` liga a gravação de jornada (veja abaixo). Ausente, nada é gravado. |
| `data-lz-replay-url` | Endereço de `/replay`. Padrão: `/replay` na origem do `src` do script (ou de `data-base`). |
| `data-base` | Origem do runtime (ex.: `https://sites.asender.net`) para `/collect` e `/replay`. Padrão: a origem do `src`. |
| `data-lz-click` | Em qualquer elemento seu: o texto que vira o nome do clique no relatório. |

### O que ele coleta

O script manda lotes de eventos para `POST /collect` (JSON, com a credencial no corpo). Eventos: `page_view`, `scroll_depth` (25, 50, 75 e 100%), `click` (apenas em links, botões e elementos com `data-lz-click`, com posição em porcentagem da página), `form_view`, `form_start`, `form_submit`, `time_on_page` e `exit`. A sessão é um id aleatório guardado em `sessionStorage` (chave `_lz_s`), que morre quando a aba fecha. **Sem cookie**, sem e-mail, sem nome, sem fingerprint.

### Formulários: o atributo `data-asender-form`

O pixel procura na página os `<form data-asender-form="…">` e emite:

- `form_view`, uma vez por formulário, quando metade dele fica visível (ou no carregamento, em navegador sem `IntersectionObserver`);
- `form_start` no primeiro foco em um campo do formulário;
- `form_submit` no envio.

Cada evento leva o `formID`, e é isso que agrupa os números por formulário no relatório. Como o HTML gerado já traz `data-asender-form`, nenhum passo extra é necessário. Se você monta o HTML à mão, escreva o atributo com o id do formulário (o nome antigo `data-form-id` ainda é aceito).

### Formulário sem pixel

Um formulário incorporado em site **sem o pixel** também aparece no Analytics geral. O script do próprio formulário manda o funil dele para `POST /f/{formID}/eventos`, e o servidor espelha três eventos (`form_view`, `form_start`, `form_submit`) no Analytics geral, marcados com origem `embed` e o host do site. Se o script detecta que o pixel está na página (`script[data-lz]`), o espelho não acontece, para não contar em dobro.

### Gravação de jornada (`/replay`)

Com `data-lz-replay="1"`, o pixel grava a **sequência de interações**: clique (seletor do elemento e posição), campo tocado, rolagem, navegação e tamanho da janela. **Não é gravação de tela nem de DOM.** Em campos de formulário, registra apenas o tipo do campo e o comprimento do valor em faixas (0, 3, 8, 16, 32, 64), nunca o texto digitado, e só quando o campo perde o foco, nunca por tecla. Campos de senha, cartão, CPF/CNPJ e semelhantes (pelo nome ou id) saem como "sensível" e sem comprimento. O seletor traz só tag, id e duas classes. Para ler as jornadas: `GET /v1/replay/sessions` e `.../sessions/{id}/events` na API de Páginas (exige sessão).

Como o snippet do painel já inclui `data-lz-replay="1"`, **a gravação de jornada vem ligada**. Para desligar, remova o atributo. Veja "Privacidade" no fim.

## 3. Chat do atendimento

O widget de chat abre uma conversa do visitante direto na caixa de entrada do Atendimento.

### Instalar

1. No Atendimento, abra **Bot com IA**, seção **Widget de chat**, informe as **origens do site** (até 10, como `https://www.seusite.com.br`) e copie o snippet. O painel gera a **chave de site** `pk_chat_…` a partir das origens.
2. Cole antes de `</body>`:

```html
<script type="module" async
        src="https://sites.asender.net/chat.js"
        data-site-key="pk_chat_…"
        data-base="https://api.atendimento.asender.net"></script>
```

| Atributo | Obrigatório | Para que serve |
| --- | --- | --- |
| `src` | sim | O widget, servido por `sites.asender.net/chat.js`. |
| `data-site-key` | sim | A chave de site `pk_chat_…`. Sem ela o widget **não monta** e escreve um aviso no console. |
| `data-base` | sim | A API do chat (`https://api.atendimento.asender.net`). Sem ele o widget **não monta** e escreve um aviso no console: a origem do `src` é o host de sites, que não é a API do chat. |
| `data-titulo` | não | Título do painel do chat. |
| `data-saudacao` | não | Primeira mensagem de boas-vindas. |
| `data-intervalo-ms` | não | Intervalo (ms) da busca de novas mensagens quando a conexão ao vivo (SSE) não está disponível. Padrão: 4000. |
| `data-manual` | não | Presente, desliga a montagem automática (para quem chama `montarChat` por conta própria). |
| `data-asender-chat` | não | Marca a tag como a do widget quando o `src` não é idêntico ao do snippet (por exemplo, atrás de proxy). |

Cor, título, saudação e posição do widget vêm da **aparência** salva na tela do Widget, que o script lê ao montar. Os atributos `data-titulo` e `data-saudacao` sobrescrevem texto na instalação.

### Segurança da chave de site

A chave de site é **pública**: ela está no código-fonte da página. A defesa é a lista de origens assinada dentro dela, conferida **no servidor** a cada chamada, mais o limite de frequência por chave. Ela só abre o chat; não vale para nenhuma outra API. Mudou o domínio do site? Gere a chave de novo com as origens novas.

### Cookie da conversa

Na primeira mensagem, o servidor grava o cookie **`asender_chat`**: um token aleatório, `HttpOnly`, `Secure`, `SameSite=None`, válido por 30 dias e restrito ao caminho `/public/v1/chat` (é enviado só às rotas do chat, nunca a outras). É ele que reencontra a conversa quando a pessoa volta ao site. Como o widget fala com um domínio diferente do seu site, é um cookie de terceiro; navegadores configurados para bloquear cookies de terceiros podem impedir que a conversa seja retomada.

## 4. Web Push

Web Push envia notificações a quem aceitou receber, mesmo com a aba fechada. O seu site registra o navegador do visitante no Asender; as campanhas saem depois, pela ferramenta de Push.

### Passo a passo

1. No app de **Push**, abra **Coletar inscrições**, informe as origens do site (de 1 a 10) e gere o pacote. Ele traz quatro itens: a **chave de site** `pk_push_…`, o **service worker** `asender-sw.js`, o **manifest** e o **snippet** de inscrição. A chave de site vale **só** para as origens informadas.
2. Salve o service worker como **`/asender-sw.js` na raiz do site**. Um service worker só controla o diretório em que é servido; num subdiretório ele não recebe push do site inteiro.
3. Salve o manifest como `/manifest.json` e referencie com `<link rel="manifest" href="/manifest.json">`. Coloque também os ícones `/icon-192.png` e `/icon-512.png`, que o manifest e as notificações usam.
4. Cole o snippet em uma tag `<script>` e chame **`asenderSubscribePush()` a partir de um clique** do visitante. Os navegadores recusam o pedido de permissão disparado no carregamento da página.
5. O site precisa estar em **HTTPS** (`localhost` é a única exceção).

O snippet faz, em ordem: verifica suporte a service worker e a `PushManager`; pede a permissão de notificação (`Notification.requestPermission()`); registra `/asender-sw.js`; assina o push com a chave pública VAPID da sua conta; e envia a inscrição ao Asender:

```bash
curl -X POST 'https://api.asender.net/v1/push/site/devices?site_key=pk_push_…' \
  -H 'Origin: https://www.seusite.com.br' \
  -H 'Content-Type: application/json' \
  -d '{ "Endpoint": "https://…", "P256dh": "…", "Auth": "…" }'
# → 200 { "Status": "registered" }
```

A chave de site vai **na query** porque o preflight do navegador (a requisição `OPTIONS` prévia) não leva cabeçalhos próprios: assim a chave e a origem já são conferidas antes do `POST` existir.

| Status | Quando |
| --- | --- |
| 200 | Inscrição registrada (`Status: "registered"`). |
| 400 | Corpo inválido (o endpoint precisa ser `https`; `P256dh` e `Auth` obrigatórios; campo extra é recusado). |
| 401 | Chave ausente ou inválida. Uma chave de servidor `sk_` apresentada aqui também é recusada. |
| 403 | `Origin` ausente ou não declarada na chave; ou conta suspensa. |
| 429 | Limite de frequência por chave e por IP. |

### Permissões e o que esperar do navegador

- O visitante vê o diálogo nativo do navegador e pode **permitir**, **bloquear** ou ignorar. Se ele bloquear, o site não pode perguntar de novo; só o próprio visitante reativa nas configurações do navegador. O snippet registra o motivo no console (`permissão de notificação negada pelo usuário`) e não faz nada além disso.
- Peça a permissão **depois de uma ação clara**, com um botão ou convite explicando o que a pessoa vai receber. Pedir no carregamento é bloqueado pelos navegadores e reduz a aceitação.
- Navegadores sem suporte a Web Push mostram `este browser não suporta Web Push` no console e seguem sem notificações.
- A notificação mostra título, texto, ícone (o da campanha, ou `/icon-192.png`) e, se houver, imagem. O clique abre a URL da campanha, reaproveitando uma aba do seu site já aberta.

Em páginas publicadas **pelo próprio Asender** com a coleta de push ligada, o convite de inscrição e o service worker (`/asender-sw.js`) já vêm no host da página; nada disso é preciso colar.

## 5. SDK `@asender/pages-sdk`

O repositório contém o SDK JavaScript **`@asender/pages-sdk`** (versão 0.2.1), com três pontos de entrada: `.` (servidor, com API key), `./client` (navegador, sem credencial, com `createBrowserClient` e `rastrearFormulario` para o funil de um formulário seu) e `./chat` (o widget de chat, o mesmo que `chat.js` entrega).

**Ele ainda não está publicado no npm.** Não há `npm install @asender/pages-sdk` funcionando hoje. Para o navegador, use os caminhos desta página, que não dependem de pacote:

- formulário: o snippet `embed.js` ou o `POST /f/{formID}` direto (`application/x-www-form-urlencoded`; o `submitForm` do SDK faz o mesmo);
- chat: o `chat.js` por CDN, como na seção 3;
- do seu servidor: `POST /v1/leads` com API key, no [guia da API de Páginas](https://developers.asender.net/apis/pages.html).

A publicação do pacote está **planejada**. Quando sair, este guia passa a mostrar a instalação.

## 6. CSP e privacidade

### Content-Security-Policy

Se o seu site usa CSP, libere o que for usar. Os domínios abaixo valem para o host canônico; acrescente os equivalentes `.com.br` se houver snippet antigo.

| Recurso | Diretiva | O que liberar |
| --- | --- | --- |
| Formulário incorporado | `script-src` | `https://embed.asender.net` **e** `'unsafe-inline'` (veja a nota) |
| Formulário incorporado | `style-src` | `'unsafe-inline'` |
| Formulário incorporado | `connect-src` | `https://embed.asender.net` (envio, carimbo, eventos e endereço); `https://sites.asender.net` só para snippets antigos |
| Formulário incorporado, envio sem JavaScript | `frame-src`, `form-action` | `https://embed.asender.net` |
| Pixel | `script-src`, `connect-src` | `https://sites.asender.net` |
| Chat | `script-src` | `https://sites.asender.net` |
| Chat | `connect-src` | `https://api.atendimento.asender.net` |
| Chat | `style-src` | `'unsafe-inline'` (o widget injeta seu estilo) |
| Web Push | `connect-src` | `https://api.asender.net` |
| Web Push | `worker-src` | `'self'` (o service worker mora no seu domínio) |

Exemplo para um site que usa tudo:

```
Content-Security-Policy:
  script-src  'self' 'unsafe-inline' https://embed.asender.net https://sites.asender.net;
  style-src   'self' 'unsafe-inline';
  connect-src 'self' https://embed.asender.net https://sites.asender.net
              https://api.atendimento.asender.net https://api.asender.net;
  frame-src   https://embed.asender.net;
  form-action 'self' https://embed.asender.net;
  worker-src  'self';
```

> **Por que `'unsafe-inline'` no formulário.** O formulário incorporado vem com `<style>` e vários `<script>` embutidos no próprio HTML (máscaras, anti-spam, funil). O `embed.js` recria esses scripts na sua página, e eles precisam de `script-src 'unsafe-inline'` (um `nonce` do seu site não é herdado por scripts criados dessa forma). Se a sua política não admite `'unsafe-inline'`, use o formulário só em uma página com política própria, ou abra o formulário publicado pelo Asender em vez de incorporá-lo. Pixel, chat e Web Push não exigem `'unsafe-inline'` em `script-src`.

### O que fica no navegador do visitante

| Peça | Onde | O quê | Quanto dura |
| --- | --- | --- | --- |
| Pixel | `sessionStorage` `_lz_s` | id aleatório da visita | até a aba fechar |
| Formulário | `localStorage` `asf_d` | id aleatório do dispositivo | até o visitante apagar |
| Formulário | `localStorage` `asf_v`, `asf_ft` | contagem de visitas ao formulário e a origem da primeira visita | até o visitante apagar |
| Formulário | cookies `_fbp`, `_fbc` | **somente leitura**, para a conversão de anúncio | não escrevemos esses cookies |
| Chat | cookie `asender_chat` | token da conversa, `HttpOnly` | 30 dias |
| Web Push | service worker e assinatura de push | inscrição do navegador | até o visitante cancelar |

O pixel e o formulário **não gravam cookie** próprio.

### Dados enviados junto do formulário

Além dos campos que a pessoa preencheu, o formulário envia um contexto técnico: página, idioma, fuso, tamanho de tela, tipo de dispositivo, parâmetros `utm_*` e identificadores de clique de anúncio presentes na URL (como `gclid` e `fbclid`), origem da primeira visita, número de visitas, id do dispositivo, tempo no formulário e a sessão do pixel, quando há. Não coleta impressão digital de canvas ou áudio, nem geolocalização do navegador. O IP e a geolocalização por IP são resolvidos no servidor. Os eventos do funil do formulário (`/eventos`) carregam só o nome dos campos tocados, nunca o valor.

### Consentimento: o que é com você

O Asender **não traz um banner de cookies**. Você define a política do seu site. Pontos práticos:

- Para o **formulário**, use a opção de exigir consentimento com o texto de aceite que sua base legal pede; o aceite fica registrado junto do lead.
- O **pixel** e a **gravação de jornada** são analytics. Se a sua política exige opt-in para analytics, carregue o `pixel.js` só depois do aceite. Remova `data-lz-replay` se não quiser a jornada.
- O **Web Push** e o **chat** dependem de ação do visitante (aceitar a notificação, abrir o chat), mas informe o uso na sua política de privacidade.
- Em todos os casos, não coloque `sk_` nem outro segredo em código de página.



==============================================================================
# GUIA: Domínios e DNS
==============================================================================

# Domínios: envio de e-mail e páginas

Para o Asender trabalhar com a sua marca, o DNS do seu domínio precisa dizer duas coisas: que o Asender **pode enviar e-mail em nome dele** (domínio de envio) e que o Asender **pode servir as suas páginas nele** (domínio de páginas). Este guia mostra os dois caminhos de configuração (o botão de 1 clique e o manual), os registros de cada caso, as ferramentas públicas de checagem e os problemas mais comuns.

Os valores exatos dos registros (host de entrada, `include` de SPF, chave DKIM, token de posse) são **gerados para a sua conta** e aparecem na tela do domínio. Os exemplos abaixo usam marcadores entre `< >` nesses pontos: copie sempre o valor da tela, nunca de um exemplo.

## Visão geral

| | Domínio de envio de e-mail | Domínio de páginas |
| --- | --- | --- |
| Onde cadastrar | Admin, **Domínios** | Páginas, **Domínios** |
| Para quê | Enviar (e, se você quiser, receber) e-mail com a sua marca: e-mail marketing, transacional e caixas. | Publicar páginas em `lp.suaempresa.com.br`, com HTTPS automático. |
| O que prova | Posse (TXT), SPF, DKIM e, no modo completo, MX. DMARC é recomendado, não bloqueia. | Posse (TXT), apontamento (CNAME ou equivalente) e certificado. |
| Automático | Verificação periódica; 1 clique na Cloudflare. | Verificação sob pedido; 1 clique na Cloudflare. |

Você também ganha, sem configurar nada, um endereço de páginas gratuito em `apages.xyz`. O domínio próprio é opcional.

## Caminho rápido: conectar com 1 clique (Domain Connect)

O Asender usa o protocolo aberto **Domain Connect**: você entra no provedor de DNS, confere os registros que o Asender vai criar e autoriza. Nenhuma senha nem token fica com o Asender. Hoje o provedor compatível é a **Cloudflare**.

Quando o domínio está na Cloudflare e o recurso está disponível, a tela do domínio mostra o bloco **Conectar com Cloudflare**. O botão leva você à Cloudflare, e na volta o Asender verifica o domínio sozinho. Cancelar na Cloudflare não altera nada no seu DNS.

O que cada serviço pede à Cloudflare:

| Serviço | Registros criados |
| --- | --- |
| **Páginas** | `TXT _asender-verify` (posse, só se ainda não provada) e o apontamento: `CNAME` para o nome-alvo das páginas. No domínio principal (`@`) a Cloudflare aceita o CNAME e o "achata" (CNAME flattening); só se o ambiente não tem nome-alvo é que o pedido usa `A`. |
| **E-mail** | `TXT _asender-verify` (posse), **SPF** (o `include` do Asender é *mesclado* no SPF que você já tem), **DKIM**, e **DMARC** somente se o domínio ainda não tem um. No modo completo também: **MX** e, opcionalmente, o grupo do cliente de e-mail (`CNAME autoconfig` e `SRV _imaps`, `_submissions`, `_submission`). |

Se o botão de 1 clique não aparece (seu DNS não está na Cloudflare, o recurso ainda não foi liberado para o ambiente, ou a Cloudflare ainda não liberou o modelo do Asender), há duas alternativas:

- **Token de API da Cloudflare.** Na Cloudflare, crie um token com o modelo **Editar DNS da zona** (Zone → DNS → Edit), limitado **a esta zona**. Cole o token na tela do domínio e use **Aplicar registros na Cloudflare**. O token é guardado cifrado e você pode removê-lo quando quiser (revogue-o também na Cloudflare). A aplicação só cria os registros do Asender e informa o resultado de cada um: criado, atualizado, já estava certo, precisa de você (conflito) ou falhou.
- **Manual**, como descrito abaixo.

Os modelos do Asender para o Domain Connect se chamam `asender.net.pages.json` (páginas) e `asender.net.mail.json` (e-mail); o link de autorização sai assinado pelo Asender, então ninguém troca um valor no caminho.

## Domínio de envio de e-mail

### Dois modos

Ao cadastrar o domínio em Admin, **Domínios**, você escolhe **onde ficam as caixas de e-mail**:

- **Aqui no Asender (modo completo).** O Asender recebe e envia. O MX do domínio passa a apontar para o Asender.
- **Em outro provedor (modo só envio).** Seu e-mail continua chegando no Google Workspace, no Microsoft 365 ou onde estiver hoje. O MX **não muda**; o Asender só assina e envia. É o modo certo para quem quer usar o e-mail marketing sem mexer na caixa de entrada.

Não publique os registros do modo completo num domínio que usa Google ou Microsoft: o MX do Asender tiraria seu e-mail de lá, e o `-all` do SPF faria o que o Google envia falhar na autenticação.

### Registros

Na tela do domínio, **Ver DNS** lista os registros exatos. No domínio `exemplo.com.br`:

| Tipo | Nome | Valor | Para quê |
| --- | --- | --- | --- |
| `TXT` | `_asender-verify.exemplo.com.br` | `asender-verify=<token>` | Prova de posse. Publique antes de verificar. |
| `MX` (só modo completo) | `exemplo.com.br` | `10 <host-de-entrada-do-Asender>.` | Recebimento. |
| `TXT` | `exemplo.com.br` | modo completo: `v=spf1 include:<include-spf-do-Asender> -all` | **SPF**: autoriza o Asender a enviar. |
| `TXT` | `exemplo.com.br` | modo só envio: o **seu SPF atual** com `include:<include-spf-do-Asender>` acrescentado | SPF mesclado (veja abaixo). |
| `TXT` | `s1._domainkey.exemplo.com.br` | `v=DKIM1; k=rsa; p=<chave pública do domínio>` | **DKIM**: a chave que valida a assinatura. |
| `TXT` | `_dmarc.exemplo.com.br` | `v=DMARC1; p=none; rua=mailto:dmarc@exemplo.com.br` | **DMARC**: política e relatórios. |
| `CNAME` | `autoconfig.exemplo.com.br` | `<host-de-autoconfiguracao>.` | (modo completo) o Thunderbird e similares se configuram sozinhos. |
| `SRV` | `_imaps._tcp`, `_submissions._tcp`, `_submission._tcp` | portas 993, 465 e 587 | (modo completo) servidores de IMAP e SMTP para clientes de e-mail. |

Detalhes que valem atenção:

- **Cada domínio tem a sua chave DKIM.** O seletor padrão é `s1` e a chave pública vem da tela. Em modo só envio ela convive com a do Google (`google._domainkey`): cada assinatura tem seu seletor, e o destinatário usa o que vier na mensagem. **Não remova** o seletor do Google.
- **Um domínio só pode ter UM registro SPF.** Publicar um segundo `v=spf1` invalida os dois. No modo só envio, **substitua** o SPF atual pelo valor da tela, que já preserva tudo o que existia (inclusive o Google) e mantém o seu mecanismo final (`-all`, `~all`). O Asender detecta SPF duplicado e mostra como juntar os dois em um.
- **DMARC começa em `p=none`**, que apenas monitora. Subir direto para `reject` sem ler os relatórios pode derrubar e-mail legítimo mal configurado. Endureça depois. O endereço `dmarc@seu-domínio` precisa existir se você quer receber os relatórios. Se o domínio **já tem** um DMARC seu, não o troque: o Asender alinha o envio pelo DKIM do seu domínio, então a sua política atual continua valendo.
- **Valor, não só nome.** O verificador compara o conteúdo: o token de posse tem de ser exatamente o da tela, o `p=` do DKIM tem de ser o da chave gerada, e o SPF tem de conter o `include` atual.

### Quando o domínio conta como verificado

| Modo | Exige |
| --- | --- |
| Completo | posse + MX + SPF + DKIM |
| Só envio | posse + SPF + DKIM |

DMARC e o grupo do cliente de e-mail entram no retrato da tela, mas **não bloqueiam** a verificação. Você pode clicar em **Verificar** a qualquer momento. Sem clicar, o Asender verifica sozinho: 15 tentativas de 1 em 1 minuto, depois 10 de 5 em 5 minutos, depois de 15 em 15 minutos sem prazo final. Domínio já verificado é reconferido a cada 15 minutos e só vira "desatualizado" depois de 3 checagens seguidas erradas, para que uma oscilação de DNS não derrube o envio. Cada registro tem um estado: **ok**, **ausente**, **divergente**, **modelo antigo** (apontava para um endereço antigo da plataforma, atualize para o valor da tela), **indeterminado** (o DNS não respondeu; nada é desverificado por isso) ou **não se aplica**.

Quer que outra pessoa publique o DNS? Em **Enviar para webmaster**, informe o e-mail dela: ela recebe os registros prontos para publicar, e a verificação é automática depois.

### O que o e-mail marketing exige

O e-mail marketing só envia com remetente de **domínio verificado da conta**. Se o `From` de uma campanha usa um domínio que não está verificado, a mensagem **não sai** (ela é marcada como falha, em vez de sair com outro remetente). O seletor de remetente do assistente de campanha lista os domínios verificados. Sem nenhum, ele pede para verificar um em Admin, **Domínios**.

### Return-path, VERP e retorno de devoluções

Devoluções (bounces) e reclamações de spam voltam para um endereço de retorno no formato `b-<token>@<domínio de retorno da plataforma>` (VERP), que o Asender lê para suprimir endereços que não existem mais. Esse domínio de retorno é **da plataforma**: **você não publica nenhum registro para ele.** Duas consequências, quando o recurso está ativo na plataforma:

- o endereço de retorno das mensagens aponta para o domínio do Asender, não para o seu. Por isso o **alinhamento do DMARC passa pelo DKIM** do seu domínio (que o Asender assina em toda mensagem de marketing), e não pelo SPF;
- o SPF do seu domínio com o `include` do Asender continua **recomendado** (reputação) e continua sendo checado na verificação.

## Domínio de páginas

### Subdomínio ou domínio principal

Em Páginas, **Domínios**, adicione o domínio (por exemplo `lp.exemplo.com.br`). A tela guia três passos:

1. **Posse.** Publique um `TXT` em `_asender-verify.<host>` com o token mostrado (começa com `asv_`). Sem essa prova, qualquer conta poderia pedir certificado para um domínio que não é dela.
2. **Apontamento.** Faça o domínio apontar para o nome-alvo do Asender.
3. **Certificado.** Com posse e apontamento ok, o HTTPS é emitido automaticamente (a verificação já faz a primeira conexão que dispara a emissão); a tela mostra o estado (`pendente`, depois `ativo`).

O domínio fica **pronto** quando os três passos estão ok.

**Subdomínio (recomendado)**, como `lp.exemplo.com.br`:

| Tipo | Nome | Valor |
| --- | --- | --- |
| `TXT` | `_asender-verify.lp.exemplo.com.br` | `<token>` |
| `CNAME` | `lp.exemplo.com.br` | `<nome-alvo mostrado na tela>` (por exemplo, `cname.apages.xyz`) |

Use sempre o **nome-alvo** e não um endereço IP: se o Asender trocar de servidor, o seu domínio continua certo, sem você mexer em nada.

**Domínio principal** (o "apex", como `exemplo.com.br`): a regra do DNS não permite `CNAME` no domínio nu, então a tela pede um registro **ALIAS** (também chamado ANAME ou CNAME flattening, conforme o provedor) para o mesmo nome-alvo. Na Cloudflare, basta criar um `CNAME` em `@`; ela o achata sozinha. Provedores sem ALIAS (como o DNS do Registro.br) usam o último recurso: registros `A` (e `AAAA`) com os endereços que a tela mostra. Esses endereços **podem mudar**; a tela avisa e recomenda migrar para ALIAS ou CNAME assim que o provedor permitir. Outra saída é usar o **www**: cadastre `www.exemplo.com.br` (um CNAME comum) e redirecione o domínio principal para ele.

Domínios próprios contam na cota do seu plano (acima dela o cadastro responde **402**). Um domínio já cadastrado por outra conta responde **409**, e um host inválido, reservado (como os do próprio Asender) ou sob um sufixo público responde **422**.

### Na API

```bash
curl -X POST 'https://api.pages.asender.net/v1/dominios' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "host": "lp.exemplo.com.br" }'
```

A resposta traz `registro_txt` (o **nome** do TXT de posse, `_asender-verify.lp.exemplo.com.br`), `token` (o **valor** a publicar) e os blocos `posse`, `apontamento` e `tls`. Depois, `POST /v1/dominios/{id}/verificar` confere os três passos e responde **200** com o estado de cada um (`posse.ok`, `apontamento.ok`, `tls.estado`) e `pronto`; um registro que ainda não propagou aparece como passo pendente, não como erro. Só responde **503** quando o DNS não pôde ser consultado. A posse, uma vez provada, não é reconsultada: você pode apagar o TXT depois. A referência completa está no [guia da API de Páginas](https://developers.asender.net/apis/pages.html).

## Ferramentas públicas de checagem

Antes de abrir chamado, confira o seu DNS nas ferramentas gratuitas do Asender, sem login, em `https://tools.asender.net`:

- **DNS Overview** (`https://tools.asender.net/dns-overview`). Digite o domínio e receba um raio-X de MX, SPF, DKIM (procura nos seletores mais comuns, entre eles `s1`, `google` e `selector1`), DMARC, TLS de entrega e higiene, com nota, achados por gravidade e o registro pronto para copiar. Achar nada num seletor não significa "sem DKIM": significa "não achei nos nomes que conheço". Para a API: `GET https://tools.asender.net/api/tools/v1/dns-overview?dominio=exemplo.com.br`.
- **Email Tester** (`https://tools.asender.net/email-tester`). A ferramenta dá um endereço de uso único; você envia um e-mail de teste do seu domínio para ele e recebe o relatório de autenticação e qualidade da mensagem.

As duas têm limite de uso por IP (por minuto). Se você receber um erro de limite, espere um instante.

## Problemas comuns

| Sintoma | Causa provável | O que fazer |
| --- | --- | --- |
| "Verificar" não acha o registro recém-criado | O DNS ainda está propagando. | Espere alguns minutos (pode levar algumas horas) e verifique de novo. O e-mail se verifica sozinho; as páginas, ao clicar em verificar. Confirme o registro na DNS Overview. |
| Posse falha mesmo com o TXT publicado | Nome ou valor errado. No e-mail o valor é `asender-verify=<token>`; em páginas o valor é o `token` puro (`asv_…`), e o nome é `_asender-verify.<host>` nos dois. Alguns painéis acrescentam o domínio ao nome sozinhos. | Compare nome e valor com a tela, letra por letra. Em painel que completa o domínio, escreva só `_asender-verify` (ou `_asender-verify.lp`). |
| SPF "divergente" | Há **dois** registros `v=spf1`, ou o SPF existente não tem o `include` do Asender. | Mantenha **um** só. Use o valor sugerido na tela, que já junta tudo. Não publique um segundo SPF. |
| SPF passa a falhar para o Google depois de configurar | O SPF do Asender substituiu o seu em vez de ser mesclado. | Republique o SPF com o que o Google precisa **e** o `include` do Asender (modo só envio). |
| DKIM "divergente" ou "ausente" | A chave foi truncada ao colar (a chave é longa) ou está no seletor errado. | Cole o valor inteiro. Se o seu provedor limita o tamanho de cada texto, divida em partes entre aspas dentro do **mesmo** registro, como ele pedir. Confira o seletor (`s1`). |
| "Modelo antigo" | O domínio ainda aponta para um endereço de uma configuração anterior da plataforma. | Atualize para os valores atuais da tela. |
| MX "divergente" e o domínio recebe no Google ou Microsoft | O domínio está no modo completo. | Mude o modo para **só envio** e não toque no MX. |
| MX publicado como "nulo" (`0 .`) | O domínio foi configurado para não receber e-mail. | Se só vai enviar, use o modo **só envio**. Se vai receber no Asender, troque o MX. |
| Domínio verificado, mas a campanha falha com remetente recusado | O `From` usa um domínio diferente do verificado. | Escolha o remetente na lista de domínios verificados. |
| O `CNAME` não pode ser criado no domínio principal | O DNS não permite `CNAME` no domínio nu, ou há outros registros no mesmo nome (um `CNAME` não convive com nenhum outro registro no mesmo nome, como `MX` ou `TXT`). | Use ALIAS/ANAME/CNAME flattening, ou o `www`. Na Cloudflare o CNAME no `@` é aceito. |
| O apontamento não verifica e a tela diz que "o proxy da Cloudflare está ativo" | O registro das páginas está com o proxy ligado (nuvem laranja). | Deixe o registro como **somente DNS** (nuvem cinza). O mesmo vale para registros de e-mail, que não funcionam por trás do proxy laranja. |
| Já havia um registro no mesmo nome, ou conflito no "Aplicar" | `A`, `AAAA` e `CNAME` conflitam entre si no mesmo nome; dois `MX` de provedores diferentes disputam a entrega. | Resolva o conflito na zona (remova o antigo) e aplique de novo; a tela mostra "precisa de você" no registro em conflito. |
| Certificado `pendente` por muito tempo | O apontamento ainda não chegou ao Asender, ou o proxy do provedor está no meio. | Confira o CNAME na DNS Overview; deixe o registro sem proxy e aguarde. |
| Registro apagado depois de verificado | Alguém removeu ou alterou o DNS. | O Asender reconfere a cada 15 minutos e avisa os administradores uma vez por dia enquanto houver algo a corrigir. Republique o registro. |
| Mudei o servidor de nomes (NS) do domínio | O novo provedor de DNS está vazio. | Recrie todos os registros no novo provedor; a verificação consulta os servidores autoritativos do domínio, então a troca vale assim que o novo NS responde. |



==============================================================================
# GUIA: SMTP e IMAP com senhas de app
==============================================================================

# SMTP e IMAP (clientes de e-mail)

Este guia mostra como usar uma **caixa do Asender Mail** num cliente de e-mail
(Thunderbird, Apple Mail, Outlook, celular) ou em código, por **IMAP** (ler) e
**SMTP de submissão** (enviar), em vez de usar o webmail ou a API HTTP.

> **Disponibilidade: em implantação.** O gateway de IMAP/SMTP está construído e
> testado, mas **ainda não está liberado ao público**: o serviço só é ligado nas
> máquinas em que a operação o declara, e a autoconfiguração (`autoconfig` e
> registros `SRV` no DNS) depende desse mesmo passo. Os endereços, portas e
> comportamentos abaixo são os definidos no código, mas **não configure clientes de
> produção até este aviso sair deste guia**. Para enviar e-mail agora, use a
> [API de envio](#smtp-ou-api-de-envio-quando-usar-cada-um).

## Resumo

| | IMAP (leitura) | SMTP (envio) |
| --- | --- | --- |
| Servidor | `imap.asender.com.br` | `smtp.asender.com.br` |
| Porta e segurança | **993**, SSL/TLS (TLS implícito) | **465**, SSL/TLS (TLS implícito) **ou 587**, STARTTLS |
| Usuário | o **endereço completo** da caixa (`voce@seudominio.com.br`) | o mesmo |
| Senha | **senha de aplicativo** com escopo `mail:imap` | **senha de aplicativo** com escopo `mail:smtp` |
| Autenticação | senha normal (PLAIN/LOGIN), **só dentro de TLS** | `PLAIN` ou `LOGIN`, **só dentro de TLS** |

Fatos que evitam tentativa e erro:

- **A senha da conta não funciona aqui.** O gateway só aceita **senha de
  aplicativo** (próxima seção). Cada aplicativo tem a sua e você revoga uma sem
  afetar as outras.
- **Não há texto puro nem POP3.** Não existe IMAP na 143, e o `AUTH` sequer é
  oferecido antes do TLS. No 587 o `STARTTLS` é **obrigatório** antes do login. A
  versão mínima do TLS é a 1.2.
- **Os servidores são os mesmos para todos os domínios.** Mesmo que o seu e-mail
  seja `voce@seudominio.com.br`, o servidor é `imap.asender.com.br` /
  `smtp.asender.com.br` (e não `imap.seudominio.com.br`). Para confirmar os nomes,
  veja os registros `SRV` do seu domínio:
  `dig +short SRV _imaps._tcp.seudominio.com.br`.
- **Só para caixas hospedadas no Asender Mail.** Se o seu domínio usa o Asender
  apenas para **enviar** (o recebimento é do Google Workspace ou do Microsoft 365),
  não há caixa aqui — use o cliente do seu provedor de recebimento.

## 1. Crie uma senha de aplicativo

A senha de aplicativo é uma credencial própria para o programa de e-mail, no lugar
da senha da conta.

1. Entre em `https://auth.asender.net` e abra **Minha conta → Dispositivos**
   (`https://auth.asender.net/conta/dispositivos`).
2. Na seção **Senhas de aplicativo**, clique em **Criar senha**.
3. Dê um **nome** ao aplicativo (por exemplo, "Thunderbird no notebook", até 60
   caracteres) e marque o que ele pode fazer: **Ler e organizar e-mails (IMAP)**,
   que dá o escopo `mail:imap`, e/ou **Enviar e-mails (SMTP)**, que dá o escopo
   `mail:smtp`.
4. Confirme com o seu segundo fator, se for pedido (a criação exige reautenticação).
5. **Copie a senha agora.** Ela aparece **uma única vez**; depois só é possível criar
   outra. O formato é `asp_` seguido de dois blocos (`asp_XXXXXXXX_…`).

Regras:

- Marque só os escopos de que o aplicativo precisa. Uma senha com `mail:imap` não
  consegue enviar, e uma com `mail:smtp` não consegue ler. Um cliente de e-mail
  completo precisa dos dois escopos (pode ser uma senha só, com os dois).
- O limite é de **20 senhas de aplicativo vivas** por usuário. A emissão atual não
  define validade: a senha vale até você revogá-la.
- **Revogue** uma senha na mesma lista, em **Revogar**; ela deixa de funcionar
  imediatamente. Elas também são todas revogadas quando a senha ou o segundo fator da
  conta são redefinidos ou a conta é excluída; uma conta suspensa não consegue usá-las.
- Uma senha de aplicativo **não cria outras** nem serve de sessão da conta: ela só
  abre IMAP/SMTP.
- Guarde-a como um segredo: cofre de senhas do cliente de e-mail, variável de
  ambiente do servidor; nunca em repositório, navegador ou log.

## 2. Configuração automática

### Thunderbird

O Thunderbird procura `https://autoconfig.<domínio-do-e-mail>/mail/config-v1.1.xml`.
Para o seu domínio responder, é preciso este registro DNS (e o domínio **verificado**
no Asender):

```
autoconfig.seudominio.com.br.   CNAME   autoconfig.asender.com.br.
```

O Asender responde `200` com um XML que aponta o IMAP para `imap.asender.com.br:993`
(SSL) e o SMTP para `smtp.asender.com.br:465` (SSL), com usuário
`%EMAILADDRESS%`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<clientConfig version="1.1">
  <emailProvider id="seudominio.com.br">
    <domain>seudominio.com.br</domain>
    <displayName>Asender E-mail (seudominio.com.br)</displayName>
    <displayShortName>Asender</displayShortName>
    <incomingServer type="imap">
      <hostname>imap.asender.com.br</hostname>
      <port>993</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <outgoingServer type="smtp">
      <hostname>smtp.asender.com.br</hostname>
      <port>465</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>
  </emailProvider>
</clientConfig>
```

("password-cleartext" é o nome que o Thunderbird dá à senha enviada **dentro do
TLS**; a conexão é sempre criptografada.) Detalhes do comportamento da rota:

- Responde só para **domínio existente e verificado** no Asender; qualquer outro caso
  (domínio inexistente, não verificado, formato inválido) devolve o **mesmo `404`**,
  sem dizer qual.
- Também aceita o endereço na consulta:
  `https://autoconfig.asender.com.br/autoconfig/mail/config-v1.1.xml?emailaddress=voce@seudominio.com.br`.
- O limite é de 60 consultas por minuto por IP (acima disso, `429` com
  `Retry-After: 60`). A resposta pode ser guardada em cache por 1 hora.
- O cliente de e-mail pode tentar o endereço em HTTP antes de HTTPS; a rota
  responde nos dois.

### Registros `SRV` (RFC 6186)

Para clientes que descobrem servidores por `SRV`, o grupo "Clientes de e-mail
(IMAP/SMTP)" do domínio publica:

```
_imaps._tcp.seudominio.com.br.         SRV  0 1 993  imap.asender.com.br.
_submissions._tcp.seudominio.com.br.   SRV  0 1 465  smtp.asender.com.br.
_submission._tcp.seudominio.com.br.    SRV  0 1 587  smtp.asender.com.br.
```

Em **Admin → Domínios** do painel, o card "Clientes de e-mail (IMAP/SMTP)" mostra se
o grupo está publicado e oferece aplicá-lo (na Cloudflare) ou ver os registros para
publicar à mão. Ele é **opcional**: não bloqueia a verificação do domínio, e a
configuração manual continua valendo.

### Apple Mail e Outlook

- **Outlook (Autodiscover): ainda não disponível.** Não existe o endpoint de
  Autodiscover; no Outlook, configure **manualmente** (próxima seção).
- **Apple Mail:** não usa o `autoconfig` do Thunderbird. Os registros `SRV` acima
  seguem o padrão que alguns clientes usam, mas **não conte com a descoberta
  automática**: configure manualmente.

## 3. Configuração manual, passo a passo

Os nomes dos menus mudam entre versões; o que importa são os valores.

### Thunderbird

1. **Conta → Configurar conta de e-mail** e informe nome, endereço
   (`voce@seudominio.com.br`) e a **senha de aplicativo**.
2. Se o autoconfig não responder, clique em **Configuração manual**. Em **Entrada**,
   escolha o protocolo **IMAP**, servidor `imap.asender.com.br`, porta **993**,
   segurança **SSL/TLS** e autenticação **Senha normal**. Em **Saída**, servidor
   `smtp.asender.com.br`, porta **465** com **SSL/TLS** (ou **587** com
   **STARTTLS**) e autenticação **Senha normal**. O nome de usuário, nos dois, é o
   **endereço completo**.
3. Para ler **e** enviar, a senha de aplicativo precisa ter os dois escopos (ou crie
   duas senhas e informe cada uma no seu servidor).

### Apple Mail (macOS e iOS)

1. **Ajustes → Contas de Internet → Adicionar Conta → Outra** e escolha **Conta de
   e-mail**. Informe nome, endereço e a senha de aplicativo.
2. Quando a configuração automática falhar, escolha **Configuração manual** com tipo
   de conta **IMAP**. Servidor de entrada: `imap.asender.com.br` (porta 993, SSL
   ligado). Servidor de saída: `smtp.asender.com.br` (porta 465 com SSL, ou 587 com
   STARTTLS). Usuário: o endereço completo; senha: a senha de aplicativo.
3. Em **Avançado**, confira que **Usar SSL** está ligado e a autenticação é **Senha**.

### Outlook (versão clássica para Windows)

1. **Arquivo → Adicionar Conta**, digite o endereço, abra **Opções avançadas** e
   marque **Permitir configurar manualmente minha conta**, escolhendo **IMAP**.
2. Em **Entrada**, informe `imap.asender.com.br`, porta **993**, método de
   criptografia **SSL/TLS**. Em **Saída**, `smtp.asender.com.br`, porta **465** com
   **SSL/TLS** (ou 587 com **STARTTLS**).
3. Quando pedir a senha, use a **senha de aplicativo**.

### Celular (Android e iOS)

Adicione uma conta "Outro/IMAP" com os mesmos valores: IMAP `imap.asender.com.br`
993 SSL, SMTP `smtp.asender.com.br` 465 SSL (ou 587 STARTTLS), usuário igual ao
endereço, senha de aplicativo.

## 4. Configuração por código

Em todos os exemplos, o **usuário é o endereço completo da caixa**, a senha é a
**senha de aplicativo** e o `From` tem de ser a própria caixa ou uma identidade
("enviar como") dela — veja [Regras de envio](#regras-de-envio).

### Node.js (Nodemailer)

```js
import nodemailer from "nodemailer";

const transporte = nodemailer.createTransport({
  host: "smtp.asender.com.br",
  port: 465,
  secure: true, // TLS implícito; para a 587 use port: 587, secure: false, requireTLS: true
  auth: { user: process.env.SMTP_USUARIO, pass: process.env.SMTP_SENHA_APP },
});

const info = await transporte.sendMail({
  from: process.env.SMTP_USUARIO, // a própria caixa, ex.: voce@seudominio.com.br
  to: "cliente@exemplo.test",
  subject: "Proposta comercial",
  text: "Olá, segue a proposta que conversamos.",
});
console.log("aceita:", info.messageId);
```

### Python (`smtplib` e `imaplib`)

Envio:

```python
import os
import smtplib
import ssl
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = os.environ["SMTP_USUARIO"]  # a própria caixa
msg["To"] = "cliente@exemplo.test"
msg["Subject"] = "Proposta comercial"
msg.set_content("Olá, segue a proposta que conversamos.")

contexto = ssl.create_default_context()  # valida o certificado e o nome do servidor
with smtplib.SMTP_SSL("smtp.asender.com.br", 465, context=contexto, timeout=60) as s:
    s.login(os.environ["SMTP_USUARIO"], os.environ["SMTP_SENHA_APP"])
    s.send_message(msg)

# Alternativa na 587 (STARTTLS obrigatório antes do login):
# with smtplib.SMTP("smtp.asender.com.br", 587, timeout=60) as s:
#     s.starttls(context=contexto)
#     s.login(...)
#     s.send_message(msg)
```

Leitura (IMAP):

```python
import imaplib
import os

with imaplib.IMAP4_SSL("imap.asender.com.br", 993) as c:
    c.login(os.environ["SMTP_USUARIO"], os.environ["SMTP_SENHA_APP"])
    c.select("INBOX", readonly=True)
    _, dados = c.search(None, "UNSEEN")
    for num in dados[0].split()[:10]:
        _, partes = c.fetch(num, "(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT)])")
        print(partes[0][1].decode("utf-8", "replace"))
```

### PHP (PHPMailer)

```php
<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php'; // composer require phpmailer/phpmailer

$mail = new PHPMailer(true);
try {
    $mail->isSMTP();
    $mail->Host       = 'smtp.asender.com.br';
    $mail->SMTPAuth   = true;
    $mail->Username   = getenv('SMTP_USUARIO');   // endereço completo da caixa
    $mail->Password   = getenv('SMTP_SENHA_APP'); // senha de aplicativo
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS; // 465; para a 587: ENCRYPTION_STARTTLS e Port = 587
    $mail->Port       = 465;
    $mail->CharSet    = 'UTF-8';

    $mail->setFrom(getenv('SMTP_USUARIO'));
    $mail->addAddress('cliente@exemplo.test');
    $mail->Subject = 'Proposta comercial';
    $mail->Body    = 'Olá, segue a proposta que conversamos.';
    $mail->send();
} catch (Exception $e) {
    error_log('falha no envio: ' . $mail->ErrorInfo);
}
```

> Use sempre destinatários de teste (`@exemplo.test`, `.invalid`, `.example`) em
> ambientes que não sejam de produção. Fora de produção, um destinatário real faz o
> envio ser recusado de propósito.

## Regras de envio

O SMTP do Asender é uma **submissão autenticada**: ele recebe a mensagem pronta do seu
cliente, confere se você pode enviá-la e a entrega ao serviço de envio do Asender, que
assina o e-mail com o **DKIM do seu domínio** e o despacha. Por isso:

- **Remetente.** O endereço do `MAIL FROM` (e o cabeçalho `From`, que precisa ser
  igual a ele) tem de ser a **caixa autenticada** ou uma **identidade** ("enviar
  como") dela. Qualquer outro remetente é recusado com `553 5.7.1`; um `From` diferente
  do envelope é recusado com `550 5.7.1`. O domínio do remetente precisa estar
  verificado no Asender, com o DKIM conferido.
- **Cópia em Enviados.** O envio por SMTP **não grava** a mensagem na pasta
  **Enviados**. Quem salva a cópia é o cliente de e-mail, por um `APPEND` por IMAP — o
  que Thunderbird, Apple Mail e Outlook fazem sozinhos. Em código, você mesmo precisa
  fazer o `APPEND` se quiser a cópia.
- **Cópia oculta.** Os destinatários em Cco são entregues e removidos do cabeçalho da
  mensagem que chega aos demais.
- **Quota do plano.** Cada destinatário (Para, Cc e Cco) consome **um envio** da
  quota do plano. Ao estourar o teto, o SMTP responde `452 4.2.2` (cota de envio
  esgotada, tente de novo mais tarde).
- **Supressão.** Destinatário em supressão global (bounce permanente, reclamação) é
  recusado já no `RCPT TO` com `550 5.1.1`.
- **Antivírus.** Anexo infectado recusa a mensagem inteira (`554 5.7.0`).

## Limites

| Limite | Valor |
| --- | --- |
| Tamanho da mensagem (SMTP) | **25 MiB** de mensagem completa, depois da codificação (anexos crescem cerca de 33% em base64). Acima: `552 5.3.4` |
| Destinatários por mensagem (SMTP) | **100**. Acima: `452 4.5.3` |
| Conexões simultâneas por IP | **20**, no SMTP e no IMAP. Acima: `421 4.7.0` (SMTP) ou `BYE Too many connections` (IMAP) |
| Conexões IMAP simultâneas por usuário | **15** |
| Tamanho de um `APPEND` (IMAP) | **25 MiB** |
| Prazo por comando | 60 s de leitura/escrita; 90 s para o envio e a autenticação terminarem |
| Tentativas de login | após falhas repetidas (10 do mesmo IP, 20 do mesmo usuário ou 10 da mesma senha, em 15 min), o acesso é bloqueado com espera crescente (de 2 s até 15 min); **toda falha de login demora de 1 a 3 s** de propósito |

O gateway SMTP não aplica, no seu próprio código, um limite de mensagens por minuto;
o teto de envio é a **quota do plano** (acima) e o limite de conexões por IP.

## O que o IMAP oferece

IMAP4rev1 com `IDLE` (notificação de novas mensagens), `UIDPLUS`, `MOVE`,
`SPECIAL-USE`, `NAMESPACE`, `CHILDREN`, `ESEARCH`, `LIST-EXTENDED`, `LIST-STATUS`,
`LITERAL+` e `APPENDLIMIT`. **Não** há `CONDSTORE`/`QRESYNC` nem IMAP4rev2.

As pastas padrão da caixa são **Entrada** (`INBOX`), **Enviados**, **Rascunhos**,
**Arquivo**, **Spam** e **Lixeira**, e o servidor as marca com `SPECIAL-USE`
(`\Sent`, `\Drafts`, `\Archive`, `\Junk`, `\Trash`); use o atributo, e não o nome, para
descobrir qual é qual. A quarentena de segurança nunca aparece no IMAP.

## Mensagens de erro comuns

| Resposta | Significado |
| --- | --- |
| `535 5.7.8` (SMTP) ou `Authentication failed` (IMAP) | usuário, senha ou escopo errados — o servidor **nunca diz qual**: usuário inexistente, senha errada ou revogada, escopo ausente e caixa sem acesso dão a mesma resposta |
| `523` / `530 5.7.0` (SMTP) | tentou autenticar sem TLS (na 587, falta o `STARTTLS`) ou mandou um comando sem estar logado |
| `454 4.7.0` (SMTP) | a autenticação está **temporariamente indisponível**; tente de novo em instantes |
| `451 4.3.0` (SMTP) | não foi possível entregar agora; o cliente mantém a mensagem e tenta de novo |
| `553 5.7.1` (SMTP) | o remetente não é a caixa autenticada nem uma identidade dela |
| `552 5.3.4` (SMTP) | mensagem maior que o limite |
| `452 4.2.2` (SMTP) | quota de envio do plano esgotada |
| `550 5.1.1` (SMTP) | destinatário em supressão global |
| `554 5.7.1` (SMTP) | envio externo bloqueado neste ambiente (fora de produção) |

## SMTP ou API de envio: quando usar cada um

| | SMTP de submissão (este guia) | API de envio transacional |
| --- | --- | --- |
| Para quê | pessoas e programas que **já falam SMTP/IMAP**: cliente de e-mail, impressora, CMS, biblioteca legada | sistemas que **enviam e-mail por código**: confirmações, recibos, códigos de verificação (OTP) |
| Rota | `smtp.asender.com.br` (465/587) | `POST https://api.asender.net/v1/emails/send` (remetente de domínio verificado) ou `POST https://api.mail.asender.net/v1/emails` (a partir de uma caixa existente) |
| Credencial | **senha de aplicativo** de um usuário (`mail:smtp`) | **chave de API** da conta (`sk_…`, escopo `email:send`) |
| Remetente | a caixa (ou identidade) autenticada | qualquer endereço de domínio verificado (`/v1/emails/send`) ou uma caixa existente (`/v1/emails`) |
| Idempotência | não há; o cliente reenvia a mensagem | `Idempotency-Key` |
| Cópia em Enviados | só se o cliente fizer o `APPEND` | a Mail API grava em Enviados |
| Erros | códigos SMTP | JSON com status HTTP |
| Disponibilidade | **em implantação** | disponível |

Regra prática: **código seu enviando mensagens de sistema** usa a API (chave de
API, idempotência, resposta estruturada, `202` imediato). **Uma pessoa usando uma
caixa** — ou um software que só sabe SMTP — usa o SMTP com a senha de aplicativo
dela. Detalhes das APIs: [Mail API](https://developers.asender.net/apis/mail.html) e
[Plataforma](https://developers.asender.net/apis/platform.html).



==============================================================================
# GUIA: Conversões e conectores
==============================================================================

# Conversões e conectores

Este guia cobre dois assuntos que usam a mesma plataforma de **Integrações**:

- **Conversões**: mandar o resultado de um lead (formulário preenchido, lead
  qualificado, venda) de volta às plataformas de anúncio, **pelo servidor**, para
  elas otimizarem a campanha. Hoje: **Meta**, **Google Ads** e **TikTok**.
- **Conectores**: levar o lead capturado para o sistema do cliente (**API própria /
  CRM próprio** e **Kommo**) e, no caso do Kommo, também ler relatórios dele.

Tudo é configurado no painel. A API pública permite **consultar** o que foi
enviado (`GET /v1/conversions`); não existe API pública para criar ou editar
integrações.

> **O que existe e o que é planejado.** Existem os apps Meta (API de Conversões),
> Google Ads, TikTok (Events API), API própria (HTTP), Kommo e Kommo somente
> leitura. **Não existem conectores nativos** para Zapier, n8n, Make, HubSpot,
> RD Station ou similares: veja [Zapier, n8n e Make](#zapier-n8n-e-make). Conectores
> nativos e gestão de integrações por API (`webhooks:manage`) são **planejados**.

## Onde configurar

Em **Administração → Integrações**
(`https://admin.asender.net/t/<conta>/integracoes`) você vê o catálogo de apps e as
**instalações** da conta. Cada instalação mostra o status, a saúde, o tamanho da
fila e o último erro, e abre um detalhe com configuração, **teste de conexão**,
**entregas** e auditoria.

| app | para quê | como conecta |
| --- | --- | --- |
| **Meta (API de Conversões)** | conversões no Facebook e Instagram | ID do pixel + token de acesso |
| **Google Ads (conversões)** | conversões no Google Ads | autorização OAuth da sua conta Google |
| **TikTok (Events API)** | conversões no TikTok | código do pixel + token de acesso |
| **API própria / CRM próprio** | entregar o lead a qualquer API HTTPS | URL, autenticação e modelo de corpo |
| **Kommo** | criar o lead (negócio) com o contato na Kommo | token de longa duração ou integração privada (OAuth) |
| **Kommo (somente leitura)** | copiar dados da Kommo para relatórios | token de longa duração ou integração privada (OAuth) |

Estados de uma instalação: `rascunho` (criada, ainda sem credencial válida ou
teste ok; não recebe entrega), `ativa`, `pausada` (você pausou; as entregas esperam
até religar ou 7 dias), `reautorizar` (a credencial foi recusada; as entregas
esperam até reconectar) e `removida`. Os segredos (tokens, senhas) **só são
escritos**: depois de salvos, o painel mostra apenas se existe e os últimos
caracteres.

## Conversões para plataformas de anúncio

### Quando uma conversão é enviada

Há dois caminhos, e ambos usam as mesmas instalações:

1. **Formulário de Páginas.** Ao escolher a instalação como destino do formulário,
   cada lead capturado gera uma conversão (por padrão o evento `Lead`).
2. **Jornada do CRM, ação "Enviar conversão (anúncios)"**: a conversão **offline**.
   Quando algo acontece depois do formulário (o lead virou "qualificado", o
   negócio foi ganho), a jornada avisa a plataforma para otimizar pelo resultado
   real. A ação pede: a **integração** (a instalação), o **evento** (por exemplo
   `QualifiedLead`, `Purchase`), e opcionalmente **valor** (decimal com ponto, como
   `1500.50`) e **moeda** (ISO 4217; o padrão é `BRL`). O gatilho típico é
   **"Etapa alterada"**. Os parâmetros são validados ao salvar a jornada, não
   quando o lead qualifica.

A mesma ação aceita só instalações dos apps `meta_capi`, `google_ads` e
`tiktok_events`.

### O que é enviado

Em todos os casos o servidor monta o pedido; **e-mail e telefone nunca saem em
claro**, só o hash.

| | Meta | TikTok | Google Ads |
| --- | --- | --- | --- |
| Hash | e-mail, telefone, nome e sobrenome em **SHA-256** (minúsculas, sem espaços) | e-mail e telefone em **SHA-256** | e-mail e telefone em **SHA-256** |
| Identificadores de clique | cookies `_fbp` e `_fbc` (ou derivado do `fbclid`) | `ttclid` | `gclid`, depois `gbraid`, depois `wbraid` (só um por conversão) |
| Sem clique | `external_id` (hash do e-mail) | e-mail e telefone em hash | conversão otimizada para leads, com e-mail e telefone em hash |
| IP e user agent | enviados em claro, como a Meta exige | enviados em claro | não enviados |
| Valor e moeda | enviados só quando vêm **juntos** | idem | idem |
| Deduplicação | `event_id` | `event_id` | `order_id` = `event_id` |

Detalhes que valem a pena conhecer:

- **Telefone** só é enviado com código do país. Sem `+`, um número brasileiro de
  10 ou 11 dígitos recebe `55`; qualquer outro número sem código do país é
  descartado (um hash errado só geraria ruído na plataforma).
- **Deduplicação com o pixel.** O `event_id` é o do navegador (o mesmo que o pixel
  usou) ou, na falta dele, o id do envio do formulário. Assim a Meta e o TikTok
  contam o evento uma vez, mesmo que ele chegue pelo pixel **e** pelo servidor.
  Para isso funcionar, use o **mesmo `event_id`** no pixel do seu site.
- **Idade do evento.** A Meta recusa `event_time` com mais de 7 dias; a entrega
  avisa quando o evento é mais velho que isso.
- **Google Ads:** o app nasce com **"Só validar"** ligado (`validate_only`): o
  Google valida o pedido, mas **não registra a conversão**. Desligue quando o
  teste estiver ok, e confira que a **ação de conversão** é a certa.

### Consentimento

A conversão só sai se o contato **consentiu com publicidade/marketing**. Sem o
consentimento (ausente, recusado, ou formulário sem caixa de aceite), a entrega é
**ignorada**: não vai à plataforma, não conta como erro e não afeta a saúde da
instalação. No CRM, o consentimento precisa estar ativo para publicidade. A
entrega ignorada aparece com o motivo "o contato não deu consentimento".

### Configurar no painel

**Meta.** Em Integrações, instale **Meta (API de Conversões)**. Informe o **ID do
pixel** (Gerenciador de Eventos → Fontes de dados) e o **token de acesso** da
Conversions API. Opcionais: versão da Graph API e **código de evento de teste**.

**TikTok.** Instale **TikTok (Events API)** com o **código do pixel** (TikTok Ads
Manager → Eventos) e o **token de acesso**.

**Google Ads.** Instale **Google Ads (conversões)**, autorize o acesso com a conta
Google e informe o **ID da conta** (10 dígitos, sem hífens), o **ID da conta
gerente (MCC)** se o acesso for por ela, e a **ação de conversão** (ID ou nome do
recurso).

Em cada uma, use **Testar conexão** antes de ativar. O teste da Meta vai
sempre com o **código de evento de teste**, e o evento aparece na aba de eventos
de teste da própria plataforma, sem contar como conversão.

### Fora de produção nada é enviado de verdade

Em ambientes de desenvolvimento e homologação, as entregas vão para um **sink**
interno, não para a Meta, o Google ou o TikTok, e o **código de evento de teste é
obrigatório** na Meta e no TikTok, enquanto o Google fica sempre em "só validar".
Só em produção a conversão real é enviada.

### Ver entregas e erros

No detalhe da instalação, a aba **Entregas** lista cada tentativa: estado, número
de tentativas, código HTTP e o motivo do último erro. O pedido enviado, que carrega
dado pessoal, não é exibido; o trecho da resposta da plataforma sai redigido e
segredos são mascarados de qualquer mensagem. O que acontece em falha:

| resposta da plataforma | tratamento |
| --- | --- |
| `401`/`403` | credencial: a instalação vai para `reautorizar` até você reconectar; as entregas esperam |
| `408`, `425`, `429`, `5xx` | transitório: tenta de novo com espera crescente (respeita `Retry-After`, no máximo 1 h) |
| outro `4xx` | final: o motivo da plataforma (até 200 caracteres) fica registrado |
| falha de rede | tenta de novo; o `event_id` evita contar duas vezes |

São até **12 tentativas** por entrega.

### Consultar pela API pública: `GET /v1/conversions`

Escopo `conversions:read` (chave de API ou token de app; o usuário do token precisa
de acesso ao CRM). Mostra o que o CRM registrou na linha do tempo do lead quando uma
**jornada** enviou (ou deixou de enviar) uma conversão offline e o desfecho da
entrega. Não traz e-mail, telefone, corpo do pedido nem token.

```bash
curl -s 'https://api.asender.net/v1/conversions?limit=100&created_after=2026-10-01T00:00:00Z' \
  -H "Authorization: Bearer $ASENDER_API_KEY"
```

```json
{
  "data": [
    { "id": "atv_…", "lead_id": "ctt_…", "type": "sent", "event": "QualifiedLead",
      "event_ref": "", "value": "1500.50", "currency": "BRL", "platform": "meta_capi",
      "delivery_status": "enviada", "reason": "",
      "source": { "utm_source": "meta", "utm_campaign": "outubro" },
      "occurred_at": "2026-10-19T14:02:11Z", "created_at": "2026-10-19T14:02:11Z" },
    { "id": "atv_…", "lead_id": "ctt_…", "type": "result", "event": "",
      "event_ref": "…", "platform": "meta_capi", "delivery_status": "enviado",
      "occurred_at": "2026-10-19T14:02:15Z", "created_at": "2026-10-19T14:02:15Z" }
  ],
  "next_cursor": null
}
```

- `type`: `sent` (a conversão entrou na fila de entrega), `ignored` (não foi
  enviada; o `reason` diz por quê) ou `result` (o desfecho da entrega, ligado à
  conversão por `event_ref`).
- `platform`: `meta_capi`, `google_ads` ou `tiktok_events`.
- `delivery_status` no `result`: `enviado`, `simulado` (fora de produção),
  `falhou`, `morta` (esgotou as tentativas) ou `ignorada_sem_consentimento`.
- Os registros não mudam depois de escritos, então `created_after` basta para
  sincronizar. `limit` de 1 a 200 (padrão 50), `next_cursor` opaco.
- `lead_id` é o mesmo `id` de `GET /v1/leads` e de `GET /v1/conversations`.
- Este endpoint reflete as conversões da **jornada**. As entregas de formulário
  aparecem no detalhe da instalação, no painel.

Detalhes de autenticação, paginação e sincronização incremental estão no
[guia da API Platform](https://developers.asender.net/apis/platform.html#dados-leitura-do-que-a-conta-tem).

### A integração de conversão do CRM (Meta)

O CRM também tem uma rota própria para uma integração de conversão **só com a
Meta**: `/v1/integracoes-de-conversao` na [API do CRM](https://developers.asender.net/apis/crm.html)
(`provedor` `meta`, com `pixel_id` e o token no campo `segredo`). Ela existe antes do
catálogo de Integrações e continua funcionando; para Google Ads, TikTok e para a
conversão offline por jornada, use as instalações de Integrações descritas acima.
O endereço da API de destino é fixo no servidor: não há campo de URL, de propósito,
para que o token de acesso nunca possa ser apontado para outro lugar.

## Conectores de lead

### API própria / CRM próprio (HTTP genérico)

Envia o lead capturado a **qualquer API HTTPS**: o seu CRM, uma planilha com
endpoint, um sistema interno. Você configura:

- **URL** (HTTPS), **método** (`POST`, `PUT` ou `PATCH`) e **formato** do corpo
  (`json` ou `form`);
- o **corpo por modelo**, com os campos do lead (até 32 KB) e **cabeçalhos fixos**
  (até 20, sem dados secretos);
- a **autenticação**: nenhuma, chave de API (em cabeçalho ou na query), `Bearer`,
  `Basic` ou OAuth 2 por *client credentials*;
- **assinar o corpo** (HMAC-SHA256), para o seu servidor provar que a entrega veio
  da Asender;
- o **critério de sucesso**: `2xx` e, se quiser, um campo da resposta com valor
  esperado (para APIs que respondem `200` mesmo com erro);
- opcionalmente o caminho do **id gerado** na resposta e um **link** para o
  registro remoto.

Cada entrega leva os cabeçalhos `Idempotency-Key`, `X-Asender-Entrega-Id` e
`X-Asender-Tentativa`, e, com a assinatura ligada, `X-Asender-Assinatura` no formato
`t=<unix>,v1=<hex>`, onde `v1` é o HMAC-SHA256 de `"<t>.<corpo>"` com o seu segredo.
**Use o `Idempotency-Key` para deduplicar** do seu lado: uma entrega pode ser
repetida. Como verificar a assinatura está no [guia de webhooks](https://developers.asender.net/guias/webhooks.html).

Limites: 10 s por requisição, resposta até 64 KB, até 12 tentativas. Destinos na
rede interna ou sem HTTPS são recusados, e redirecionamentos não são seguidos.
Use **Testar conexão** para enviar um lead de exemplo.

### Kommo

O app **Kommo** cria, na etapa escolhida, o **lead (negócio)** com o **contato**,
com tags, responsável, UTMs e campos personalizados. Você escolhe a conexão:

- **Token de longa duração**: gerado na Kommo; opcionalmente informe o vencimento
  (há aviso 7 dias antes);
- **Integração privada (OAuth)**: ID da integração, segredo e o fluxo de autorização
  da Kommo; a Asender renova o token sozinha.

Configure o **subdomínio** (`minhaempresa` em `minhaempresa.kommo.com`), o **funil**
e a **etapa** padrão (o painel os lê da Kommo), o responsável, as tags, o modelo
do nome do lead e o **mapa de campos** (campo da Asender para campo da Kommo,
até 40). Para não duplicar contatos, a deduplicação usa e-mail e depois telefone;
a opção de completar o contato existente **nunca sobrescreve** um valor já
preenchido. Há um limite de requisições por subdomínio para respeitar o da Kommo.

### Kommo, somente leitura (relatórios)

O app **Kommo (somente leitura)** copia **leads, contatos, tarefas, notas e
eventos** da Kommo para relatórios de funil, ganhos e perdas, tempo por etapa e
origem. **Nunca escreve na Kommo.** Você escolhe os funis a sincronizar (vazio =
todos) e precisa **declarar ter base legal (LGPD)** para copiar os dados à Asender,
que atua como operadora. Aceita os mesmos dois modos de conexão do app de escrita (token de longa duração
ou integração privada), configurados na própria instalação.

### Destinos de lead do CRM (webhooks)

No CRM, **destinos de lead** (`/v1/destinos` na
[API do CRM](https://developers.asender.net/apis/crm.html)) entregam cada lead capturado
a um **webhook seu**, com `url`, `segredo` (opcional, para assinatura) e `ativo`. O
segredo nunca volta nas respostas, só o indicador `tem_segredo`. Cada destino tem
**entregas** (diagnóstico por tentativa, sem o conteúdo) e **teste**
(`POST /v1/destinos/{id}/testar`). Para receber e validar, veja o
[guia de webhooks](https://developers.asender.net/guias/webhooks.html).

## Zapier, n8n e Make

**Não existem conectores nativos** da Asender para Zapier, n8n ou Make. O que você
pode fazer hoje, e funciona:

- **Receber leads e eventos** num fluxo do Zapier, n8n ou Make: crie um *webhook*
  (gatilho "Catch Hook") na ferramenta e use a URL dele como destino de lead do CRM
  ou como instalação do app **API própria / CRM próprio**.
- **Ler dados** da Asender numa automação: use o módulo HTTP da ferramenta com a
  [API pública](https://developers.asender.net/apis/platform.html) e uma
  [chave de API](https://developers.asender.net/guias/chaves-de-api.html) de escopos de
  leitura (`leads:read`, `conversions:read` etc.).
- **Enviar mensagens** a partir da automação: chame as rotas `/v1/*/send` com uma
  chave de escopo de envio, de dentro do servidor da ferramenta.

Conectores nativos (com cadastro de conta e gatilhos prontos) são **planejados**.

## Próximos passos

- [Chaves de API](https://developers.asender.net/guias/chaves-de-api.html) e [API Platform](https://developers.asender.net/apis/platform.html).
- [Webhooks](https://developers.asender.net/guias/webhooks.html): assinatura e retentativas.
- [Navegador](https://developers.asender.net/guias/navegador.html): o pixel e o `event_id` que deduplicam com a conversão do servidor.
- [Integrações](https://developers.asender.net/guias/integracoes.html): o mapa de todos os meios de integrar.



==============================================================================
# GUIA: Servidor MCP
==============================================================================

# Servidor MCP

A Asender tem um servidor **MCP** (Model Context Protocol) remoto. Com ele, um
agente de IA (Claude, ChatGPT, Cursor, VS Code e outros clientes MCP) consulta os
dados da sua conta: leads, formulários, campanhas, relatórios, conversas e mais.
Com **chave de API** e o escopo certo, o agente também **escreve**: envia um e-mail
e cria ou atualiza leads (veja [Ferramentas de escrita](#ferramentas-de-escrita)).
Token OAuth continua **somente leitura**.

- **URL:** `https://api.asender.net/mcp`
- **Transporte:** Streamable HTTP **stateless** (um `POST` por mensagem JSON-RPC; sem SSE e sem sessão)
- **Versões do protocolo aceitas:** `2025-11-25`, `2025-06-18` e `2025-03-26`
- **Autenticação:** chave de API `sk_*` ou token OAuth de um app, no header `Authorization: Bearer`
- **Ferramentas:** 32 (veja o [catálogo](#catálogo-de-ferramentas)): 27 de leitura que servem a chave e o token OAuth, 2 de leitura de DNS e **3 de escrita**, estas 5 só para chave `sk_*`

## Status

| Forma de conectar | Situação |
| --- | --- |
| **Chave de API `sk_*`** no header `Authorization: Bearer` | Funciona em qualquer cliente que permita configurar headers (Claude Code, Cursor, VS Code, MCP Inspector). É a alternativa quando o cliente não faz OAuth. |
| **OAuth com registro automático do cliente** (CIMD / DCR) | Clientes MCP com OAuth (Claude, ChatGPT, Cursor, VS Code, MCP Inspector) se **registram sozinhos** no servidor de autorização, e o usuário autoriza na tela de consentimento. O cliente aparece com o selo **Não verificado** até a equipe Asender verificá-lo, e só recebe escopos de leitura. Disponível após a implantação em cada ambiente. |
| **OAuth com app cadastrado** (`client_id` informado manualmente) | Para clientes que aceitam `client_id` (e `client_secret`, se o app for confidencial) digitados à mão, como as configurações avançadas do conector personalizado do Claude. Veja [Aplicativos](aplicativos.html). |

O registro automático está descrito em
[Aplicativos](aplicativos.html#clientes-registrados-automaticamente-mcp). O que
ainda não existe está em [Limites e o que vem a seguir](#limites-e-o-que-vem-a-seguir).

## Conectar um cliente

A configuração exata muda de cliente para cliente e de versão para versão. Em
todos os casos você informa **a URL** `https://api.asender.net/mcp`. Clientes com
OAuth se registram sozinhos e abrem a tela de consentimento da Asender; nos demais,
informe **o header** `Authorization: Bearer sk_live_...`. Crie a chave em [Chaves de API](https://developers.asender.net/guias/chaves-de-api.html)
com só os escopos de leitura de que o agente precisa.

### Claude Code

```bash
claude mcp add --transport http asender https://api.asender.net/mcp \
  --header "Authorization: Bearer sk_live_..."
```

### Claude (claude.ai e Claude Desktop)

Em **Configurações > Conectores**, adicione um **conector personalizado**
(Custom connectors) e informe a URL `https://api.asender.net/mcp`. O cliente se
registra sozinho e você autoriza na tela de consentimento da Asender (selo
**Não verificado** até a equipe verificar o cliente). Se preferir, abra as
configurações avançadas do conector e informe o `client_id` de um
[app cadastrado](https://developers.asender.net/guias/aplicativos.html) (e o segredo, se for
um app confidencial). Esse caminho não oferece um campo para o header com a chave
`sk_*`; para usar a chave, conecte pelo Claude Code.

### ChatGPT

Ative o **modo desenvolvedor** e adicione um conector (app) MCP remoto com a URL
`https://api.asender.net/mcp`. A autenticação é por OAuth: o ChatGPT se registra
sozinho (CIMD ou DCR) e você autoriza na tela de consentimento da Asender; se a sua
versão permitir, também dá para informar o `client_id` de um app cadastrado.

### Cursor

No `mcp.json` do Cursor, declare um servidor com `url` e `headers`:

```json
{
  "mcpServers": {
    "asender": {
      "url": "https://api.asender.net/mcp",
      "headers": { "Authorization": "Bearer ${env:ASENDER_API_KEY}" }
    }
  }
}
```

### VS Code

No `mcp.json` do VS Code, declare um servidor do tipo `http`:

```json
{
  "servers": {
    "asender": {
      "type": "http",
      "url": "https://api.asender.net/mcp",
      "headers": { "Authorization": "Bearer ${input:asender-key}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "asender-key", "description": "Chave de API da Asender", "password": true }
  ]
}
```

### MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

Escolha o transporte **Streamable HTTP**, informe a URL `https://api.asender.net/mcp`
e adicione o header `Authorization: Bearer sk_live_...` (ou use o fluxo OAuth do
Inspector, que se registra sozinho). O Inspector, que roda em
`http://localhost:6274`, passa pela verificação de `Origin`.

### Qualquer outro cliente

Adicione um servidor MCP remoto HTTP (Streamable HTTP) com a URL
`https://api.asender.net/mcp` e o header `Authorization: Bearer <chave sk_*>`. O
servidor não usa SSE: um cliente que só fale SSE não conecta.

## Autenticação

O servidor é um *resource server* OAuth 2.1 e também aceita chave de API.

### Chave de API

Envie `Authorization: Bearer sk_live_...`. Valem os **escopos da chave**: a
ferramenta só aparece e só roda se a chave tem o escopo dela. Uma chave sem
escopo de leitura enxerga no máximo `asender_account_get`.

### OAuth (app)

1. **Descoberta.** Uma chamada sem credencial recebe `401` com
   `WWW-Authenticate: Bearer resource_metadata="https://api.asender.net/.well-known/oauth-protected-resource/mcp"`.
2. O cliente lê esse documento (RFC 9728), que lista em `authorization_servers`
   o servidor de autorização `https://auth.asender.net`, os `scopes_supported` e o
   link desta documentação.
3. Em `https://auth.asender.net/.well-known/oauth-authorization-server` (RFC 8414)
   estão os endpoints de autorização, de token e de revogação, além do
   `registration_endpoint` (`https://auth.asender.net/register`, DCR) e de
   `client_id_metadata_document_supported: true` (CIMD).
4. **Registro.** O cliente que ainda não tem `client_id` se registra: publica um
   documento de metadados e usa a URL dele como `client_id` (CIMD) ou faz
   `POST /register` (DCR, RFC 7591). O cliente nasce **público** (PKCE, sem
   segredo), **Não verificado** e só com escopos de leitura. Os formatos estão em
   [Aplicativos](aplicativos.html#clientes-registrados-automaticamente-mcp).
5. O cliente abre `/authorize` com **PKCE `S256`** (obrigatório) e o parâmetro
   **`resource=https://api.asender.net/mcp`** (RFC 8707). O `resource` faz o token
   nascer com `aud` do MCP. Um `resource` fora da lista permitida é recusado com
   `invalid_target`.
6. O usuário entra, **escolhe a conta** e aprova os escopos na tela de
   consentimento, que mostra o selo **Não verificado** e o domínio do cliente até a
   equipe Asender verificá-lo. **Um token vale para um usuário e uma conta.** Para
   trocar de conta, autorize de novo.
7. O cliente troca o `code` em `/token` e chama `/mcp` com o token. O token de
   acesso dura 15 minutos e é renovado com refresh token.

Clientes públicos (sem segredo, como apps de desktop) usam PKCE sem `client_secret`
e podem usar redirect de loopback (`http://127.0.0.1` ou `http://[::1]`, com porta
qualquer), conforme a RFC 8252.

### Escopos

O token OAuth só exerce **leitura**; as ferramentas de escrita (`email:send`,
`leads:write`) nunca aparecem para ele, mesmo que o token traga o escopo. Escopos disponíveis: `account:read`,
`leads:read`, `conversions:read`, `forms:read`, `analytics:read`, `campaigns:read`,
`email:read`, `messaging:read`, `conversations:read`, `journeys:read`, `logs:read`
e `openid` (identidade do usuário que autorizou). Escopo de envio nunca vale para
token OAuth. Para chave, valem os escopos da própria chave, descritos em
[Chaves de API](https://developers.asender.net/guias/chaves-de-api.html).

### Token do MCP e a API REST

Um token com `aud` **só** `https://api.asender.net/mcp` **não** vale na API REST
(`/v1`): recebe `401`. O inverso funciona: um token emitido sem `resource`, com
`aud` `https://api.asender.net`, também é aceito no `/mcp`.

## Catálogo de ferramentas

As de leitura anunciam `readOnlyHint: true`; as 3 de escrita estão em
[Ferramentas de escrita](#ferramentas-de-escrita) (`readOnlyHint: false`). **Ferramenta cujo escopo a
credencial não tem não aparece em `tools/list`**, e chamá-la diretamente devolve
erro. Além do escopo, a conta precisa ter o **produto** correspondente: sem ele a
chamada falha como a REST falharia.

| Ferramenta | O que faz | Escopo | Produto exigido | Argumentos principais |
| --- | --- | --- | --- | --- |
| `asender_account_get` | Conta a que a credencial pertence | `account:read` (OAuth); qualquer chave válida | nenhum | nenhum |
| `asender_me_get` | Quem autorizou o app, a conta e os escopos concedidos | `openid` (só token OAuth) | nenhum | nenhum |
| `asender_leads_list` | Lista leads do CRM (mais antigo atualizado primeiro) | `leads:read` | CRM | `limit`, `cursor`, `updated_after`, `created_after` |
| `asender_leads_get` | Um lead pelo id | `leads:read` | CRM | `lead_id` (obrigatório) |
| `asender_forms_list` | Lista formulários de captura | `forms:read` | Pages | `limit`, `cursor`, `updated_after`, `created_after` |
| `asender_forms_submissions_list` | Envios recebidos por um formulário | `forms:read` | Pages | `form_id` (obrigatório), `limit`, `cursor`, `updated_after`, `created_after` |
| `asender_conversions_list` | Conversões enviadas às plataformas de anúncio | `conversions:read` | CRM | `limit`, `cursor`, `updated_after`, `created_after` |
| `asender_campaigns_list` | Campanhas de e-mail marketing | `campaigns:read` | E-mail marketing | `limit`, `cursor`, `updated_after` |
| `asender_campaigns_get` | Uma campanha | `campaigns:read` | E-mail marketing | `campaign_id` (obrigatório) |
| `asender_campaigns_report` | Totais de entrega e engajamento de uma campanha | `campaigns:read` | E-mail marketing | `campaign_id` (obrigatório) |
| `asender_email_reports_overview` | Panorama de e-mail da conta nos últimos N dias | `campaigns:read` | E-mail marketing | `days` (1 a 365) |
| `asender_email_reports_timeseries` | Envios, aberturas e cliques ao longo do tempo | `campaigns:read` | E-mail marketing | `from`, `to`, `period`, `granularity` (`hour`, `day`, `week`) |
| `asender_email_reports_top_emails` | Melhores e piores e-mails da janela | `campaigns:read` | E-mail marketing | `from`, `to`, `period`, `order` (`volume`, `open_rate`, `click_rate`), `limit`, `min_delivered` |
| `asender_email_reports_domains` | Resultados por provedor de caixa postal | `campaigns:read` | E-mail marketing | `from`, `to`, `period` |
| `asender_emails_list` | E-mails transacionais enviados pela API | `email:read` | E-mail marketing | `status`, `q`, `cursor`, `limit`, `created_after` |
| `asender_emails_get` | Um e-mail enviado e seu status de entrega | `email:read` | E-mail marketing | `email_id` (obrigatório) |
| `asender_messaging_messages_list` | Mensagens de SMS, WhatsApp ou push | `messaging:read` | SMS, WhatsApp (Zapify) ou Push, conforme o canal | `channel` (obrigatório: `sms`, `whatsapp`, `push`), `limit`, `cursor`, `created_after` |
| `asender_messaging_overview` | Panorama de entrega de um canal | `messaging:read` | SMS, WhatsApp (Zapify) ou Push, conforme o canal | `channel` (obrigatório), `days` |
| `asender_analytics_overview` | Totais de analytics de site e páginas (padrão: últimos 30 dias) | `analytics:read` | Pages | `from`, `to`, `page_id`, `form_id`, `source`, `medium`, `campaign`, `country`, `device` |
| `asender_analytics_timeseries` | Série diária de analytics | `analytics:read` | Pages | os mesmos filtros de `asender_analytics_overview` |
| `asender_analytics_breakdown` | Analytics agrupado por dimensão | `analytics:read` | Pages | filtros acima, `dimension` (`page`, `source`, `medium`, `campaign`, `country`, `device`, `form`), `limit` |
| `asender_analytics_forms` | Funil de formulários (visualizações, inícios, envios) | `analytics:read` | Pages | `from`, `to`, `form_id` (omitido = resumo de todos), `limit` |
| `asender_conversations_list` | Conversas de atendimento | `conversations:read` | Atendimento | `limit`, `cursor`, `updated_after` |
| `asender_conversations_messages_list` | Linha do tempo de uma conversa | `conversations:read` | Atendimento | `conversation_id` (obrigatório), `limit`, `cursor`, `created_after` |
| `asender_journeys_list` | Jornadas de automação | `journeys:read` | CRM | `limit`, `cursor`, `updated_after`, `created_after` |
| `asender_journeys_get` | Uma jornada | `journeys:read` | CRM | `journey_id` (obrigatório) |
| `asender_logs_list` | Log de requisições da API pública da conta | `logs:read` | nenhum | `limit`, `after`, `before`, `status_class`, `status`, `method`, `path`, `api_key_id`, `error_code`, `idempotency_key`, `message_id`, `mode`, `since`, `until` |
| `asender_dns_zones_list` | Zonas de DNS da conta (**só chave**) | `dns:read` | nenhum | nenhum |
| `asender_dns_records_list` | Registros de DNS de uma zona (**só chave**) | `dns:read` | nenhum | `zone_id` (obrigatório), `type`, `name`, `page`, `per_page` |
| `asender_emails_send` | **Envia** um e-mail transacional (**só chave**; escrita) | `email:send` | E-mail marketing | `from`, `to` (obrigatórios), `subject`, `text`/`html`, `cc`, `bcc`, `reply_to`, `tags`, `idempotency_key` |
| `asender_leads_create` | **Cria** um lead (**só chave**; escrita) | `leads:write` | CRM | `email` e/ou `phone`, `first_name`, `last_name`, `job_title`, `stage`, `tags`, `custom_fields`, `idempotency_key`… |
| `asender_leads_update` | **Atualiza** um lead (**só chave**; escrita) | `leads:write` | CRM | `lead_id` (obrigatório), os campos de `asender_leads_create`, `idempotency_key` |

Datas aceitam instante RFC 3339 (por exemplo `2026-10-01T00:00:00Z`); nos
relatórios e no analytics também `YYYY-MM-DD`. `limit` vai de 1 a 200 (padrão 50).
A conta é sempre a da credencial: **não há argumento de conta**.

### Ferramentas de escrita

São três e só aparecem em `tools/list` para uma **chave `sk_*`** que tenha o escopo
(`email:send` para o e-mail, `leads:write` para os leads). Chamá-las sem o escopo, ou
com token OAuth, devolve `isError`. Cada uma roda o **mesmo handler da API REST**
(`POST /v1/emails/send`, `POST /v1/leads`, `PATCH /v1/leads/{id}`): mesmas validações,
mesmo corpo fechado (argumento desconhecido é recusado), a conta é sempre a da chave.

| Ferramenta | `destructiveHint` | `idempotentHint` | `openWorldHint` | Observação |
| --- | --- | --- | --- | --- |
| `asender_emails_send` | `false` | `true` | `true` | O e-mail vai para pessoas **reais** e não volta. O remetente (`from`) precisa ser de um domínio verificado da conta; senão `422 RemetenteNaoVerificado`. Fora de produção nada é entregue de verdade. |
| `asender_leads_create` | `false` | `true` | `false` | Precisa de `email` ou `phone`; outro lead da conta com o mesmo e-mail ou telefone dá `409`. |
| `asender_leads_update` | `true` | `true` | `false` | Só os campos enviados mudam; `tags` **substitui** a lista e `""` limpa os textos opcionais, por isso é anunciada como destrutiva. |

Todas têm `readOnlyHint: false`. As anotações são **dicas** ao cliente (por exemplo,
para pedir confirmação ao usuário), não uma garantia de segurança: quem protege é o
escopo da chave.

**Idempotência.** Toda escrita leva um `Idempotency-Key`:

- Se você passa o argumento `idempotency_key` (1 a 128 caracteres de `[A-Za-z0-9._:-]`),
  ele é a chave. Repetir a chamada com a mesma chave e os mesmos argumentos devolve o
  **mesmo resultado** sem escrever de novo; a mesma chave com argumentos diferentes é
  recusada (`422 IdempotencyKeyReused`).
- Se omite, o servidor **deriva** a chave dos argumentos (`mcp:` + hash do nome da
  ferramenta, da conta e dos argumentos, sem importar a ordem). Assim, um agente que
  **repete a mesma chamada** (timeout, retry do cliente, modelo que insiste) não envia
  dois e-mails nem cria dois leads. Para **reenviar de propósito** a mesma coisa, passe
  um `idempotency_key` diferente. A janela de deduplicação é a do dono do dado
  (24 h nos leads).

Exemplo (enviar um e-mail):

```bash
curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"asender_emails_send","arguments":{"from":"contato@exemplo.com","to":["cliente@exemplo.org"],"subject":"Seu pedido","text":"Obrigado pela compra.","idempotency_key":"pedido-1042-aviso"}}}'
```

### Formato da resposta

Uma chamada com sucesso devolve o mesmo JSON da API REST em duas formas: em
`content` (um bloco `text` com o JSON) e em `structuredContent` (o objeto). Uma
resposta acima de 1 MiB é recusada com a orientação de reduzir `limit`, usar
`cursor` ou estreitar a janela de tempo.

### Erros

- **Erro de negócio** (argumento inválido, escopo ou produto ausente, `404`, `429`,
  `5xx` da rota) não é erro JSON-RPC: volta como resultado com `isError: true` e um
  texto como `HTTP 404 Not Found: ...`, para o modelo se corrigir.
- **Erro de protocolo** usa os códigos JSON-RPC: `-32700` (JSON inválido),
  `-32600` (pedido inválido), `-32601` (método inexistente) e `-32602` (parâmetros
  inválidos ou ferramenta desconhecida).
- **Erro de transporte:** `401` sem credencial válida; `403` para `Origin` não
  permitido; `400` para `MCP-Protocol-Version` desconhecida, lote JSON-RPC ou JSON
  inválido; `413` acima de 1 MiB; `405` para `GET` e `DELETE`.

### Paginação

As listas devolvem `next_cursor` quando há mais itens. Para a próxima página,
repita a chamada passando esse valor em `cursor` (valor opaco: não o monte nem o
interprete). `asender_logs_list` pagina por `after`/`before`, com ids de log.

## Exemplos com curl

Defina a chave em uma variável de ambiente:

```bash
export ASENDER_API_KEY='sk_live_...'
```

**`initialize`**

```bash
curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```

A resposta traz `protocolVersion`, `capabilities` (`tools`), `serverInfo` e as
`instructions` do servidor. Depois do `initialize`, um cliente completo envia a
notificação `notifications/initialized` (resposta `202` sem corpo); com `curl`
isso é opcional, porque o servidor não guarda sessão.

**`tools/list`**

```bash
curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```

Só aparecem as ferramentas que a chave pode usar.

**`tools/call`**

```bash
curl -s https://api.asender.net/mcp \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"asender_leads_list","arguments":{"limit":10}}}'
```

Para a página seguinte, repita com `"arguments":{"limit":10,"cursor":"<next_cursor>"}`.

## Segurança

- **Origin.** Chamadas de navegador de um site que não seja da Asender recebem
  `403`. Clientes de servidor e de linha de comando não enviam `Origin` e passam;
  loopback (`localhost`, como o MCP Inspector) é aceito.
- **CORS.** Liberado para qualquer origem **sem credenciais**
  (`Access-Control-Allow-Origin: *`), o que deixa um cliente web ler o
  `WWW-Authenticate` do `401`. A autenticação é só pelo header `Authorization`,
  nunca por cookie.
- **Limite de taxa.** O `/mcp` tem limite de taxa; ao exceder, a ferramenta
  devolve `isError` com `HTTP 429`. Reduza a frequência das chamadas.
- **Acesso por conta.** Além do escopo, a Asender confere a cada chamada que o
  usuário do token ainda tem acesso àquela conta e àquele produto. Quem perde o
  acesso à conta perde o acesso do app em **até 60 segundos**.
- **Revogação.** O usuário revoga o acesso de um app na tela **Apps conectados**
  do login da Asender; a chave de API é revogada no painel, em Chaves de API.
- **Token só do MCP.** O `aud` do token o amarra ao recurso: um token do `/mcp`
  não funciona na REST.
- **Prompt injection.** O conteúdo que o agente lê, como nome, e-mail, mensagem
  de lead, resposta de formulário ou texto de conversa, **vem de terceiros** e deve
  ser tratado como **dado não confiável**. Um texto de lead que diga "ignore as
  instruções anteriores" não é uma ordem para o modelo. Com as ferramentas de
  **escrita** (e-mail e leads) o risco é real: um lead ou uma conversa podem tentar
  induzir o agente a enviar e-mail ou alterar dados. Por isso o token OAuth não
  escreve, a escrita exige chave com escopo próprio e, no cliente, vale exigir
  **confirmação humana** antes de `asender_emails_send` (ele anuncia
  `openWorldHint: true`).
- **Menor privilégio.** Para o agente, crie uma chave **só com os escopos de que ele
  precisa** (de preferência só leitura; `email:send` e `leads:write` apenas se o
  agente realmente escreve) e use uma chave por integração, para revogar sem
  derrubar o resto.

## Limites e o que vem a seguir

- **Escrita só com chave e só em 3 ferramentas.** Há e-mail transacional e
  criar/atualizar lead. Não há ferramenta para SMS, WhatsApp ou push, apagar lead,
  nem escrita por token OAuth (`leads:write` segue não concedível a apps).
- **Só `tools`.** O servidor não expõe `resources` nem `prompts` ainda, e não
  envia notificações (`listChanged` é falso).
- **Sem stream.** Não há SSE nem sessão (`Mcp-Session-Id`); `GET /mcp` responde
  `405`. Não há lote JSON-RPC.
- **Clientes registrados automaticamente são "Não verificados".** Recebem só
  escopos de leitura e exibem o aviso na tela de consentimento até a equipe Asender
  verificá-los; a equipe também pode suspender um cliente ou bloquear um domínio.
- **Uma conta por conexão.** Para consultar outra conta, conecte de novo
  escolhendo a outra conta (ou use outra chave).



==============================================================================
# GUIA: Aplicativos (OAuth)
==============================================================================

# Aplicativos (OAuth)

Um **aplicativo** (app) Asender é a sua integração registrada para agir **em nome
de usuários de outras contas**, com o consentimento deles. Com um app você oferece
o botão **Entrar com Asender**, lê dados pela API pública e conecta agentes de IA
pelo [servidor MCP](mcp.html), sempre com os escopos que cada usuário aprovou.

Este guia mostra como criar e manter um app no painel, o ciclo de vida até a
publicação e como clientes MCP se registram sozinhos. O fluxo OAuth em si (passo a
passo, tokens e erros) está em [Entrar com Asender](entrar-com-asender.html).

- **Servidor de autorização:** `https://auth.asender.net`
- **Painel:** `https://admin.asender.net`
- **API de recursos:** `https://api.asender.net`

## App ou chave de API?

| | **Chave de API** (`sk_live_`, `sk_test_`) | **App (OAuth)** |
| --- | --- | --- |
| Age em nome de | da **sua própria conta** | de **cada usuário que autoriza**, em outras contas |
| Quem concede | você, ao criar a chave | o usuário, na tela de consentimento |
| Escopos | os que você marca na chave | os que o usuário aprova (o app só pede o que declarou) |
| Revogação | você revoga a chave no painel | o usuário revoga o acesso do app, ou a Asender suspende o app |
| Uso típico | seu backend falando com a sua conta | produto de terceiros, integração para clientes, agentes de IA |

Se o código só acessa a **sua** conta, use [chave de API](chaves-de-api.html): é mais
simples. Crie um app quando outras pessoas precisam entrar com a conta Asender delas
no seu produto.

## Criar um app no painel

1. Entre em `https://admin.asender.net`, escolha a conta e abra
   **Desenvolvedores > Aplicativos** (`https://admin.asender.net/t/<conta>/aplicativos`).
2. Preencha **Novo aplicativo** e confirme com **Criar aplicativo**.

**Quem pode:** só quem é **owner** ou **admin** da conta enxerga e gerencia os apps
dela. Quem tem outro papel recebe a mensagem "Só owner e admin da conta gerenciam
aplicativos".

| Campo | Regra |
| --- | --- |
| **Nome** | obrigatório, até 100 caracteres |
| **Site do app** | URL `https://`; opcional para criar, **obrigatório para pedir revisão** |
| **Logo (URL)** | URL `https://`; aparece na tela de autorização (só para app verificado) |
| **Redirect URIs** | de 1 a 10; `https://` ou loopback (`http://localhost`, `http://127.0.0.1`, `http://[::1]`); sem `#` (fragmento) e sem usuário/senha na URL |
| **Tipo** | servidor com segredo ou sem segredo (PKCE); veja abaixo |
| **Escopos** | os que o app precisa; `openid` está sempre incluído |

Os escopos que a tela oferece são de identidade (`profile`, `email`,
`offline_access`) e de **leitura** (`account:read`, `leads:read`, `conversions:read`,
`forms:read`, `analytics:read`, `campaigns:read`, `email:read`, `messaging:read`,
`conversations:read`, `journeys:read`, `logs:read`). Peça só o que o app usa: a
revisão pesa isso (veja [O que a revisão confere](#o-que-a-revisão-confere)).

### Confidencial ou público

| | **Confidencial** (servidor, com segredo) | **Público** (sem segredo, PKCE) |
| --- | --- | --- |
| Para | backend seu, que guarda o segredo | SPA, app mobile ou desktop, CLI, cliente MCP local |
| Credenciais | `client_id` + `client_secret` | só `client_id` |
| Autenticação em `/token` | `client_secret_basic` (ou `client_secret_post`) | `token_endpoint_auth_method: none`; o `code_verifier` do PKCE é a prova |
| Redirect de loopback | casa exatamente, com a porta | `http://127.0.0.1`, `http://[::1]` e `http://localhost` casam **qualquer porta** (RFC 8252); esquema, host, caminho e query continuam exatos |
| Refresh token | conforme a configuração do servidor | vale até 30 dias |

**PKCE `S256` é obrigatório nos dois tipos.** Um app público que envie
`client_secret` recebe `invalid_client`. Na troca do `code`, o `redirect_uri` precisa
ser o mesmo do `/authorize`, inclusive a porta.

### O segredo aparece uma vez

Para app confidencial, o `client_secret` é mostrado **uma única vez**, logo depois
de criar (e depois de girar). A tela o mantém só até você fechá-la; a Asender não
consegue mostrá-lo de novo. Guarde-o no cofre ou nas variáveis de ambiente do
**seu backend**, nunca no navegador, em app mobile, repositório ou log.

**Girar o segredo** (botão **Girar segredo** no detalhe do app) emite um novo e
**invalida o atual na hora**: o app para de trocar tokens até receber o novo. App
público não tem segredo, então não há o que girar.

### Limites

| Limite | Valor |
| --- | --- |
| Apps por conta | 10 (acima disso: "A conta já tem 10 aplicativos") |
| Criações de app | 5 por hora, por usuário (acima disso, tente mais tarde) |
| Redirect URIs por app | 10 |
| Testadores por app | 25 |

**Excluir** um app o desativa e revoga todas as autorizações e refresh tokens.

## Ciclo de vida

Todo app nasce em **Desenvolvimento**. Enquanto não está publicado, só a equipe dele
consegue autorizá-lo; assim você integra e testa sem esperar ninguém.

| Estado | Quem consegue autorizar o app | Escopos |
| --- | --- | --- |
| **Desenvolvimento** | membros da conta dona e testadores | todos os declarados |
| **Em revisão** | membros da conta dona e testadores | todos os declarados |
| **Publicado** | qualquer usuário Asender | os **aprovados** na revisão; os declarados ainda não aprovados valem só para membros e testadores |
| **Recusado** | membros da conta dona e testadores | todos os declarados |
| **Suspenso** | ninguém; os acessos existentes são revogados | nenhum |

Quem não pode autorizar vê a tela "Este aplicativo não está disponível" e o app
recebe um erro no redirect. O motivo da recusa ou da suspensão aparece no app, no
painel.

### Testadores

Em **Testadores**, convide por **e-mail** pessoas que **já têm usuário Asender**
(sem usuário com aquele e-mail, o convite falha). O testador pode autorizar o app
mesmo em desenvolvimento, em revisão ou recusado, sem ser membro da sua conta. São
até 25 por app, e você remove quando quiser.

### Pedir revisão

Quando o app estiver pronto, **Pedir revisão** o envia à equipe Asender. Antes
disso, preencha o **site do app**: sem ele o pedido é recusado. Só se pede revisão de
app em Desenvolvimento ou Recusado, e há no máximo uma revisão pendente por app. A
equipe **aprova** (o app vira Publicado e **Verificado**, com os escopos aprovados,
que podem ser menos que os pedidos) ou **recusa**, sempre com um motivo registrado no
**Histórico de revisões** do app. Quem revisa não decide apps de uma conta da qual é
membro.

#### O que a revisão confere

Não há prazo garantido de resposta. A equipe avalia, entre outros pontos:

- **Identidade e site reais:** o site do app existe, é do responsável pelo app e
  explica o que ele faz; nome e logo não imitam outro produto nem a própria Asender.
- **Redirects no domínio do app:** as `redirect_uri` apontam para domínios que o app
  controla (loopback é aceito para apps públicos e para desenvolvimento).
- **Escopos mínimos e justificados:** cada escopo pedido tem um uso claro no app;
  o que não for necessário sai.
- **Política de privacidade:** o app informa ao usuário como trata os dados lidos da
  Asender.

### Mudar um app já publicado

- **Ampliar escopos** abre uma **nova revisão**. Até a aprovação, o escopo novo vale
  **só para membros da conta e testadores**; os demais usuários continuam com os
  escopos já aprovados.
- **Reduzir escopos** vale **na hora**.
- Trocar os redirects de um app publicado não abre revisão; mesmo assim, mantenha-os
  no seu domínio.

### Suspensão

A equipe pode **suspender** um app a qualquer momento (por exemplo, por abuso ou
denúncia). A suspensão revoga as autorizações e os refresh tokens existentes e o app
deixa de funcionar para todos até uma reativação. Uma autorização revogada na
suspensão **não volta sozinha**: o usuário autoriza de novo.

## Selo Verificado e Não verificado

Na tela de consentimento o usuário vê **o nome do app junto do domínio dele**, os
escopos em português, a conta em que o app vai operar e para onde voltará (**Após
autorizar, você volta para**).

- **Verificado pela Asender:** o app passou pela revisão (ou é da própria Asender).
  O logo remoto só aparece nesse caso.
- **Não verificado pela Asender:** aviso "A Asender não revisou este aplicativo. Só
  continue se você confia em *domínio*", com os domínios de destino em destaque. Vale
  para clientes registrados automaticamente e para qualquer app publicado que perca o
  selo. Um app não verificado só recebe escopos de **identidade e leitura**, mesmo
  que declare mais.
- **Aplicativo em desenvolvimento:** faixa "disponível só para a equipe dele e
  testadores", para apps em desenvolvimento, em revisão ou recusados.
- Clientes de IA/MCP registrados automaticamente mostram "Cliente de IA/MCP
  registrado automaticamente".

## Clientes registrados automaticamente (MCP)

Clientes MCP (Claude, ChatGPT, Cursor, VS Code, MCP Inspector e outros) não têm
alguém para criar o app no painel. Por isso o servidor de autorização aceita dois
registros automáticos, **sem cadastro prévio**:

| | **CIMD** (documento de metadados) | **DCR** (registro dinâmico) |
| --- | --- | --- |
| Padrão | *OAuth Client ID Metadata Document* | RFC 7591 |
| `client_id` | uma **URL `https`** que você hospeda | `dcr_` + 32 hex, emitido pela Asender |
| Quando | o cliente usa a URL como `client_id` no `/authorize` | o cliente faz `POST` em `/register` antes |

Os dois geram um cliente **público** (PKCE, sem segredo) que já nasce
**Publicado**, porém **Não verificado**: exibe o selo de aviso, mostra o domínio do
redirect na tela de consentimento e **só recebe escopos de identidade e leitura**.
A equipe Asender pode **verificar** um cliente, **suspendê-lo** ou **bloquear um
domínio** (o bloqueio suspende os clientes registrados automaticamente naquele
domínio e recusa novos). CIMD e DCR podem estar desligados em um ambiente; os
metadados do servidor só anunciam o que está ligado.

### Descoberta

```bash
curl -s https://auth.asender.net/.well-known/oauth-authorization-server
```

O documento (RFC 8414) traz, quando o recurso está ligado:

- `registration_endpoint`: `https://auth.asender.net/register` (DCR);
- `client_id_metadata_document_supported`: `true` (CIMD);
- `token_endpoint_auth_methods_supported`: `client_secret_basic`, `client_secret_post` e `none`;
- `code_challenge_methods_supported`: `S256`.

### CIMD: a URL é o `client_id`

Publique um documento JSON em uma URL **`https`** estável (por exemplo
`https://app.exemplo.com/oauth/client.json`) e use essa URL como `client_id`:

```json
{
  "client_id": "https://app.exemplo.com/oauth/client.json",
  "client_name": "Meu agente",
  "client_uri": "https://app.exemplo.com",
  "logo_uri": "https://app.exemplo.com/logo.png",
  "redirect_uris": ["http://127.0.0.1/callback", "https://app.exemplo.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "openid profile email leads:read"
}
```

O que a Asender exige da URL e do documento:

- **URL:** `https`, porta 443, com caminho (não só `/`), sem usuário, sem fragmento
  (`#`), sem `.` ou `..` no caminho, host com nome DNS (não IP) e até 2048 caracteres.
- **Resposta:** status `200`, `Content-Type: application/json`, até 64 KiB, sem
  redirect, em até 5 segundos. A Asender não acessa endereços de rede interna.
- **`client_id` do documento igual à URL**, caractere a caractere.
- **Sem `client_secret`** (nem `client_secret_expires_at`) no documento.
- **`token_endpoint_auth_method`** ausente ou `none`; `grant_types` dentro de
  `authorization_code` e `refresh_token`; `response_types` só `code`.
- **`redirect_uris`:** de 1 a 10, `https` ou loopback, sem fragmento. Loopback casa
  qualquer porta.
- **`client_uri` e `logo_uri`:** `https`, se presentes. `client_name` perde
  caracteres de controle e é cortado em 100 caracteres.
- **`scope`:** o que passar de identidade e leitura é ignorado; omitido, vale todo o
  conjunto permitido a clientes não verificados.

**Cache.** A Asender guarda o documento conforme o `Cache-Control: max-age` da
resposta, limitado entre **5 minutos e 24 horas** (sem cabeçalho, 24 horas;
`no-store` e `no-cache` valem 5 minutos). Se uma nova busca falhar por problema de
rede, a cópia de até 7 dias é usada; um documento que ficou inválido nunca é
aproveitado do cache. Se o documento não puder ser buscado ou validado, o
`/authorize` responde `invalid_client`.

### DCR: `POST /register`

```bash
curl -s https://auth.asender.net/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Meu agente",
    "redirect_uris": ["http://127.0.0.1/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "openid profile email leads:read"
  }'
```

Resposta `201 Created`:

```json
{
  "client_id": "dcr_0123456789abcdef0123456789abcdef",
  "client_id_issued_at": 1792454400,
  "client_name": "Meu agente",
  "redirect_uris": ["http://127.0.0.1/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "openid profile email leads:read"
}
```

Campos aceitos no pedido: `client_name`, `client_uri`, `logo_uri`, `redirect_uris`
(obrigatório), `grant_types`, `response_types`, `token_endpoint_auth_method` (só
`none`) e `scope`. As regras são as mesmas do CIMD; campos desconhecidos são
ignorados. Sem `client_name`, o nome vira o domínio do primeiro redirect. O corpo é
JSON, com `Content-Type: application/json`, até 64 KiB.

- **Sem `client_secret`:** o cliente é sempre público e usa PKCE.
- **Sem RFC 7592:** a resposta não traz `registration_access_token` nem
  `registration_client_uri`; não há como ler, alterar ou apagar o registro depois. Se
  precisar mudar algo, registre outro cliente.
- **Limite:** 10 registros por hora por IP; acima disso, `429` com `Retry-After`.

Erros seguem a RFC 7591, no formato `{"error", "error_description"}`:

| Status | `error` | Quando |
| --- | --- | --- |
| `400` | `invalid_redirect_uri` | `redirect_uris` ausente, com mais de 10, fora de `https`/loopback, com fragmento ou credencial, ou de domínio bloqueado |
| `400` | `invalid_client_metadata` | `Content-Type` diferente de JSON, corpo ilegível ou grande demais, `token_endpoint_auth_method` diferente de `none`, `grant_types`/`response_types` não suportados, `client_uri`/`logo_uri` que não são `https` |
| `429` | `too_many_requests` | limite por hora atingido |
| `404` | `not_found` | registro dinâmico desligado neste ambiente |

## O parâmetro `resource` (RFC 8707)

O `resource` diz **para qual API** o token vale e define o `aud` do token. Os
valores aceitos são:

- `https://api.asender.net`: a API REST pública;
- `https://api.asender.net/mcp`: o [servidor MCP](mcp.html).

Envie-o no `/authorize` (o parâmetro pode se repetir). Qualquer outro valor é
recusado com **`invalid_target`**: no `/authorize`, como `error=invalid_target` no
redirect; no `/token`, como `400` com `{"error":"invalid_target"}`. No `/token` e no
refresh você pode repetir `resource` com um subconjunto do que foi autorizado, para
estreitar o `aud` do token; pedir algo que não foi autorizado também dá
`invalid_target`. Sem `resource`, o token vale para `https://api.asender.net`.

Um token só do MCP não vale na API REST; veja o
[guia MCP](mcp.html#token-do-mcp-e-a-api-rest).

## Próximos passos

- O fluxo completo, com exemplo de código e tratamento de erros:
  [Entrar com Asender](entrar-com-asender.html).
- Conectar um agente de IA: [Servidor MCP](mcp.html).
- Chave de API para a sua própria conta: [Chaves de API](chaves-de-api.html).



==============================================================================
# GUIA: Alias de e-mail
==============================================================================

# Alias de e-mail: vários endereços, uma caixa

Um **alias** é um endereço extra (`vendas@empresa.com.br`) que entrega na caixa de outra pessoa
(`ana@empresa.com.br`). Quem escreve para o alias recebe resposta normal; você lê tudo numa caixa só e a mensagem
mostra "recebido como vendas@…".

## Como funciona

- O alias aponta para **uma caixa real** (nunca para outro alias).
- O alias pode estar em **outro domínio** seu, desde que seja da mesma conta.
- Ordem no recebimento: caixa com aquele endereço, depois alias, depois catch-all, depois criação automática.
- Se o alias e a caixa-destino estiverem entre os destinatários da mesma mensagem, ela chega **uma vez só**.
- Não dá para criar alias num endereço que já é de uma caixa (inclusive de uma caixa que você removeu: restaure-a
  ou escolha outro), de outro alias, ou identidade de envio de outra caixa.
- Caixa de atendimento (com assinatura ativa) ainda não recebe alias.
- Para remover uma caixa que tem alias, apague os alias antes (a API responde 409 com o vínculo `alias`).
- Cada caixa pode ter até 50 alias (o limite pode ser ajustado para a sua conta).

## Responder como o alias

Ao criar, envie `"responder_como": true` para poder escolher o alias no campo "De". Isso só vale se o domínio do
alias tem o DKIM publicado e é da mesma conta da caixa; caso contrário o alias é criado normalmente, sem a opção de
envio, e a resposta explica o motivo (`dominio_sem_dkim`, `org_diferente`).

## No painel (admin.asender)

- **Domínios**: em cada domínio que recebe, a seção "Alias de recebimento" lista, cria, apaga e (em "Ver apagados")
  restaura alias, e mostra o limite por caixa. A caixa-destino pode ser de outro domínio da conta.
- **Caixas**: sob cada caixa, "Alias de recebimento" mostra os alias que entregam nela e permite apagá-los.
- **Endereço apagado**: ainda em Domínios, "Mensagem para endereço apagado" escolhe entre reter na quarentena (padrão)
  e recusar com 550. Ao criar uma caixa num endereço que já foi de uma caixa apagada, o painel pede para restaurar a
  caixa antiga ou recriar uma nova informando o motivo (fica na auditoria).

## API (administrador do e-mail ou chave com `mail:admin`)

```
POST   /domains/{id}/aliases        {"local_part":"vendas","mailbox_id":"<uuid>","responder_como":false}
GET    /domains/{id}/aliases        [?apagados=1]
GET    /mailboxes/{id}/aliases
DELETE /aliases/{id}                {"motivo":"opcional"}      (apaga sem perder o histórico)
POST   /aliases/{id}/restaurar
```

Erros: `409` AliasColideCaixa / AliasRepetido / AliasColideIdentidade / AliasLimite; `422` AliasDeAlias /
DestinoIndisponivel / CaixaAssinada; `429` criação rápida demais (aguarde 1 minuto). Detalhes: `openapi.yaml` do
`asender_mail_api` e ADR-0142.

Observação para a documentação publicada: este guia ainda não está listado em `guias.json` (registrar quando a tela
de alias for ao ar).



==============================================================================
# GUIA: Convenções da API
==============================================================================

# Convenções da API

O contrato comum das APIs públicas da Asender: autenticação, formato de requisição e
resposta, erros, paginação, idempotência, limites e versionamento. Cada ferramenta
tem a API dela, num endereço próprio:

| API | endereço |
| --- | --- |
| Plataforma (envio e leitura de dados por API key) | `https://api.asender.net` |
| E-mail | `https://api.mail.asender.net` |
| CRM | `https://api.crm.asender.net` |
| Páginas | `https://api.pages.asender.net` |
| Identidade (OIDC / OAuth 2.1) | `https://auth.asender.net` |

> **As APIs não falam todas o mesmo dialeto.** O que é igual em todas (HTTPS, JSON,
> `Authorization: Bearer`, cursor em vez de offset) está abaixo. O que difere (caixa
> das chaves, envelope de erro, forma da paginação) está dito **por superfície** —
> não reaproveite o parser de uma API em outra. Para escolher o meio de integração,
> comece pelo [mapa de integrações](integracoes.html).

---

## 1. Princípios

1. **JSON em tudo.** Corpo de requisição e de resposta são JSON (`Content-Type: application/json`).
2. **Contrato estrito.** Campo que a API não conhece é recusado com `400`, não ignorado em silêncio.
3. **A conta vem da credencial.** O `tenant` é sempre resolvido da API key ou do token, nunca de um campo do corpo.
4. **Cursor, nunca offset.** Listagens longas paginam por cursor opaco.
5. **Escrita idempotente onde há efeito.** Envio aceita `Idempotency-Key`.
6. **Versão no caminho.** Todas as rotas públicas começam em `/v1`.
7. **Rastreável.** Toda resposta traz `X-Request-Id`; cite-o ao abrir suporte.

---

## 2. Autenticação

### Cabeçalho

```
Authorization: Bearer <credencial>
```

É a única forma aceita. `?api_key=` e `X-Api-Key` não existem (respondem `401`).

### Credenciais

| Credencial | Formato | Para quê |
| --- | --- | --- |
| API key de servidor | `sk_live_` + 48 hex (produção), `sk_test_` + 48 hex (teste) | Integração de máquina, de servidor para servidor. Cada chave tem **escopos** (`email:send`, `leads:read`…); rota fora do escopo responde `403`. |
| Token de aplicativo OAuth | JWT (três segmentos) emitido por `auth.asender.net` | App de terceiro que lê dados da conta com o consentimento do usuário (somente leitura). Ver [Entrar com Asender](entrar-com-asender.html). |
| Chave pública de Web Push | `pk_push_…` | **Só** para registrar a inscrição de Web Push do navegador do visitante, em `POST /v1/push/site/devices`. Não é segredo e não vale em nenhuma outra rota. |
| Sessão OIDC | Bearer do usuário logado | O painel. Não é para integração de máquina. |

Não existe "chave publicável" genérica de leitura: **a API key de servidor nunca
vai para o navegador**. Para o que roda no site do visitante, use as chaves e o
embed próprios — ver [No navegador](navegador.html).

---

## 3. Formato de requisição

### Cabeçalhos em `POST`/`PUT`/`PATCH`

```
Content-Type: application/json
```

### Caixa dos campos (muda por API)

| API | campos |
| --- | --- |
| Plataforma — envio (`/v1/emails/*`, `/v1/sms/send`, `/v1/push/send`…) | `PascalCase`, no estilo do Amazon SES (`Source`, `Destination.ToAddresses`, `Message.Subject.Data`) |
| Plataforma — leitura de dados (`/v1/leads`, `/v1/campaigns`, `/v1/analytics/*`…) | `snake_case` (`next_cursor`, `updated_after`) |
| E-mail | minúsculas (`from`, `to`, `subject`, `text`, `html`) |
| CRM e Páginas | `snake_case` / português (`contatos`, `proximo`, `paginas`) |

Exemplo (Plataforma): `POST https://api.asender.net/v1/emails/send`

```json
{
  "Source": "noreply@example.com",
  "Destination": { "ToAddresses": ["user@example.com"] },
  "Message": {
    "Subject": { "Data": "Olá", "Charset": "UTF-8" },
    "Body": { "Text": { "Data": "Oi!" } }
  }
}
```

### Idempotência

Os `POST` de envio da Plataforma (`/v1/emails/send`, `/v1/emails/batch`,
`/v1/sms/send`, `/v1/push/send`) aceitam o cabeçalho (tem precedência):

```
Idempotency-Key: uuid-ou-qualquer-texto      # 1 a 128 caracteres de [A-Za-z0-9._:-]
```

ou o campo `IdempotencyKey` no corpo.

- **Mesma chave e mesmo corpo** → `202` com o `MessageId` da mensagem original e
  `"ReusedIdempotency": true`. Nada é enfileirado nem cobrado de novo.
- **Mesma chave e corpo diferente** → `409` com `Code: "IdempotencyConflict"`. O corpo novo não é enviado.
- **Chave malformada** → `422` `ValidationError`. Nunca é ignorada em silêncio.
- **Lote** (`/v1/emails/batch`): a chave do cabeçalho é da requisição e vira uma chave por item
  (`<chave>:<índice>`); repetir o lote deduplica item a item.

Nas outras APIs a idempotência é própria: a Mail API devolve `200` com
`"idempotent_replay": true`; o envio de lead em Páginas aceita `Idempotency-Key` (ou
`id_externo`) e devolve `Idempotent-Replayed: true`. Está no guia de cada uma.

---

## 4. Formato de resposta

### Sucesso na Plataforma (envio)

```json
{
  "MessageId": "msg_xxx",
  "Status": "queued",
  "RequestId": "req_xxx"
}
```

O envio é assíncrono: `202 Accepted` significa "aceito e enfileirado", não "entregue".

### Códigos HTTP

| Código | Uso |
| --- | --- |
| 200 | Sucesso em leitura e atualização |
| 201 | Recurso criado |
| 202 | Envio aceito (enfileirado) |
| 400 | Validação falhou (corpo malformado, campo desconhecido, parâmetro inválido) |
| 401 | Credencial ausente ou inválida |
| 403 | Sem permissão, ou chave sem o escopo da rota |
| 404 | Recurso não encontrado (inclui recurso de outra conta) |
| 405 | Método HTTP errado |
| 409 | Conflito (por exemplo `IdempotencyConflict`) |
| 422 | Regra de negócio (remetente de domínio não verificado, `Idempotency-Key` malformada) |
| 429 | Limite de taxa ou de cota excedido |
| 5xx | Falha do serviço ou de uma dependência (`503` pode trazer `Retry-After`) |

### Paginação

Listagens longas paginam por **cursor opaco** — passe de volta o valor que recebeu,
sem decodificar nem montar. Offset não existe. A forma varia por superfície:

| Superfície | pedido | resposta |
| --- | --- | --- |
| Plataforma — dados (`/v1/leads`, `/v1/forms/{id}/submissions`, `/v1/conversions`, `/v1/campaigns`, `/v1/messaging/*`, `/v1/conversations`…) | `?limit=` (1–200, padrão 50), `?cursor=`, `?updated_after=`, `?created_after=` (RFC 3339) | `{ "data": [...], "next_cursor": "…" \| null }` — `null` quando acabou |
| Plataforma — histórico de e-mail (`GET /v1/emails`) | `?limit=`, `?cursor=`, `?status=`, `?q=` | `{ "Messages": [...], "NextCursor": "…", "HasMore": true, "RequestId": "…" }` |
| Plataforma — log de requisições (`GET /v1/logs`) | `?limit=` (1–100), `?after=`, `?before=` | `has_more` e `next` em `snake_case` (ver o guia da Plataforma) |
| E-mail (mensagens de uma caixa) | `?limit=`, `?cursor=` | `{ "messages": [...], "next_cursor": "…" }` |
| CRM (contatos, timeline) | `?limite=`, `?cursor=` | `{ "contatos": [...], "proximo": "…" }` — vazio quando acabou |
| Páginas | `?limite=` em algumas coleções | lista sob chave nomeada (`{"paginas":[…]}`); analytics por janela `?de=&ate=` — **sem cursor** |

Para sincronizar de forma incremental, prefira `updated_after` (nas rotas de dados da
Plataforma) a reler tudo.

```
GET /v1/leads?limit=100&cursor=eyJ…

{ "data": [ { "id": "ctt_…", "email": "…" } ], "next_cursor": "eyJ…" }
```

### Cabeçalhos de resposta

Presentes na Plataforma (`api.asender.net`):

```
X-Request-Id: req_xxx
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
Cache-Control: no-store
```

Nas rotas sujeitas a limite de taxa (ver [Limites](#8-limites)):

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1681234567     # instante (epoch, segundos) em que a janela reabre
Retry-After: 1                    # só em 429 (e em alguns 503): segundos para tentar de novo
```

---

## 5. Erros

### Dois envelopes de erro

Cada superfície tem o seu envelope. **Leia o `Content-Type` e o código HTTP primeiro**
e escolha o parser pela API que respondeu:

| Superfície | envelope |
| --- | --- |
| Plataforma — envio e histórico (`/v1/emails*`, `/v1/sms/send`, `/v1/push/*`…) | `{ "Error": { "Type", "Code", "Message", "Details" }, "RequestId" }` |
| Plataforma — leitura de dados (`/v1/leads`, `/v1/campaigns`, `/v1/analytics/*`, `/v1/me`…) | `{ "error": { "type", "message" } }` |
| E-mail (`api.mail.asender.net`) | `{ "error": "<Código>", "message": "<texto>" }` |
| CRM (`api.crm.asender.net`) | `{ "erro": "<mensagem>" }` |
| Páginas — autoria (`api.pages.asender.net`) | `{ "erro": "<mensagem>" }` |
| Páginas — coleta pública e runtime | `{ "error": { "message": "<texto>" } }` |
| Identidade — `/token` e `/userinfo` | `{ "error": "<código OAuth>", "error_description": "<texto>" }` (RFC 6749); no `/authorize` o erro volta por redirecionamento, em `?error=` |

Os envelopes coexistem de propósito: unificar seria uma mudança incompatível. Um
cliente que fala com mais de uma API precisa de um parser para cada. Na Plataforma,
`404` e `405` em `/v1/*` também usam o envelope SES-like (`Code` `NotFound` /
`MethodNotAllowed`), com uma dica quando o caminho é de outra API.

### Estrutura do envelope SES-like (Plataforma — envio)

```json
{
  "Error": {
    "Type": "Sender",
    "Code": "ValidationError",
    "Message": "Messages must contain at least one entry.",
    "Details": { "Destination.ToAddresses": "must contain at least one address" }
  },
  "RequestId": "req_xxx"
}
```

- `Type`: `Sender` (4xx, o cliente errou) ou `Receiver` (5xx, o serviço falhou).
- `Code`: classe estável (`ValidationError`, `AuthorizationError`, `InsufficientScope`,
  `NotFound`, `IdempotencyConflict`, `Throttling`, `InternalError`…). Novos códigos podem
  ser acrescentados; o significado de um existente não muda.
- `Message`: texto para humanos.
- `Details`: opcional, contexto legível por máquina (em validação, o campo e o motivo).

Os códigos de cada API estão na página dela; aqui só o que é comum.

### Quem repete e quem não repete

Repita (com espera) em `429` (respeite `Retry-After`) e em `502`/`503`. **Não** repita
`400`, `401`, `403`, `404` nem `422`: são determinísticos, repetir só repete o erro.

---

## 6. Webhooks

A Asender **emite** webhooks (eventos de entrega da conta, leads do CRM, submissões de
formulário e entregas do conector de Integrações) e **recebe** webhooks de provedores (por
exemplo, o status de SMS). Todo webhook que a Asender emite usa o formato único
**Asender Webhook v1** (ADR-0133): os cabeçalhos `Asender-Webhook-Id` (estável entre
tentativas, a chave de deduplicação), `Asender-Event` e
`Asender-Signature: t=<unix>,v1=<hex>`, onde `v1` é o HMAC-SHA256 do segredo sobre
`"<t>.<corpo cru>"`, com tolerância de 300 s e possibilidade de vários `v1=` durante a
rotação do segredo. Os cabeçalhos de assinatura anteriores de cada emissor são
**descontinuados** e saem em **2027-04-20** (`Sunset`). Os endpoints de eventos da conta
são gerenciados pela API pública em `/v1/webhooks` (escopo `webhooks:manage`, só chave).
O formato, um verificador por linguagem (Node, Python, Go, PHP), as tentativas de cada
emissor e a migração estão no guia de [webhooks](webhooks.html).

Regras que valem para qualquer webhook que você receber:

- verifique a assinatura sobre o **corpo cru**, em tempo constante, antes de confiar no conteúdo;
- responda rápido com `2xx` e processe depois;
- trate a entrega como **pelo menos uma vez**: deduplique pelo id do evento.

---

## 7. CORS e navegador

A API de servidor (`sk_…`) é **de servidor para servidor**; não a chame do navegador
(isso exigiria expor a chave). O que roda no navegador do visitante usa chaves e rotas
próprias, com origem autorizada: o registro de Web Push (`POST /v1/push/site/devices`
com `pk_push_…`) e a coleta de formulários e analytics de Páginas. Veja
[No navegador](navegador.html).

---

## 8. Limites

### Limite de taxa (Plataforma)

- **Por credencial**: cada API key tem o seu balde; cada par **app OAuth × conta** também
  (um app barulhento numa conta não consome a cota do mesmo app em outra). O padrão é de
  **100 requisições por segundo**, ajustável pela Asender.
- **Rotas de login e de recuperação** têm teto próprio **por IP** (proteção contra
  força bruta).
- Estourou: `429`, `Code: "Throttling"`, com `Retry-After` e os `X-RateLimit-*`. O limitador
  é controle de abuso; se ele estiver indisponível, a API segue atendendo.

### Cota do plano (E-mail)

A Mail API barra o envio ao atingir o teto do plano com `429` `QuotaExceeded` e os
cabeçalhos `X-Quota-*` (qual janela barrou, quando reabre, `Retry-After`).

### Outros tetos

Cada API declara os seus (por exemplo, Páginas limita o envio de lead por chave por
minuto e o tamanho do corpo). Estão no guia da API.

---

## 9. Versionamento

O número da versão vai no caminho (`/v1`). Mudança **incompatível** cria uma nova versão
maior; mudança compatível (campo novo opcional, valor novo de enum, rota nova) **não**
muda a versão — escreva o cliente para ignorar o que não conhece, nos campos de
**resposta**. (Nos campos de **requisição** vale o contrário: o corpo é estrito.)

Quando algo for ser descontinuado, a Asender avisa pelo registro de mudanças do guia
da API e dá prazo antes de remover. Um cabeçalho `Sunset` por resposta ainda **não** é
emitido (planejado).

---

## 10. Lote de e-mails

`POST https://api.asender.net/v1/emails/batch` envia até **500** e-mails independentes
numa chamada. Escopo `email:send`.

```json
{
  "Messages": [
    { "Source": "noreply@example.com",
      "Destination": { "ToAddresses": ["a@example.com"] },
      "Message": { "Subject": { "Data": "Olá A" }, "Body": { "Text": { "Data": "Oi A" } } } },
    { "Source": "noreply@example.com",
      "Destination": { "ToAddresses": ["b@example.com"] },
      "Message": { "Subject": { "Data": "Olá B" }, "Body": { "Text": { "Data": "Oi B" } } } }
  ]
}
```

Cada item tem o mesmo formato de `POST /v1/emails/send`. Resposta, `202`:

```json
{
  "Results": [
    { "Index": 0, "Status": "queued", "MessageId": "msg_xxx", "MessageIds": ["msg_xxx"], "ReusedIdempotency": false },
    { "Index": 1, "Status": "rejected", "Error": { "Code": "ValidationError", "Details": { "Destination.ToAddresses": "…" } } }
  ],
  "Count": 2,
  "RequestId": "req_xxx"
}
```

- `Status` por item: `queued`, `rejected` (a validação recusou) ou `failed` (não deu para
  enfileirar). Falha de um item **não** derruba os outros: o lote devolve `202` mesmo com
  falha parcial. **Inspecione `Results[].Status`.**
- `Messages` vazio ou com mais de 500 itens → `400` `ValidationError`.
- Use `Idempotency-Key` para poder repetir o lote com segurança (ver seção 3).

---

## 11. Filtros

As listagens aceitam filtros por query string, e cada rota documenta os seus. O que é
comum nas rotas de dados da Plataforma: `limit`, `cursor`, `updated_after`,
`created_after` (datas em RFC 3339, por exemplo `2026-10-19T12:00:00Z`). Valor inválido
é `400` (`InvalidParameter`), nunca "corrigido" em silêncio.

---

## 12. Segurança

- **HTTPS obrigatório.** Nenhuma credencial trafega em HTTP.
- **Guarde as chaves no servidor** (variável de ambiente ou cofre). Nunca em bundle de
  navegador, app móvel, repositório ou log.
- **Escopo mínimo.** Crie uma chave por integração, só com os escopos que ela usa;
  revogue a que vazou — [chaves de API](chaves-de-api.html).
- A credencial identifica a **conta**: não existe parâmetro para escolher outra.
- Respostas da Plataforma não são cacheáveis (`Cache-Control: no-store`).

---

## 13. SDKs

Hoje o contrato é a [OpenAPI unificada](../openapi.json) e as páginas de cada API; não
há SDK oficial de servidor. Se você escrever um cliente, ele deve:

- ler a chave de variável de ambiente;
- repetir com recuo exponencial em `429`/`5xx` (honrando `Retry-After`) e **não** repetir `4xx`;
- usar `Idempotency-Key` em todo envio;
- não decodificar o cursor.

No navegador existe o `@asender/pages-sdk`, para formulários e leads de Páginas — ver
[No navegador](navegador.html).



==============================================================================
# CRM  (https://api.crm.asender.net)
==============================================================================

# CRM API

A API do **CRM** Asender: o contato canônico da pessoa (com estágio, dono,
origem, consentimento e timeline), os **segmentos** que recortam a base, as
**jornadas** de automação, os **alertas** de captura, os **destinos** de lead
(webhooks e integrações de conversão) e as configurações de retenção e uso. É um
sistema à parte, com endereço próprio — o CRM fora do ar é o CRM fora do ar, e
não arrasta as outras ferramentas.

- **Base URL:** `https://api.crm.asender.net`
- **Autenticação:** sessão do usuário (`Authorization: Bearer <token>` ou o
  cookie `asender_session`) + o header `X-Asender-Tenant`
- **Formato:** JSON (`application/json; charset=utf-8`)

> Esta é a API que o **painel** do CRM consome. Diferente da Mail e da Platform,
> ela **não** aceita API key: é uma superfície de **sessão**, pensada para o
> usuário logado operando a própria conta. Integração máquina-a-máquina com dado
> de CRM ainda não tem superfície pública.

## Autenticação

Toda rota de `/v1` (fora das probes de saúde) exige uma **sessão válida**. O
token de sessão é emitido pelo [Identity Server](https://auth.asender.net) (OIDC
/ OAuth 2.1 + PKCE) e chega de duas formas equivalentes:

```
Authorization: Bearer <token-de-sessão>
```

ou, no navegador, pelo cookie `asender_session` que o painel já mantém. O serviço
valida o token no `asender_auth_api` a cada requisição — token ausente, inválido
ou de sessão sem usuário responde **401**; se o serviço de identidade estiver
fora do ar, a resposta é **503** (a distinção importa: 401 manda refazer login,
503 manda olhar o auth).

### A conta em que você opera — `X-Asender-Tenant`

Um usuário pode pertencer a mais de uma conta. O header `X-Asender-Tenant` diz em
**qual** conta a requisição opera; ele aceita o **id** ou o **slug** da conta:

```
X-Asender-Tenant: acme-corp
```

O header é uma **preferência**, não uma autorização: o que impede operar em conta
alheia é a checagem de **pertinência** contra a lista de contas que a sessão
prova serem suas. Um tenant fora dessa lista responde **404** (não 403 — um 403
confirmaria que a conta existe, e é assim que se enumeram contas alheias). Sem o
header, a requisição cai na **primeira** conta da sessão.

### Acesso à ferramenta

Ter sessão não basta: a conta precisa ter o **produto CRM** habilitado. Quem não
tem acesso à ferramenta recebe **404** em todas as rotas de `/v1` — o mesmo 404
de recurso inexistente, de propósito (um 403 contaria a quem não tem acesso que a
ferramenta existe; isso se descobre pelo site, não pela API).

## Erros

Toda falha usa o mesmo envelope — **um campo só**, `erro`, com a mensagem
legível:

```json
{ "erro": "contato não encontrado" }
```

A mensagem descreve o que está errado no **pedido**, nunca o estado interno: um
erro nunca vaza schema, nome de tabela ou mensagem de driver (isso vai para o log
do servidor, com `trace_id`).

| código HTTP | quando |
| --- | --- |
| 400 | corpo malformado, campo desconhecido (contrato estrito), query string inválida, cursor adulterado |
| 401 | sessão ausente ou inválida (`sem tenant na sessão` quando o tenant não chegou ao contexto) |
| 404 | recurso não encontrado, de outra conta, ou sem acesso à ferramenta (não revela existência alheia) |
| 409 | conflito de unicidade (contato com e-mail repetido, segmento com nome em uso) |
| 422 | corpo bem formado mas conteúdo inválido pela regra de negócio (estágio desconhecido, jornada com buraco na numeração, `recebe` ausente no consentimento) |
| 500 | falha interna (mensagem genérica; o erro real vai para o log) |
| 503 | serviço de identidade fora, ou dependência opcional desligada (ex.: exportação sem trilha) |

O corpo de escrita é lido com **contrato estrito**: campo desconhecido é **400**,
não é ignorado em silêncio — é o que barra *mass assignment* (um `tenant_id` no
corpo vira erro explícito, não uma conta escolhida pelo cliente). O limite de
corpo é 256 KiB.

## Paginação

As coleções longas — **contatos** e a **timeline** de um contato — paginam por
**cursor opaco**, nunca por offset:

```
GET /v1/contatos?limite=50
→ { "contatos": [...], "proximo": "eyJ…" }

GET /v1/contatos?limite=50&cursor=eyJ…
```

Passe `proximo` de volta como `cursor`. Vazio significa que acabou. Um cursor
adulterado responde **400**. O cursor é cifrado de propósito: o id interno é uma
sequência global, e devolvê-lo cru entregaria o volume e a ordem da base. As
demais coleções (segmentos, alertas, destinos, jornadas) são curtas e voltam
inteiras.

## Convenções que valem para todos os recursos

- **O `tenant` nunca vem do corpo nem da URL** — vem da sessão. O mesmo vale para
  o **autor** de uma nota ou exportação: é quem a sessão provou ser, não um campo
  do pedido. É o que mantém a trilha de auditoria confiável.
- **404 é o "não é seu"** — contato, segmento, jornada, destino ou alerta de
  outra conta respondem o mesmo 404 de um id que nunca existiu.
- **Datas** saem em UTC, formato `YYYY-MM-DDTHH:MM:SSZ`.

---

## Jornadas — `/v1/jornadas`

A automação: **gatilho + passos**. O contato entra pelo gatilho e caminha pelos
passos (esperar, agir, condição), um de cada vez e **na ordem**.

Uma jornada **nasce sempre desligada** (`ativa: false`): criar e ativar são
operações separadas porque ativar tem consequência no mundo — assim que liga, o
próximo lead capturado entra nela e recebe mensagem, e não há desfazer para
e-mail enviado.

### `GET /v1/jornadas` — listar

```bash
curl 'https://api.crm.asender.net/v1/jornadas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'X-Asender-Tenant: acme-corp'
```

`200` → `{ "jornadas": [ Jornada, … ] }`.

### `POST /v1/jornadas` — criar (sempre inativa)

Corpo: `nome` (obrigatório), `gatilho` e `passos`. Os passos são numerados de 1
em diante, **sem buraco**. Gatilhos: `lead_capturado`, `campo_mudou`,
`inatividade`, `evento_pixel`. Tipos de passo: `esperar` (exige `espera` > 0),
`agir` (exige `acao` conhecida: `email`, `push`, `webhook`, `mudar_estagio`,
`entrar_lista`), `condicao` (exige `se_pular_ir` para um passo existente).

```bash
curl -X POST 'https://api.crm.asender.net/v1/jornadas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'X-Asender-Tenant: acme-corp' \
  -H 'Content-Type: application/json' \
  -d '{
    "nome": "Boas-vindas",
    "gatilho": { "tipo": "lead_capturado" },
    "passos": [
      { "numero": 1, "tipo": "agir", "acao": "email", "parametros": { "template": "welcome" } },
      { "numero": 2, "tipo": "esperar", "espera": 86400000000000 },
      { "numero": 3, "tipo": "agir", "acao": "email", "parametros": { "template": "dica" } }
    ]
  }'
```

`201` → a `Jornada` criada. `422` se o nome faltar ou a validação não fechar
(numeração com buraco, ação desconhecida, salto inválido).

> `espera` é uma duração em **nanossegundos** (o `time.Duration` do Go); 1 dia =
> `86400000000000`.

### `GET /v1/jornadas/{id}` — obter

`200` → a `Jornada`; `404` se não existe ou é de outra conta.

### `PUT /v1/jornadas/{id}/ativa` — ligar/desligar

Corpo: `{ "ativa": true }`. **Ligar revalida** a jornada (ela pode ter sido
editada depois de criada); desligar não revalida — uma jornada quebrada tem de
poder ser parada. `200` → a `Jornada`; `422` ao tentar ligar uma jornada
inválida.

---

## Contatos — `/v1/contatos`

O contato canônico. O **e-mail e o telefone são PII cifrada** no banco e só
aparecem decifrados na leitura de quem é dono da conta; nunca saem os índices
cegos (HMAC de dedup), sob risco de enumeração.

### `GET /v1/contatos` — listar (paginado)

Query: `estagio` (allowlist: `novo`, `contatado`, `qualificado`, `cliente`,
`descartado`), `limite`, `cursor`. Um `estagio` desconhecido é **400** (o
silêncio mentiria: quem filtra por um plural e recebe a base inteira acha que não
há ninguém).

```bash
curl 'https://api.crm.asender.net/v1/contatos?estagio=qualificado&limite=50' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'X-Asender-Tenant: acme-corp'
```

`200` → `{ "contatos": [ Contato, … ], "proximo": "eyJ…" }`.

### `POST /v1/contatos` — criar

Corpo: `email`, `telefone`, `nome`, `estagio`, `dono_id`, `marcadores`. Ao menos
um de e-mail/telefone. Nasce em `novo` se o estágio não vier. `201` → o `Contato`;
`409` se já existe contato com aquele identificador; `422` se a validação falha.

### `GET /v1/contatos/{id}` — obter

`200` → o `Contato`; `404` se não é seu.

### `PATCH /v1/contatos/{id}` — atualizar (parcial)

Campo **ausente preserva** o que havia; `marcadores: []` remove todos (a lista
vazia é intencional). `200` → o `Contato`.

### `DELETE /v1/contatos/{id}` — apagar o contato (soft delete)

Corpo opcional `{ "motivo": "..." }`. **Apagar é reversível** (ADR-0112): o contato ganha
`apagado_em/por/motivo` e some das listagens, relatórios e jornadas, mas **nada é
destruído** — o painel master restaura. Registra `contato_apagado` na timeline. `204` sem
corpo; `404` cobre "não existe", "de outra conta" e "já apagado". Só existe quando o serviço
tem a trilha ligada; senão, **503**.

### `/v1/pedidos-exclusao` — o pedido do titular (LGPD art. 18)

A plataforma **nunca apaga dado do contratante por conta própria**. O pedido do titular vira
uma *task* que um **administrador da conta** aprova ou recusa:

- `POST /v1/pedidos-exclusao` `{contato_id, solicitante, canal, motivo?}` — qualquer membro
  registra; `201` com o pedido `pendente`. **Não apaga nada.** Avisa os admins pela central
  de notificações. `409` se já há pedido pendente para o contato.
- `GET /v1/pedidos-exclusao?status=&cursor=&limite=` — a fila (só admin; quem não é recebe `404`).
- `POST /v1/pedidos-exclusao/{id}/aprovar` — só admin (decidido no servidor pelo PDP): **anonimiza
  aquele contato** irreversivelmente, na mesma transação que a timeline e a auditoria; `200` com o
  pedido `executado`.
- `POST /v1/pedidos-exclusao/{id}/recusar` `{motivo}` — só admin; motivo obrigatório (`422`);
  nada é apagado. `409` se o pedido já foi decidido.

### `GET /v1/contatos/exportar.csv` — exportar

Query opcional `limite` (teto de 10.000). Devolve um **CSV** (não JSON) com
`Content-Disposition: attachment`, e **registra a exportação** na timeline antes
de o arquivo sair (LGPD art. 37 — sem trilha, não exporta). `503` se a trilha não
estiver disponível.

```bash
curl 'https://api.crm.asender.net/v1/contatos/exportar.csv' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'X-Asender-Tenant: acme-corp' -o contatos.csv
```

---

## Timeline — `/v1/contatos/{id}/atividades`

A trilha de auditoria do contato: mudanças de estágio, mensagens, submissões e
**notas** manuais. Mora sob o contato de propósito — não há rota de topo que
despejaria o histórico da conta inteira.

### `GET /v1/contatos/{id}/atividades` — listar (paginado)

Query: `limite`, `cursor`. `200` →
`{ "atividades": [ Atividade, … ], "proximo": "eyJ…", "total": 42 }`.
`404` se o contato não é seu.

### `POST /v1/contatos/{id}/atividades` — anexar nota

Corpo: `{ "texto": "..." }` (até 4000 caracteres). **Só nota**: os outros tipos
são consequência do que o sistema fez, e deixar o cliente escrevê-los permitiria
forjar a trilha. O autor vem da sessão, não do corpo. `201` → a `Atividade`;
`422` se o texto é vazio ou longo demais.

---

## Consentimento — `/v1/contatos/{id}/consentimento`

A preferência da pessoa, **canal a canal** (`email`, `push`).

### `GET /v1/contatos/{id}/consentimento`

`200` → `{ "recebe": { "email": true, "push": false }, "fuso": "America/Sao_Paulo" }`.
Responde **todos** os canais conhecidos, inclusive os sem opt-out. O campo é
`recebe` (positivo) e não `opt_out` — uma negação no nome faria toda leitura
exigir uma inversão mental que alguém erra, e o erro liga o envio para quem pediu
para sair.

### `PUT /v1/contatos/{id}/consentimento`

Corpo: `{ "canal": "email", "recebe": false, "origem": "painel" }`. **Um canal
por vez**, e `recebe` é obrigatório — sua ausência é **422** (com `bool` comum,
"esqueci o campo" seria indistinguível de "descadastra esta pessoa"). `200` → o
estado relido do banco.

---

## Segmentos — `/v1/segmentos`

Conjuntos salvos de **critérios** que recortam a base. Cada critério é
`campo` + `operador` + `valor`; os critérios se combinam por `conjuncao` (`e` /
`ou`, padrão `e`).

- **Campos** (allowlist): `estagio`, `dono`, `nome`, `origem_source`,
  `origem_medium`, `origem_campanha`, `origem_dominio`, `origem_form`,
  `origem_modo`, `criado_em`, `atualizado_em`, `marcador`, `consentimento`.
- **Operadores**: `igual`, `diferente`, `contem`, `comeca_com`, `existe`,
  `nao_existe`, `maior_que`, `menor_que`, `tem_marcador`, `nao_tem_marcador`.

### `GET /v1/segmentos` — listar

`200` → `{ "segmentos": [ Segmento, … ] }`.

### `POST /v1/segmentos` — criar

```bash
curl -X POST 'https://api.crm.asender.net/v1/segmentos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'X-Asender-Tenant: acme-corp' \
  -H 'Content-Type: application/json' \
  -d '{
    "nome": "Qualificados de SP",
    "conjuncao": "e",
    "criterios": [
      { "campo": "estagio", "operador": "igual", "valor": "qualificado" },
      { "campo": "origem_dominio", "operador": "contem", "valor": "sp" }
    ]
  }'
```

`201` → `{ "segmento": Segmento, "alcance": 128 }`. `409` se o nome já existe;
`422` se um campo/operador está fora da allowlist ou não há critério.

### `POST /v1/segmentos/previa` — alcance sem salvar

Mesmo corpo do criar; **não grava nada**, só responde quantas pessoas o segmento
alcança agora. `200` → `{ "alcance": 128 }`.

### `GET /v1/segmentos/{id}` — obter (com alcance)

`200` → `{ "segmento": Segmento, "alcance": 128 }`. O alcance vem junto porque é
a única razão de abrir um segmento; `alcance: -1` significa "não consegui contar"
(distinto de 0, que é "não alcança ninguém").

### `PUT /v1/segmentos/{id}` — substituir

PUT e não PATCH: um segmento **é** a sua lista de critérios, e mesclar listas não
tem significado. `200` → `{ "segmento", "alcance" }`; `409`/`404`/`422` como no
criar.

### `DELETE /v1/segmentos/{id}` — remover

Remoção lógica. `204` sem corpo.

---

## Alertas — `/v1/alertas`

Avisam quando a **captura para** ou a **qualidade cai**. Tipos: `sem_leads`,
`queda_qualidade`. Estado: `calmo` / `disparado`.

### `GET /v1/alertas` — listar

`200` → `{ "alertas": [ Alerta, … ] }`.

### `POST /v1/alertas` — criar

Corpo: `nome`, `tipo`, `limiar`, `janela_minutos`, `destino_id` (opcional),
`ativo` (opcional). `201` → o `Alerta`; `422` se a regra não valida (janela curta
demais, limiar fora de faixa).

### `GET /v1/alertas/eventos` — histórico de transições

Query opcional `limite`. `200` → `{ "eventos": [ AlertaEvento, … ] }`. Da
**conta**, não de um alerta: quem investiga "o que aconteceu ontem" quer a linha
do tempo inteira.

### `PUT /v1/alertas/{id}` — atualizar

Mudar a configuração **acalma** o alerta (ele passa a observar outra coisa).
`200` → o `Alerta`; `404` se não é seu.

### `DELETE /v1/alertas/{id}` — remover

`204` sem corpo.

---

## Destinos de lead — `/v1/destinos`

Para onde o lead capturado é entregue: **webhooks** do cliente. O **segredo** de
assinatura nunca volta na resposta — só o booleano `tem_segredo`.

### `GET /v1/destinos` — listar

`200` → `{ "destinos": [ Destino, … ] }`.

### `POST /v1/destinos` — criar

Corpo: `nome`, `url` (http/https; a rede interna é recusada com 422), `segredo`
(opcional), `ativo`. `201` → o `Destino`.

### `PUT /v1/destinos/{id}` — atualizar

`segredo` ausente **preserva** o gravado (a tela nunca recebe o valor atual, e
apagá-lo a cada edição de nome derrubaria a assinatura). `200` → o `Destino`.

### `DELETE /v1/destinos/{id}` — remover

`204` sem corpo.

### `GET /v1/destinos/{id}/entregas` — diagnóstico

Query opcional `limite`. `200` → `{ "entregas": [ Entrega, … ] }`. O **payload**
não volta (carrega PII) — só estado, código e tentativas.

### `POST /v1/destinos/{id}/testar` — entrega de teste

Enfileira uma entrega de teste pela **mesma fila** das reais (mesmo guard do piso
18, mesma assinatura). `202` → `{ "enfileiradas": 1, "aviso": "…" }`; `404` se o
destino está inativo ou não existe. Acompanhe o resultado em `/entregas`.

---

## Integrações de conversão — `/v1/integracoes-de-conversao`

O **mesmo conjunto de rotas** dos destinos, para o outro assunto: mandar a
conversão de volta à plataforma de anúncio. Esta rota do CRM aceita **só o
provedor `meta`** (Conversions API). São um grupo separado porque, numa lista só,
quem procura uma acharia as duas — e a integração de conversão **não tem URL
própria** (o endereço da API é do provedor e é fixo; deixar o cliente escolhê-lo
permitiria vazar o token de acesso para qualquer lugar). O corpo pede `provedor`
(`meta`), `config` (com `pixel_id`) e o token de acesso em `segredo`; `provedor`
diferente de `meta` responde `422`.

> **Google Ads e TikTok.** Não passam por esta rota. As conversões para **Meta,
> Google Ads e TikTok** são instalações do catálogo de **Integrações** (no painel de
> administração), usadas como destino de formulário de Páginas e pela ação de
> jornada **`enviar_conversao`** (parâmetros `instalacao_id`, `evento`, `valor`,
> `moeda`), que aceita instalações dos apps `meta_capi`, `google_ads` e
> `tiktok_events`. O desfecho aparece na linha do tempo do lead e em
> `GET /v1/conversions` da API pública. Veja
> [Conversões e conectores](https://developers.asender.net/guias/conversoes-e-conectores.html).

- `GET /v1/integracoes-de-conversao` → `{ "integracoes": [ Destino, … ] }`
- `POST /v1/integracoes-de-conversao` → `201` `Destino`
- `PUT /v1/integracoes-de-conversao/{id}` → `200` `Destino`
- `DELETE /v1/integracoes-de-conversao/{id}` → `204`
- `GET /v1/integracoes-de-conversao/{id}/entregas` → `{ "entregas": [ … ] }`
- `POST /v1/integracoes-de-conversao/{id}/testar` → `202`

---

## Configurações da conta

### `GET /v1/configuracoes/retencao` — política de retenção

`200` → `{ "retencao": { "dias": 90, "anonimizados_total": 12, … } }`. Conta sem
política responde `dias: null` (o estado normal), não 404.

### `PUT /v1/configuracoes/retencao` — definir

Corpo: `{ "dias": 90 }` ou `{ "dias": null }` (guardar indefinidamente). O campo
**ausente é 400** (não desliga por engano); `null` é a ordem explícita de manter
para sempre. `422` se o prazo sai da faixa de 30 a 3650 dias.

### `GET /v1/uso` — consumo da conta

Query opcional `periodo=YYYY-MM` (padrão: mês corrente). `200` →
`{ "uso": UsoView }`. Os números **locais** (quantos contatos, quantos entraram
no mês) sempre voltam; a **quota** e os contadores de envio vivem no core, e com
ele fora a resposta sai com `core_disponivel: false` e `quota_conhecida: false`
(nunca "ilimitado" — a tela mostra o que sabe e diz o que não conseguiu saber).

---

> **Superfície interna (não pública).** O CRM também expõe um canal interno de
> control plane e uma **sessão de suporte** (somente leitura), reservados aos
> serviços da casa. Nada disso é
> superfície de integração e não está documentado aqui — a superfície pública é a
> **sessão do usuário**.


### GET /dados/conversoes
página de conversões em ordem `(registrado_em, id)`, depois de `cursor` ou de `created_after` (exclusivo).
Onde é usada: BFF, `GET /v1/conversions`.
Saídas: 200 `{data, next_cursor}`; 400 parâmetro inválido; 401 sem credencial.

curl -X GET 'https://api.crm.asender.net/dados/conversoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /dados/jornadas
GET /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma leitura.

curl -X GET 'https://api.crm.asender.net/dados/jornadas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /dados/jornadas/{id}
GET /v1/clientes/{id}. Outra conta = 404, como inexistente.

curl -X GET 'https://api.crm.asender.net/dados/jornadas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /dados/leads
página de leads em ordem `(atualizado_em, id)`, depois de `cursor` ou de `updated_after` (exclusivo). Contatos apagados/anonimizados não aparecem.
Onde é usada: BFF, `GET /v1/leads`.
Saídas: 200 `{data, next_cursor}`; 400 parâmetro inválido; 401 sem credencial.

curl -X GET 'https://api.crm.asender.net/dados/leads' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /dados/leads
cria o lead da conta do principal (origem "api").
Onde é usada: BFF, `POST /v1/leads`.
Saídas: 201 lead público; 400 corpo inválido; 409 já existe (e-mail/telefone) ou chave em andamento; 413 corpo grande; 422 validação ou chave reusada; 401 sem credencial.

curl -X POST 'https://api.crm.asender.net/dados/leads' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /dados/leads/{id}
um lead pelo id público. 404 para id inexistente OU de outra conta — o mesmo 404, para não confirmar a existência a quem sonda ids.
Onde é usada: BFF, `GET /v1/leads/{id}`.

curl -X GET 'https://api.crm.asender.net/dados/leads/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /dados/leads/{id}
altera só os campos presentes do lead.
Onde é usada: BFF, `PATCH /v1/leads/{id}`.
Saídas: 200 lead público; 404 inexistente OU de outra conta (o mesmo 404); demais como CriarLead.

curl -X PATCH 'https://api.crm.asender.net/dados/leads/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/alertas
Lista os alertas da conta.
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 os alertas.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/alertas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/alertas
Cria um alerta.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 o alerta criado.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/alertas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/alertas/{id}
Atualiza a configuração de um alerta (acalma-o).
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o alerta atualizado.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/alertas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/alertas/{id}
Remove um alerta.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 removido.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X DELETE 'https://api.crm.asender.net/v1/alertas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/alertas/eventos
Lista o histórico de transições dos alertas da conta.
Onde é usada: tela de alertas — a linha do tempo.
Efeitos: uma leitura. Da CONTA, e não de um alerta: quem investiga "o que aconteceu ontem" quer a linha do tempo inteira, e paginar por alerta a obrigaria a abrir um por um.
Parâmetros: X-Asender-Tenant (header); limite (query)
Respostas: 200 os eventos.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/alertas/eventos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/campos
Catálogo de campos nativos de contato e empresa.
Onde é usada: tela de contatos (colunas e filtros), editor de contato e integrações.
Efeitos: nenhum — o catálogo é estático, embutido no binário.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 o catálogo.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/campos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/clientes
GET /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma leitura.

curl -X GET 'https://api.crm.asender.net/v1/clientes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/clientes
POST /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma escrita.

curl -X POST 'https://api.crm.asender.net/v1/clientes' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/clientes/{id}
GET /v1/clientes/{id}. Outra conta = 404, como inexistente.

curl -X GET 'https://api.crm.asender.net/v1/clientes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/clientes/{id}
PUT /v1/alertas/{id}.
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.

curl -X PATCH 'https://api.crm.asender.net/v1/clientes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/clientes/{id}
DELETE /v1/alertas/{id}.
Onde é usada: tela de alertas.
Efeitos: uma escrita.

curl -X DELETE 'https://api.crm.asender.net/v1/clientes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/configuracoes/retencao
Lê a política de retenção da conta.
Onde é usada: tela de configurações da conta.
Efeitos: uma leitura. Conta sem política configurada responde 200 com `dias: null` — e não 404: "não configurei retenção" é o estado NORMAL, e a tela precisa dele para desenhar o formulário vazio.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 a política.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/configuracoes/retencao' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/configuracoes/retencao
Define a política de retenção.
Onde é usada: tela de configurações da conta.
Efeitos: uma escrita; passa a anonimizar contato antigo em até uma hora. # `null` desliga, ausente é erro Os dois cairiam no mesmo ponteiro nil se o corpo fosse decodificado direto — e um cliente que esquecesse o campo desligaria a retenção sem querer. `null` é uma ORDEM ("guarde para sempre"); campo ausente é um pedido malformado.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 a política salva.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/configuracoes/retencao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/contatos
Lista uma página de contatos da conta.
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header); estagio (query); q (query); pais (query); estado (query); cidade (query); empresa_id (query); cargo (query); marcador (query); dono_id (query); fonte (query); utm_source (query); dispositivo (query); so (query); navegador (query); ip_pais (query); email_status (query); genero (query); nivel_hierarquico (query); origem_canal (query); landing_page (query); criado_de (query); criado_ate (query); limite (query); cursor (query)
Respostas: 200 a página de contatos e o cursor seguinte.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/contatos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/contatos
Cria um contato; cifra a PII antes de gravar.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 o contato criado.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 409 já existe contato com aquele identificador.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/contatos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/contatos/{id}
Lê um contato da conta.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o contato.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/contatos/{id}
Atualiza um contato (parcial — campo ausente preserva).
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o contato atualizado.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PATCH 'https://api.crm.asender.net/v1/contatos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/contatos/{id}
Apaga um contato (soft delete, reversível pelo painel master).
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 apagado (soft delete).; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 503 apagamento indisponível neste serviço.

curl -X DELETE 'https://api.crm.asender.net/v1/contatos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/contatos/{id}/atividades
Lista a timeline de um contato (paginada).
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); limite (query); cursor (query)
Respostas: 200 a página de atividades, o cursor seguinte e o total.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI/atividades' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/contatos/{id}/atividades
Anexa uma nota à timeline do contato.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 201 a nota criada.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/contatos/id_AQUI/atividades' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/contatos/{id}/consentimento
Lê a preferência do contato, canal a canal.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o que o contato recebe por canal.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI/consentimento' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/contatos/{id}/consentimento
Muda a preferência de um canal (um por vez).
Onde é usada: tela de contato, e o link de descadastro via BFF.
Efeitos: cria ou remove a linha de opt-out. # `recebe` é ponteiro, e a ausência é ERRO Com um `bool` comum, um corpo sem o campo viria como `false` — e "esqueci de mandar o campo" seria indistinguível de "descadastra esta pessoa". O ponteiro transforma a omissão em 422 explícito.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o estado relido do banco.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/contatos/id_AQUI/consentimento' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/contatos/{id}/conversas
Lista as conversas do atendimento ligadas a este contato.
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); limite (query)
Respostas: 200 as conversas, mais recente primeiro.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI/conversas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/contatos/{id}/identidades
Lista as identidades ativas do contato (valor SEMPRE mascarado).
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 as identidades, da mais antiga para a mais nova.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI/identidades' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/contatos/{id}/identidades
Liga uma identidade a um contato que já existe (fonte `manual`).
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 já estava ligada a este contato.; 201 identidade ligada agora.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 o endereço já pertence a outro contato desta conta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/contatos/id_AQUI/identidades' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/contatos/{id}/identidades/{identidade_id}/desvincular
Desvincula (soft) uma identidade do contato.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); identidade_id (path, obrigatório)
Respostas: 204 desvinculada.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/contatos/id_AQUI/identidades/identidade_id_AQUI/desvincular' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/contatos/{id}/promover
POST /v1/contatos/{id}/promover (D1, 028/029). Sem corpo — a ação é binária, e um corpo que aceitasse `promovido_em`/`promovido_por` do cliente deixaria a data e o autor da promoção sob controle de quem chama a API.
Onde é usada: botão "Promover a contato" nas telas Leads e Contatos.
Efeitos: escreve a coluna, a timeline (`ciclo_mudou`) e o outbox (`crm.contact.promoted`), atômico (repo.ContatoPG.MudarCiclo). Promover quem já é contato responde 200 sem gerar nova atividade nem novo evento (idempotente) — não é erro repetir o clique.

curl -X POST 'https://api.crm.asender.net/v1/contatos/id_AQUI/promover' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/contatos/{id}/rebaixar
POST /v1/contatos/{id}/rebaixar — reverte uma promoção feita por engano.
Onde é usada: ação "Rebaixar a lead" na ficha do contato.
Efeitos: escreve a coluna e a timeline (`ciclo_mudou`); NÃO publica evento — só a promoção é fato que jornadas/relatórios querem (doc-comment de `eventos.SubjectContatoPromovido`).

curl -X POST 'https://api.crm.asender.net/v1/contatos/id_AQUI/rebaixar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/contatos/{id}/visita-pages
GET /v1/clientes/{id}. Outra conta = 404, como inexistente.

curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI/visita-pages' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/contatos/exportar.csv
Exporta os contatos da conta em CSV (registra a exportação na timeline).
Onde é usada: botão "exportar" da lista de contatos.
Efeitos: uma leitura; decifra a PII; registra a exportação na timeline. # A PII é decifrada AQUI, e só para quem é dono O tenant vem da sessão verificada e a RLS já filtra a consulta. Este handler nunca vê contato de outra conta, e a decifragem acontece com a chave do processo — não há caminho em que o CSV carregue dado alheio. # Cada exportação vira uma ATIVIDADE, e isso não é opcional A LGPD (art. 37) exige registro das operações de tratamento, e exportar é tratamento: a partir dali o dado existe num arquivo que ninguém controla. Sem esse registro, "quem baixou a base e quando" não tem resposta — e é a primeira pergunta de todo incidente de vazamento. O registro é gravado ANTES do arquivo sair. Se a gravação falhar, a exportação não acontece: um download sem trilha é exatamente o que a trilha existe para impedir, e "o arquivo já foi" não se desfaz.
Parâmetros: X-Asender-Tenant (header); limite (query)
Respostas: 200 o CSV dos contatos.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 503 exportação indisponível (trilha desligada neste serviço).

curl -X GET 'https://api.crm.asender.net/v1/contatos/exportar.csv' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/destinos
Lista os destinos (webhooks) da conta.
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 os destinos.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/destinos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/destinos
Cria um destino (webhook); cifra o segredo antes.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 o destino criado.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/destinos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/destinos/{id}
Atualiza um destino; segredo ausente preserva o gravado.
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o destino atualizado.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/destinos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/destinos/{id}
Remove um destino.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 removido.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X DELETE 'https://api.crm.asender.net/v1/destinos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/destinos/{id}/entregas
Lista as tentativas de entrega de um destino (sem o payload).
Onde é usada: diagnóstico da tela de integrações.
Efeitos: uma leitura. O PAYLOAD não volta: ele carrega a PII do contato, e quem pergunta "por que não chegou" precisa do estado e do código — não do dado da pessoa repetido numa segunda tela.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); limite (query)
Respostas: 200 as entregas.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/destinos/id_AQUI/entregas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/destinos/{id}/testar
Enfileira uma entrega de teste pela mesma fila das reais.
Onde é usada: botão "testar" da tela de integrações.
Efeitos: cria uma entrega pendente. # ENFILEIRA, e não entrega na hora A entrega passa pelo MESMO dreno das entregas de verdade — e portanto pelo mesmo guard do piso 18, pela mesma guarda de rede e pela mesma assinatura. Um caminho de teste que chamasse o webhook direto seria um segundo caminho de saída, e o segundo caminho é sempre o que esquece uma guarda. O operador vê o resultado em `GET /entregas`, que é a mesma tela onde ele vê as entregas reais — então "o teste funcionou" e "a integração funciona" são a mesma leitura, e não duas afirmações que podem divergir.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 202 teste enfileirado; acompanhe em /entregas.; 401 sessão ausente ou inválida.; 404 destino não encontrado ou inativo.

curl -X POST 'https://api.crm.asender.net/v1/destinos/id_AQUI/testar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/empresas
Lista as empresas da conta (também serve o seletor flutuante).
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header); q (query); setor (query); porte (query); pais (query); tipo_empresa (query); regime_tributario (query); segmento (query); cnae (query); estado (query); cidade (query); ano_de (query); ano_ate (query); qtd_min (query); qtd_max (query); limite (query); cursor (query)
Respostas: 200 a página de empresas.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/empresas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/empresas
Cria uma empresa.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 a empresa criada.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 409 CNPJ (ou nome sem CNPJ) já em uso na conta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/empresas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/empresas/{id}
Lê uma empresa da conta (outra conta = 404).
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 a empresa.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/empresas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/empresas/{id}
Altera uma empresa (parcial).
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 a empresa alterada.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 CNPJ (ou nome sem CNPJ) já em uso na conta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PATCH 'https://api.crm.asender.net/v1/empresas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/empresas/{id}
Remove a empresa (lógico) e solta os contatos dela — os contatos ficam.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 removida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X DELETE 'https://api.crm.asender.net/v1/empresas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/empresas/{id}/contatos
Contatos da empresa — mesma listagem e filtros de /v1/contatos.
Onde é usada: ficha da empresa.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); limite (query); cursor (query)
Respostas: 200 a página de contatos da empresa.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/empresas/id_AQUI/contatos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/empresas/{id}/pessoas
GET /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma leitura.

curl -X GET 'https://api.crm.asender.net/v1/empresas/id_AQUI/pessoas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/empresas/{id}/pessoas
POST /v1/empresas/{id}/pessoas {contato_id, papel}. Sempre entra como vínculo SECUNDÁRIO — tornar principal é a rota dedicada, que passa pela coluna `contatos.empresa_id` (a fonte da verdade, migration 031).

curl -X POST 'https://api.crm.asender.net/v1/empresas/id_AQUI/pessoas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/empresas/{id}/pessoas/{contato_id}
DELETE /v1/empresas/{id}/pessoas/{contato_id} → 204. Era o vínculo PRINCIPAL: `contatos.empresa_id` desta pessoa também é zerado (o repo cuida disso na mesma transação — nunca duas fontes divergentes).

curl -X DELETE 'https://api.crm.asender.net/v1/empresas/id_AQUI/pessoas/contato_id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/empresas/{id}/pessoas/{contato_id}/principal
PUT /v1/empresas/{id}/pessoas/{contato_id}/principal. A antiga principal (se houver, mesmo de outra empresa) vira secundária — nunca some.

curl -X PUT 'https://api.crm.asender.net/v1/empresas/id_AQUI/pessoas/contato_id_AQUI/principal' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/identidades/resolver
Traduz uma identidade (e-mail, telefone…) no contato que a tem.
Onde é usada: item 1 do plano — "API para resolver identidade → contato". Uso previsto: a inbox do atendimento (frente C, front do CRM) perguntando "esta pessoa já é alguém?" antes de abrir uma ficha nova à mão.
Efeitos: uma leitura. O VALOR nunca é ecoado de volta, e a resposta nunca inclui PII — só `achou`/`contato_id`. Quem quiser o e-mail/telefone pede `GET /v1/contatos/{id}` depois, pela rota que já decifra sob autorização.
Parâmetros: X-Asender-Tenant (header); canal (query, obrigatório); valor (query, obrigatório)
Respostas: 200 achou (e o contato), ou achou:false.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.; 503 resolução de identidade indisponível (cifrador não configurado).

curl -X GET 'https://api.crm.asender.net/v1/identidades/resolver' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/identidades/sugestoes
GET /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma leitura.

curl -X GET 'https://api.crm.asender.net/v1/identidades/sugestoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/identidades/sugestoes/{id}/decisao
PUT /v1/identidades/sugestoes/{id}/decisao
Onde é usada: tela do atendente, nos botões "é a mesma pessoa" / "não é".
Efeitos: uma escrita. # ACEITAR NÃO FUNDE NADA Esta rota grava que um humano concordou que os dois contatos são a mesma pessoa. As duas fichas continuam existindo, separadas, com e-mail, telefone, timeline, consentimento e dono intactos. Fundir automaticamente é decisão do dono e está PARQUEADA (ADR-0061) — e é por isso que a resposta desta rota devolve a sugestão decidida, e não um contato.

curl -X PUT 'https://api.crm.asender.net/v1/identidades/sugestoes/id_AQUI/decisao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/importacoes
GET /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma leitura.

curl -X GET 'https://api.crm.asender.net/v1/importacoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/importacoes
POST /v1/importacoes (multipart: campo "arquivo" + campo "config" com o JSON de `pedidoIniciar`) — o MESMO arquivo da prévia, reenviado.
Onde é usada: botão "confirmar importação" da tela de mapeamento.
Efeitos: uma escrita (o lote, status `pendente`); o processamento em si acontece depois, em segundo plano — a resposta não espera por ele.

curl -X POST 'https://api.crm.asender.net/v1/importacoes' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/importacoes/{id}
GET /v1/clientes/{id}. Outra conta = 404, como inexistente.

curl -X GET 'https://api.crm.asender.net/v1/importacoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/importacoes/{id}/desfazer
POST /v1/importacoes/{id}/desfazer.
Onde é usada: botão "desfazer importação" do relatório final.
Efeitos: anonimiza os contatos que o lote criou (ver o doc-comment de `Servico.Desfazer` para o porquê de não tocar os que ele só atualizou).

curl -X POST 'https://api.crm.asender.net/v1/importacoes/id_AQUI/desfazer' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/importacoes/{id}/erros.csv
GET /v1/importacoes/{id}/erros.csv.
Efeitos: uma leitura. # Mesma neutralização de fórmula da exportação de contatos O MOTIVO de um erro pode ecoar um valor da própria linha ("e-mail inválido: =cmd|'/c calc'!A1"): se um CSV hostil chegou como upload, o relatório de erro NÃO pode virar o vetor de saída da mesma injeção — por isso reaproveita `exportacao.Escritor`, o mesmo pacote que já neutraliza a exportação de contatos.

curl -X GET 'https://api.crm.asender.net/v1/importacoes/id_AQUI/erros.csv' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/importacoes/campos
GET /v1/campos → `{versao, grupos, campos}` do contrato `asender_docs/contratos/campos-contato.json`.
Onde é usada: tela de contatos (colunas e filtros), editor de contato e integrações.
Efeitos: nenhum — o catálogo é estático, embutido no binário.

curl -X GET 'https://api.crm.asender.net/v1/importacoes/campos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/importacoes/previa
POST /v1/importacoes/previa (multipart, campo "arquivo").
Onde é usada: primeiro passo da tela de importação, assim que a pessoa solta o CSV.
Efeitos: nenhum — nada é persistido aqui (ver o doc-comment de `Servico.Prevalidar` para o porquê de o mesmo arquivo ser reenviado no passo de confirmação).

curl -X POST 'https://api.crm.asender.net/v1/importacoes/previa' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/integracoes-de-conversao
Lista as integrações de conversão da conta.
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 as integrações.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/integracoes-de-conversao' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/integracoes-de-conversao
Cria uma integração de conversão (provedor meta; sem URL própria).
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 a integração criada.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/integracoes-de-conversao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/integracoes-de-conversao/{id}
Atualiza uma integração de conversão.
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 a integração atualizada.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/integracoes-de-conversao/{id}
Remove uma integração de conversão.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 removida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X DELETE 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/integracoes-de-conversao/{id}/entregas
Lista as tentativas de entrega de uma integração (sem o payload).
Onde é usada: diagnóstico da tela de integrações.
Efeitos: uma leitura. O PAYLOAD não volta: ele carrega a PII do contato, e quem pergunta "por que não chegou" precisa do estado e do código — não do dado da pessoa repetido numa segunda tela.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); limite (query)
Respostas: 200 as entregas.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI/entregas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/integracoes-de-conversao/{id}/testar
Enfileira uma entrega de teste da integração pela mesma fila das reais.
Onde é usada: botão "testar" da tela de integrações.
Efeitos: cria uma entrega pendente. # ENFILEIRA, e não entrega na hora A entrega passa pelo MESMO dreno das entregas de verdade — e portanto pelo mesmo guard do piso 18, pela mesma guarda de rede e pela mesma assinatura. Um caminho de teste que chamasse o webhook direto seria um segundo caminho de saída, e o segundo caminho é sempre o que esquece uma guarda. O operador vê o resultado em `GET /entregas`, que é a mesma tela onde ele vê as entregas reais — então "o teste funcionou" e "a integração funciona" são a mesma leitura, e não duas afirmações que podem divergir.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 202 teste enfileirado; acompanhe em /entregas.; 401 sessão ausente ou inválida.; 404 integração não encontrada ou inativa.

curl -X POST 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI/testar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/jornadas
Lista as jornadas da conta (ativas e inativas).
Onde é usada: painel, tela de jornadas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 as jornadas da conta.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/jornadas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/jornadas
Cria uma jornada — sempre INATIVA.
Onde é usada: painel, botão "criar jornada".
Efeitos: cria a linha. # Nasce desligada, sem exceção Criar e ativar são operações separadas porque ativar tem consequência no mundo: assim que a jornada liga, o próximo lead capturado entra nela e recebe mensagem. Um POST que já criasse ativa transformaria um erro de digitação numa campanha disparando — e não existe desfazer para e-mail enviado.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 a jornada criada (com `avisos`, se algo não pôde ser conferido).; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/jornadas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/jornadas/{id}
Lê uma jornada da conta.
Onde é usada: painel, tela de edição.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 a jornada.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/jornadas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/jornadas/{id}
Reescreve o desenho de uma jornada DESLIGADA.
Onde é usada: botão "salvar" da tela de edição visual.
Efeitos: reescreve a jornada. NÃO liga: a jornada continua desligada, e ativar tem rota própria que revalida. # Por que a jornada tem de estar DESLIGADA para ser editada Uma inscrição em andamento guarda o número do passo em que está. Trocar os passos por baixo dela faria o contato retomar num passo que virou outra coisa — a oferta no lugar da espera, ou um salto para um número que não existe mais. Editar exige desligar antes; religar revalida. O 409 diz isso ao operador em vez de deixá-lo salvar por cima de uma campanha correndo.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 a jornada atualizada (com `avisos`, se algo não pôde ser conferido).; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 a jornada está ativa; desligue-a antes de editar.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/jornadas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/jornadas/{id}/ativa
Liga ou desliga a jornada.
Onde é usada: painel, interruptor da jornada.
Efeitos: muda o estado; ligada, a jornada passa a inscrever contatos. # Revalida ANTES de ligar A jornada foi validada na criação, mas pode ter sido editada depois — e uma jornada com buraco na numeração deixaria o contato preso no meio do caminho, sem erro em lugar nenhum. Validar de novo aqui custa nada e é o último ponto antes de a coisa começar a mandar mensagem. Desligar NÃO revalida: uma jornada quebrada tem de poder ser desligada, e exigir que ela esteja válida para parar seria prender o operador justamente no caso em que ele mais precisa do botão.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 a jornada com o novo estado (com `avisos`, se algo não pôde ser conferido).; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/jornadas/id_AQUI/ativa' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/jornadas/catalogo
Catálogo de gatilhos e ações do construtor visual.
Onde é usada: tela do construtor visual.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 o catálogo.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/jornadas/catalogo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/lixeira
Lista o que a conta apagou (lixeira do usuário).
Saídas: 200 `{itens, cursor}`; 401 sem tenant; 422 tipo/cursor inválido.
Efeitos: só leitura.
Parâmetros: X-Asender-Tenant (header); tipo (query); cursor (query)
Respostas: 200 os itens apagados, do mais recente ao mais antigo.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X GET 'https://api.crm.asender.net/v1/lixeira' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/lixeira/{tipo}/{id}/restaurar
Restaura um item apagado.
Saídas: 204; 401; 404 (não apagado, outra conta ou tipo fora da allowlist); 409 `{"motivo": conflito_unicidade|pai_apagado, "pai"?}`.
Efeitos: um UPDATE carimbando `restaurado_em/por` e um log de auditoria.
Parâmetros: X-Asender-Tenant (header); tipo (path, obrigatório); id (path, obrigatório)
Respostas: 204 restaurado.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 não dá para restaurar agora.

curl -X POST 'https://api.crm.asender.net/v1/lixeira/tipo_AQUI/id_AQUI/restaurar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/painel
GET /v1/clientes/{id}. Outra conta = 404, como inexistente.

curl -X GET 'https://api.crm.asender.net/v1/painel' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/pedidos-exclusao
Lista a fila de pedidos de exclusão (só admin da conta).
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header); status (query); cursor (query); limite (query)
Respostas: 200 a página de pedidos.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X GET 'https://api.crm.asender.net/v1/pedidos-exclusao' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/pedidos-exclusao
Registra o pedido de exclusão de um titular (task pendente; NÃO apaga nada).
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 o pedido pendente.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 já existe um pedido pendente para este contato.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/pedidos-exclusao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/pedidos-exclusao/{id}/aprovar
Aprova o pedido e anonimiza o contato (só admin da conta; irreversível).
Efeitos: irreversível sobre a PII; é o ÚNICO caminho HTTP até ela.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o pedido executado.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 o pedido já foi decidido.

curl -X POST 'https://api.crm.asender.net/v1/pedidos-exclusao/id_AQUI/aprovar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/pedidos-exclusao/{id}/recusar
Recusa o pedido (só admin da conta; motivo obrigatório; nada é apagado).
Efeitos: nada é apagado; o contato recebe um registro na timeline.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o pedido recusado.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 o pedido já foi decidido.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/pedidos-exclusao/id_AQUI/recusar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/projetos
GET /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma leitura.

curl -X GET 'https://api.crm.asender.net/v1/projetos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/projetos
POST /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma escrita.

curl -X POST 'https://api.crm.asender.net/v1/projetos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/projetos/{id}
GET /v1/clientes/{id}. Outra conta = 404, como inexistente.

curl -X GET 'https://api.crm.asender.net/v1/projetos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/projetos/{id}
PUT /v1/alertas/{id}.
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.

curl -X PATCH 'https://api.crm.asender.net/v1/projetos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/projetos/{id}
DELETE /v1/alertas/{id}.
Onde é usada: tela de alertas.
Efeitos: uma escrita.

curl -X DELETE 'https://api.crm.asender.net/v1/projetos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/projetos/{id}/logo
Troca a logo do projeto (multipart, campo `arquivo`).
Onde é usada: tela de projeto (ficha). Mesma capacidade de editar projeto (o grupo `/v1/projetos` inteiro passa pelo mesmo `autenticar` + produto).
Efeitos: grava `projeto_logos`; loga (sem bytes) tenant, projeto, sha e tamanho.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o projeto atualizado (`tem_logo` verdadeiro e novo `logo_versao`).; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 413 arquivo acima de 512 KiB (`ArquivoGrande`).; 422 `FormatoInvalido` ou `ArquivoInfectado`.; 503 antivírus indisponível (`AntivirusIndisponivel`); tente de novo (`Retry-After`).

curl -X PUT 'https://api.crm.asender.net/v1/projetos/id_AQUI/logo' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/projetos/{id}/logo
Remove a logo do projeto (idempotente).
Onde é usada: ficha do projeto, "remover logo".
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 removida (ou já não havia).; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X DELETE 'https://api.crm.asender.net/v1/projetos/id_AQUI/logo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/projetos/{id}/logo
Os bytes da logo (já re-codificada).
Onde é usada: `<img>` da ficha e do cartão do projeto (versão em `logo_versao`).
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); If-None-Match (header)
Respostas: 200 a imagem.; 304 o `If-None-Match` ainda vale; sem corpo.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/projetos/id_AQUI/logo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/projetos/{id}/mover
PUT /v1/projetos/{id}/mover.

curl -X PUT 'https://api.crm.asender.net/v1/projetos/id_AQUI/mover' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/projetos/colunas
GET /v1/projetos/colunas.

curl -X GET 'https://api.crm.asender.net/v1/projetos/colunas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/projetos/colunas
POST /v1/projetos/colunas.

curl -X POST 'https://api.crm.asender.net/v1/projetos/colunas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /v1/projetos/colunas/{id}
PATCH /v1/projetos/colunas/{id}.

curl -X PATCH 'https://api.crm.asender.net/v1/projetos/colunas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/projetos/colunas/{id}
DELETE /v1/projetos/colunas/{id}.

curl -X DELETE 'https://api.crm.asender.net/v1/projetos/colunas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/projetos/colunas/{id}/mover
PUT /v1/projetos/colunas/{id}/mover.

curl -X PUT 'https://api.crm.asender.net/v1/projetos/colunas/id_AQUI/mover' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/relatorios/atividade
Atividade responde GET /v1/relatorios/atividade?de=&ate=.

curl -X GET 'https://api.crm.asender.net/v1/relatorios/atividade' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/relatorios/funil
Funil responde GET /v1/relatorios/funil?de=&ate=.

curl -X GET 'https://api.crm.asender.net/v1/relatorios/funil' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/relatorios/origem
Leads criados no período, por fonte, por formulário e por canal de conversa.
Parâmetros: X-Asender-Tenant (header); de (query); ate (query)
Respostas: 200 as três agregações do período.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/relatorios/origem' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/relatorios/projetos
Projetos responde GET /v1/relatorios/projetos?de=&ate=.

curl -X GET 'https://api.crm.asender.net/v1/relatorios/projetos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/relatorios/tarefas
Tarefas responde GET /v1/relatorios/tarefas?de=&ate=.

curl -X GET 'https://api.crm.asender.net/v1/relatorios/tarefas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/relatorios/trafego
duas leituras INDEPENDENTES — uma consulta local (`LeadsPorOrigemUTM`) e uma chamada HTTP ao Pages (`pages.Resumo`, reaproveitando `top_origens`, já calculado com o mesmo critério que a Início usa) — casadas em memória pela string de `utm_source`. NUNCA um JOIN de banco: os dois dados vivem em bancos de serviços diferentes (piso 6/10), e cruzá-los aqui, na borda, é o único jeito de fazer isso sem um serviço ler o schema do outro.
Onde é usada: tela de Relatórios do CRM.
Efeitos: uma consulta local; uma chamada HTTP ao Pages. Pages fora do ar NÃO derruba a rota: ela responde 200 com `disponivel: false` e as linhas só com o lado do CRM (sessões ficam de fora, e `taxa_de_conversao` sai vazia em todas) — o operador ainda vê "quantos leads por origem", só sem cruzar com sessão.

curl -X GET 'https://api.crm.asender.net/v1/relatorios/trafego' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/resumo
Resumo da ferramenta para o hub e a home (contrato comum de resumo).
Parâmetros: X-Asender-Tenant (header); periodo (query)
Respostas: 200 o resumo da ferramenta `crm`.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 403 membro da conta sem acesso a esta ferramenta.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/resumo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/segmentos
Lista os segmentos vivos da conta.
Onde é usada: tela de alertas.
Efeitos: uma leitura.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 os segmentos.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/segmentos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/segmentos
Cria um segmento; devolve o alcance atual.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 o segmento criado e seu alcance.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 409 já existe um segmento com esse nome.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/segmentos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/segmentos/{id}
Lê um segmento e quantas pessoas ele alcança agora.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o segmento e seu alcance.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X GET 'https://api.crm.asender.net/v1/segmentos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/segmentos/{id}
Substitui nome, conjunção e critérios de um segmento.
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 o segmento atualizado e seu alcance.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.; 409 já existe um segmento com esse nome.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X PUT 'https://api.crm.asender.net/v1/segmentos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/segmentos/{id}
Remove (logicamente) um segmento.
Onde é usada: tela de alertas.
Efeitos: uma escrita.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 removido.; 401 sessão ausente ou inválida.; 404 recurso inexistente, de outra conta, ou sem acesso à ferramenta.

curl -X DELETE 'https://api.crm.asender.net/v1/segmentos/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/segmentos/previa
Calcula o alcance de um segmento AINDA NÃO salvo.
Onde é usada: enquanto o usuário monta os critérios na tela.
Efeitos: uma consulta; NÃO grava nada. Existe para que a pergunta "isto alcança quem?" seja respondida ANTES de salvar. Sem ela, o caminho para descobrir o alcance é criar o segmento — e a tela enche de segmentos descartados chamados "teste 3".
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 o alcance calculado.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.; 422 corpo bem formado, mas o conteúdo não passa na regra de negócio.

curl -X POST 'https://api.crm.asender.net/v1/segmentos/previa' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/tarefas
GET /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma leitura.

curl -X GET 'https://api.crm.asender.net/v1/tarefas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/tarefas
POST /v1/alertas.
Onde é usada: tela de alertas.
Efeitos: uma escrita.

curl -X POST 'https://api.crm.asender.net/v1/tarefas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/tarefas/{id}
GET /v1/clientes/{id}. Outra conta = 404, como inexistente.

curl -X GET 'https://api.crm.asender.net/v1/tarefas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/tarefas/{id}
PUT /v1/alertas/{id}.
Onde é usada: tela de alertas.
Efeitos: uma escrita. Mudar a configuração ACALMA o alerta: ele passa a observar outra coisa, e manter o estado faria a próxima avaliação comparar maçã com laranja — ele não avisaria pela condição NOVA, porque já estaria "disparado" pela antiga.

curl -X PATCH 'https://api.crm.asender.net/v1/tarefas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/tarefas/{id}
DELETE /v1/alertas/{id}.
Onde é usada: tela de alertas.
Efeitos: uma escrita.

curl -X DELETE 'https://api.crm.asender.net/v1/tarefas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/tarefas/{id}/mover
PUT /v1/projetos/{id}/mover.

curl -X PUT 'https://api.crm.asender.net/v1/tarefas/id_AQUI/mover' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/uso
Lê o consumo da conta (números locais + quota do core).
Onde é usada: tela de conta/plano.
Efeitos: uma leitura local e até duas chamadas ao core. # O core fora do ar NÃO derruba esta rota Os números locais (quantos contatos, quantos entraram no mês) são a metade que o CRM sabe sozinho, e são justamente a metade que a tela usa todo dia. Com o core fora, a resposta sai com `core_disponivel: false` — a tela mostra o que tem e diz o que não conseguiu saber (piso 10).
Parâmetros: X-Asender-Tenant (header); periodo (query)
Respostas: 200 o consumo da conta.; 400 corpo malformado, campo desconhecido ou query inválida.; 401 sessão ausente ou inválida.

curl -X GET 'https://api.crm.asender.net/v1/uso' \
  -H 'Authorization: Bearer SEU_TOKEN'



==============================================================================
# E-mail  (https://api.mail.asender.net)
==============================================================================

# Mail API

A API do **e-mail corporativo** Asender: envio transacional assinado por DKIM,
gestão de domínios e caixas, e a superfície de leitura/escrita do webmail
(mensagens, rascunhos, contatos, assinatura). É um sistema à parte, com endereço
próprio — o e-mail fora do ar é o e-mail fora do ar, e não arrasta as outras
ferramentas.

- **Base URL:** `https://api.mail.asender.net`
- **Autenticação:** API key (`Authorization: Bearer sk_…`)
- **Formato:** JSON (`application/json; charset=utf-8`)

> **Envelope de erro desta API:** `{ "error", "message" }`. A Platform API
> (`api.asender.net`) usa outro: `{ "Error": { "Type", "Code", "Message", "Details" }, "RequestId" }`.
> Não use o mesmo parser nas duas ([Convenções](https://developers.asender.net/guias/convencoes.html#dois-envelopes-de-erro)).

> **Código de verificação (2FA/OTP) ou e-mail transacional de qualquer endereço de
> um domínio verificado?** Use `POST https://api.asender.net/v1/emails/send`
> (Platform API, escopo `email:send`): ele aceita **qualquer remetente de um domínio
> verificado**, sem criar caixa. Esta API (`POST /v1/emails`) é para enviar **a partir
> de uma caixa corporativa que já existe**: `from` tem de ser uma caixa, não só um
> domínio verificado. O resto desta página é para quem envia dessas caixas, administra
> domínios e caixas ou constrói um cliente de e-mail sobre a plataforma.

## Autenticação

Toda rota (fora das probes de saúde) exige uma **API key** da conta. A chave é
uma credencial de **máquina**: o `tenant_id` é resolvido *da chave*, nunca de um
campo do corpo ou da URL, e **cada rota exige um escopo da chave** (abaixo).

Envie a chave em `Authorization`:

```
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
```

Só `Authorization: Bearer` é aceito: `X-Api-Key` e `?api_key=` foram removidos
(2026-10-07) e, sozinhos, dão **401**.

**Como obter uma chave.** As API keys são emitidas pela Plataforma, não pela Mail
API. Crie uma em `POST https://api.asender.net/api/tenants/{id}/api-keys` (ver a
[Platform API](https://developers.asender.net/apis/platform.html)) ou pela tela de
API keys do painel. Use `sk_test_…` fora de produção e `sk_live_…` em produção —
a chave `test` é barrada pelos guardas de efeito externo (piso 18).

Chave ausente ou inválida devolve **401**:

```json
{ "error": "AuthorizationError", "message": "API key inválida." }
```

### Escopos da API key (obrigatórios)

A chave só alcança as rotas abaixo, cada uma com o escopo indicado; chave **sem
escopos**, `full_access`, `send_only` ou `emails:*` não concede nada. Falta de
escopo devolve **403**, nomeando o escopo exigido:

```json
{ "error": "InsufficientScope", "message": "API key lacks the required scope: email:send." }
```

| escopo | rotas |
| --- | --- |
| `email:send` | `POST /v1/emails`, `POST /mailboxes/{id}/send` |
| `email:read` | `GET /mailboxes/{id}/messages`, `GET /mailboxes/{id}/messages/{msgId}`, `…/raw`, `…/attachments/{attId}`, `GET /mailboxes/{id}/threads/{threadId}` |
| `mail:admin` | administração de domínios e caixas da própria conta: `GET /orgs`, `POST`/`GET /orgs/{orgID}/domains`, `GET /domains/{id}/dns`, `POST /domains/{id}/verify`, `POST`/`GET /domains/{id}/mailboxes`, `PUT /domains/{id}/catchall`, `PUT /domains/{id}/autocreate`, `PUT /mailboxes/{id}/tipo`. **Não lê mensagens** (isso é `email:read`) nem envia (`email:send`) |

Qualquer outra rota desta API (Cloudflare, contas de caixa, concessões, filtros,
rascunhos, contatos…) é **plano de controle**, feito pela sessão do painel, e
responde **403** a uma API key. Emita a chave com os escopos mínimos da integração (o catálogo completo está
na [Platform API](https://developers.asender.net/apis/platform.html)).

## Envio transacional — `POST /v1/emails`

O coração da API. Envia de uma **caixa existente** da conta (em domínio verificado), assina com o
DKIM do domínio e grava em *Enviados*.

```bash
curl -X POST 'https://api.mail.asender.net/v1/emails' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f7c1e2a-6b3d-4a1e-9c2f-0d5e7a1b2c3d' \
  -d '{
    "from": "joana@empresa.com.br",
    "to": ["cliente@exemplo.test"],
    "subject": "Proposta comercial",
    "text": "Olá, segue a proposta que conversamos. Qualquer dúvida, é só responder."
  }'
```

Resposta `202`:

```json
{ "message_id": "0b9c…", "status": "sent" }
```

Regras que valem a pena saber antes de integrar:

- **`from` tem de ser uma CAIXA que existe na conta da chave.** Domínio verificado
  não basta: `auth@empresa.com.br` só envia depois que a caixa `auth` for criada no
  domínio `empresa.com.br` daquela conta (ver [Antes do primeiro envio](#antes-do-primeiro-envio-crie-a-caixa-remetente)).
  Caixa inexistente — ou de outra conta — responde **422**
  `CaixaRemetenteInexistente` com a dica de usar `POST https://api.asender.net/v1/emails/send`
  para remetentes de domínio (a resposta é a mesma nos dois casos, para não
  revelar caixa de outro tenant).
- **Idempotência.** Repita a mesma `Idempotency-Key` para tornar seguro o retry
  de uma resposta que você não recebeu: o replay volta **200** com
  `"idempotent_replay": true` e **nada é reenviado**.
- **Anti-injeção de cabeçalho.** Endereços com CR/LF são recusados na borda
  (**400**) — eles virariam cabeçalhos forjados num e-mail assinado.
- **Anexos** vão em `attachments[]` como base64 (`filename` + `content`).

### Antes do primeiro envio: crie a caixa remetente

O envio exige duas coisas na **mesma conta da API key**:

1. **Domínio verificado** (MX, SPF, DKIM e DMARC) — pela tela *Domínios* do
   e-mail ou por `POST /orgs/{orgID}/domains` + verificação.
2. **A caixa do endereço `from`** criada nesse domínio — um endereço só de envio
   (`no-reply@`, `auth@`, `notify@`) também é uma caixa.

Pela tela: **mail.asender.net → Domínios → (o domínio) → Nova caixa**.

Pela API, com uma chave que tenha o escopo **`mail:admin`** (administrar domínios e
caixas de e-mail; emita-a na tela de API keys) — e `email:send` para o envio em si.
Sem `mail:admin` a criação responde **403** `InsufficientScope` nomeando
`mail:admin`, mesmo com `email:send`; `mail:admin` sozinho **não** envia nem lê
mensagens:

```bash
# 1) a organização de e-mail da conta
curl -s 'https://api.mail.asender.net/orgs' -H 'Authorization: Bearer sk_live_…'
# → {"orgs":[{"id":"<orgID>", …}]}

# 2) o id do domínio
curl -s 'https://api.mail.asender.net/orgs/<orgID>/domains' -H 'Authorization: Bearer sk_live_…'
# → {"domains":[{"id":"<domainID>","domain":"empresa.com.br","active":true, …}]}

# 3) uma caixa por remetente
curl -s -X POST 'https://api.mail.asender.net/domains/<domainID>/mailboxes' \
  -H 'Authorization: Bearer sk_live_…' -H 'Content-Type: application/json' \
  -d '{"local_part":"no-reply","display_name":"Empresa"}'
# → 201 com a caixa criada
```

Criar a caixa é idempotente do ponto de vista do envio: depois de existir, todo
`POST /v1/emails` com aquele `from` passa. A API key de **outra** conta não
enxerga o domínio (404) — gere a chave na conta onde o domínio está.

### Quota do plano (429)

Cada destinatário em `to`/`cc`/`bcc` é **um disparo** e consome a quota do plano.
Ao estourar o teto, a resposta é **429** e os cabeçalhos dizem qual janela barrou
e quando ela reabre:

| header | significado |
| --- | --- |
| `X-Quota-Limit` | teto do plano na janela que barrou |
| `X-Quota-Used` | disparos já consumidos |
| `X-Quota-Remaining` | disparos restantes |
| `X-Quota-Escala` | `dia` ou `mes` — qual janela barrou (o corporativo tem as duas) |
| `Retry-After` | segundos até a janela reabrir |

```json
{ "error": "QuotaExceeded", "message": "limite MENSAL do plano atingido — suba de plano ou compre créditos para seguir enviando neste ciclo." }
```

> **Nota de disponibilidade (fail-open deliberado).** Se o contador de quota
> estiver indisponível no momento do envio, o e-mail **passa** (registra em log e
> segue). Um provedor de OTP não pode parar de entregar código de login porque o
> medidor de cobrança piscou. A *autenticação* continua fail-closed — a chave já
> foi validada antes de o envio começar.

### Não-produção nunca entrega de verdade (piso 18)

Fora de `prd`, um destinatário fora do domínio de teste faz o envio **falhar**
(502) por construção — não por lembrança. Use `@exemplo.test` (ou os TLDs
reservados `.test`/`.invalid`/`.example`) em fixtures e testes. Nunca use
`@gmail.com`, o domínio de um cliente ou um e-mail de pessoa real: bounce em
massa queima o IP e o domínio e derruba o transacional de produção — inclusive o
OTP de login.

## Erros

Toda falha desta API usa o mesmo envelope (`{ "error", "message" }`; a Platform API usa `{ "Error": {…}, "RequestId" }`):

```json
{ "error": "ValidationError", "message": "campo 'to' é obrigatório." }
```

| código HTTP | `error` típico | quando |
| --- | --- | --- |
| 400 | `ValidationError` | corpo inválido, `from`/`to` ausentes, injeção de cabeçalho, anexo inválido |
| 401 | `AuthorizationError` | API key ausente ou inválida |
| 403 | `InsufficientScope` | a chave não tem o escopo da rota (ex.: `POST /v1/emails` sem `email:send`), não tem escopo algum, ou a rota não é de API key |
| 404 | `NotFound` | recurso fora do escopo da chave (não revela existência alheia) |
| 422 | `CaixaRemetenteInexistente` | `POST /v1/emails` com `from` que não é uma caixa da conta (para remetente de domínio verificado use `POST https://api.asender.net/v1/emails/send`) |
| 429 | `QuotaExceeded` | teto de disparos do plano (ver cabeçalhos `X-Quota-*`) |
| 502 | `SendFailed` | entrega recusada (piso 18) ou falha no relay; a quota é estornada |
| 503 | `InternalError` | envio não configurado / backend de auth indisponível |

O corpo de requisição é lido com **contrato estrito**: campo desconhecido é
**400**, não é ignorado em silêncio; o limite é 1 MiB.

## Paginação

Coleções longas (mensagens) paginam por **cursor opaco**, nunca por offset:

```
GET /mailboxes/{id}/messages?limit=50
→ { "messages": [...], "next_cursor": "eyJ…" }

GET /mailboxes/{id}/messages?limit=50&cursor=eyJ…
```

Passe `next_cursor` de volta como veio. Vazio significa que acabou. Um cursor
velho ou inválido volta à primeira página em vez de virar erro. O escopo é
sempre a caixa da rota — a query string recorta, nunca amplia.

## Superfície da API

- **Envio** — `POST /v1/emails` (transacional público), `POST /mailboxes/{id}/send`.
- **Mensagens** — listar (por pasta/marcadores/busca), ler, `.eml` original,
  patch (lida/estrelada/mover), lote e pastas.
- **Rascunhos** — auto-save, retomada e descarte.
- **Contatos** — agenda por caixa e autocomplete de destinatários.
- **Assinatura** — HTML por caixa, sanitizado no servidor.

A referência completa de cada rota — parâmetros, corpo, respostas e um `curl`
pronto — está logo abaixo, gerada do código e da spec.

> **O que não está aqui, e por quê.** Domínios e caixas têm a escrita por API key
> descrita acima (`mail:admin`). O resto do plano de controle (Cloudflare, contas de
> caixa, concessões) e as telas do webmail (filtros, remetentes, preferências) são
> feitos pelo painel — não são superfície de integração por API key e por isso ficam
> fora desta documentação.

## Registro de mudanças

| data | mudança | quem é afetado |
| --- | --- | --- |
| 2026-10-07 | **Novo escopo `mail:admin`.** Libera, para API key, a administração de domínios e caixas da própria conta (`GET /orgs`, domínios, DNS, verificação, caixas, catch-all/autocreate, tipo da caixa). Não lê mensagens. Sem ele, 403 `InsufficientScope` nomeando `mail:admin`. | Quem cria domínio/caixa por API key: emita a chave com `mail:admin` (e `email:send` para enviar). |
| 2026-10-07 | **Quebra de contrato: chaves sem escopo deixam de funcionar.** `POST /v1/emails` passa a exigir o escopo `email:send` e a leitura de mensagens `email:read`; chave sem escopos, `full_access`, `send_only` ou `emails:*` recebe `403 InsufficientScope`. As rotas de plano de controle (orgs, domínios, caixas, filtros…) deixam de aceitar API key (`403`) — exceto domínios e caixas, devolvidos pelo escopo `mail:admin` (linha acima). | Quem usa chave emitida antes desta data sem escopo do catálogo, ou criava domínio/caixa por API key: gere outra chave com `email:send` (e `mail:admin` para domínios e caixas). |


### DELETE /aliases/{id}
admin do mail do tenant do alias (outro tenant = 404); corpo opcional {motivo}. A linha, o ator e o motivo ficam (auditoria); o endereço volta a ficar livre.
Onde é usada: DELETE /aliases/{id}.
Saídas: 200 {removed, alias}; 403; 404.

curl -X DELETE 'https://api.mail.asender.net/aliases/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /aliases/{id}/restaurar
409 se o endereço foi tomado (outro alias ou caixa), 422 se a caixa-destino sumiu ou foi assinada.
Onde é usada: POST /aliases/{id}/restaurar.
Saídas: 200 {restored, alias}; 403; 404; 409; 422.

curl -X POST 'https://api.mail.asender.net/aliases/id_AQUI/restaurar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /autoconfig/mail/config-v1.1.xml
Configuração automática do Thunderbird (autoconfig, config-v1.1) do domínio
Onde é usada: as duas rotas de `registrar`.
Parâmetros: emailaddress (query)
Respostas: 200 XML clientConfig 1.1; 404 domínio não verificado ou desconhecido (corpo idêntico); 429 muitos pedidos; 503 consulta de domínio indisponível

curl -X GET 'https://api.mail.asender.net/autoconfig/mail/config-v1.1.xml' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mail/config-v1.1.xml
Configuração automática do Thunderbird (autoconfig, config-v1.1) do domínio
Onde é usada: as duas rotas de `registrar`.
Parâmetros: emailaddress (query)
Respostas: 200 XML clientConfig 1.1; 404 domínio não verificado ou desconhecido (corpo idêntico); 429 muitos pedidos; 503 consulta de domínio indisponível

curl -X GET 'https://api.mail.asender.net/mail/config-v1.1.xml' \
  -H 'Authorization: Bearer SEU_TOKEN'

### DELETE /mailboxes/{id}
exige administrador e posse do tenant (404 para outro tenant ou caixa já removida, sem vazar existência). Com vínculos (catch-all, encaminhamento/regra de outra caixa que aponta para ela, assinatura do atendimento) recusa com 409 `CaixaComVinculos` + `vinculos` — NÃO limpa o roteamento alheio em silêncio. Com sucesso a caixa deixa de receber (rejeita como inexistente), de autenticar no IMAP/SMTP, some das listas e do "De"; nenhuma mensagem, anexo ou blob é tocado.
Onde é usada: DELETE /mailboxes/{id}.
Saídas: 200 {removed, address}; 403; 404; 409.

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/aliases
ListarAliasesDaCaixa lista os alias ativos que entregam numa caixa do tenant.
Onde é usada: GET /mailboxes/{id}/aliases.
Saídas: 200 {aliases, limite_por_caixa}; 403; 404.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/aliases' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/avatar
exigirCaixaOuGestao (tenant + grant, ou admin do mail: a foto é metadado de gestão; 404 para quem não pode) e os bytes com os cabeçalhos que impedem a imagem de virar documento na origem do webmail.
Onde é usada: GET /mailboxes/{id}/avatar.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/avatar' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /mailboxes/{id}/avatar
só ADMIN do mail no tenant da caixa (exigirAdminNaCaixa); a imagem é decodificada e recodificada em PNG ≤ 256 px ANTES de tocar o blob.
Onde é usada: PUT /mailboxes/{id}/avatar.

curl -X PUT 'https://api.mail.asender.net/mailboxes/id_AQUI/avatar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/avatar
ApagarAvatarDaCaixa remove a foto.
Onde é usada: DELETE /mailboxes/{id}/avatar (admin).

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/avatar' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/contacts
Listar a agenda da caixa
Onde é usada: GET /mailboxes/{id}/contacts. `q` casa nome OU e-mail (substring, case-insensitive); ausente devolve tudo.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/contacts' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/contacts
Adicionar contato à agenda da caixa
Onde é usada: POST /mailboxes/{id}/contacts. E-mail repetido na caixa -> 409.
Parâmetros: id (path, obrigatório)
Respostas: 201 criado; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/contacts' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /mailboxes/{id}/contacts/{contatoId}
Atualizar contato
Onde é usada: PATCH /mailboxes/{id}/contacts/{contatoId}. Contato de outra caixa (ou id que não é contato) -> 404; novo e-mail que colide -> 409.
Parâmetros: id (path, obrigatório); contatoId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X PATCH 'https://api.mail.asender.net/mailboxes/id_AQUI/contacts/contatoId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/contacts/{contatoId}
Apagar contato
Onde é usada: DELETE /mailboxes/{id}/contacts/{contatoId}. Contato inexistente ou de outra caixa -> 404 (o mesmo da leitura; não deixa sondar contato alheio).
Parâmetros: id (path, obrigatório); contatoId (path, obrigatório)
Respostas: 204 apagado; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/contacts/contatoId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/drafts
Criar rascunho (auto-save do compositor)
Onde é usada: POST /mailboxes/{id}/drafts.
Parâmetros: id (path, obrigatório)
Respostas: 201 criado; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/drafts' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/drafts/{draftId}
Retomar rascunho
Onde é usada: GET /mailboxes/{id}/drafts/{draftId}, disparado ao abrir um item da pasta Rascunhos. Não-rascunho/outra caixa -> 404.
Parâmetros: id (path, obrigatório); draftId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/drafts/draftId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /mailboxes/{id}/drafts/{draftId}
Atualizar rascunho
Onde é usada: PUT /mailboxes/{id}/drafts/{draftId}.
Parâmetros: id (path, obrigatório); draftId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X PUT 'https://api.mail.asender.net/mailboxes/id_AQUI/drafts/draftId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/drafts/{draftId}
Descartar rascunho
Onde é usada: DELETE /mailboxes/{id}/drafts/{draftId}.
Parâmetros: id (path, obrigatório); draftId (path, obrigatório)
Respostas: 204 descartado; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/drafts/draftId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/folders
Pastas da caixa, com total e não-lidas
Onde é usada: GET /mailboxes/{id}/folders, que desenha o rail.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/folders' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/folders
Criar pasta do usuário (kind=custom)
Onde é usada: POST /mailboxes/{id}/folders.
Saídas: 201 com a pasta; 400/409 conforme o nome; 404 se a caixa não é de quem pediu.
Parâmetros: id (path, obrigatório)
Respostas: 201 criada; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/folders' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /mailboxes/{id}/folders/{fid}
authz por caixa + UPDATE restrito a `custom`.
Onde é usada: PATCH /mailboxes/{id}/folders/{fid}.

curl -X PATCH 'https://api.mail.asender.net/mailboxes/id_AQUI/folders/fid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/folders/{fid}
authz por caixa + DELETE restrito a `custom` e sem conteúdo.
Onde é usada: DELETE /mailboxes/{id}/folders/{fid}.

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/folders/fid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/forwarding
LerForward devolve a regra de encaminhamento da caixa.
Onde é usada: GET /mailboxes/{id}/forwarding.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/forwarding' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /mailboxes/{id}/forwarding
valida o destino (net/mail, no store) e faz UPSERT.
Onde é usada: PUT /mailboxes/{id}/forwarding. Ligar sem destino é recusado (400). O encaminhamento em si é um ENVIO no recebimento (guard do piso 18).

curl -X PUT 'https://api.mail.asender.net/mailboxes/id_AQUI/forwarding' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/identities
Listar identidades de envio da caixa (M-E)
Onde é usada: GET /mailboxes/{id}/identities.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/identities' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/identities
Criar identidade de envio (send-as)
Onde é usada: POST /mailboxes/{id}/identities.
Parâmetros: id (path, obrigatório)
Respostas: 201 criada; 400 endereço inválido; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 endereço já existe na caixa

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/identities' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /mailboxes/{id}/identities/{identityId}
Editar uma identidade de envio
Onde é usada: PATCH /mailboxes/{id}/identities/{identityId}.
Parâmetros: id (path, obrigatório); identityId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 endereço já existe na caixa

curl -X PATCH 'https://api.mail.asender.net/mailboxes/id_AQUI/identities/identityId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/identities/{identityId}
Apagar uma identidade de envio
Onde é usada: DELETE /mailboxes/{id}/identities/{identityId}.
Parâmetros: id (path, obrigatório); identityId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/identities/identityId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/import
decodifica o arquivo, separa nas mensagens, e grava cada uma que a caixa ainda não tem (por Message-ID).
Onde é usada: POST /mailboxes/{id}/import.
Saídas: {imported, skipped, total}. Uma mensagem que falha ao gravar é contada em `errors` e NÃO derruba o import inteiro — o resto é aproveitado.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/import' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/import/remote
CriarImportacaoRemota cifra a senha e enfileira o job.
Onde é usada: POST /mailboxes/{id}/import/remote. Com `conexao_id` no corpo, host e senha vêm da conexão do cofre (conexoes_job.go); sem ele, são os digitados. Respostas: 202 {job_id}; 400 ValidationError; 409 ImportacaoEmAndamento (já há job ativo na caixa); 429. A mesma validação síncrona LEVE do teste (sem rede).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/import/remote' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/import/remote
ListarImportacoesRemotas devolve os últimos 20 jobs da caixa.
Onde é usada: GET /mailboxes/{id}/import/remote.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/import/remote' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/import/remote/{job_id}
LerImportacaoRemota devolve um job. Job de outra caixa ou outro tenant = 404.
Onde é usada: GET .../{job_id}.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/import/remote/job_id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/import/remote/{job_id}/cancel
CancelarImportacaoRemota cancela o job (zera a senha, audita). Idempotente em estado terminal.
Onde é usada: POST .../{job_id}/cancel. O runner percebe o status e para o motor; o já importado fica.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/import/remote/job_id_AQUI/cancel' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/import/remote/test
TestarImportacaoRemota conecta no provedor, autentica e lista as pastas. NÃO persiste nada.
Onde é usada: POST /mailboxes/{id}/import/remote/test. Respostas: 200 {folders:[{name,messages,special_use}]}; 400 ValidationError; 422 DestinoBloqueado|AutenticacaoFalhou|CertificadoInvalido; 429; 502 ProvedorIndisponivel.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/import/remote/test' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/labels
Listar etiquetas da caixa (M-E)
Onde é usada: GET /mailboxes/{id}/labels.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/labels' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/labels
Criar etiqueta na caixa
Onde é usada: POST /mailboxes/{id}/labels.
Parâmetros: id (path, obrigatório)
Respostas: 201 criada; 400 nome inválido; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 nome já existe na caixa

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/labels' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /mailboxes/{id}/labels/{labelId}
Renomear/recolorir uma etiqueta
Onde é usada: PATCH /mailboxes/{id}/labels/{labelId}.
Parâmetros: id (path, obrigatório); labelId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 nome já existe na caixa, ou etiqueta de sistema (só a cor muda)

curl -X PATCH 'https://api.mail.asender.net/mailboxes/id_AQUI/labels/labelId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/labels/{labelId}
Apagar uma etiqueta (as mensagens perdem só o vínculo)
Onde é usada: DELETE /mailboxes/{id}/labels/{labelId}.
Parâmetros: id (path, obrigatório); labelId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 etiqueta de sistema não se apaga

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/labels/labelId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/labels/resumo
Etiquetas da caixa com origem e contagens (a lateral)
Onde é usada: GET /mailboxes/{id}/labels/resumo -> EtiquetasNav do mail_front.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/labels/resumo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/lixeira
lista o que o usuário apagou na caixa, do mais recente ao mais antigo.
Onde é usada: tela Configurações → Lixeira do webmail. Exige acesso à caixa (mesmo critério de apagar) e sessão de usuário.
Saídas: 200 `{itens, cursor}`; 403 sem sessão de usuário; 404 caixa inacessível; 422 tipo/cursor inválido. Só leitura.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/lixeira' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/lixeira/{tipo}/{itemId}/restaurar
devolve à vista do usuário um item que ELE apagou na caixa.
Onde é usada: botão Restaurar da tela de Lixeira.
Saídas: 204; 403 sem sessão de usuário; 404 (não está apagado, é de outro usuário/caixa, ou tipo fora da allowlist); 409 `conflito_unicidade`.
Efeitos: UPDATE com origem `usuario:<id>` e log do evento.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/lixeira/tipo_AQUI/itemId_AQUI/restaurar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/messages
Listar mensagens da caixa (por pasta, marcadores e busca)
Onde é usada: GET /mailboxes/{id}/messages?folder=&unread=1&starred=1&q=&limit=N&cursor=… O recorte vem da query string, mas o ESCOPO não: a caixa sai da rota já autorizada, e é ela que a consulta usa. Um `?mailbox=` no filtro seria a própria pessoa escolhendo o que pode ver.
Parâmetros: id (path, obrigatório); folder (query); unread (query); starred (query); q (query); label (query); todas (query); ocultas (query); limit (query); cursor (query)
Respostas: 200 ok; 400 busca inválida (BuscaInvalida; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/messages' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/messages/{msgId}
Ler a mensagem completa (marca como lida)
Onde é usada: GET /mailboxes/{id}/messages/{msgId}. Cross-tenant/outra caixa -> 404.
Parâmetros: id (path, obrigatório); msgId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /mailboxes/{id}/messages/{msgId}
Marcar lida, estrelar ou mover uma mensagem
Onde é usada: PATCH /mailboxes/{id}/messages/{msgId}.
Erros: patch vazio -> 400 (não é sucesso silencioso); mensagem de outra caixa -> 404, o mesmo da leitura, que não revela a existência dela.
Parâmetros: id (path, obrigatório); msgId (path, obrigatório)
Respostas: 200 aplicado; 400 corpo sem nenhum campo; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 mover PARA a Quarentena, ou tirar dela por aqui — a saída é POST …/quarantine/release (ADR-0087)

curl -X PATCH 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/messages/{msgId}/attachments/{attId}
caixa->domínio->tenant + AcharAnexo (scopeado à mensagem/caixa); responde com o conteúdo e Content-Disposition.
Onde é usada: GET /mailboxes/{id}/messages/{msgId}/attachments/{attId}.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/attachments/attId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/messages/{msgId}/labels
Aplicar uma etiqueta a uma mensagem (idempotente)
Onde é usada: POST /mailboxes/{id}/messages/{msgId}/labels {label_id}.
Parâmetros: id (path, obrigatório); msgId (path, obrigatório)
Respostas: 200 aplicado; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/labels' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/messages/{msgId}/labels/{labelId}
Remover uma etiqueta de uma mensagem (idempotente)
Onde é usada: DELETE /mailboxes/{id}/messages/{msgId}/labels/{labelId}.
Parâmetros: id (path, obrigatório); msgId (path, obrigatório); labelId (path, obrigatório)
Respostas: 200 removido; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/labels/labelId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/messages/{msgId}/pgp-verify
carrega a mensagem (da caixa), acha a chave do From e verifica o clearsign do corpo.
Onde é usada: POST /mailboxes/{id}/messages/{msgId}/pgp-verify.
Saídas: {verified, signer_fingerprint} — `verified:false` (200) quando não há chave do remetente ou a assinatura não confere; a tela mostra "não verificado" em vez de tratar como erro de sistema.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/pgp-verify' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/messages/{msgId}/phishing
ver o comentário do arquivo.
Onde é usada: botão "É golpe"/"Não é golpe" do webmail.
Saídas: 200 {ok, pasta, item_id?}; 400 corpo inválido; 404 caixa/mensagem alheia; 409 `nao_esta_em_phishing`; 429 teto diário; 503 `servico_indisponivel`.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/phishing' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/messages/{msgId}/quarantine/release
Liberar uma mensagem da Quarentena para a Entrada (ADR-0087)
Onde é usada: POST /mailboxes/{id}/messages/{msgId}/quarantine/release. O veredito continua `infectado` (liberar é decisão humana, não exame): o download dos anexos segue pedindo confirmação de risco (anexos.go).
Parâmetros: id (path, obrigatório); msgId (path, obrigatório)
Respostas: 200 liberada; 400 sem a confirmação; 403 achado de assinatura e quem pede não é admin; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 a mensagem não está na Quarentena

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/quarantine/release' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/messages/{msgId}/raw
Baixar o .eml original (ADR-0028)
Onde é usada: GET /mailboxes/{id}/messages/{msgId}/raw. Por que a rota existe: o `.eml` é o único artefato fiel do que chegou ou saiu — com cabeçalhos, ordem das partes e assinatura DKIM. É o que se abre noutro cliente, o que se anexa a uma disputa e o que se reprocessa quando o parser melhora. Sem rota, ele seria um arquivo num volume que ninguém alcança. Mensagem anterior ao ADR-0028 não tem bruto: 404, que é a verdade — e não um arquivo vazio com cara de download bem-sucedido.
Parâmetros: id (path, obrigatório); msgId (path, obrigatório)
Respostas: 200 message/rfc822; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/raw' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/messages/{msgId}/rescan
Reexaminar agora uma mensagem pendente ou não verificada (ADR-0087)
Onde é usada: POST /mailboxes/{id}/messages/{msgId}/rescan.
Parâmetros: id (path, obrigatório); msgId (path, obrigatório)
Respostas: 200 veredito; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 409 já verificada; 429 teto de 10 reexames por minuto na caixa (Retry-After); 503 antivírus desligado neste ambiente ou indisponível (Retry-After)

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/msgId_AQUI/rescan' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/messages/batch
Aplicar a mesma alteração a várias mensagens
Onde é usada: POST /mailboxes/{id}/messages/batch. # A resposta diz o que NÃO foi feito Id que não é desta caixa volta em `negados`. Não é aplicado — e também não é ignorado em silêncio: a tela precisa poder dizer "3 de 5 movidas" em vez de mostrar cinco linhas somindo e duas voltando no próximo carregamento (piso 4). O status é 200 mesmo com negados: a operação aconteceu, parcialmente, e a lista dos dois lados é a resposta — um 4xx obrigaria o cliente a adivinhar o que foi aplicado.
Parâmetros: id (path, obrigatório)
Respostas: 200 aplicado (possivelmente em parte); 400 lista vazia, mais de 500, ou patch sem campo; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/batch' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/messages/labels
Aplicar/remover etiquetas em lote (até 500 mensagens × 20 etiquetas)
Onde é usada: POST /mailboxes/{id}/messages/labels (barra de lote e atalho `l`).
Saídas: 200 {vinculadas, desvinculadas}; 400 lote inválido; 404 caixa alheia.
Parâmetros: id (path, obrigatório)
Respostas: 200 feito; 400 lote vazio, grande demais, id malformado ou a mesma etiqueta nos dois lados; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/labels' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/messages/parecidos
Filtrar parecidos — o que as mensagens escolhidas têm em comum, como critérios de busca
Parâmetros: id (path, obrigatório)
Respostas: 200 critérios; 400 sem ids; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/messages/parecidos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/pgp/keys
ListarChavesPGP devolve as chaves públicas da caixa (fingerprint + uid, sem o
Onde é usada: GET /mailboxes/{id}/pgp/keys.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/pgp/keys' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/pgp/keys
valida o bloco armored no servidor (é chave PÚBLICA? qual a fingerprint?), deriva fingerprint/uid e faz UPSERT por (caixa, endereço).
Onde é usada: POST /mailboxes/{id}/pgp/keys {email, public_key, is_own}. A fingerprint devolvida é a DERIVADA aqui — a pessoa a confere fora de banda.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/pgp/keys' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /mailboxes/{id}/pgp/keys/{keyId}
ApagarChavePGP remove uma chave da caixa.
Onde é usada: DELETE .../pgp/keys/{keyId}.

curl -X DELETE 'https://api.mail.asender.net/mailboxes/id_AQUI/pgp/keys/keyId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mailboxes/{id}/recipients/suggest
Autocomplete de destinatários (catálogo + histórico)
Onde é usada: GET /mailboxes/{id}/recipients/suggest?q=. Combina o catálogo e o histórico de mensagens da caixa (ver store.SugerirDestinatarios).
Parâmetros: id (path, obrigatório); q (query)
Respostas: 200 sugestões; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/recipients/suggest' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/restaurar
exige administrador; acha a removida (404 se ativa/inexistente/outro tenant); 409 `EnderecoEmUso` se uma caixa ativa já tomou o endereço e 409 `DominioRemovido` se o domínio saiu da conta. As mensagens retidas na quarentena para o endereço são ENTREGUES na caixa (idempotente) e a ação é auditada (ator).
Onde é usada: POST /mailboxes/{id}/restaurar.
Saídas: 200 {restored, mailbox, retidas_entregues, retidas_pendentes?}.

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/restaurar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /mailboxes/{id}/send
Enviar a partir de uma caixa específica
Onde é usada: POST /mailboxes/{id}/send. Fluxo: JSON -> outbound.Service.Enviar (assina d=domínio) -> relay /raw.
Parâmetros: id (path, obrigatório)
Respostas: 202 enviado; 401 API key ausente ou inválida.; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).; 422 malware num anexo (`AnexoInfectado`); nada foi enviado (ADR-0087); 503 mensagem com anexo e antivírus fora (`AntivirusIndisponivel`, Retry-After); o rascunho fica

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/signature
Ler a assinatura da caixa
Onde é usada: GET /mailboxes/{id}/signature — a aba Assinatura das configurações e o compositor, que a injeta numa composição nova.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/signature' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /mailboxes/{id}/signature
Gravar a assinatura da caixa (sanitizada no servidor)
Onde é usada: PUT /mailboxes/{id}/signature, corpo {"signature_html": "..."}. Devolve a assinatura COMO FICOU GRAVADA (já sanitizada), para a tela mostrar exatamente o que passou a valer — e não o que a pessoa digitou.
Parâmetros: id (path, obrigatório)
Respostas: 200 gravada; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X PUT 'https://api.mail.asender.net/mailboxes/id_AQUI/signature' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/threads/{threadId}
Conversa agrupada (threading, M-C)
Onde é usada: GET /mailboxes/{id}/threads/{threadId}. Cross-caixa/tenant -> 404 (a thread de outra caixa não é alcançável mesmo com o uuid). Marca a conversa como lida (best-effort) — abrir a thread é ler.
Parâmetros: id (path, obrigatório); threadId (path, obrigatório)
Respostas: 200 ok; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/threads/threadId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mailboxes/{id}/threads/{threadId}/labels
Aplicar/remover etiquetas em todas as mensagens de uma conversa
Onde é usada: POST /mailboxes/{id}/threads/{threadId}/labels (leitura em conversa).
Saídas: 200 {vinculadas, desvinculadas}; 400; 404 (caixa ou conversa alheia).
Parâmetros: id (path, obrigatório); threadId (path, obrigatório)
Respostas: 200 feito; 400 pedido malformado; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X POST 'https://api.mail.asender.net/mailboxes/id_AQUI/threads/threadId_AQUI/labels' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /mailboxes/{id}/tipo
Mudar o tipo da caixa (pessoal ↔ coletiva)
Onde é usada: PUT /mailboxes/{id}/tipo (a tela da caixa no admin, U6).
Parâmetros: id (path, obrigatório)
Respostas: 200 caixa atualizada (com tipo e origem); 400 tipo inválido; 403 não é uma pessoa admin do e-mail; 404 caixa inexistente ou de outra conta; 422 inelegível ou assinada

curl -X PUT 'https://api.mail.asender.net/mailboxes/id_AQUI/tipo' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /mailboxes/{id}/vacation
LerFerias devolve a regra de férias da caixa (o padrão quando não há).
Onde é usada: GET /mailboxes/{id}/vacation.

curl -X GET 'https://api.mail.asender.net/mailboxes/id_AQUI/vacation' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /mailboxes/{id}/vacation
valida a janela e faz UPSERT.
Onde é usada: PUT /mailboxes/{id}/vacation. A auto-resposta em si é um ENVIO no recebimento e passa pelo guard do piso 18; aqui só se guarda a REGRA.

curl -X PUT 'https://api.mail.asender.net/mailboxes/id_AQUI/vacation' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/conexoes
ListarConexoes devolve as conexões da caixa `?mailbox_id=`.
Onde é usada: GET /v1/conexoes. Respostas: 200 {conexoes:[…]} (sem segredo); 400 sem/inválido mailbox_id; 403; 404.

curl -X GET 'https://api.mail.asender.net/v1/conexoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/conexoes
CriarConexao cifra o segredo e guarda a conexão.
Onde é usada: POST /v1/conexoes. Respostas: 201 (a conexão, sem segredo); 400 ValidationError; 403; 404; 409 LimiteDeConexoes; 429; 503.

curl -X POST 'https://api.mail.asender.net/v1/conexoes' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /v1/conexoes/{id}
AlterarConexao aplica o PATCH.
Onde é usada: PATCH /v1/conexoes/{id}. `segredo` ausente/vazio mantém o segredo guardado; trocar servidor, porta, segurança ou usuário exige informá-lo de novo (400). Respostas: 200 (a conexão, sem segredo); 400; 403; 404; 429.

curl -X PATCH 'https://api.mail.asender.net/v1/conexoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/conexoes/{id}
RemoverConexao apaga a conexão e o segredo de verdade (exceção a "nada se apaga": é credencial). NÃO toca o
Onde é usada: DELETE /v1/conexoes/{id}. Respostas: 204; 403; 404; 429.

curl -X DELETE 'https://api.mail.asender.net/v1/conexoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/conexoes/{id}/testar
TestarConexao conecta no provedor com a conexão guardada, autentica e lista as pastas, e grava o resultado
Onde é usada: POST /v1/conexoes/{id}/testar. Respostas: 200 {ok:true,folders,conexao} ou 200 {ok:false,error_code} (DestinoBloqueado|AutenticacaoFalhou|CertificadoInvalido|ProvedorIndisponivel|…); 429; 500.

curl -X POST 'https://api.mail.asender.net/v1/conexoes/id_AQUI/testar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/emails
Enviar e-mail a partir de uma caixa da conta (público)
Onde é usada: POST /v1/emails. Fluxo: API key -> tenant -> caixa por endereço -> outbound -> relay /raw.
Parâmetros: Idempotency-Key (header)
Respostas: 200 replay idempotente (já enviado antes).; 202 aceito e entregue.; 400 validação (from inválido, to vazio, header-injection em endereço, anexo inválido).; 401 API key ausente ou inválida.; 403 `InsufficientScope` — a chave não tem o escopo `email:send` (sem escopos, `full_access`, `send_only` e `emails:*` também caem aqui).; 422 o antivírus encontrou malware num anexo (`AnexoInfectado`); nada foi enviado (ADR-0087).; 429 Limite de disparos do plano atingido no período. Os cabeçalhos dizem qual janela barrou e quando reabre.; 502 envio recusado (piso 18 fora de prd) ou a entrega falhou; a quota é estornada.; 503 envio não configurado no serviço (boot sem outbound), ou mensagem COM anexo com o antivírus configurado e fora (`AntivirusIndisponivel`, com Retry-After) — nada sai sem exame.

curl -X POST 'https://api.mail.asender.net/v1/emails' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/lixeira/{tipo}/{id}/enviar-admin
tira da vista do usuario SEM encurtar os 180d; Idempotency-Key OBRIGATORIA; nenhum parametro reduz o prazo;
Onde é usada: botao "enviar para a administrativa").

curl -X POST 'https://api.mail.asender.net/v1/lixeira/tipo_AQUI/id_AQUI/enviar-admin' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/resumo
Resumo da ferramenta para o hub e a home (contrato comum de resumo).
Onde é usada: hub (`asender_plataforma_bff` /api/resumo) e a Visão geral do webmail.
Efeitos: duas leituras (store.ResumoDoUsuario), nenhuma escrita. Tenant e usuário vêm do principal que o middleware verificou — nunca da query.
Parâmetros: periodo (query)
Respostas: 200 o resumo da ferramenta `mail`.; 400 Parâmetro de query fora do conjunto aceito.; 401 API key ausente ou inválida.; 403 membro da conta sem acesso a esta ferramenta.; 404 Recurso inexistente ou fora do escopo da chave (não revela existência em outra conta).

curl -X GET 'https://api.mail.asender.net/v1/resumo' \
  -H 'Authorization: Bearer SEU_TOKEN'



==============================================================================
# Identidade (OIDC / OAuth 2.1)  (https://auth.asender.net)
==============================================================================

# Identidade — OIDC / OAuth 2.1

O **Authorization Server** do Asender. É daqui que sai o token que todas as
outras APIs exigem: seu app não guarda a senha de ninguém nem valida um segundo
fator — ele delega o login para `auth.asender.net` pelo fluxo padrão
**OpenID Connect / OAuth 2.1 + PKCE** e recebe de volta dois tokens: um que
prova **quem** logou (o ID token) e um que **abre as APIs** (o access token).

- **Base URL:** `https://auth.asender.net`
- **Perfil:** OAuth 2.1 — Authorization Code **com PKCE `S256` obrigatório**.
  Sem *implicit*, sem *password grant*, sem `plain`.
- **Assinatura:** RS256. As chaves públicas ficam no JWKS; você valida os tokens
  sozinho, sem chamar o servidor a cada request.

> **É só isto que é público.** Esta página cobre os 6 endpoints de protocolo que
> um integrador usa. O resto do serviço de identidade (usuários, sessões, 2FA,
> autorização por ferramenta) é control plane interno, reservado aos serviços da
> casa — não é superfície de integração e não se documenta aqui.

## Antes de começar: registre um client

Um **client** é o seu app do ponto de vista do login. Cada client tem um
`client_id` e uma **allowlist EXATA de `redirect_uri`** — a comparação é
caractere a caractere, sem curinga, porque é ela que impede que um code de login
seja desviado para um endereço que não é seu.

- **Client público** (SPA, mobile, CLI): não tem segredo. Quem prova que a troca
  do code é legítima é o **PKCE**. É o caso da maioria das integrações.
- **Client confidencial** (backend que guarda segredo com segurança): autentica
  no `/token` por HTTP Basic (`client_secret_basic`) ou pelos campos do corpo.

O registro do client (id, redirect_uris, post-logout, tipo) é feito pela equipe
da plataforma. Peça com: os `redirect_uri` exatos, se é público ou confidencial,
e os `post_logout_redirect_uri`.

## Discovery: descubra os endpoints, não os crave

O primeiro request de um client bem-feito é o de **discovery**. Em vez de cravar
URLs, leia-as de:

```bash
curl 'https://auth.asender.net/.well-known/openid-configuration'
```

```json
{
  "issuer": "https://auth.asender.net",
  "authorization_endpoint": "https://auth.asender.net/authorize",
  "token_endpoint": "https://auth.asender.net/token",
  "userinfo_endpoint": "https://auth.asender.net/userinfo",
  "jwks_uri": "https://auth.asender.net/.well-known/jwks.json",
  "end_session_endpoint": "https://auth.asender.net/logout",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"]
}
```

Toda biblioteca OIDC séria consome esse documento — aponte a sua para o `issuer`
`https://auth.asender.net` e ela se autoconfigura. O documento é cacheável
(`Cache-Control: public, max-age=300`); só muda em deploy ou rotação de chave.

### Escopos

| escopo | o que traz |
| --- | --- |
| `openid` | **obrigatório** — é o que faz o fluxo ser OIDC; é sempre garantido |
| `profile` | o `name` do usuário no ID token / `/userinfo` |
| `email` | o `email` e o `email_verified` |
| `offline_access` | **um `refresh_token`** — peça só se o app precisa agir com a sessão fora da presença do usuário |

## O fluxo, passo a passo (Authorization Code + PKCE)

### 1. Gere o par PKCE

Antes de mandar o usuário para o login, gere um `code_verifier` aleatório
(43–128 caracteres, base64url) e o seu `code_challenge`:

```
code_verifier  = base64url(random 32 bytes)
code_challenge = base64url( SHA-256( code_verifier ) )
```

Guarde o `code_verifier` do lado do app (na sessão do browser, por exemplo).
Gere também um `state` aleatório (anti-CSRF) e, opcionalmente, um `nonce`
(anti-replay do ID token). **`state` e `nonce` vêm de um CSPRNG**, nunca de
`Math.random()`.

### 2. Mande o browser para `/authorize`

Redirecione o usuário (navegação de browser, não `fetch`) para:

```
https://auth.asender.net/authorize
  ?response_type=code
  &client_id=app-exemplo
  &redirect_uri=https://app.exemplo.com.br/callback
  &scope=openid%20profile%20email%20offline_access
  &state=xyz123
  &nonce=n-0S6_WzA2Mj
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
```

O servidor valida o `client_id` e a `redirect_uri`, reaproveita a sessão do
usuário no domínio de auth (ou o manda logar e volta) e redireciona de volta ao
seu `redirect_uri`:

```
https://app.exemplo.com.br/callback?code=cod_9f8e7d…&state=xyz123
```

**Confira o `state`** antes de qualquer coisa: se não for o que você enviou,
aborte. Se o login falhar depois da validação do redirect, a volta traz
`?error=…&error_description=…&state=…` em vez do `code`.

### 3. Troque o `code` por tokens em `/token`

Do **backend** (ou BFF), troque o code pelos tokens, provando o PKCE com o
`code_verifier` que você guardou. Corpo `x-www-form-urlencoded`:

```bash
curl -X POST 'https://auth.asender.net/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=cod_9f8e7d…' \
  -d 'redirect_uri=https://app.exemplo.com.br/callback' \
  -d 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \
  -d 'client_id=app-exemplo'
```

Resposta `200` (`Cache-Control: no-store`):

```json
{
  "access_token": "eyJhbGciOiJSUzI1Ni…",
  "token_type": "Bearer",
  "expires_in": 900,
  "id_token": "eyJhbGciOiJSUzI1Ni…",
  "refresh_token": "rft_1a2b3c…",
  "scope": "openid profile email offline_access"
}
```

O `redirect_uri` aqui tem de ser **idêntico** ao do passo 2 (o servidor amarra o
code àquele valor — é o que barra a injeção de code). O `refresh_token` só vem se
o scope pediu `offline_access`. Client confidencial acrescenta a autenticação:

```bash
  -u 'app-exemplo:CLIENT_SECRET'      # HTTP Basic (client_secret_basic)
```

## Os dois tokens, e o que fazer com cada um

O `/token` devolve **dois** JWT RS256, e a diferença entre eles é de segurança,
não de detalhe:

- **ID token** (`id_token`) — prova **quem** logou. É para o SEU app consumir:
  valide-o e leia os claims (`sub`, `email`, `name`). **Nunca** o mande para uma
  API como credencial.
- **Access token** (`access_token`) — é a **credencial** para chamar as APIs do
  Asender. Vai em `Authorization: Bearer …`. Traz `tok_use: "access"`; o
  `/userinfo` e as APIs recusam um ID token apresentado no lugar dele.

### Validar o ID token (faça no client)

Não confie num token só porque ele chegou. Valide, nesta ordem:

1. **Assinatura** — pegue a chave do JWKS (`/.well-known/jwks.json`) cujo `kid`
   casa com o header do token; verifique a assinatura **RS256**. Rejeite
   qualquer `alg` fora de `RS256` (nunca aceite `none`).
2. **`iss`** — exatamente `https://auth.asender.net`.
3. **`aud`** — exatamente o seu `client_id`.
4. **`exp` / `nbf`** — dentro da validade.
5. **`nonce`** — igual ao que você enviou no `/authorize`.

```bash
curl 'https://auth.asender.net/.well-known/jwks.json'
```

```json
{ "keys": [ { "kty": "RSA", "use": "sig", "alg": "RS256", "kid": "2026-08a", "n": "0vx7…", "e": "AQAB" } ] }
```

Cacheie o JWKS e recarregue quando aparecer um `kid` desconhecido — é assim que
uma **rotação de chave** funciona sem downtime: a chave nova entra no JWKS antes
de ser usada, e a antiga fica até os tokens que ela assinou expirarem. Uma boa
biblioteca OIDC faz tudo isto para você a partir do `issuer`.

Claims disponíveis no ID token: `sub`, `iss`, `aud`, `exp`, `iat`, `nonce`,
`auth_time`, `email`, `name`, `tenant`. O **`sub` é o ID interno imutável** do
usuário — é por ele que você o identifica no seu lado, **nunca pelo e-mail**
(uma pessoa pode ter vários e-mails, e o primário pode mudar).

### `/userinfo` — o perfil a partir do access token

Alternativa (ou complemento) ao ID token para hidratar o perfil:

```bash
curl 'https://auth.asender.net/userinfo' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1Ni…'
```

```json
{ "sub": "usr_01J…", "email": "pessoa@empresa.com.br", "email_verified": true, "name": "Fulana" }
```

Bearer ausente, inválido, expirado — ou um ID token no lugar do access — devolve
`401 invalid_token`.

## Manter a sessão viva: refresh token

Com `offline_access`, você recebe um `refresh_token` opaco. Quando o access
expirar (`expires_in`), troque o refresh por tokens novos:

```bash
curl -X POST 'https://auth.asender.net/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=rft_1a2b3c…' \
  -d 'client_id=app-exemplo'
```

**Rotação com detecção de reuso.** Cada refresh é de **uso único**: usá-lo
invalida aquele e devolve um novo — guarde sempre o mais recente. Se um refresh
já usado for reapresentado (sinal clássico de token roubado), o servidor
**revoga a família inteira** e responde `400 invalid_grant`; a partir daí, o
usuário precisa logar de novo. Trate `invalid_grant` no refresh como "recomece o
fluxo do `/authorize`", não como erro a repetir.

## Sair: logout

Para encerrar a sessão, mande o browser ao `end_session_endpoint`:

```
https://auth.asender.net/logout
  ?client_id=app-exemplo
  &post_logout_redirect_uri=https://app.exemplo.com.br/adeus
  &state=xyz123
```

O logout é **server-side e irreversível** (piso 17): revoga a sessão e a família
de refresh, não só apaga o cookie — um refresh emitido antes não volta a valer.
O redirecionamento só vai para o `post_logout_redirect_uri` se ele estiver na
allowlist do client; senão, cai na tela de login.

## Erros

`/token` e `/userinfo` usam o envelope OAuth (`{ "error", "error_description" }`).
No `/authorize`, o erro volta por `302` com `?error=` **depois** que a
`redirect_uri` foi validada; antes disso (client/redirect desconhecidos) a falha
é mostrada, não redirecionada — devolver a uma URI não registrada seria
open-redirect.

| `error` | onde | quando |
| --- | --- | --- |
| `invalid_request` | `/authorize`, `/token` | falta PKCE `S256`, parâmetro ou corpo inválido |
| `unsupported_response_type` | `/authorize` | `response_type` ≠ `code` |
| `invalid_client` | `/authorize`, `/token` | `client_id` desconhecido ou client não autenticado (`401` no `/token`) |
| `unsupported_grant_type` | `/token` | `grant_type` fora de `authorization_code`/`refresh_token` |
| `invalid_grant` | `/token` | code/refresh inválido, expirado, já usado; `redirect_uri`/PKCE não conferem; refresh reusado (família revogada) |
| `invalid_token` | `/userinfo` | access token ausente/inválido, ou um ID token no lugar dele |
| `server_error` | `/authorize`, `/token` | falha interna ao emitir |

## Checklist de integração segura

- Cliente OIDC que consome o **discovery** e o **JWKS**, apontado para o
  `issuer` `https://auth.asender.net` — não crave URLs nem chaves.
- **PKCE `S256`** sempre; `state` e `nonce` de CSPRNG, conferidos na volta.
- Valide o ID token por inteiro (assinatura RS256 + `iss` + `aud` + `exp` +
  `nonce`); rejeite `alg` fora de RS256.
- Identifique o usuário pelo **`sub`**, nunca pelo e-mail.
- O **access token** chama as APIs; o **ID token** fica no app. Não troque os
  papéis.
- A troca do `code` e o `refresh` moram no **backend/BFF**; guarde o refresh mais
  recente e trate `invalid_grant` como "refaça o login".



------------------------------------------------------------------------------
## GUIA DA API: Entrar com Asender (apps de terceiro)  (https://developers.asender.net/guias/entrar-com-asender.html)
------------------------------------------------------------------------------

# Entrar com Asender

"Entrar com Asender" deixa o seu app (site, SaaS, integração) identificar um
usuário Asender e, com o consentimento dele, **ler dados de uma conta Asender**
pela API pública, com escopos mínimos. O usuário clica no botão e, se já estiver
logado na Asender e já tiver autorizado o app antes, volta para o seu app em um
redirect, sem tela intermediária.

- **Servidor de autorização:** `https://auth.asender.net` (OIDC / OAuth 2.1)
- **API de recursos:** `https://api.asender.net/v1`
- **Perfil:** Authorization Code + **PKCE `S256` obrigatório**, client
  **confidencial** (`client_secret_basic`) ou **público** (sem segredo), `redirect_uri` exata.

> Este guia é para apps de terceiro. Para o login OIDC genérico (fronts e
> integrações próprias), veja o guia de Identidade. Os valores aqui vêm do código
> do servidor de autorização; confira sempre o discovery
> (`/.well-known/openid-configuration`) antes de cravar um endereço.

## 1. Como o seu app é cadastrado

Você mesmo cadastra o app no painel, em `https://admin.asender.net`, na conta
que será a dona dele: **Desenvolvedores > Aplicativos** (só owner e admin da conta).
O guia de [Aplicativos](https://developers.asender.net/guias/aplicativos.html) descreve
cada campo, os limites e o ciclo de vida. Ao criar, você recebe:

- `client_id`;
- `client_secret`, **só para app confidencial**, mostrado uma única vez (se perder,
  gire o segredo no painel: o antigo deixa de valer na hora).

Para o cadastro, informe: nome do app, site (`site_url`), logo, os **`redirect_uri`
exatos** (sem curinga) e os escopos de que precisa. O `client_secret` fica **só no
seu backend** (cofre ou variável de ambiente do servidor), nunca no navegador, em
app mobile, repositório ou log. Apps que não conseguem guardar segredo (SPA, mobile,
CLI) escolhem o tipo **público**: sem `client_secret`, só PKCE.

**Publicação e revisão.** O app nasce em **desenvolvimento**: só membros da sua conta
e testadores convidados conseguem autorizá-lo, o que basta para integrar e testar.
Para abri-lo a qualquer usuário Asender, peça **revisão** no painel; a equipe Asender
avalia e, aprovado, o app vira **publicado** e **verificado**. Até lá, usuários de
fora recebem o aviso de indisponível. Detalhes em
[Aplicativos](https://developers.asender.net/guias/aplicativos.html).

O app só consegue pedir os escopos declarados no cadastro (e, depois de publicado,
os aprovados na revisão). Pedir além disso retorna `invalid_scope`.

## 2. O fluxo, passo a passo

### 2.1 Descubra os endpoints

```bash
curl -s https://auth.asender.net/.well-known/openid-configuration
```

Campos que importam: `authorization_endpoint` (`/authorize`), `token_endpoint`
(`/token`), `revocation_endpoint` (`/oauth/revoke`), `introspection_endpoint`
(`/oauth/introspect`), `jwks_uri`, `scopes_supported`,
`code_challenge_methods_supported` (`S256`),
`authorization_response_iss_parameter_supported` (`true`) e
`prompt_values_supported` (`none`, `login`, `consent`).

### 2.2 Gere `state`, `nonce` e o par PKCE (no backend)

Use um gerador criptográfico (CSPRNG), nunca `Math.random()`.

```bash
CODE_VERIFIER=$(openssl rand -base64 48 | tr -d '=+/\n' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)
NONCE=$(openssl rand -hex 16)
```

Guarde `CODE_VERIFIER`, `STATE` e `NONCE` **no servidor, ligados à sessão do
navegador do usuário** (cookie de sessão do seu app, `HttpOnly`, `Secure`,
`SameSite=Lax`). O `code_verifier` nunca vai na URL.

### 2.3 Mande o usuário para `/authorize`

```http
GET https://auth.asender.net/authorize
  ?response_type=code
  &client_id=<CLIENT_ID>
  &redirect_uri=https%3A%2F%2Fapp.exemplo.com%2Fcallback
  &scope=openid%20profile%20email%20offline_access%20leads%3Aread%20conversions%3Aread
  &state=<STATE>
  &nonce=<NONCE>
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
```

| parâmetro | obrigatório | nota |
| --- | --- | --- |
| `response_type` | sim | sempre `code` |
| `client_id` | sim | o seu |
| `redirect_uri` | sim | igual, caractere a caractere, a uma cadastrada |
| `scope` | sim | separado por espaço; `openid` é sempre incluído; veja o catálogo na seção 4 |
| `state` | sim | anti-CSRF; volta igual no redirect |
| `nonce` | recomendado | volta no ID token; confira |
| `code_challenge` / `code_challenge_method` | sim | somente `S256` |
| `prompt` | não | `none`, `login` ou `consent` (veja abaixo) |

O que o usuário vê:

1. **Sem sessão Asender:** vai ao login (com 2º fator, passkey etc.) e volta.
2. **Primeiro acesso do seu app (ou escopos novos):** tela de **consentimento**
   mostrando o seu app, os escopos em português e **a conta** em que o app vai
   operar. Ele aprova ou nega.
3. **Já autorizou antes e a sessão está viva:** redirect imediato (o "1 clique").

`prompt`:

- `none`: nunca mostra tela. Se faltar login, volta `error=login_required`; se
  faltar consentimento, `error=consent_required`. Não combine com outros valores.
- `consent`: força a tela de consentimento, mesmo com consentimento lembrado (use
  para trocar de conta ou ampliar escopos).
- `login`: força um novo login.

### 2.4 Receba o redirect e confira `iss` e `state`

Sucesso:

```
https://app.exemplo.com/callback?code=<CODE>&state=<STATE>&iss=https%3A%2F%2Fauth.asender.net
```

Erro:

```
https://app.exemplo.com/callback?error=access_denied&error_description=...&state=<STATE>&iss=https%3A%2F%2Fauth.asender.net
```

Antes de qualquer coisa, no seu backend:

1. `state` igual ao guardado (e descarte-o: uso único);
2. **`iss` igual a `https://auth.asender.net`.** O servidor publica
   `authorization_response_iss_parameter_supported` (RFC 9207). Conferir impede o
   ataque de *mix-up*, em que um servidor malicioso faz o seu app enviar o code
   (e o `code_verifier`) para o lugar errado. Se `iss` faltar ou divergir,
   aborte sem trocar o code.

O `code` vale **60 segundos** e é de uso único.

### 2.5 Troque o code em `/token`

Autentique com `client_secret_basic` (Basic de `client_id:client_secret`),
**somente do seu backend**:

```bash
curl -s https://auth.asender.net/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://app.exemplo.com/callback" \
  -d code_verifier="$CODE_VERIFIER"
```

A resposta traz `access_token`, `id_token`, `token_type`, `expires_in` e, se
`offline_access` foi concedido, `refresh_token`. Valide o ID token (assinatura pelo
JWKS, `iss`, `aud` igual ao seu `client_id`, `exp` e o `nonce` guardado).

### 2.6 O access token

JWT RS256. Claims do token de app de terceiro:

| claim | significado |
| --- | --- |
| `iss` | `https://auth.asender.net` |
| `sub` | id público do usuário (imutável; **nunca** use e-mail como id) |
| `aud` | `https://api.asender.net` (o recurso, não o seu client) |
| `azp` | o seu `client_id` |
| `tenant` | a conta escolhida pelo usuário (`acc_...`) |
| `scope` | escopos efetivos, separados por espaço |
| `ext` | `true`: token de terceiro |
| `jti`, `iat`, `exp` | id, emissão e expiração (**15 minutos**) |

Trate o token como string opaca e envie no header; leia `scope` e `tenant` só para
decidir o que mostrar. Quem autoriza é a API.

```bash
curl -s https://api.asender.net/v1/account -H "Authorization: Bearer $ACCESS_TOKEN"
```

A API cruza três coisas: o escopo do token, a conta (`tenant`) e o que o próprio
usuário pode ver **naquela conta**. O escopo só restringe, nunca amplia: se o
usuário sair da conta ou perder o papel, o app perde o acesso em até cerca de um
minuto.

> Um token de app de terceiro **não** vale como sessão do usuário em nenhuma outra
> parte da Asender (painel, APIs internas das ferramentas). Só serve na API
> pública, dentro dos escopos.

## 3. Refresh, revogação e introspecção

### Refresh com rotação

O access token dura 15 min. Para continuar sem o usuário presente, peça
`offline_access` e use o refresh token (a validade é definida por app no
cadastro; para o owiew, 90 dias). O refresh fica preso ao **consentimento**, não ao
navegador: o app segue sincronizando depois que o usuário fecha a aba.

```bash
curl -s https://auth.asender.net/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"
```

Regras:

- **Cada refresh é de uso único.** A resposta traz um refresh token novo:
  **grave-o antes de usar o novo access token** (transação atômica no seu banco).
- **Reuso derruba tudo.** Apresentar um refresh já usado revoga **todos** os
  refresh daquele consentimento, e o app precisa pedir autorização de novo. Por
  isso serialize os refreshes (um por vez por conta conectada, com lock) e não
  reenvie um refresh por retry cego depois de um timeout sem saber se o primeiro
  foi aplicado: se houver dúvida, refaça o login.
- Antes de cada refresh o servidor reconfere se o consentimento continua vigente e
  se o usuário ainda pertence à conta. Se não, `invalid_grant`.

### Revogar (RFC 7009)

```bash
curl -s https://auth.asender.net/oauth/revoke \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN" -d token_type_hint=refresh_token
```

Use ao desconectar a conta no seu app. O usuário também revoga em "Apps
conectados", na conta Asender; nesse caso o próximo refresh retorna
`invalid_grant`: marque a conexão como encerrada e peça para reconectar.

### Introspecção (RFC 7662)

Somente para client confidencial autenticado:

```bash
curl -s https://auth.asender.net/oauth/introspect \
  -u "$CLIENT_ID:$CLIENT_SECRET" -d token="$TOKEN"
```

Devolve `{"active": false}` para token inválido, expirado ou revogado; se ativo,
traz `scope`, `client_id`, `sub`, `exp`, `iat`, `iss`, `aud`, `tenant` e `jti`. Use
pontualmente (diagnóstico), não a cada chamada de dados.

## 4. Catálogo de escopos

Peça **o mínimo necessário**. O usuário vê estes rótulos na tela de consentimento.

| escopo | descrição |
| --- | --- |
| `openid` | Confirmar quem é o usuário (necessário para entrar). |
| `profile` | Ver o nome do perfil. |
| `email` | Ver o e-mail principal. |
| `offline_access` | Continuar conectado em segundo plano (emite refresh token). |
| `account:read` | Nome e dados cadastrais da conta escolhida. |
| `leads:read` | Contatos do CRM e envios de formulário da conta. |
| `conversions:read` | Eventos de conversão e entregas para Meta, Google e TikTok. |
| `forms:read` | Formulários da conta e suas configurações. |
| `analytics:read` | Métricas de páginas e formulários. |
| `campaigns:read` | Campanhas de e-mail marketing e relatórios. |
| `email:read` | Mensagens e eventos de e-mail da conta. |
| `messaging:read` | Mensagens e relatórios de SMS, WhatsApp e push. |
| `conversations:read` | Conversas de atendimento. |
| `journeys:read` | Jornadas de automação. |
| `logs:read` | Registros de chamadas e eventos da conta. |
| `webhooks:manage` | Criar e remover webhooks da conta (planejado). |
| `leads:write` | Criar e atualizar contatos e leads (planejado). |

A lista viva está em `scopes_supported` do discovery. O escopo efetivo do token é
**pedido, limitado ao liberado para o seu app e ao concedido pelo usuário**;
confira o claim `scope` do que realmente veio.

## 5. O botão e o "1 clique"

Faça o botão apontar para **o seu endpoint** (`/auth/asender/login`), que gera
`state`/`nonce`/PKCE, grava na sessão e responde `302` para o `/authorize`. O botão
nunca monta o `/authorize` no navegador: o `code_verifier` e o `client_secret` não
podem passar por lá.

```html
<a class="btn-asender" href="/auth/asender/login">Entrar com Asender</a>
```

Para a experiência de 1 clique:

- No primeiro login, use o fluxo normal, **sem `prompt`**: ele mostra login e
  consentimento quando necessário, e o consentimento fica lembrado.
- Se a sessão Asender estiver viva e o consentimento lembrado cobrir os escopos
  pedidos, o `/authorize` responde direto com o code, sem nenhuma tela.
- Para tentar uma entrada silenciosa (por exemplo, ao abrir o app), use
  `prompt=none` e trate `login_required`/`consent_required` mostrando o botão
  normal.
- Pedir um escopo novo depois exige nova aprovação do usuário (ele vê a tela).

## 6. Escolha de conta

**Um token = um usuário + uma conta.** A conta é escolhida na tela de
consentimento (entre as contas onde o usuário tem permissão) e vai no claim
`tenant`. Para operar outra conta do mesmo usuário, faça um novo `/authorize` com
**`prompt=consent`**, que reabre a escolha, e guarde a nova conexão como outra conta
no seu app (`sub` + `tenant` identificam a conexão). Nunca aceite `tenant` vindo do
cliente: use sempre o da conexão que você gravou.

## 7. Erros

No redirect do `/authorize` (query: `error`, `error_description`, `state`, `iss`):

| `error` | quando | o que fazer |
| --- | --- | --- |
| `invalid_scope` | escopo desconhecido ou não liberado ao app | corrija o pedido; peça liberação ao time Asender |
| `access_denied` | o usuário negou | respeite; não insista em loop |
| `login_required` | `prompt=none` sem sessão | mostre o botão e reinicie sem `prompt=none` |
| `consent_required` | `prompt=none` sem consentimento que cubra os escopos | idem |
| `invalid_request` | parâmetro faltando ou inválido; `prompt=none` combinado com outro valor | corrija |
| `temporarily_unavailable` / `server_error` | falha momentânea | tente de novo depois, com espera |

Se o `redirect_uri` ou o `client_id` forem inválidos, o servidor **não** redireciona
(mostra o erro ao usuário): isso é erro de cadastro.

No `/token`, `/oauth/revoke` e `/oauth/introspect` (JSON com `error` e
`error_description`):

| HTTP | `error` | causa comum |
| --- | --- | --- |
| 400 | `invalid_grant` | code expirado ou já usado; `redirect_uri` ou PKCE não conferem; refresh inválido, expirado, **reusado** ou revogado; usuário revogou o app ou saiu da conta |
| 400 | `invalid_request` / `unsupported_grant_type` | corpo malformado, grant não suportado |
| 401 | `invalid_client` | `client_id`/`client_secret` errados, ou introspecção por client que não é confidencial |
| 5xx | `server_error` | falha; refaça com espera (em `503` na conferência do acesso o refresh não é consumido) |

`invalid_grant` no refresh significa: encerre a conexão e peça ao usuário para
entrar de novo.

## 8. Segurança (checklist)

- `client_secret` e refresh tokens **só no backend**, cifrados em repouso; nunca em
  `NEXT_PUBLIC_*`, bundle, app mobile ou repositório.
- `redirect_uri` exata e fixa; sem redirect aberto no seu callback.
- `state` (CSRF), `nonce` (replay do ID token) e PKCE `S256` com `code_verifier`
  gerado por CSPRNG, todos por tentativa e de uso único.
- Confira `iss` na volta e no ID token.
- **Nunca** coloque token em URL, query, log, mensagem de erro, analytics ou
  rastreador de erros. Redija o header `Authorization` nos logs.
- HTTPS sempre; valide o ID token antes de confiar no `sub`.
- Identifique o usuário por `sub`, não por e-mail (ele pode ter vários).
- Ao receber `invalid_grant` no refresh, pare de tentar e peça nova autorização.

## 9. Lendo dados: a API pública

Base: `https://api.asender.net/v1`, com `Authorization: Bearer <access_token>`. A
conta vem do token; **não** há header nem parâmetro de conta.

### Convenções das rotas de dados

- Somente leitura (`GET`), JSON em `snake_case`.
- Lista: `{"data": [...], "next_cursor": "<opaco>" | null}`.
- `limit`: de 1 a 200 (padrão 50). `cursor`: o `next_cursor` da página anterior,
  opaco e estável; não monte nem interprete.
- Incremental: `updated_after` (RFC 3339) onde o recurso é alterável, ordenado por
  `(updated_at, id)`; `created_after` onde o recurso é imutável.
- Erros: `{"error": {"type": "...", "message": "..."}}`.
- Token ausente, inválido ou expirado: `401`. Escopo ou acesso insuficiente: erro
  de autorização (`403`).

### Sincronização incremental (boas práticas)

1. **Carga inicial:** percorra a lista seguindo `next_cursor` até `null`, com
   `limit=200`. Anote o instante de **início** da carga (`T0`) antes da primeira
   página.
2. **Rodadas seguintes:** peça `updated_after=<marca anterior>` e percorra os
   cursores. Ao terminar com sucesso, grave como nova marca o `T0` daquela rodada
   (não o fim), menos uma pequena folga (por exemplo, 60 s) para não perder
   escritas simultâneas.
3. **Idempotência:** faça upsert pelo `id` do recurso; a folga e os retries geram
   repetição, e isso é esperado.
4. Não recomece do zero por erro transitório: retome do último `cursor` gravado.
5. Espace as rodadas (minutos, não segundos) e não faça varredura completa
   recorrente.
6. **Rate limit:** o limite é por app e conta. Em `429`, espere o tempo do header
   `Retry-After` (segundos) antes de tentar de novo; se não vier, use *backoff*
   exponencial com jitter. Não paralelize além do necessário. Em `5xx`, tente de
   novo com espera crescente.
7. Em `401`, renove o access token (um único refresh, serializado) e repita a
   chamada uma vez.

### Rotas por escopo

Todas as rotas abaixo estão **disponíveis** e aceitam o token de app (e também a chave
`sk_*` com o mesmo escopo). Os campos completos de cada resposta estão na OpenAPI
pública (`/v1/...`, esquema `OAuthBearer`); a tabela traz o que sincronizar.

| escopo | rota | produto exigido do usuário | incremental | campos principais |
| --- | --- | --- | --- | --- |
| `account:read` | `GET /v1/account` | (só a conta) | não | dados da conta, `ClientId` |
| `leads:read` | `GET /v1/leads`, `GET /v1/leads/{id}` | CRM | `updated_after` (`updated_at`) | `id` (id público do lead), `first_name`, `last_name`, `email`, `phone`, `company`, `job_title`, `stage`, `lifecycle`, `source` (`name`, `utm_*`, `referrer`, `domain`, `form_id`), `tags`, `custom_fields`, `created_at`, `updated_at` |
| `forms:read` | `GET /v1/forms` | Páginas | não (lista pequena) | `id`, `name`, `external_id`, `requires_consent`, `legal_basis`, `fields` (`name`, `label`, `type`, `required`, `options`, `key`) |
| `forms:read` | `GET /v1/forms/{id}/submissions` | Páginas | `created_after` (`created_at`) | `id`, `form_id`, `mode`, `fields` (em claro), `source` (`utm_*`, `referrer`), `consent` (`state`, `legal_basis`, `at`), `created_at` |
| `conversions:read` | `GET /v1/conversions` | CRM | `created_after` (`created_at`) | `id`, `lead_id`, `type` (`sent`, `ignored`, `result`), `event`, `value`, `currency`, `platform`, `delivery_status`, `reason`, `source`, `occurred_at`, `created_at` |
| `campaigns:read` | `GET /v1/campaigns` | E-mail Marketing | `updated_after` | `id`, `name`, `status`, `subject`, `recipients`, `sent`, `failed`, `scheduled_at`, `updated_at` |
| `campaigns:read` | `GET /v1/campaigns/{id}` | E-mail Marketing | n/a | o mesmo objeto da campanha, sem envelope |
| `campaigns:read` | `GET /v1/campaigns/{id}/report` | E-mail Marketing | n/a | `data.totals` (enviados, entregues, aberturas, cliques, bounces) |
| `campaigns:read` | `GET /v1/reports/email/overview`, `/timeseries`, `/top-emails`, `/domains` | E-mail Marketing | janela `days` ou `from`+`to`/`period` | `data` com `totals`, `previous`, `points` |
| `email:read` | `GET /v1/emails`, `GET /v1/emails/{id}` | Marketing | `created_after` | formato legado (`PascalCase`) |
| `messaging:read` | `GET /v1/messaging/sms/messages`, `/whatsapp/messages`, `/push/messages` | SMS, WhatsApp ou Push | `created_after` (ordem crescente) | `id`, `to`, `status`, `queued_at`, `created_at` (+ `segments` no SMS, `title` no push) |
| `messaging:read` | `GET /v1/messaging/{sms,whatsapp,push}/reports/overview` | idem | janela `days` | `data` com totais por status |
| `analytics:read` | `GET /v1/analytics/overview`, `/timeseries`, `/breakdown`, `/forms` | Páginas | janela `from`/`to` (até 92 dias) | `totals`, `data[]` (visitas, visualizações, conversões, funil de formulário) |
| `conversations:read` | `GET /v1/conversations` | Atendimento | `updated_after` (atividade, inclusive mensagem nova) | `id`, `channel`, `status`, `lead_id`, `assigned_to`, `updated_at`, `message_count` |
| `conversations:read` | `GET /v1/conversations/{id}/messages` | Atendimento | `created_after` | `id`, `direction`, `author_type`, `text`, `delivery_status`, `sent_at`, `attachment_count` |
| `journeys:read` | `GET /v1/journeys`, `GET /v1/journeys/{id}` | CRM | `updated_after` | `id`, `name`, `active`, `trigger`, `steps`, `stats`, `updated_at` |
| `webhooks:manage`, `leads:write` | gestão e escrita | | | planejado |

Pontos que valem para todas:

- **Nomes em inglês, `snake_case`, em todas as rotas de dados.** As chaves que pertencem à
  conta (`custom_fields` do lead e `fields` de um envio) vêm como a conta as definiu e não
  são traduzidas. Valores de enumeração (como `stage`) são os da conta.
- **Mesmo identificador de lead.** `lead_id` em `/v1/conversions` e em
  `/v1/conversations` é o `id` de `GET /v1/leads`; dá para ligar conversa, conversão e
  lead sem tabela de apoio.
- **Recurso único** (`/v1/leads/{id}`, `/v1/campaigns/{id}`, `/v1/journeys/{id}`) vem
  como objeto, sem envelope. Relatórios agregados vêm em `{"data": {...}}`.
- Id inexistente **ou de outra conta** é sempre `404` idêntico: nunca `403`.
- Conta cujo canal de e-mail ou mensageria ainda não migrou para a ferramenta dedicada
  responde `503` com `Retry-After` (volte depois; o resto da API não é afetado).
- Parâmetro de query desconhecido nas rotas de campanhas, relatórios e mensageria é
  `400` (nada é ignorado em silêncio). Janela acima do teto da rota também é `400`.
- Cada rota exige o escopo correspondente **e** que o usuário que autorizou o app tenha,
  na conta do token, acesso ao produto da coluna "produto exigido" (`403 Forbidden`
  se não tiver; a remoção do usuário passa a valer em até 60 s).

Exemplo (lista incremental de leads):

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.asender.net/v1/leads?limit=200&updated_after=2026-10-01T00:00:00Z"
# {"data":[{"id":"ctt_...","email":"..."}],"next_cursor":"..."}
```

## 10. Exemplo mínimo

Um exemplo server-side (Next.js route handlers, TypeScript, PKCE por CSPRNG, sem
segredo no código), publicado aqui mesmo. Ele cobre: iniciar o login, callback com
conferência de `state` e `iss`, troca do code, refresh com rotação e chamada à API.
O armazenamento de sessão e de tokens é um ponto marcado para você implementar no
seu app. As variáveis de ambiente ficam no servidor; nenhum segredo vai ao navegador.

### `asender-oauth.ts` — o núcleo (PKCE, authorize, troca de code, refresh, API)

```ts
/**
 * asender-oauth.ts — núcleo do "Entrar com Asender" para um backend Node/Next.js.
 *
 * O quê: gera state/nonce/PKCE por CSPRNG, monta o /authorize, troca code e
 * refresh por tokens e chama a API pública. Só roda no SERVIDOR.
 * Onde: usado pelos route handlers de `routes.ts` (login, callback, sincronização).
 * Não há segredo no código: tudo vem do ambiente do servidor.
 *
 *   ASENDER_ISSUER          https://auth.asender.net
 *   ASENDER_API             https://api.asender.net
 *   ASENDER_CLIENT_ID       recebido no cadastro do app
 *   ASENDER_CLIENT_SECRET   recebido UMA vez no cadastro (cofre do servidor)
 *   ASENDER_REDIRECT_URI    exatamente como cadastrada
 */
import { createHash, randomBytes } from "node:crypto";

export const ESCOPOS = "openid profile email offline_access leads:read conversions:read";

function env(nome: string): string {
  const v = process.env[nome];
  if (!v) throw new Error(`variável de ambiente ausente: ${nome}`);
  return v;
}

/** Valor aleatório URL-safe de `bytes` bytes (CSPRNG do Node). */
function aleatorio(bytes: number): string {
  return randomBytes(bytes).toString("base64url");
}

export interface TentativaLogin {
  state: string;
  nonce: string;
  codeVerifier: string;
  url: string;
}

/**
 * Cria uma tentativa de login: devolve a URL do /authorize e os segredos da
 * tentativa, que o chamador grava NA SESSÃO DO SERVIDOR (nunca na URL nem em
 * cookie legível por JS). Uso único por tentativa.
 */
export function novaTentativa(opcoes: { prompt?: "none" | "consent" | "login" } = {}): TentativaLogin {
  const state = aleatorio(16);
  const nonce = aleatorio(16);
  const codeVerifier = aleatorio(48); // 64 caracteres, dentro de 43..128
  const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");

  const q = new URLSearchParams({
    response_type: "code",
    client_id: env("ASENDER_CLIENT_ID"),
    redirect_uri: env("ASENDER_REDIRECT_URI"),
    scope: ESCOPOS,
    state,
    nonce,
    code_challenge: codeChallenge,
    code_challenge_method: "S256",
  });
  if (opcoes.prompt) q.set("prompt", opcoes.prompt);

  return { state, nonce, codeVerifier, url: `${env("ASENDER_ISSUER")}/authorize?${q}` };
}

/** Basic auth do client confidencial (client_secret_basic). */
function basic(): string {
  const par = `${encodeURIComponent(env("ASENDER_CLIENT_ID"))}:${encodeURIComponent(env("ASENDER_CLIENT_SECRET"))}`;
  return "Basic " + Buffer.from(par).toString("base64");
}

export interface Tokens {
  access_token: string;
  id_token?: string;
  refresh_token?: string;
  expires_in: number;
  token_type: string;
}

export class ErroOAuth extends Error {
  constructor(public status: number, public codigo: string, mensagem: string) {
    super(mensagem);
  }
}

/** POST no /token. Nunca registra o corpo da resposta nem os parâmetros. */
async function postToken(corpo: Record<string, string>): Promise<Tokens> {
  const resp = await fetch(`${env("ASENDER_ISSUER")}/token`, {
    method: "POST",
    headers: { Authorization: basic(), "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams(corpo),
    cache: "no-store",
  });
  if (!resp.ok) {
    const erro = (await resp.json().catch(() => ({}))) as { error?: string };
    throw new ErroOAuth(resp.status, erro.error ?? "server_error", "falha no /token");
  }
  return (await resp.json()) as Tokens;
}

/**
 * Valida o redirect do /authorize e troca o code. Confere `error`, `state` e `iss`
 * ANTES de usar o code. `esperado` vem da sessão do servidor.
 */
export async function trocarCode(
  query: URLSearchParams,
  esperado: { state: string; codeVerifier: string },
): Promise<Tokens> {
  if (query.get("iss") !== env("ASENDER_ISSUER")) throw new ErroOAuth(400, "iss_invalido", "iss inesperado");
  if (query.get("state") !== esperado.state) throw new ErroOAuth(400, "state_invalido", "state inesperado");
  const erro = query.get("error");
  if (erro) throw new ErroOAuth(400, erro, "autorização recusada"); // access_denied, consent_required...
  const code = query.get("code");
  if (!code) throw new ErroOAuth(400, "invalid_request", "code ausente");

  return postToken({
    grant_type: "authorization_code",
    code,
    redirect_uri: env("ASENDER_REDIRECT_URI"),
    code_verifier: esperado.codeVerifier,
  });
}

/**
 * Renova com o refresh token. O refresh é de USO ÚNICO: o chamador deve gravar o
 * novo `refresh_token` na mesma transação, antes de usar o access token, e
 * serializar (lock por conexão). `invalid_grant` = conexão encerrada: peça novo login.
 */
export function renovar(refreshToken: string): Promise<Tokens> {
  return postToken({ grant_type: "refresh_token", refresh_token: refreshToken });
}

/** Revoga o refresh token (ao desconectar a conta no seu app). */
export async function revogar(refreshToken: string): Promise<void> {
  const resp = await fetch(`${env("ASENDER_ISSUER")}/oauth/revoke`, {
    method: "POST",
    headers: { Authorization: basic(), "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ token: refreshToken, token_type_hint: "refresh_token" }),
  });
  if (!resp.ok) throw new ErroOAuth(resp.status, "revoke_falhou", "falha ao revogar");
}

/**
 * GET na API pública respeitando 429/Retry-After. Devolve o JSON; em 401 o
 * chamador renova o access token UMA vez e repete.
 */
export async function chamarApi<T>(caminho: string, accessToken: string, tentativas = 3): Promise<T> {
  for (let i = 0; i < tentativas; i++) {
    const resp = await fetch(`${env("ASENDER_API")}${caminho}`, {
      headers: { Authorization: `Bearer ${accessToken}` },
      cache: "no-store",
    });
    if (resp.status === 429 || resp.status >= 500) {
      const espera = Number(resp.headers.get("Retry-After")) || 2 ** i + Math.random();
      await new Promise((r) => setTimeout(r, espera * 1000));
      continue;
    }
    if (!resp.ok) throw new ErroOAuth(resp.status, "api_erro", `API respondeu ${resp.status}`);
    return (await resp.json()) as T;
  }
  throw new ErroOAuth(503, "api_indisponivel", "API indisponível após retries");
}

export interface Pagina<T> {
  data: T[];
  next_cursor: string | null;
}

/**
 * Percorre uma lista paginada (`data`/`next_cursor`), opcionalmente incremental.
 * `aoPagina` grava cada página (upsert por id) e o cursor, para retomar depois.
 */
export async function sincronizar<T>(
  caminho: string,
  accessToken: string,
  aoPagina: (itens: T[], cursor: string | null) => Promise<void>,
  opcoes: { updatedAfter?: string; cursor?: string } = {},
): Promise<void> {
  let cursor: string | null = opcoes.cursor ?? null;
  do {
    const q = new URLSearchParams({ limit: "200" });
    if (opcoes.updatedAfter) q.set("updated_after", opcoes.updatedAfter);
    if (cursor) q.set("cursor", cursor);
    const pag = await chamarApi<Pagina<T>>(`${caminho}?${q}`, accessToken);
    cursor = pag.next_cursor;
    await aoPagina(pag.data, cursor);
  } while (cursor);
}
```

### `routes.ts` — os route handlers de login e callback

```ts
/**
 * routes.ts — route handlers (Next.js App Router) do "Entrar com Asender".
 *
 * O quê: `GET /auth/asender/login` inicia o fluxo; `GET /auth/asender/callback`
 * conclui. Cada bloco abaixo é um arquivo `route.ts` próprio no seu projeto
 * (app/auth/asender/login/route.ts e app/auth/asender/callback/route.ts).
 * Onde: usa `asender-oauth.ts`. O armazenamento (`sessao`, `conexoes`) é do SEU app:
 * aqui só a interface esperada. Sem segredo real neste arquivo.
 */
import { NextRequest, NextResponse } from "next/server";
import { ErroOAuth, novaTentativa, trocarCode } from "./asender-oauth";

/** Sessão do SEU app, no servidor (cookie de sessão HttpOnly+Secure+SameSite=Lax). */
declare const sessao: {
  gravarTentativa(req: NextRequest, t: { state: string; nonce: string; codeVerifier: string }): Promise<void>;
  /** Lê E APAGA a tentativa (uso único). */
  consumirTentativa(req: NextRequest): Promise<{ state: string; nonce: string; codeVerifier: string } | null>;
};
/** Persistência cifrada em repouso dos tokens por conexão (usuário Asender + conta). */
declare const conexoes: {
  salvar(c: { sub: string; tenant: string; refreshToken: string | undefined; scope: string }): Promise<void>;
};
/** Extrai sub/tenant/scope do access token (decodifique o JWT; a API é quem autoriza). */
declare function lerClaims(accessToken: string): { sub: string; tenant: string; scope: string };

// ── app/auth/asender/login/route.ts ─────────────────────────────────────────
export async function GET_login(req: NextRequest): Promise<NextResponse> {
  const t = novaTentativa(); // prompt opcional: "none" para tentativa silenciosa
  await sessao.gravarTentativa(req, { state: t.state, nonce: t.nonce, codeVerifier: t.codeVerifier });
  return NextResponse.redirect(t.url, 302);
}

// ── app/auth/asender/callback/route.ts ──────────────────────────────────────
export async function GET_callback(req: NextRequest): Promise<NextResponse> {
  const tentativa = await sessao.consumirTentativa(req);
  if (!tentativa) return NextResponse.redirect(new URL("/entrar?erro=sessao", req.url), 302);

  try {
    const tokens = await trocarCode(req.nextUrl.searchParams, tentativa);
    // Valide o id_token aqui (assinatura pelo JWKS, iss, aud, exp e nonce === tentativa.nonce).
    const { sub, tenant, scope } = lerClaims(tokens.access_token);
    await conexoes.salvar({ sub, tenant, refreshToken: tokens.refresh_token, scope });
    return NextResponse.redirect(new URL("/painel", req.url), 302);
  } catch (e) {
    // Nunca logue token, code nem URL com query; só o código do erro.
    const codigo = e instanceof ErroOAuth ? e.codigo : "server_error";
    console.warn("entrar-com-asender: falha", { codigo });
    // login_required / consent_required (prompt=none): mostre o botão normal.
    return NextResponse.redirect(new URL(`/entrar?erro=${encodeURIComponent(codigo)}`, req.url), 302);
  }
}
```


### GET /
Identidade do serviço.
Onde é usada: rota raiz.
Efeitos: escreve a resposta. Serve para saber QUAL binário está rodando quando o comportamento diverge do esperado — a primeira pergunta de todo diagnóstico de deploy.
Respostas: 200 OK

curl -X GET 'https://auth.asender.net/' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /.well-known/jwks.json
Chaves públicas (JWKS)
Onde é usada: verificação no client.
Respostas: 200 O JWK Set.

curl -X GET 'https://auth.asender.net/.well-known/jwks.json' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /.well-known/oauth-authorization-server
Metadados do Authorization Server (RFC 8414)
Onde é usada: clientes MCP (spec 2025-11-25) descobrem o AS aqui a partir do `authorization_servers` do recurso (RFC 9728).
Respostas: 200 Os metadados do Authorization Server.

curl -X GET 'https://auth.asender.net/.well-known/oauth-authorization-server' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /.well-known/openid-configuration
Metadados do provedor OIDC (discovery)
Onde é usada: os clients leem isto no bootstrap para se autoconfigurar. Cacheável (muda só em deploy).
Respostas: 200 Os metadados do provedor.

curl -X GET 'https://auth.asender.net/.well-known/openid-configuration' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /acoes-sensiveis/{id}
Consultar atende GET /v1/acoes-sensiveis/{id}: o solicitante ou um admin do tenant.

curl -X GET 'https://auth.asender.net/acoes-sensiveis/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /authorize
Início do login (Authorization Code + PKCE)
Onde é usada: o browser é redirecionado para cá pelo client (app) que quer logar.
Parâmetros: response_type (query, obrigatório); client_id (query, obrigatório); redirect_uri (query, obrigatório); scope (query); state (query); nonce (query); prompt (query); resource (query); code_challenge (query, obrigatório); code_challenge_method (query, obrigatório)
Respostas: 302 Redireciona ao `redirect_uri` com `code` e `state` (sucesso) ou com `error`/`error_description` e `state` (falha após validar o redirect); ou à tela de login quando não há sessão.; 400 `client_id` desconhecido ou `redirect_uri` não registrada — a falha é mostrada aqui, não redirecionada.

curl -X GET 'https://auth.asender.net/authorize' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /logout
Logout iniciado pelo app (end session)
Onde é usada: o client manda o browser para cá ao sair.
Parâmetros: post_logout_redirect_uri (query); client_id (query); state (query)
Respostas: 302 Redireciona ao `post_logout_redirect_uri` (se permitido) ou à tela de login.

curl -X GET 'https://auth.asender.net/logout' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /oauth/introspect
Introspecção de token (RFC 7662)
Respostas: 200 Estado do token.; 400 `invalid_request` — corpo inválido ou sem `token`.; 401 `invalid_client` — client não autenticado ou não confidencial.

curl -X POST 'https://auth.asender.net/oauth/introspect' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /oauth/revoke
Revoga um refresh token (RFC 7009)
Saídas: 200 vazio; 401 invalid_client se o client não se autentica.
Respostas: 200 Revogado (ou nada a revogar).; 400 `invalid_request` — corpo inválido ou sem `token`.; 401 `invalid_client` — client não autenticado.

curl -X POST 'https://auth.asender.net/oauth/revoke' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /register
Registro dinâmico de client (RFC 7591)
Respostas: 201 Client registrado (sem segredo).; 400 `{"error":"invalid_redirect_uri"|"invalid_client_metadata","error_description":"…"}` (RFC 7591 §3.2.2).; 404 Registro dinâmico desligado.; 429 Limite de registros por hora do IP atingido (`Retry-After`).

curl -X POST 'https://auth.asender.net/register' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /token
Troca de code/refresh por tokens
Onde é usada: o client troca aqui, servidor-a-servidor (ou pelo BFF), o code/refresh por tokens.
Respostas: 200 Tokens emitidos.; 400 `invalid_grant` (code/refresh inválido, expirado, já usado, ou redirect_uri/PKCE que não conferem; refresh reusado → família revogada; refresh de SESSÃO encerrada — revogada ou expirada — → família revogada, "sessão encerrada"), `invalid_request` (corpo inválido) ou `unsupported_grant_type`, ou `invalid_target` (apps de terceiro: `resource` fora do concedido ou da allowlist).; 401 `invalid_client` — client não autenticado.

curl -X POST 'https://auth.asender.net/token' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /userinfo
Claims do usuário do access token
Onde é usada: o client chama para hidratar o perfil. Sem token válido -> 401 invalid_token.
Respostas: 200 Os claims do usuário.; 401 `invalid_token` — Bearer ausente, inválido, ou não é um access token.

curl -X GET 'https://auth.asender.net/userinfo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /version
Versão e commit do binário em execução.
Onde é usada: rota pública, usada por ops e por quem investiga incidente. Pública porque a primeira pergunta de todo incidente é "que versão está no ar?", e ela tem de ser respondível sem credencial — quem investiga muitas vezes ainda não tem uma. O que sai é só isso: nunca configuração, nunca endereço interno.
Respostas: 200 OK

curl -X GET 'https://auth.asender.net/version' \
  -H 'Authorization: Bearer SEU_TOKEN'



==============================================================================
# Páginas  (https://api.pages.asender.net)
==============================================================================

# Pages API

A API da ferramenta **Páginas** do Asender: constrói a landing page, publica, e
mede o que acontece nela.

> **Vai criar ou editar o CONTEÚDO de páginas (você ou um agente de IA)?** Leia
> [Páginas: o JSON do documento v2](https://developers.asender.net/guias/pages-documento-v2.html):
> modelo mental, todos os campos de todos os itens, erros de validação, mídia, fluxos
> seguros (rascunho/versão/publicação), receitas completas e um prompt pronto. É **uma ferramenta servida por dois processos** — a
**autoria** (o construtor: páginas, formulários, mídia, domínios, links curtos,
marca, geração por IA, testes A/B) e o **runtime** (o que serve a página
publicada ao visitante e a mede: captura de lead, analytics, pixels, session
replay). Para quem integra, é **uma API só**, num endereço só.

- **Base (tudo o que você integra):** `https://api.pages.asender.net` — autoria,
  leitura de métricas **e o envio de lead server-to-server** (o proxy roteia por
  caminho para o runtime).
- **Runtime público (página publicada, snippet, pixel):** `https://sites.asender.net`
  — também serve o envio de lead por chave, **igual** ao `api.pages`
  (o antigo `https://sites.asender.com.br` continua servindo **igual**, sem
  redirecionar — formulário e integração já colados com ele seguem funcionando)
- **Formato:** JSON (`application/json; charset=utf-8`)

> **Por que dois endereços, e onde passa a fronteira.** A fronteira interna
> autoria/runtime **não é sua** — você não precisa saber por onde ela passa. A
> regra prática é simples: tudo o que **você** administra (páginas, formulários,
> pixels, relatórios) fala com `api.pages.asender.net`; tudo o que o **visitante
> da página publicada** dispara (o formulário embutido, o pixel, o link curto)
> acontece em `sites.asender.net`, e você quase nunca chama isso à mão — é a
> página servida que chama. `sites.asender.net` **não é uma API**: é onde a
> página publicada é servida. Se o runtime cair, o que quebra é a analytics de
> Páginas — não o CRM, não o e-mail, não a plataforma (ADR-0037).

## Autenticação

Páginas tem **três públicos**, e cada um usa uma credencial diferente. A spec diz
qual vale em cada rota.

### Sessão (OIDC) — a autoria e a leitura de métricas

O construtor e as telas de analytics/pixels/replay são operados por um **usuário
logado**. A credencial é a **sessão OIDC** (OAuth 2.1 + PKCE, emitida por
`https://auth.asender.net`). O token vai em `Authorization: Bearer` **ou** no
cookie `asender_session` (o caminho dos frontends da casa):

```
Authorization: Bearer <token-de-sessão>
X-Asender-Tenant: <slug-da-conta-ativa>
```

O `X-Asender-Tenant` é uma **preferência** — diz em qual das suas contas você
está operando. Ele **não autoriza nada**: o acesso é decidido no servidor pelo
PEP do produto `pages`, e o `tenant` efetivo é sempre resolvido do token. Sessão
ausente ou inválida responde **401**; a sessão de um usuário sem o produto
`pages` na conta responde **403**.

### API key — integração server-to-server (formulários, leads e páginas)

Um sistema seu — ou um **agente de IA** — pode **administrar formulários**, **enviar leads** e
**criar e manter páginas** sem sessão de usuário, com uma **API key** da conta (`sk_live_…`/`sk_test_…`). A chave vai em
`Authorization: Bearer` e é validada a cada chamada — **chave revogada para de
valer na hora** (sem cache). A conta é resolvida **da chave**; um `tenant_id` no
corpo é ignorado (piso 3). Em Páginas a chave vale **só** nas rotas abaixo, e
cada uma exige um **escopo** (deny-default: rota fora da tabela, ou chave sem o
escopo, responde **403**):

| Escopo | Rotas |
| --- | --- |
| `forms:read` | `GET /v1/formularios` (aceita `?external_id=`), `GET /v1/formularios/{id}`, `GET /v1/formularios/externo/{external_id}` |
| `pages:read` | `GET /v1/paginas`, `GET /v1/paginas/{id}`, `GET /v1/paginas/{id}/rascunho`, `GET /v1/paginas/{id}/seo`, `GET /v1/midias`, `GET /v1/dominios` (lista os domínios da conta; o padrão vem primeiro, com `padrao: true`) |
| `pages:write` | criar e editar **sem publicar**: `POST /v1/paginas`, `POST /v1/paginas/importar`, `POST /v1/paginas/{id}/versoes`, `PUT`/`DELETE /v1/paginas/{id}/rascunho`, `PUT /v1/paginas/{id}/seo`, `POST /v1/paginas/{id}/midias/copiar`, `PUT /v1/paginas/{id}/dominio` (move a página de domínio e/ou caminho), `PUT`/`DELETE /v1/dominios/{id}/pagina-inicial` (página inicial do domínio), `POST /v1/paginas/lote` (`duplicar`, `mudar_dominio`), `POST /v1/midias`, `POST /v1/midias/de-url` |
| `pages:publish` | publicar e despublicar — o ato visível ao público: `POST /v1/paginas/{id}/publicar` (com `versao` obrigatória) e `POST /v1/paginas/lote` (`publicar`, `despublicar`) |
| `forms:write` | `POST /v1/formularios`, `PUT /v1/formularios/{id}`, `PUT /v1/formularios/externo/{external_id}`, `DELETE /v1/formularios/{id}`, e o envio de lead: `POST /v1/leads`, `POST /v1/forms/{formID}/submissions`, `POST /v1/forms/externo/{externalID}/submissions` |

Os escopos **não se implicam** (`pages:write` não lê nem publica). Todo o resto (editar
slug/título, A/B, roteamento, destinos, demais rotas de domínios, apagar mídia, SEO do site,
analytics…) é **só sessão**: com chave responde 401/403. Contra sobrescrever trabalho de pessoas, o
`PUT …/rascunho` por chave exige `?base=` (428 sem ele; 409 com os dois lados preservados) e a
escrita é limitada por chave (60/min; publicar 20/min). O guia completo para agentes, com o
contrato do documento, está em [Documento de página v2](https://developers.asender.net/guias/pages-documento-v2.html). Passo a passo em
[Integrar um formulário externo](#integrar-um-formulario-externo-ex-blog).

**Como obter uma chave.** As API keys são emitidas pela Plataforma
(`POST https://api.asender.net/api/tenants/{id}/api-keys`, ver a
[Platform API](https://developers.asender.net/apis/platform.html)) ou pela tela de API
keys do painel, informando os `scopes` (`forms:read`, `forms:write`, `pages:read`, `pages:write`, `pages:publish`). Use
`sk_test_…` fora de produção.

### Sem credencial — o visitante da página publicada

O **snippet** de formulário embutido em site de terceiro (`POST /f/{formID}`), a
**coleta de pixel** (`/pixel.js`, `POST /collect`), a gravação de **session
replay** (`POST /replay`) e o **link curto** (`GET /r/{slug}`) são **anônimos**:
quem chama é o navegador de um visitante, não um integrador. Quando há alguma
credencial, ela é a do **pixel** — um token assinado que a página servida já
carrega, enviado no corpo — nunca uma chave sua. Esses endpoints defendem-se por
**origem** (a allowlist do formulário ou do pixel) e por **rate-limit**, não por
sessão.

## Erros

O envelope de erro **difere por processo**, e a spec diz a verdade sobre cada um.

**Autoria** (`api.pages.asender.net`, control plane) responde com a chave `erro`:

```json
{ "erro": "já existe uma página no endereço \"promo\"" }
```

**Runtime** (captura, envio de lead por chave, analytics/pixels/replay) responde no
formato RFC 7807-compatível da casa, com `error.message`:

```json
{ "error": { "message": "credencial ausente ou inválida" } }
```

Os códigos e quando cada um aparece:

| HTTP | quando |
| --- | --- |
| 400 | corpo inválido, parâmetro de query malformado, submissão recusada pela validação do formulário |
| 401 | sessão/credencial ausente ou inválida (chave revogada, conta inativa) |
| 403 | produto `pages` ausente na conta (autoria); **chave sem o escopo da rota** (`a chave não tem o escopo forms:write`); origem não autorizada (snippet/coleta) |
| 404 | recurso inexistente ou fora do escopo da credencial (não revela existência em outra conta) |
| 409 | conflito de unicidade (slug/nome/`external_id` já em uso, experimento já rodando) |
| 413 | upload de mídia grande demais |
| 422 | regra de negócio (título ausente, domínio não verificado, peso fora de 0–100); `Idempotency-Key` já usada com outro corpo |
| 429 | excesso nas rotas públicas de coleta/replay (rate-limit por credencial × IP) e no envio de lead por chave (300/min por conta) — traz `Retry-After` |
| 502 | a captura ou a geração por IA não pôde completar agora |
| 503 | dependência indisponível ou recurso desligado neste ambiente (IA, importação por URL, validação da chave) — tente de novo com backoff |

## Paginação e janelas

Páginas **não usa cursor opaco** (diferente da Mail API). As coleções de autoria
(páginas, formulários, redirects, pixels) devolvem a **lista** sob uma chave
nomeada (`{"paginas":[…]}`, `{"formularios":[…]}`, …); onde há muito volume, um
`?limite=N` recorta. Os relatórios de **analytics** trabalham por **janela de
tempo**: `?de=…&ate=…` em **RFC3339**; ausente usa os **últimos 7 dias**, e o
teto é de **92 dias**.

---

## Autoria — o ciclo de vida de uma página

A base de tudo nesta seção é `https://api.pages.asender.net`, com **sessão**.

### Criar, salvar versão, publicar

Uma página nasce com um título e (opcionalmente) um `slug` e um `dominio`
próprio. Salvar o trabalho do editor cria uma **versão**; publicar promove uma
versão ao ar.

```bash
# 1) criar a página
curl -X POST 'https://api.pages.asender.net/v1/paginas' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "titulo": "Lançamento", "slug": "promo" }'
# → 201 { "id": "…", "slug": "promo", "titulo": "Lançamento", … }

# 2) salvar uma versão (auto-save do editor)
curl -X POST 'https://api.pages.asender.net/v1/paginas/<id>/versoes' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "template": { "versao": 2, "secoes": [ { "id": "s1", "colunas": [ { "id": "s1c1", "itens": [
        { "id": "t1", "tipo": "titulo", "props": { "texto": "Olá", "nivel": 1 } } ] } ] } ] } }'
# → 201 { "versao": 3 }

# 3) publicar (sem corpo, publica a última salva)
curl -X POST 'https://api.pages.asender.net/v1/paginas/<id>/publicar' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "versao": 3 }'
# → 200 { "versao_publicada": 3 }
```

Regras que valem antes de integrar:

- **Domínio próprio exige posse provada.** Criar/editar uma página com um
  `dominio` que não está **verificado** na conta responde **422**. Cadastre e
  verifique o host em `/v1/dominios` primeiro (abaixo).
- **Bloco privilegiado exige nível.** Um `template` com bloco de **HTML cru** é
  barrado pelo PEP com **403** para quem não tem o nível — a página segue
  editável sem ele.
- **Endereço é único.** `slug`+`dominio` repetido responde **409**.

### Domínios próprios

Adicionar um domínio devolve o **registro TXT de posse** a publicar no DNS;
depois você pede a verificação.

```bash
curl -X POST 'https://api.pages.asender.net/v1/dominios' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "host": "lp.empresa.com.br" }'
# → 201 { "id":"…", "host":"lp.empresa.com.br", "registro_txt":"_asender-verify.lp.empresa.com.br", "token":"asv_…", "verificado":false }
#   (publique um TXT com NOME = registro_txt e VALOR = token)

curl -X POST 'https://api.pages.asender.net/v1/dominios/<id>/verificar' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>'
# → 200 { …, "verificado": true|false, … }   (200 traz o estado de cada passo, inclusive TXT ainda não propagado; 503 só se o DNS não respondeu)
```

### Domínio padrão e mover uma página de endereço

Toda conta ganha, automaticamente, um **domínio padrão** em `apages.xyz`.
`GET /v1/dominios` (sessão ou chave `pages:read`) lista os domínios com o padrão
**primeiro** e `"padrao": true` nele.

`PUT /v1/paginas/{id}/dominio` (sessão ou chave `pages:write`) move a página:

```bash
curl -X PUT 'https://api.pages.asender.net/v1/paginas/<id>/dominio' \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ "dominio_id": "dom_01J9XYZ", "caminho": "meu-slug" }'
# → 200 { "pagina_id":"…", "dominio_id":"dom_01J9XYZ", "dominio":"minhaconta.apages.xyz",
#         "caminho":"meu-slug", "url_publica":"https://minhaconta.apages.xyz/meu-slug",
#         "alterado":true, "publicada":true,
#         "redirecionamento": { "criado":true, "de":"https://sites.asender.net/slug-antigo" } }
```

- `dominio_id: ""` = host da plataforma. `caminho: ""` mantém o slug atual; o
  caminho é um slug de um segmento (`^[a-z0-9]+(-[a-z0-9]+)*$`).
- **O endereço antigo passa a responder 301** para o novo (308 se não for
  GET/HEAD), com a query string preservada, desde que a página já tenha sido
  publicada alguma vez (`redirecionamento: null` caso contrário). Repetir o
  pedido é idempotente (`alterado: false`).

| Status | Quando |
| --- | --- |
| 400 | corpo inválido |
| 401 / 403 | sem credencial / chave sem `pages:write` |
| 404 | página ou domínio inexistente **ou de outra conta** (não revela existência) |
| 409 | `motivo: caminho_em_uso` (endereço de outra página) ou `pagina_inicial` (a página é a home do domínio de origem) |
| 422 | `motivo: dominio_nao_verificado` ou `caminho_invalido` |

### Página inicial do domínio (o que responde em `/`)

`PUT /v1/dominios/{id}/pagina-inicial` (sessão ou chave `pages:write`) define a
página que responde em `https://<host>/` — subdomínio `*.apages.xyz` ou domínio
próprio:

```bash
curl -X PUT 'https://api.pages.asender.net/v1/dominios/<dominio_id>/pagina-inicial' \
  -H 'Authorization: Bearer sk_live_...' -H 'Content-Type: application/json' \
  -d '{"pagina_id":"<pagina_id>"}'
```

- Página de **outro endereço** (outro domínio ou a plataforma) é movida para este
  domínio, com o mesmo slug (o endereço antigo passa a responder 301 se já esteve
  no ar), e vira a inicial.
- Trocar a inicial **não apaga nada**: a anterior continua publicada no próprio slug.
- `DELETE /v1/dominios/{id}/pagina-inicial` tira a inicial (idempotente); `/` volta
  a responder como antes (404 sem inicial). A resposta traz `pagina_inicial` (ou `null`).
- Erros: 404 (domínio/página inexistente ou de outra conta), 409 `pagina_inicial`
  (a página é a inicial de OUTRO domínio) ou `caminho_em_uso`, 422
  `dominio_nao_verificado`/`caminho_invalido`.

### Ações em massa (publicar, despublicar, duplicar, mudar domínio)

`POST /v1/paginas/lote` (sessão ou chave: `publicar`/`despublicar` exigem `pages:publish`; `duplicar`/`mudar_dominio`, `pages:write`) aplica **uma** ação a até
**100** páginas. Cada página é processada de forma independente: não há
tudo-ou-nada, e a resposta diz o desfecho de cada uma.

```bash
curl -X POST 'https://api.pages.asender.net/v1/paginas/lote' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "acao": "publicar", "ids": ["pag_01","pag_02"], "rascunho": "pular" }'
# → 200 { "lote_id":"lot_…", "acao":"publicar", "total":2, "ok":1, "puladas":1, "erros":0,
#         "resultados":[ {"id":"pag_01","status":"ok","versao":3},
#                        {"id":"pag_02","status":"pulada","motivo":"rascunho_mais_novo"} ] }
```

- `simular: true` devolve o que aconteceria **sem escrever nada** (é o que a tela
  usa para montar a confirmação).
- **publicar** publica a última versão **salva**, é idempotente (já no ar =
  `ok` + `sem_mudanca`) e pula conteúdo que o contrato recusa
  (`conteudo_invalido`). Com rascunho de servidor mais novo que a última versão,
  `rascunho: "pular"` (padrão) pula a página; `"publicar_salva"` publica a última
  versão salva — o rascunho nunca vira versão nem é descartado.
- **despublicar** tira do ar sem tocar em versões ou rascunho; **duplicar** cria
  uma cópia despublicada (`-copia`); **mudar_dominio** (`dominio_id`, e
  `caminho_por_pagina` opcional) segue as regras de `PUT /v1/paginas/{id}/dominio`.
- Um id de outra conta volta como `erro/nao_encontrada`, igual a um id inexistente.
- Não existe exclusão em massa. Limite: 12 chamadas/min por conta (429); mais de
  100 ids ou nenhum → 422. Cada página processada gera um log de auditoria.

### Formulários — o contrato de campos

Um formulário **declara** seus campos; a captura **recusa** submissão de campo
não declarado (é assim que a base do CRM não fica suja com `telefone`/`Telefone`/
`tel`). O `origens[]` é a allowlist do **modo snippet** (CORS por formulário).

```bash
curl -X POST 'https://api.pages.asender.net/v1/formularios' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{
    "nome": "Contato",
    "campos": [
      { "nome": "email", "rotulo": "E-mail", "tipo": "email", "obrigatorio": true },
      { "nome": "nome",  "rotulo": "Nome",   "tipo": "texto", "obrigatorio": false }
    ],
    "origens": ["https://empresa.com.br"],
    "mensagem_pos_envio": "Recebemos, obrigado."
  }'
# → 201 { "id": "…", "nome": "Contato", "campos": [ … ] }
```

Tipos de campo: `texto`, `texto_longo`, `email`, `telefone`, `numero`,
`booleano`, `opcao` (com `opcoes[]`), `data`, `url`, `oculto` e outros (ver o
schema `Campo`). Um sistema externo também administra formulários **por chave**,
amarrando-os ao seu próprio id (`external_id`) — veja
[Integrar um formulário externo](#integrar-um-formulario-externo-ex-blog). `GET /v1/formularios/{id}` devolve também o **snippet** de embed.

**Campo `agendamento`.** O visitante escolhe um horário livre de uma agenda da
conta. Declare `{ "nome": "horario", "tipo": "agendamento", "agendamento": { "agenda_id": "agd_…" } }`
(no máximo um por formulário; `agenda_id` obrigatório). O valor enviado é o
**início do horário em RFC 3339** (`2026-12-01T10:00:00-03:00` é gravado como
`2026-12-01T13:00:00Z`). Ao salvar, a agenda é conferida no serviço Agenda:
inexistente ou de outra conta → 422, inativa → 422, serviço fora do ar → 503
`application/problem+json` (formulários **sem** o campo salvam normalmente).
`GET /v1/formularios/agendas` (só sessão) lista as agendas da conta para o
seletor do construtor. O gerador por IA nunca cria este campo.

### Mídia, links curtos, marca, geração por IA

- **Mídia** — galeria por conta. `POST /v1/midias` recebe `multipart/form-data`
  com o arquivo no campo `arquivo` (dedup por conteúdo: reenviar o mesmo arquivo
  responde 200 em vez de 201). `POST /v1/midias/de-url` importa por URL, com
  defesa contra SSRF. A **leitura pública** — `GET /v1/public/midias/{id}` — é
  **anônima**: é o `src` que a página no ar carrega, e exigir sessão quebraria
  toda página publicada.
- **Links curtos** — `/v1/redirects` (CRUD) + `/v1/redirects/{id}/cliques`. O
  visitante resolve pelo runtime em `GET https://sites.asender.net/r/{slug}`.
- **Marca** — `GET/PUT /v1/configuracoes/marca` (logo, favicon, cor primária).
- **Geração por IA** — `POST /v1/ia/gerar-pagina` produz um rascunho de
  `template` a partir de um `pedido` em linguagem natural. Responde **503** onde
  o provedor de IA não está configurado (quem não contratou não paga).

### Fontes da página

O documento v2 aceita, no **estilo da página**, duas famílias de fonte:
`estilo.fonte_titulos` (títulos `h1`–`h6`) e `estilo.fonte_texto` (texto corrido).
Vazio ou ausente **herda do kit de marca**; senão o valor tem de ser **um destes
ids, exatamente assim** (minúsculas, sem espaços):

`comfortaa`, `urbanist`, `montserrat`, `inter`, `poppins`, `open-sans`, `nunito`,
`playfair-display`, `merriweather`, `dm-sans`, `manrope`, `raleway`.

As fontes são **auto-hospedadas** pelo runtime (`/_f/…`, cache de um ano): a página
publicada não chama nenhum serviço de terceiros. Qualquer outro valor (`"Inter"`,
`"arial"`, um nome com espaço, texto com CSS) é recusado na gravação com
`422` e código `ErrEstiloInvalido`, com `estilo.fonte_titulos` ou
`estilo.fonte_texto` na mensagem de erro. A lista também é o `enum` desses campos no schema
`DocV2_estiloPagina` da especificação.

```json
{ "versao": 2, "estilo": { "fonte_titulos": "playfair-display", "fonte_texto": "inter" }, "secoes": [ … ] }
```

### Testes A/B e roteamento

Sob `/v1/paginas/{id}` moram duas mecânicas de desvio, **exclusivas entre si**
(ADR-0014):

- **A/B** (`/experimento`, `/variantes`, `/ab/promover`, `/experimento/auto-stop`):
  variantes com `peso` de 0–100. Um experimento **em curso** não é editável
  (**409**); a leitura do resultado é a analytics `GET /v1/analytics/ab`.
- **Roteamento** (`/roteamento`): desvio por regra (geo/device/idioma), até **20
  destinos**. Salvar roteamento onde já há experimento ativo responde **409**.

---

## Captura de lead — os modos de submissão

Um formulário recebe submissão de três formas, e **todas caem no mesmo pipeline**
(validação do contrato de campos → antispam → grava → outbox para o CRM).

### Modo API (server-to-server, com API key)

Para o seu backend enviar um lead. Base: `https://api.pages.asender.net`
(`sites.asender.net` serve igual). Exige chave com `forms:write`. O sucesso é
**201** (novo) ou **200** (deduplicado); o corpo traz `duplicada`.

```bash
curl -X POST 'https://api.pages.asender.net/v1/forms/<form_id>/submissions' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "campos": { "email": "cliente@exemplo.test", "nome": "Fulana" },
    "origem": { "utm_source": "google", "utm_medium": "cpc" }
  }'
# → 201 { "ok": true, "lead_id": "…", "duplicada": false }
```

`POST /v1/leads` é o mesmo, com o `form_id` no corpo em vez de no path, e
`POST /v1/forms/externo/{externalID}/submissions` acha o formulário pelo seu
`external_id`. O corpo completo (`id_externo`, `consentimento`, `ocorrido_em`,
`origem.url`/`utm_*`) está no passo 3 da integração externa. Os campos
são **explícitos** (`campos` é um mapa nome→valor) — nada de bind do corpo
inteiro (anti mass assignment, §37).

### Modo snippet (embutido, anônimo)

O snippet gerado pelo formulário posta em `POST /f/{formID}` **sem credencial**:
a conta sai do próprio formulário, e a **origem** é conferida contra a allowlist
dele **quando a trava de sites autorizados está ligada** (senão **403**); a trava
é opcional e, desligada, qualquer origem passa. Um `<form>` nativo recebe a **tela de agradecimento**; um XHR
recebe JSON. **Sempre responde 200** — inclusive quando a submissão é
classificada como **spam**: aceitar e descartar são indistinguíveis, de
propósito (devolver 403 ensinaria o bot a ajustar até passar).

### Pixel do navegador + API de conversão (dedup por `eventID`)

Depois de um envio aceito via `fetch` (snippet e página), o script do formulário
expõe o **id público da submissão** à página (ADR-0120):

- `window.asenderSubmissao = { id, formulario_id }`;
- o `CustomEvent` **`asender:submissao`** (sobe até `document`) com o mesmo `detail`.

O `id` é o mesmo `event_id` que o servidor manda à API de conversão (Meta,
Google Ads, TikTok). Um pixel colado na página deduplica assim:

```html
<script>
  document.addEventListener("asender:submissao", function (e) {
    fbq("track", "Lead", {}, { eventID: e.detail.id });
  });
</script>
```

Spam e respostas sem `lead_id` não disparam o evento. O servidor lê `_fbp`/`_fbc`
(só leitura) e os ids de clique (`gclid`, `fbclid`, `ttclid`…) capturados na
chegada; nada disso aparece em log.

### Modo página nativa

Quando o formulário faz parte de uma página servida pelo runtime, o `POST` da
própria página (`sites.asender.net/…`) alimenta o mesmo pipeline. Nada a
integrar — é a página publicada funcionando.

> **Não-produção nunca entrega efeito externo real (piso 18).** O lead capturado
> segue para o CRM por outbox; use **`@exemplo.test`** (ou os TLDs reservados
> `.test`/`.invalid`/`.example`) em fixtures e testes, nunca um e-mail de pessoa
> real ou o domínio de um cliente.

---

## Integrar um formulário externo (ex.: blog)

Caso: o seu blog (ou outro sistema) tem um formulário próprio e você quer que
cada envio vire **lead no Asender** — contato no CRM, mensagem na caixa de
atendimento, e marketing quando houver opt-in. Tudo **server-to-server**, em
`https://api.pages.asender.net`, com uma API key. O fluxo é: **chave → upsert do
formulário → enviar leads**.

> **Não-produção nunca entrega efeito externo real (piso 18).** Fora de `prd`
> use chave `sk_test_…` e e-mails sintéticos `@exemplo.test` (ou os TLDs
> reservados `.test`/`.invalid`/`.example`) — nunca e-mail de pessoa real nem o
> domínio de um cliente. Os exemplos abaixo já seguem isso.

### 1. Crie a chave com os escopos certos

No painel (API keys) ou pela Plataforma:

```bash
curl -X POST 'https://api.asender.net/api/tenants/<tenant_id>/api-keys' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "blog-formularios", "scopes": ["forms:write", "forms:read"] }'
# → o segredo sk_… aparece UMA vez
```

- `forms:write` cria/edita/apaga formulários **e envia leads**; `forms:read` só
  lê. Para o fluxo deste guia, `forms:write` basta; `forms:read` é útil para
  conferir o que está no ar.
- `sk_test_…` fora de produção, `sk_live_…` só em produção.
- **O segredo vive só no servidor** (variável de ambiente, secret manager).
  Nunca no JavaScript do navegador nem em `NEXT_PUBLIC_*`. Chave vazada: revogue
  na Plataforma — para de valer na hora.

### 2. Faça o upsert do formulário por `external_id`

`PUT /v1/formularios/externo/{external_id}` cria o formulário se não existe
(**201**) e o atualiza se já existe (**200**). É **idempotente**: rodar de novo
com o mesmo corpo não muda nada — pode ir no deploy do blog. Você não precisa
guardar o id do Asender; o seu `external_id` (1–128 caracteres, `A-Z a-z 0-9 . _ : -`,
único na conta) basta.

```bash
curl -X PUT 'https://api.pages.asender.net/v1/formularios/externo/blog-contato' \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "nome": "Contato do blog",
    "exige_consentimento": true,
    "texto_consentimento": "Concordo em receber comunicações",
    "base_legal": "consentimento",
    "campos": [
      { "nome": "email",    "rotulo": "E-mail",   "tipo": "email",  "obrigatorio": true },
      { "nome": "nome",     "rotulo": "Nome",     "tipo": "texto",  "obrigatorio": true },
      { "nome": "empresa",  "chave": "empresa",    "rotulo": "Empresa", "tipo": "texto" },
      { "nome": "interesse","rotulo": "Interesse", "tipo": "opcao",  "opcoes": ["produto", "parceria"] }
    ]
  }'
# → 201 { "id": "…", "external_id": "blog-contato", "nome": "Contato do blog", "campos": [ … ] }
# → (rodando de novo) 200 { … o mesmo formulário … }
```

O PUT **substitui** a definição inteira: o que não vier no corpo deixa de
existir. Mapeamento dos campos do formulário do blog para o tipo do Asender:

| Campo do formulário do blog | `tipo` no Asender | Observação |
| --- | --- | --- |
| texto (`input text`) | `texto` | |
| área de texto (`textarea`) | `texto_longo` | |
| e-mail | `email` | alimenta o e-mail do contato |
| telefone (`tel`) | `telefone` | alimenta o telefone do contato |
| número | `numero` | |
| caixa de seleção única (`checkbox`) | `booleano` | `valor_marcado` define o valor enviado quando marcada |
| `select` / `radio` | `opcao` | liste os valores em `opcoes[]` |
| data | `data` | |
| `hidden` | `oculto` | |
| URL | `url` | |

Outras propriedades do campo:

- `chave` — a **chave do catálogo de campos nativos** (ex.: `empresa`, `cargo`)
  liga o campo ao atributo correspondente do contato no CRM. Sem `chave`, o
  campo vira um atributo personalizado com o nome do campo (nunca é descartado).
- `obrigatorio` — recusa o envio sem o campo (400).
- Consentimento: `exige_consentimento: true` faz o envio ser **recusado** sem
  consentimento; `texto_consentimento` e `base_legal` (`consentimento`,
  `legitimo_interesse`, `execucao_contrato`, `obrigacao_legal`) são do
  formulário. Alternativamente marque um campo `booleano` com `consentimento: true`
  (a caixa de aceite).

Só os campos **declarados** são aceitos no envio: campo desconhecido é
recusado, e é assim que a base do CRM não fica suja.

Para criar sem upsert, `POST /v1/formularios` aceita o mesmo corpo com
`external_id` e, opcionalmente, o header `Idempotency-Key` (1–255 caracteres):
repetir a mesma chave com o mesmo corpo devolve **201** com o **mesmo**
formulário e `Idempotent-Replayed: true`; a mesma chave com corpo diferente dá
**422**. Para conferir: `GET /v1/formularios/externo/blog-contato` ou
`GET /v1/formularios?external_id=blog-contato`. `DELETE /v1/formularios/{id}`
apaga (lógico) e libera o `external_id`.

### 3. Envie os leads, server-to-server

A cada envio no blog, o **seu servidor** chama (nunca o navegador do visitante):

```bash
curl -X POST 'https://api.pages.asender.net/v1/forms/externo/blog-contato/submissions' \
  -H "Authorization: Bearer $ASENDER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "campos": { "email": "fulana@exemplo.test", "nome": "Fulana de Tal", "empresa": "Exemplo Ltda", "interesse": "parceria" },
    "id_externo": "blog-sub-48213",
    "consentimento": true,
    "ocorrido_em": "2026-10-08T14:03:00Z",
    "origem": {
      "url": "https://blog.exemplo.test/post/lancamento",
      "utm_source": "newsletter", "utm_medium": "email", "utm_campaign": "lancamento"
    }
  }'
# → 201 { "ok": true, "lead_id": "…", "duplicada": false, "id_externo": "blog-sub-48213" }
```

(Se preferir o id do Asender: `POST /v1/forms/{formID}/submissions` ou
`POST /v1/leads` com `form_id` no corpo — mesmo corpo.)

| Campo | O que é |
| --- | --- |
| `campos` | mapa nome→valor dos campos **declarados** no passo 2 |
| `id_externo` | id desta submissão **no seu sistema**; é a chave de deduplicação (por formulário). Até 255 caracteres. O header `Idempotency-Key` serve no lugar |
| `consentimento` | `true` equivale a `campos.consentimento = "on"`; obrigatório se o formulário `exige_consentimento` |
| `ocorrido_em` | quando o visitante enviou (RFC 3339). Fora da janela — mais de 5 min no futuro ou mais de 365 dias no passado — é recusado (400) |
| `origem` | `url` (a página do blog, http/https, até 2048), `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `referrer` |

**Retry seguro.** Reenvie com o **mesmo `id_externo`** quantas vezes precisar: o
primeiro vira **201**; os seguintes dão **200** com `"duplicada": true` e o
**mesmo** `lead_id` — nada é gravado duas vezes. Trate 200 e 201 como sucesso.

**Backoff.** Em **429** espere `Retry-After` segundos; em **502/503** (core ou
registro indisponível) espere com backoff exponencial (ex.: 1 s, 2 s, 4 s… com
jitter) e reenvie com o mesmo `id_externo`. **Não** retente 400/401/403/404 —
são determinísticos (corpo, chave, escopo, formulário). O lead já aceito é
durável: o CRM e a caixa de atendimento recebem de forma assíncrona (outbox), com
retry próprio.

### 4. Onde os leads aparecem

- **CRM** — o contato é criado (ou reconhecido por e-mail/telefone) e o lead
  entra no funil; se a mesma pessoa **volta**, o lead é **requalificado**
  (estágio volta a "novo", com tag e contador) em vez de duplicar.
- **Caixa de atendimento** — o envio vira mensagem na inbox, conversa por
  contato no canal **formulário**; reabre quando o lead volta.
- **Pages** — os envios ficam na aba de envios do formulário (histórico de
  coleta, para auditoria).
- **Marketing** — o contato entra na lista/segmento só se o destino do
  formulário estiver configurado para isso **e** houve opt-in (consentimento).
  Sem consentimento, não há comunicação de marketing.

### 5. Erros, escopos, limites e LGPD

Envelopes (a spec diz a verdade por processo):

Autoria (`/v1/formularios…`):

```json
{ "erro": "a chave não tem o escopo forms:write" }
```

Envio de lead (`/v1/leads`, `/v1/forms/…`):

```json
{ "error": { "message": "o formulário exige consentimento" } }
```

| HTTP | Significado nesta integração |
| --- | --- |
| 400 | corpo inválido; campo não declarado/inválido; consentimento exigido ausente; `ocorrido_em` fora da janela |
| 401 | chave ausente, inválida, revogada ou conta inativa |
| 403 | a chave não tem o escopo da rota (`forms:read`/`forms:write`) |
| 404 | formulário inexistente **ou de outra conta** (não revela existência) |
| 409 | `external_id` ou nome já em uso |
| 422 | definição de formulário inválida; `Idempotency-Key` já usada com outro corpo |
| 429 | limite excedido — respeite `Retry-After` |
| 503 | não deu para validar a chave agora — tente de novo com backoff |

- **Limites:** 300 requisições por minuto por conta no envio de lead (excesso =
  429 com `Retry-After`) e **64 KB** por corpo.
- **LGPD:** quem decide a base legal e o texto do aceite é o **formulário**
  (`base_legal`, `texto_consentimento`); com `exige_consentimento`, o envio sem
  consentimento é recusado. Mande o `consentimento` que o visitante de fato deu
  — não o fabrique — e `ocorrido_em` com o instante real.

---

## Quickstart — integração externa (SDK JS)

Você tem um formulário numa página **sua** (ex.: um site Next próprio) e quer que
as submissões cheguem ao Asender — no CRM e no marketing. Não precisa falar HTTP
na mão: o SDK **`@asender/pages-sdk`** faz a captura pelos dois caminhos, cada um
com a defesa certa.

> O pacote **ainda não está publicado no npm**: publicação planejada; hoje use o
> snippet (veja o guia [No navegador](https://developers.asender.net/guias/navegador.html)).
> O SDK vive no repositório (`asender_pages_sdk`).

| modo | quando | endpoint | credencial |
| --- | --- | --- | --- |
| **server-to-server** | seu backend/route-handler envia o lead | `POST /v1/leads` | API key `sk_*`, **lida de env no servidor** |
| **cliente anônimo** | o browser do visitante posta direto | `POST /f/{formID}` | **nenhuma** — a defesa é a **allowlist de origem** do formulário |

> ### A API key `sk_*` é SEGREDO — nunca vai para o browser
> A chave é validada a cada chamada e resolve a conta sozinha (um `tenant_id` no
> corpo é ignorado). Ela mora **só no servidor** — variável de ambiente, secret
> manager — e **jamais** em bundle de front, `NEXT_PUBLIC_*` ou `localStorage`.
> No SDK, o modo de browser está num **entry separado** (`@asender/pages-sdk/client`)
> que não importa o caminho da chave: por construção, o bundle do navegador não
> alcança o segredo. Vazou uma chave? Revogue no painel — ela para de valer na hora.

### Gerar a API key

As chaves são emitidas pela Plataforma — pela tela de **API keys** do painel ou
por `POST https://api.asender.net/api/tenants/{id}/api-keys` (ver a
[Platform API](https://developers.asender.net/apis/platform.html)). Use **`sk_test_…`**
fora de produção e **`sk_live_…`** só em produção.

### Server-side — route handler do Next (o caso "Bioma")

O formulário da sua página posta no **seu** endpoint; o seu endpoint (no servidor)
chama o Asender com a chave. O visitante nunca vê a chave.

```ts
// app/api/lead/route.ts — RODA NO SERVIDOR
import { createServerClient, AsenderHttpError } from "@asender/pages-sdk";

const pages = createServerClient({ apiKey: process.env.ASENDER_API_KEY! });

export async function POST(req: Request) {
  const { email, nome, empresa } = await req.json();
  try {
    const r = await pages.captureLead({
      formId: "form_da_bioma",
      campos: { email, nome, empresa },           // "empresa" não-mapeado vira custom field
      origem: { utm_source: "bioma", utm_medium: "site" },
    });
    return Response.json({ ok: true, lead_id: r.lead_id, duplicada: r.duplicada });
  } catch (e) {
    if (e instanceof AsenderHttpError) return Response.json({ erro: e.message }, { status: e.status });
    throw e; // rede/validação — não engole
  }
}
```

O corpo enviado ao runtime é `{ form_id, campos, origem }` — `campos` é um mapa
**nome→valor**, explícito (anti mass assignment). Sucesso é **201** (novo) ou
**200** (deduplicado); `r.criado` traduz isso e `r.duplicada` vem do corpo.

### Client-side — snippet anônimo (sem chave)

Quando o formulário pode postar direto do browser, use o entry `/client`. **Não
há API key**: autorize a **origem** da sua página na allowlist do formulário (no
painel de Páginas) — o runtime recusa origem fora da lista com 403.

```ts
import { createBrowserClient } from "@asender/pages-sdk/client";

const pages = createBrowserClient();

form.addEventListener("submit", async (ev) => {
  ev.preventDefault();
  const campos = Object.fromEntries(new FormData(form) as any) as Record<string, string>;
  await pages.submitForm({ formId: "form_da_bioma", campos });
  // /f/{formID} SEMPRE responde 200 (aceito ou spam, indistinguível, por desenho)
});
```

### Como os campos viram destino

O que você manda em `campos` é preservado **inteiro**. Para cada campo, o
formulário aplica seu **mapa de destino**: um campo mapeado para um alvo canônico
(`email` | `telefone` | `nome`) alimenta o campo estruturado do CRM/marketing; um
campo **não-mapeado vira custom field** com o nome do campo — **nunca é
descartado**. Toda submissão é gravada no histórico de coleta para auditoria,
antes de seguir aos destinos marcados (CRM, marketing, webhook).

### Erros e retry

O SDK **não engole erro**: `AsenderValidationError` (entrada inválida, antes da
rede), `AsenderHttpError` (`.status`, mensagem já extraída do envelope) e
`AsenderNetworkError` (`.cause`). Ele re-tenta com backoff só em falha de rede e
em `429/502/503`; **nunca** em `4xx` determinístico (400/401/403/404).

---

## Medir o publicado

Base: `https://api.pages.asender.net`, com **sessão** (é o painel quem lê).

### Analytics

Relatórios por **janela** (`?de=&ate=` RFC3339, padrão 7 dias, teto 92):

```bash
curl 'https://api.pages.asender.net/v1/analytics/overview?pagina=<id>&de=2026-08-01T00:00:00Z&ate=2026-08-29T00:00:00Z' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>'
```

- `/overview`, `/breakdown` (`?dimensao=utm_source` — dimensão desconhecida
  responde **400 com a lista aceita**), `/events`, `/session/{id}`,
  `/traffic-quality`, `/ab`, `/heatmap` (`?lado=`).
- **Tempo real**: `/live` (instantâneo) e `/live/stream` (**SSE**).

### Pixels

O control plane dos pontos de coleta: `GET/POST /v1/pixels` (a criação devolve o
**snippet** pronto com a credencial assinada e URLs **absolutas** do runtime público,
prontas para colar em site externo), `…/domains` (as origens
autorizadas a coletar) e `…/conversions` (as conversões rastreadas).

```bash
curl -X POST 'https://api.pages.asender.net/v1/pixels' \
  -H 'Authorization: Bearer <token-de-sessão>' \
  -H 'X-Asender-Tenant: <slug-da-conta>' \
  -H 'Content-Type: application/json' \
  -d '{ "nome": "Landing principal", "ativo": true }'
# → 201 { "id":"…", "nome":"Landing principal", "ativo":true,
#         "snippet":"<script src=\"https://sites.asender.net/pixel.js\" data-lz=\"…\"
#                     data-lz-collect=\"https://sites.asender.net/collect\"
#                     data-lz-replay-url=\"https://sites.asender.net/replay\" data-lz-replay=\"1\" async></script>" }
```

### Coleta e session replay (público)

`GET /pixel.js` serve o script; `POST /collect` ingere um lote de eventos de
comportamento; `POST /replay` grava uma jornada. Os três rodam no runtime
(`sites.asender.net`), são **anônimos** e trazem a **credencial do pixel** no
corpo (o token assinado que a página carrega). São o que o `pixel.js` chama — você
não os invoca à mão. A **leitura** das jornadas é autenticada:
`GET /v1/replay/sessions` e `…/sessions/{id}/events`, na base de autoria.

---

A referência completa de cada rota — parâmetros, corpo, respostas e um `curl`
pronto — está logo abaixo, gerada do código e da spec.

> **Superfície interna (não pública).** O runtime e a autoria conversam por um
> canal interno de control plane, reservado aos serviços da casa: a definição do
> formulário, a página publicada para render, o `sitemap`, a
> autorização de TLS de domínio próprio e a descarga de contagens. Ele **não** é
> documentado aqui porque não é uma superfície de integração: use a sessão (para
> administrar) ou a API key (para enviar leads).



------------------------------------------------------------------------------
## GUIA DA API: Páginas: o JSON do documento v2  (https://developers.asender.net/guias/pages-documento-v2.html)
------------------------------------------------------------------------------

# Documento de página v2: guia completo para agentes

Este guia ensina uma pessoa **ou um agente de IA** a ler, criar, editar e publicar páginas e
formulários do Asender Pages pela API pública, produzindo o JSON do documento **v2** certo
na primeira tentativa. As tabelas de campos, limites e tipos são **geradas do JSON Schema
do contrato** (`asender_docs/contratos/pages-documento-v2.schema.json`), o mesmo que os
validadores Go (autoridade, roda no servidor) e TypeScript (roda no editor) provam
concordar; por isso elas não envelhecem. Tudo que aparece em JSON aqui foi validado nos
três lados.

- **Base da API:** `https://api.pages.asender.net` (JSON, UTF-8).
- **Referência de rotas:** [Pages API](https://developers.asender.net/apis/pages.html) (operações geradas do código) e o guia
  [Pages API: autenticação, erros, domínios](https://developers.asender.net/apis/pages.html#autenticacao). Este guia cobre o que
  elas não dizem: **o conteúdo da página**.
- **Contexto inteiro para um agente:** [`llms-full.txt`](https://developers.asender.net/llms-full.txt) inclui este guia.
- **Schema:** `pages-documento-v2.schema.json` (JSON Schema 2020-12), também publicado como
  `DocumentoV2` e `DocV2_*` na OpenAPI de Páginas.

> **Regra de ouro para agentes:** o servidor é a autoridade. Valide localmente contra o
> schema, **envie**, e se vier `422` leia `codigo` e `caminho` (seção 4), corrija **só aquele
> nó** e reenvie. Nunca invente campo: campo desconhecido é recusado.

## 1. Início rápido para agentes

### 1.1 Credenciais: o que cada uma alcança

Um agente externo trabalha com uma **API key** (`sk_live_...` / `sk_test_...`), criada pelo dono da
conta em *Desenvolvedores → Chaves de API* com os **escopos mínimos** da tarefa. A conta é sempre
a **da chave** (validada no servidor a cada chamada; chave revogada para na hora): nenhum header
nem campo do corpo escolhe a conta, e um `tenant_id` no corpo é recusado. Página, rascunho, mídia
ou domínio de outra conta responde `404`, igual a um id que não existe.

| Escopo da chave | O que permite |
| --- | --- |
| `pages:read` | ler: `GET /v1/paginas`, `GET /v1/paginas/{id}`, `GET /v1/paginas/{id}/rascunho`, `GET /v1/paginas/{id}/seo`, `GET /v1/dominios`, `GET /v1/midias` |
| `pages:write` | criar e editar, **sem publicar**: `POST /v1/paginas`, `POST /v1/paginas/{id}/versoes`, `PUT`/`DELETE /v1/paginas/{id}/rascunho`, `PUT /v1/paginas/{id}/seo`, `POST /v1/paginas/importar`, `POST /v1/paginas/{id}/midias/copiar`, `PUT /v1/paginas/{id}/dominio`, `POST /v1/paginas/lote` com `duplicar`/`mudar_dominio`, `POST /v1/midias`, `POST /v1/midias/de-url` |
| `pages:publish` | **publicar e despublicar** (o ato visível ao público e indexável): `POST /v1/paginas/{id}/publicar` e `POST /v1/paginas/lote` com `publicar`/`despublicar` |
| `forms:read` / `forms:write` | formulários e o envio de leads (seção 3.8) |

Os escopos **não se implicam**: `pages:write` não lê (precisa de `pages:read` para listar) nem
publica. Um agente que cria, confere e publica precisa dos três. Sem o escopo da rota, `403`
(`{"erro":"a chave não tem o escopo pages:publish"}`); rota que não aceita chave, `401`. A **sessão OIDC**
de uma pessoa (`Authorization: Bearer <token-de-sessão>` + `X-Asender-Tenant: <slug-da-conta>`)
continua alcançando tudo de autoria e é o que o painel usa; a chave **não** alcança editar
slug/título (`PATCH`), testes A/B, roteamento, apagar mídia, SEO do site, redirects nem marca.

**Regras que protegem o trabalho de pessoas** (valem só para chave):

- **Rascunho com `?base=` obrigatório.** `PUT /v1/paginas/{id}/rascunho` sem `?base=` responde
  `428`. Leia o rascunho (`GET`, devolve `rascunho_em`) e devolva esse valor em `?base=`; sem
  rascunho anterior use `?base=` vazio. Se uma pessoa (ou outro agente) gravou no meio, o
  servidor responde `409` `RascunhoConflito` com o rascunho dela e **não grava nada**: os dois
  lados ficam preservados; mescle e tente de novo com o `rascunho_em` novo.
- **Publicar exige a `versao`.** Com chave, `POST .../publicar` sem `{"versao": N}` responde `422`:
  o agente publica a versão que ele identificou (o retorno do `POST .../versoes`, ou
  `ultima_versao` em `GET /v1/paginas/{id}`), nunca "a mais recente" às cegas, que pode ser uma
  edição de pessoa ainda não revisada. `POST /v1/paginas/lote` com `publicar` publica a última
  versão **salva** e pula a página com rascunho mais novo (política `pular`, padrão).
- **Nada é sobrescrito.** Cada `POST .../versoes` cria a versão seguinte; publicar move um ponteiro.
  Desfazer é publicar a versão anterior.
- **Autoria visível.** Versões e rascunhos feitos por chave levam `apikey:<key_id>` (coluna
  `criado_por`; o rascunho devolve `rascunho_por`), distinguindo agente de pessoa; as ferramentas
  de importação por CLI (`--nova-versao`) recusam sobrescrever a última versão feita por **pessoa**.
- **Sem HTML cru.** Conteúdo com bloco/item `html` exige um usuário com nível elevado; chave de
  API recebe `403` nesse caso.
- **Ritmo por chave.** Escritas: 60 por minuto por chave; publicar/despublicar: 20 por minuto;
  acima disso `429` com `Retry-After`. Leituras não contam. `POST /v1/paginas/lote` ainda tem o
  teto de 12 chamadas por minuto por conta.
- **Tudo fica no log.** Cada chamada com chave aparece em *Desenvolvedores → Logs*
  (`servico: pages`), com a rota, o status, a chave e o conteúdo redigido.

Os exemplos usam `$KEY` (a API key) e `$API`; o mesmo curl funciona com sessão trocando o header.

```bash
export API=https://api.pages.asender.net
export KEY='sk_live_...'        # escopos: pages:read pages:write pages:publish
H=(-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json')
# Com sessão de pessoa: -H "Authorization: Bearer $TOKEN" -H "X-Asender-Tenant: $CONTA"
```

### 1.2 O documento mínimo válido

```json
{ "versao": 2, "secoes": [ { "id": "a", "colunas": [ { "id": "ac", "itens": [] } ] } ] }
```

Uma seção, uma coluna, zero itens. Com um título:

```json
{
  "versao": 2,
  "secoes": [
    { "id": "s1", "colunas": [
      { "id": "s1c1", "itens": [
        { "id": "s1c1i1", "tipo": "titulo", "props": { "texto": "Olá, mundo", "nivel": 1 } }
      ] }
    ] }
  ]
}
```

Todo item tem `id`, `tipo` e `props` (objeto, pode ser `{}`).

### 1.3 Criar, editar e publicar (o caminho feliz)

```bash
# 1) criar a página (nasce DESPUBLICADA, com a versão 1 = o template enviado)
curl -sS -X POST "$API/v1/paginas" "${H[@]}" -d '{
  "titulo": "Lançamento",
  "slug": "lancamento",
  "template": { "versao": 2, "secoes": [ { "id": "s1", "colunas": [ { "id": "s1c1", "itens": [
    { "id": "t1", "tipo": "titulo", "props": { "texto": "Olá, mundo", "nivel": 1 } } ] } ] } ] }
}'
# -> 201 { "id":"<pagina-id>", "slug":"lancamento", "dominio":"<conta>.apages.xyz", "titulo":"Lançamento",
#          "versao_publicada":0, "ultima_versao":1, "url_publica":"https://<conta>.apages.xyz/lancamento" }

# 2) salvar uma NOVA versão (cada POST cria a versão seguinte; nada é sobrescrito)
curl -sS -X POST "$API/v1/paginas/<pagina-id>/versoes" "${H[@]}" -d @corpo-versao.json   # {"template": {...}}
# -> 201 { "versao": 2 }     |  422 { "erro":"...", "codigo":"ErrPropInvalida", "caminho":"secoes[0]..." }

# 3) publicar UMA versão, pelo número (chave: escopo pages:publish e `versao` obrigatória)
curl -sS -X POST "$API/v1/paginas/<pagina-id>/publicar" "${H[@]}" -d '{ "versao": 2 }'
# -> 200 { "versao_publicada": 2 }

# Rascunho (auto-save, sem versão): leia o rascunho_em e devolva em ?base= (obrigatório com chave)
curl -sS "$API/v1/paginas/<pagina-id>/rascunho" "${H[@]}"            # -> 200 {template, rascunho_em} | 204
curl -sS -X PUT "$API/v1/paginas/<pagina-id>/rascunho?base=<rascunho_em>" "${H[@]}" -d '{"template": {...}}'
# -> 200 { "rascunho_em": "..." } | 409 RascunhoConflito (com o rascunho do servidor) | 428 sem ?base=
```

Sem `template` no `POST /v1/paginas`, a página nasce com um documento inicial (uma seção `hero`
com o título digitado). Corpo máximo: **512 KiB**.

### 1.4 O endereço da página e o domínio padrão

Toda conta tem um **domínio padrão** num subdomínio de `apages.xyz` (ex.:
`minhaconta.apages.xyz`). Uma página criada **sem** `dominio` nasce nele; a `url_publica` da
resposta é o endereço para abrir. Para usar outro domínio (um próprio, já **verificado**),
crie/atualize a página com `dominio` ou, depois, mova com `PUT /v1/paginas/{id}/dominio`
(API key `pages:write`):

```bash
curl -sS "$API/v1/dominios" "${H[@]}"          # pages:read, o padrão vem primeiro
curl -sS -X PUT "$API/v1/paginas/<pagina-id>/dominio" "${H[@]}" -d '{ "dominio_id": "<id>", "caminho": "novo-slug" }'
```

Detalhes (301 do endereço antigo, erros 409/422) na seção 6.5.

### 1.5 Antes de gerar JSON

1. Escolha a estrutura (seção 2) e os tipos de item (seção 3.1).
2. Gere `id`s únicos no documento inteiro (sugestão: `s1`, `s1c1`, `s1c1i1`...).
3. Use **somente** os campos das tabelas da seção 3; tudo que não está lá é recusado.
4. Imagens: URL da galeria da conta ou `https://` externa (seção 5).
5. Valide contra o schema, envie, leia o `422` se vier (seção 4).

## 2. Modelo mental

```
documento (versao: 2)
 |- configuracoes   (livre, passthrough)
 |- estilo          (a PÁGINA: tema, fundo, textura, fontes, caixa do conteúdo)
 '- secoes[]        (faixas horizontais, de cima para baixo)
     '- colunas[]   (células lado a lado dentro da seção)
         '- itens[] (objetos atômicos: titulo, texto, imagem, botao...)
              '- abas / acordeao: painéis com itens aninhados (um único nível)
```

- **Seção** é uma faixa de página inteira: fundo, borda, padding, altura, âncora e
  comportamento (`normal`, `fixa_topo`, `popup`). Tem de ter 1..12 colunas.
- **Coluna** é a célula da grade. Seu `largura` é um **peso** (`fr` do CSS grid): colunas 1+2
  ocupam 1/3 e 2/3; cinco colunas de peso 1 dão quintos. Define também o alinhamento do
  conteúdo e o `gap` entre os itens.
- **Item** é o objeto. Mora **sempre** dentro de uma coluna e não contém outros itens, exceto
  os painéis de `abas`/`acordeao` (um nível só, sem `abas`, `acordeao`, `html` nem `formulario`
  dentro).
- **Estilo da página** (`estilo`) vem antes das seções: tema (`claro`/`escuro`/`auto`), fundo
  atrás de tudo (cor, degradê, imagem), textura sutil, fontes e a **caixa do conteúdo**
  (`estilo.conteudo`: o miolo contido de toda seção, a "coluna estreita" de uma página de
  links).

**Responsividade.** Os pontos de quebra são fixos: celular até 767 px, tablet 768 a 1023 px,
computador a partir de 1024 px. No celular as colunas **empilham** (`layout_celular: empilhar`,
o padrão) ou ficam lado a lado (`manter`); `inverter_celular` inverte a ordem da pilha.
`padding_celular` e `espacador.altura_celular` ajustam o respiro no celular. `ocultar_em`
(seção ou item) esconde por dispositivo. Não há CSS livre: tudo é campo fechado.

**Ids.** `^[A-Za-z0-9_-]{1,64}$`, **únicos no documento inteiro**: seção, coluna, item e os
itens dentro de painéis dividem o mesmo espaço (um item de painel com o `id` de uma seção é
`ErrID`). **Âncoras** (`secao.ancora`): `^[a-z][a-z0-9-]{0,63}$`, únicas na página; viram o `id`
HTML da seção e o alvo de `#ancora` em botões e menus.

**Ordem e tamanho.** As seções são renderizadas na ordem do array. Tetos importantes: 200
seções, 12 colunas por seção, 100 itens por coluna, **1000 itens por página** (contando os de
painéis). Tabela completa na seção 3.

**Versões do formato.** Só o `versao: 2` deve ser escrito. O formato v1 (lista plana de
blocos) ainda é lido, mas está em saída; não gere v1.

**Normalização.** O servidor valida e regrava o documento na forma canônica; o que você lê de
volta pode ter a ordem das chaves diferente do que enviou.

## 3. Referência de campos

Tudo nesta seção vem do schema. Convenções das tabelas: **Tipo** é o tipo JSON; "cor" e
"url de mídia" são tipos nomeados (seção 3.4); **Padrão** é o que o renderer aplica quando a
prop está ausente (só aparece quando verificado); "obrigatório" marca campos sem os quais o
documento é recusado. Todas as props de item são opcionais, mas um item sem conteúdo
(por exemplo um `botao` sem `rotulo`) não desenha nada útil.

### 3.1 Limites do documento

| Limite | Valor | O que limita |
|---|---|---|
| `MaxSecoes` | 200 | seções por página |
| `MaxColunas` | 12 | colunas por seção |
| `MaxPesoColuna` | 12 | peso (`largura`) máximo de uma coluna |
| `MaxItensPorColuna` | 100 | itens por coluna |
| `MaxItensTotal` | 1000 | itens na página inteira (inclui os aninhados em abas/acordeão) |
| `MaxItensLista` | 50 | entradas em `links`, `tags`, `cartoes`, `redes`, `menu` |
| `MaxEspaco` | 400 | teto de padding/margem/gap/altura de espaçador (px) |
| `MaxRaio` | 200 | teto de raio (px) |
| `MaxBorda` | 20 | teto de espessura de borda (px) |
| `MinLarguraMax` | 320 | menor `largura_max` de seção (px) |
| `MaxLarguraMax` | 2400 | maior `largura_max` (px) |
| `MaxAlturaPx` | 2000 | maior `altura_minima` em px |
| `MaxAlturaVh` | 100 | maior `altura_minima` em vh |
| `MaxAtrasoPopup` | 120 | maior `atraso_popup` (segundos) |
| `GapPadraoItens` | 16 | gap padrão entre itens (px) |
| `GapPadraoColunas` | 24 | gap padrão entre colunas (px) |
| `LarguraMaxPadrao` | 1080 | largura do conteúdo contido sem `largura_max` (px) |
| `MaxTamanhoID` | 64 | caracteres de um `id` |
| `MaxTamanhoNome` | 80 | caracteres de `secao.nome` (conta code points, não bytes) |
| `MaxTamanhoURL` | 2048 | caracteres de uma URL |
| `MaxTextoCurto` | 300 | caracteres de títulos, rótulos, alt |
| `MaxTextoLongo` | 20000 | caracteres do `texto` de um item `texto` |
| `MaxTamanhoHTML` | 200000 | caracteres do item `html` |
| `MaxTamanhoPrazo` | 64 | caracteres do `prazo` do contador |
| `MaxTextoTag` | 60 | caracteres do texto de um chip / tag de cartão |
| `MaxPaineis` | 20 | abas ou painéis por item |
| `MaxItensPorPainel` | 20 | itens dentro de UM painel |
| `MaxTituloPainel` | 200 | caracteres do título de aba/pergunta |
| `MaxIconeTag` | 48 | maior `tamanho_icone` dos chips (px) |
| `MaxFAQResposta` | 4000 | caracteres da resposta de uma pergunta de FAQ |
| `MaxFAQPagina` | 50 | perguntas de FAQ somadas na página |
| `MaxSubir` | 200 | maior `estilo.subir` (px) |
| `MaxPaddingImagem` | 40 | maior `padding` da imagem (px) |
| `MinIconeFundo` | 24 | menor contêiner de ícone (px) |
| `MaxIconeFundo` | 72 | maior contêiner de ícone (px) |
| `MaxColunasCartoes` | 4 | colunas da grade de cartões |
| `MinLarguraCartao` | 96 | menor `largura_cartao` (px) |
| `MaxLarguraCartao` | 400 | maior `largura_cartao` (px) |
| `MinMiniatura` | 56 | menor `miniatura` (px) |
| `MaxMiniatura` | 96 | maior `miniatura` (px) |
| `MaxInclinar` | 12 | maior `inclinar` (graus) |
| `MaxRotacaoCartao` | 15 | maior `rotacao` de um cartão (graus, para os dois lados) |
### 3.2 Os 20 tipos de item

| Tipo | Para que serve |
|---|---|
| `titulo` | Título (`h1`..`h6`). Aceita marcação inline `[rótulo](url)` e `[[trecho]]`. |
| `texto` | Parágrafo de texto. Aceita a mesma marcação inline do título e quebras de linha. |
| `imagem` | Imagem, com forma, proporção, moldura e link opcional. |
| `botao` | Botão (ou link-botão) com visual granular, vidro, ícones e imagem. |
| `tags` | Chips (etiquetas) com ícone, link e visual por chip. |
| `links` | Lista de botões de link (o miolo de um link-na-bio), com visual por entrada. |
| `cartoes` | Galeria de cartões (foto, título, texto, tag, ícone, link) em grade, carrossel ou lista. |
| `abas` | Abas; cada aba é um painel com itens aninhados (um nível só). |
| `acordeao` | Acordeão (sanfona); com `faq: true` gera `FAQPage` no JSON-LD da página. |
| `redes` | Ícones de redes sociais (Instagram, WhatsApp...) com link. |
| `menu` | Menu de navegação (links de texto), horizontal ou vertical; pode colapsar no celular. |
| `formulario` | Embute um formulário do Asender (campos reais, anti-spam e captura de lead). |
| `video` | Vídeo incorporado (`<iframe>`) a partir de uma URL de embed. |
| `divisor` | Linha divisória horizontal. |
| `espacador` | Espaço vertical em branco. |
| `icone` | Um ícone avulso (kit de ícones ou ícone clássico). |
| `selo` | Selo (pílula de destaque com um texto curto). |
| `contador` | Contagem regressiva até um prazo. |
| `marca` | Logo e/ou nome da conta (vindos do kit de marca efetivo); útil em cabeçalhos. |
| `html` | HTML cru. PRIVILEGIADO: só quem tem o nível elevado grava; sem ele a escrita é barrada (403). |
### 3.3 Documento, estilo da página, seção e coluna

#### Documento e estilo da página

**Documento (raiz):**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `versao` (obrigatório) | const | `2` |  | Sempre `2`. Qualquer outro valor é `ErrVersao`. |
| `configuracoes` | qualquer JSON |  |  | Passthrough (objeto livre, ex.: `encurtar` links por padrão). Não é layout. |
| `estilo` | estilo da página |  |  | Objeto de estilo (ver a tabela do contexto). |
| `secoes` (obrigatório) | lista de secao | ≥1 · ≤200 |  | Lista de seções (1..200), de cima para baixo. |

**`estilo` (a página inteira):**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `tema` | enum | `claro` · `escuro` · `auto` | `claro` | `claro` (padrão), `escuro` ou `auto` (segue o aparelho). |
| `fundo` | fundo |  |  | Fundo da caixa. `tipo` decide quais campos valem: `cor` exige `cor`; `gradiente` exige `gradiente`; `imagem` exige `imagem.url`. |
| `padrao` | objeto |  |  | Textura sutil desenhada sobre o fundo da página. |
| `padrao.tipo` (obrigatório) | enum | `nenhum` · `pontos` · `grade` · `diagonal` |  | `nenhum`, `pontos`, `grade` ou `diagonal`. |
| `padrao.cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da textura (padrão: a cor do texto). |
| `padrao.opacidade` | inteiro | 0..100 | `8` | Opacidade da textura, em % (0..100). |
| `padrao.tamanho` | const ou inteiro | `0` ou 8..96 | `24` | Módulo da textura em px: `0` (padrão = 24) ou 8..96. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `fonte_titulos` | const ou enum | `""` ou `comfortaa` · `urbanist` · `montserrat` · `inter` · `poppins` · `open-sans` · `nunito` · `playfair-display` · `merriweather` · `dm-sans` · `manrope` · `raleway` |  | Família dos títulos `h1`..`h6`. Vazio herda do kit de marca. Só os ids da allowlist (auto-hospedados em `/_f/`). |
| `fonte_texto` | const ou enum | `""` ou `comfortaa` · `urbanist` · `montserrat` · `inter` · `poppins` · `open-sans` · `nunito` · `playfair-display` · `merriweather` · `dm-sans` · `manrope` · `raleway` |  | Família do texto corrido. Mesma regra de `fonte_titulos`. |
| `preloader` | objeto |  |  | Tela de carregamento com a logo do kit de marca efetivo. `logo` é uma variante do kit, nunca uma URL. |
| `preloader.ativo` | booleano | `true` / `false` |  |  |
| `preloader.logo` | enum | `principal` · `horizontal` · `icone` · `escuro` |  |  |
| `preloader.animacao` | enum | `pulso` · `fade` · `giro` · `barra` |  |  |
| `preloader.cor_fundo` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo atrás da imagem (aparece na moldura/`padding`). |
| `preloader.tamanho` | const ou inteiro | `0` ou 32..240 |  |  |
| `preloader.duracao_min_ms` | inteiro | 0..3000 |  |  |
| `conteudo` | estiloCaixa |  |  | A caixa do miolo CONTIDO de toda seção (a coluna estreita de uma página de links): fundo, borda, raio, sombra, padding. |
**Preloader.** O runtime emite `<div id="pg-pre" class="pg-pre" aria-hidden="true">` com a logo antes das seções. Funciona sem JavaScript (o overlay some sozinho por animação CSS em `duracao_min_ms` + 0,5 s, teto 3,5 s); com JavaScript some no evento `load`, respeitando a duração mínima. `prefers-reduced-motion: reduce` desliga a animação da logo e encurta a saída. O conteúdo continua no HTML (SEO intacto). O canvas do editor não desenha o overlay.

Famílias de fonte aceitas em `estilo.fonte_titulos` e `estilo.fonte_texto` (ids exatos, em
minúsculas; vazio herda do kit de marca; qualquer outro valor é `ErrEstiloInvalido`):

`comfortaa`, `urbanist`, `montserrat`, `inter`, `poppins`, `open-sans`, `nunito`, `playfair-display`, `merriweather`, `dm-sans`, `manrope`, `raleway`
São auto-hospedadas pelo runtime (`/_f/`), sem chamada a terceiros.

#### Seção

**Seção:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `id` (obrigatório) | id | `^[A-Za-z0-9_-]{1,64}$` |  | Único no documento inteiro (seção, coluna, item e itens de painel dividem o mesmo espaço). |
| `preset` | texto | `^[a-z0-9_-]{1,40}$` |  | Só registra de que fábrica a seção nasceu; o renderer não desenha diferente por causa dele. |
| `nome` | texto | ≤80 |  | Rótulo livre, só para a árvore do editor. |
| `ancora` | âncora | `^[a-z][a-z0-9-]{0,63}$` |  | Vira o `id` HTML da seção; alvo de `#ancora` em botões e menus. Única na página. |
| `comportamento` | enum | `normal` · `fixa_topo` · `popup` | `normal` | `normal`; `fixa_topo` gruda no topo ao rolar; `popup` abre por cima após `atraso_popup` s. |
| `atraso_popup` | inteiro | 0..120 |  | Segundos até o popup abrir (só com `comportamento: popup`). |
| `ocultar_em` | lista de enum | sem repetição · valores: `computador`, `tablet`, `celular` |  | Dispositivos em que o nó não aparece. Pontos de quebra: celular até 767 px, tablet 768-1023 px, computador a partir de 1024 px. |
| `ocultar_se_vazia` | booleano | `true` / `false` |  | A seção some quando nenhum item dela desenha algo (ex.: `marca` numa conta sem logo nem nome). |
| `layout_celular` | enum | `empilhar` · `manter` | `empilhar` | `empilhar` (padrão): uma coluna por linha no celular; `manter` conserva as colunas lado a lado. |
| `inverter_celular` | booleano | `true` / `false` |  | Empilha as colunas na ordem inversa no celular. |
| `estilo` | estiloSecao |  |  | Objeto de estilo (ver a tabela do contexto). |
| `colunas` (obrigatório) | lista de coluna | ≥1 · ≤12 |  | Lista de colunas da seção (1..12). |

**`estilo` da seção (`estiloSecao`):**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `padding` | lados |  |  | Respiro interno em px por lado (0..400). |
| `padding_celular` | lados |  |  | Substitui `padding` abaixo de 768 px; ausente, o celular usa `padding`. |
| `fundo` | fundo |  |  | Fundo da caixa. `tipo` decide quais campos valem: `cor` exige `cor`; `gradiente` exige `gradiente`; `imagem` exige `imagem.url`. |
| `borda` | borda |  |  | Objeto de borda (ver `borda`). |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `raio_sup_esq` | inteiro | 0..200 |  | Raio do canto superior esquerdo. Com ao menos um canto presente, o renderer emite os quatro; canto ausente usa `raio` (ou 0). Sentido horário: sup_esq, sup_dir, inf_dir, inf_esq. |
| `raio_sup_dir` | inteiro | 0..200 |  | Raio do canto superior direito (ver `raio_sup_esq`). |
| `raio_inf_dir` | inteiro | 0..200 |  | Raio do canto inferior direito (ver `raio_sup_esq`). |
| `raio_inf_esq` | inteiro | 0..200 |  | Raio do canto inferior esquerdo (ver `raio_sup_esq`). |
| `sombra` | enum | `nenhuma` · `suave` · `media` · `forte` |  | Sombra da caixa (vocabulário de caixa: suave/media/forte). |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `largura` | enum | `contida` · `total` | `contida` | `contida`: o conteúdo respeita `largura_max`; `total`: ocupa a largura toda. |
| `largura_max` | const ou qualquer JSON | `0` | `1080` | Largura do conteúdo contido, em px (320..2400); `0`/ausente = 1080. Só vale com `largura: contida`. |
| `altura_minima` | inteiro | 0..2000 |  | Altura mínima da seção; a unidade é `altura_unidade` (px até 2000, vh até 100). |
| `altura_unidade` | enum | `px` · `vh` |  | `px` (padrão) ou `vh`. |
| `alinhamento_vertical` | enum | `topo` · `centro` · `base` · `esticar` |  | Posição das colunas (seção) ou do conteúdo (coluna) no eixo vertical. |
| `gap_colunas` | inteiro | 0..400 | `24` | Espaço entre as colunas da seção, em px (padrão 24). |
Para uma seção `popup`, `atraso_popup` é em segundos (0..120). `fixa_topo` serve para
cabeçalhos. `ocultar_se_vazia` esconde a seção quando nenhum item desenha algo.

#### Coluna

**Coluna:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `id` (obrigatório) | id | `^[A-Za-z0-9_-]{1,64}$` |  | Único no documento inteiro (seção, coluna, item e itens de painel dividem o mesmo espaço). |
| `largura` | inteiro | 0..12 | `1` | PESO da coluna (unidade `fr`): 1+2 dá 1/3 + 2/3. Ausente/0 = peso 1. |
| `alinhamento_vertical` | enum | `topo` · `centro` · `base` · `esticar` |  | Posição das colunas (seção) ou do conteúdo (coluna) no eixo vertical. |
| `alinhamento_horizontal` | enum | `inicio` · `centro` · `fim` · `esticar` |  | Posição do conteúdo da coluna no eixo horizontal. |
| `gap` | inteiro | 0..400 | `16` | Espaço entre os itens da coluna, em px (padrão 16). Em `tags`/`cartoes`: espaço entre os elementos. |
| `estilo` | estiloCaixa |  |  | Objeto de estilo (ver a tabela do contexto). |
| `itens` (obrigatório) | lista de item | ≤100 |  |  |

**`estilo` da coluna (`estiloCaixa`, o mesmo de `estilo.conteudo` da página):**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `padding` | lados |  |  | Respiro interno em px por lado (0..400). |
| `padding_celular` | lados |  |  | Substitui `padding` abaixo de 768 px; ausente, o celular usa `padding`. |
| `fundo` | fundo |  |  | Fundo da caixa. `tipo` decide quais campos valem: `cor` exige `cor`; `gradiente` exige `gradiente`; `imagem` exige `imagem.url`. |
| `borda` | borda |  |  | Objeto de borda (ver `borda`). |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `raio_sup_esq` | inteiro | 0..200 |  | Raio do canto superior esquerdo. Com ao menos um canto presente, o renderer emite os quatro; canto ausente usa `raio` (ou 0). Sentido horário: sup_esq, sup_dir, inf_dir, inf_esq. |
| `raio_sup_dir` | inteiro | 0..200 |  | Raio do canto superior direito (ver `raio_sup_esq`). |
| `raio_inf_dir` | inteiro | 0..200 |  | Raio do canto inferior direito (ver `raio_sup_esq`). |
| `raio_inf_esq` | inteiro | 0..200 |  | Raio do canto inferior esquerdo (ver `raio_sup_esq`). |
| `sombra` | enum | `nenhuma` · `suave` · `media` · `forte` |  | Sombra da caixa (vocabulário de caixa: suave/media/forte). |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
#### O envelope do item

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `id` (obrigatório) | id | `^[A-Za-z0-9_-]{1,64}$` |  | Único no documento inteiro (seção, coluna, item e itens de painel dividem o mesmo espaço). |
| `tipo` (obrigatório) | enum | `titulo` · `texto` · `imagem` · `botao` · `tags` · `links` · `cartoes` · `abas` · `acordeao` · `redes` · `menu` · `formulario` · `video` · `divisor` · `espacador` · `icone` · `selo` · `contador` · `marca` · `html` |  | Tipo do item (lista fechada). |
| `props` (obrigatório) | objeto |  |  | Props do tipo (tabela do tipo); campo desconhecido é recusado. |
| `estilo` | objeto |  |  | Visual do item na coluna (margem, alinhamento, largura máxima, cor do texto, subir). |
| `estilo.margem` | lados |  |  | Respiro externo do item, por lado, em px (0..400). `subir` > 0 substitui a margem de topo. |
| `estilo.alinhamento` | enum | `herdar` · `inicio` · `centro` · `fim` | `herdar` | Sobrepõe o alinhamento horizontal da coluna; `herdar` (padrão) mantém o da coluna. |
| `estilo.largura_max` | inteiro | 0..2400 |  | Largura máxima do item, em px (0 = sem limite). |
| `estilo.cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `estilo.subir` | inteiro | 0..200 |  | Puxa o item para cima, sobre o anterior (`margin-top` negativo), 0..200 px. Substitui a margem de topo. |
| `ocultar_em` | lista de enum | sem repetição · valores: `computador`, `tablet`, `celular` |  | Dispositivos em que o nó não aparece. Pontos de quebra: celular até 767 px, tablet 768-1023 px, computador a partir de 1024 px. |
Os campos `id`, `tipo` e `props` são obrigatórios. O `estilo` do item é opcional e comum a
todos os tipos: `margem` (por lado), `alinhamento`, `largura_max`, `cor_texto` e `subir`.

### 3.4 Objetos e tipos reutilizados

#### Cores (`cor`)


Uma cor é um hex `#rrggbb` / `#rrggbbaa` OU um token da paleta da página: `transparente`, `acento`, `texto`, `suave`, `fundo`, `superficie`, `borda`. `acento` segue a cor da marca da conta; `transparente` serve de ponta de degradê (fade). Nome de cor CSS (`red`), `rgb()`, hex curto (`#fff`) e qualquer texto livre são recusados. Onde o schema diz "cor ou vazio", `""` significa "use o padrão do tema".

#### `lados`

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `topo` | inteiro | 0..400 |  | Px do lado superior. |
| `direita` | inteiro | 0..400 |  | Px do lado direito. |
| `base` | inteiro | 0..400 |  | Px do lado inferior. |
| `esquerda` | inteiro | 0..400 |  | Px do lado esquerdo. |

#### `fundo`

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `tipo` | enum | `nenhum` · `cor` · `gradiente` · `imagem` |  | `nenhum`, `cor`, `gradiente` ou `imagem`. |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do fundo (obrigatória quando `tipo` é `cor`). |
| `cor_base` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor sólida sob as demais camadas (gradiente/imagem/película). |
| `gradiente` | gradiente |  |  | Degradê (ver `gradiente`). Obrigatório quando `fundo.tipo` é `gradiente`; na película, use-o no lugar de `cor`. |
| `imagem` | objeto |  |  | Imagem de fundo (obrigatória quando `tipo` é `imagem`). |
| `imagem.url` (obrigatório) | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | URL da imagem de fundo (galeria da conta ou `https://`). Obrigatória quando `fundo.tipo` é `imagem`. |
| `imagem.posicao` | enum | `centro` · `topo` · `base` · `esquerda` · `direita` · `topo-esquerda` · `topo-direita` · `base-esquerda` · `base-direita` |  | Posição da imagem de fundo. |
| `imagem.tamanho` | enum | `cobrir` · `conter` · `auto` |  | `cobrir` (preenche cortando), `conter` (mostra inteira) ou `auto` (tamanho original). |
| `imagem.repetir` | booleano | `true` / `false` |  | Repete a imagem de fundo. |
| `imagem.fixo` | booleano | `true` / `false` |  | Fundo fixo (não rola com a página). |
| `sobreposicao` | um de |  |  | Película por cima do fundo: exige `cor` OU `gradiente` (um só) e `opacidade` 0..100 na camada inteira. |
| `sobreposicao.cor` | cor | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da película (use esta OU `gradiente`). |
| `sobreposicao.gradiente` | gradiente |  |  | Degradê (ver `gradiente`). Obrigatório quando `fundo.tipo` é `gradiente`; na película, use-o no lugar de `cor`. |
| `sobreposicao.opacidade` (obrigatório) | inteiro | 0..100 |  | Opacidade da película na camada inteira, em % (0..100). |

#### `gradiente`

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `tipo` | enum | `linear` · `radial` |  | `linear` (padrão, no `angulo`) ou `radial` (círculo a partir do centro). |
| `de` (obrigatório) | cor | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor inicial do degradê (aceita `transparente`). |
| `meio` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor intermediária opcional do degradê. |
| `para` (obrigatório) | cor | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor final do degradê (aceita `transparente`). |
| `angulo` | inteiro | 0..360 |  | Ângulo do degradê, em graus (0..360). |

#### `borda`

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `largura` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `estilo` | enum | `solida` · `tracejada` · `pontilhada` |  | `solida`, `tracejada` ou `pontilhada`. |
| `lados` | lista de enum | sem repetição · valores: `topo`, `direita`, `base`, `esquerda` |  | Lados que recebem a borda (sem repetir); ausente = os quatro. |
### 3.5 Cada tipo de item, campo a campo

#### `titulo`

Título (`h1`..`h6`). Aceita marcação inline `[rótulo](url)` e `[[trecho]]`.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `texto` | texto | ≤300 |  | Texto do título. Aceita a marcação inline (`[rótulo](url)`, `[[destaque]]`). |
| `nivel` | inteiro | 1..6 |  | Nível do cabeçalho (`h1`..`h6`). Use um único `h1` por página. |
| `tamanho` | enum | `auto` · `p` · `m` · `g` · `gg` | `auto` | Escala tipográfica: `auto` (padrão do nível), `p`, `m`, `g`, `gg`. |
| `transformar` | enum | `nenhum` · `caixa_alta` · `caixa_baixa` · `capitalizar` |  | `text-transform`: `nenhum`, `caixa_alta`, `caixa_baixa`, `capitalizar`. |
| `espacamento` | inteiro | 0..6 |  | Espaçamento entre letras (`letter-spacing`) em px, 0..6. |
| `destaque_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor aplicada aos trechos `[[destaque]]` do texto (token ou hex). |
#### `texto`

Parágrafo de texto. Aceita a mesma marcação inline do título e quebras de linha.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `texto` | texto | ≤20000 |  | Texto do parágrafo. Aceita a marcação inline (`[rótulo](url)`, `[[destaque]]`) e quebras de linha. |
| `variante` | enum | `normal` · `suave` · `destaque` · `citacao` | `normal` | `normal`, `suave` (cor atenuada), `destaque`, `citacao`. |
| `tamanho` | enum | `auto` · `p` · `m` · `g` · `gg` | `auto` | Escala tipográfica: `auto` (padrão), `p`, `m`, `g`, `gg`. |
| `transformar` | enum | `nenhum` · `caixa_alta` · `caixa_baixa` · `capitalizar` |  | `text-transform`: `nenhum`, `caixa_alta`, `caixa_baixa`, `capitalizar`. |
| `espacamento` | inteiro | 0..6 |  | Espaçamento entre letras (`letter-spacing`) em px, 0..6. |
| `destaque_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor aplicada aos trechos `[[destaque]]` do texto (token ou hex). |
#### `imagem`

Imagem, com forma, proporção, moldura e link opcional.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `url` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | URL da imagem: da galeria da conta (`/v1/public/midias/<id>`) ou `https://` externa. Sem aspas, espaços, parênteses ou `<>`. |
| `alt` | texto | ≤300 |  | Texto alternativo (acessibilidade e SEO). Descreva a imagem; vazio só para imagem decorativa. |
| `link` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | Destino ao clicar na imagem (regra de href). |
| `forma` | enum | `normal` · `arredondada` · `circulo` | `normal` | `normal`, `arredondada` ou `circulo`. `raio` presente vence `forma`. |
| `largura` | inteiro | 16..2400 |  | Largura em px (16..2400). Ausente = a imagem ocupa a coluna. |
| `proporcao` | enum | `auto` · `1:1` · `4:3` · `3:4` · `16:9` · `9:16` | `auto` | Proporção da caixa: `auto` (padrão) ou largura:altura. |
| `ajuste` | enum | `cobrir` · `conter` | `cobrir` | `cobrir` (padrão: preenche cortando) ou `conter` (mostra inteira). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `sombra` | enum | `nenhuma` · `leve` · `forte` |  | Sombra do item (vocabulário de item: leve/forte). Não misture com o de caixa. |
| `cor_fundo` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo atrás da imagem (aparece na moldura/`padding`). |
| `padding` | inteiro | 0..40 |  | Respiro interno em px por lado (0..400). |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `raio_sup_esq` | inteiro | 0..200 |  | Raio do canto superior esquerdo. Com ao menos um canto presente, o renderer emite os quatro; canto ausente usa `raio` (ou 0). Sentido horário: sup_esq, sup_dir, inf_dir, inf_esq. |
| `raio_sup_dir` | inteiro | 0..200 |  | Raio do canto superior direito (ver `raio_sup_esq`). |
| `raio_inf_dir` | inteiro | 0..200 |  | Raio do canto inferior direito (ver `raio_sup_esq`). |
| `raio_inf_esq` | inteiro | 0..200 |  | Raio do canto inferior esquerdo (ver `raio_sup_esq`). |
| `link_rastreio` | objeto ou null |  |  | Objeto do encurtador para `link` (ver `url_rastreio`). |
#### `botao`

Botão (ou link-botão) com visual granular, vidro, ícones e imagem.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `rotulo` | texto | ≤300 |  | Texto do botão. |
| `transformar` | enum | `nenhum` · `caixa_alta` · `caixa_baixa` · `capitalizar` |  | `text-transform`: `nenhum`, `caixa_alta`, `caixa_baixa`, `capitalizar`. |
| `espacamento` | inteiro | 0..6 |  | Espaçamento entre letras (`letter-spacing`) em px, 0..6. |
| `url` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | Destino do link: `http`, `https`, `mailto`, `tel`, `#ancora` ou `/caminho` (nunca `//`). Vazio = sem link (o botão sai como `<span>`). |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `variante` | enum | `solido` · `contorno` · `texto` | `solido` | `solido` (padrão), `contorno` ou `texto`. |
| `tamanho` | enum | `p` · `m` · `g` | `m` | `p`, `m` (padrão) ou `g`. |
| `largura_total` | booleano | `true` / `false` | `false` | O botão ocupa a largura toda da coluna. |
| `nova_aba` | booleano | `true` / `false` | `false` | Abre em nova aba (`target=_blank` com `rel=noopener`). |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `raio_sup_esq` | inteiro | 0..200 |  | Raio do canto superior esquerdo. Com ao menos um canto presente, o renderer emite os quatro; canto ausente usa `raio` (ou 0). Sentido horário: sup_esq, sup_dir, inf_dir, inf_esq. |
| `raio_sup_dir` | inteiro | 0..200 |  | Raio do canto superior direito (ver `raio_sup_esq`). |
| `raio_inf_dir` | inteiro | 0..200 |  | Raio do canto inferior direito (ver `raio_sup_esq`). |
| `raio_inf_esq` | inteiro | 0..200 |  | Raio do canto inferior esquerdo (ver `raio_sup_esq`). |
| `padding_v` | inteiro | 0..400 |  | Respiro vertical interno em px (0..400). |
| `padding_h` | inteiro | 0..400 |  | Respiro horizontal interno em px (0..400). |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` |  | Peso da fonte, como TEXTO: `"400"`, `"500"`, `"600"`, `"700"`, `"800"`. |
| `fonte_tamanho` | inteiro | 10..72 |  | Tamanho da fonte em px (10..72). |
| `sombra` | enum | `nenhuma` · `leve` · `forte` |  | Sombra do item (vocabulário de item: leve/forte). Não misture com o de caixa. |
| `icone` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Nome do ícone (`^[a-z0-9_-]{1,40}$`): clássico (`raio`, `escudo`, `check`, `seta`, `calendario`, `telefone`...), rede (`instagram`, `whatsapp`...) ou do kit (`tabler-`, `tabler-f-`, `ph-`, `hero-`, `hero-s-` + nome; sem prefixo = Lucide). Nome desconhecido não quebra a página: o ícone some (em `links` vira o ícone genérico de link). |
| `icone_dir` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Ícone do FIM (direita) do botão/entrada. Mesmas regras de `icone`. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `hover_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda no hover. |
| `vidro` | booleano | `true` / `false` |  | Liga o efeito VIDRO LÍQUIDO (fundo translúcido + `backdrop-filter`). Sem `true`, os demais `vidro_*` são ignorados. |
| `vidro_opacidade` | inteiro | 0..100 |  | Alfa do fundo de vidro, em % (0..100). Padrão com vidro ligado: 30. |
| `vidro_desfoque` | inteiro | 0..40 |  | Desfoque do fundo atrás do vidro, em px (0..40). Padrão: 14. |
| `vidro_saturacao` | inteiro | 100..200 |  | Saturação do fundo atrás do vidro, em % (100..200). Padrão: 160. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `cor_icone_inicio` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone do início (vence `cor_icone`). |
| `cor_icone_fim` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone do fim (vence `cor_icone`). |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone no hover. |
| `imagem` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Imagem DENTRO do botão/entrada: URL de mídia (galeria ou `https://`). |
| `imagem_alt` | texto | ≤300 |  | Texto alternativo da imagem do botão. |
| `imagem_posicao` | enum | `inicio` · `fim` · `topo` | `inicio` | Onde fica a imagem: `inicio` (padrão), `fim` ou `topo`. |
| `imagem_tamanho` | enum | `p` · `m` · `g` | `m` | Tamanho da imagem: `p`, `m` (padrão) ou `g`. |
| `imagem_forma` | enum | `quadrada` · `arredondada` · `circulo` | `arredondada` | `quadrada`, `arredondada` (padrão) ou `circulo`. |
| `icone_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Ícone PERSONALIZADO do início: URL de mídia (vira `<img>`). Vence o glifo `icone`; cores de ícone não se aplicam. |
| `icone_dir_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Ícone personalizado do fim (ver `icone_img`). |
| `url_rastreio` | objeto ou null |  |  | Objeto do encurtador de links (`link_id`, `codigo`, `destino`...). Normalmente gerenciado pelo editor; ao importar para outra conta é removido. |
#### `tags`

Chips (etiquetas) com ícone, link e visual por chip.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `itens` | lista de objeto | ≤50 |  | Até 50 chips. |
| `preset` | enum | `translucido` · `solido` · `contorno` | `translucido` | Aparência base dos chips: `translucido` (padrão), `solido`, `contorno`. |
| `icone` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Nome do ícone (`^[a-z0-9_-]{1,40}$`): clássico (`raio`, `escudo`, `check`, `seta`, `calendario`, `telefone`...), rede (`instagram`, `whatsapp`...) ou do kit (`tabler-`, `tabler-f-`, `ph-`, `hero-`, `hero-s-` + nome; sem prefixo = Lucide). Nome desconhecido não quebra a página: o ícone some (em `links` vira o ícone genérico de link). |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `vidro` | booleano | `true` / `false` |  | Liga o efeito VIDRO LÍQUIDO (fundo translúcido + `backdrop-filter`). Sem `true`, os demais `vidro_*` são ignorados. |
| `vidro_opacidade` | inteiro | 0..100 |  | Alfa do fundo de vidro, em % (0..100). Padrão com vidro ligado: 30. |
| `vidro_desfoque` | inteiro | 0..40 |  | Desfoque do fundo atrás do vidro, em px (0..40). Padrão: 14. |
| `vidro_saturacao` | inteiro | 100..200 |  | Saturação do fundo atrás do vidro, em % (100..200). Padrão: 160. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone no hover. |
| `tamanho_icone` | inteiro | 10..48 |  | Tamanho do ícone em px. |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `hover_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda no hover. |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `padding_v` | inteiro | 0..400 |  | Respiro vertical interno em px (0..400). |
| `padding_h` | inteiro | 0..400 |  | Respiro horizontal interno em px (0..400). |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` |  | Peso da fonte, como TEXTO: `"400"`, `"500"`, `"600"`, `"700"`, `"800"`. |
| `fonte_tamanho` | inteiro | 10..72 |  | Tamanho da fonte em px (10..72). |
| `gap` | inteiro | 0..400 |  | Espaço entre os itens da coluna, em px (padrão 16). Em `tags`/`cartoes`: espaço entre os elementos. |
| `alinhamento` | enum | `inicio` · `centro` · `fim` | `inicio` | Alinhamento do conjunto de chips. |
| `quebra` | enum | `quebrar` · `linha` | `quebrar` | `quebrar` (padrão) quebra linha; `linha` mantém uma linha só. |

**Cada entrada de `tags.itens[]`:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `texto` | texto | ≤60 |  | Texto do chip. |
| `icone` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Nome do ícone (`^[a-z0-9_-]{1,40}$`): clássico (`raio`, `escudo`, `check`, `seta`, `calendario`, `telefone`...), rede (`instagram`, `whatsapp`...) ou do kit (`tabler-`, `tabler-f-`, `ph-`, `hero-`, `hero-s-` + nome; sem prefixo = Lucide). Nome desconhecido não quebra a página: o ícone some (em `links` vira o ícone genérico de link). |
| `url` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | Destino do link: `http`, `https`, `mailto`, `tel`, `#ancora` ou `/caminho` (nunca `//`). Vazio = sem link (o botão sai como `<span>`). |
| `nova_aba` | booleano | `true` / `false` |  | Abre em nova aba (`target=_blank` com `rel=noopener`). |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `hover_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda no hover. |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `padding_v` | inteiro | 0..400 |  | Respiro vertical interno em px (0..400). |
| `padding_h` | inteiro | 0..400 |  | Respiro horizontal interno em px (0..400). |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` |  | Peso da fonte, como TEXTO: `"400"`, `"500"`, `"600"`, `"700"`, `"800"`. |
| `fonte_tamanho` | inteiro | 10..72 |  | Tamanho da fonte em px (10..72). |
| `sombra` | enum | `nenhuma` · `leve` · `forte` |  | Sombra do item (vocabulário de item: leve/forte). Não misture com o de caixa. |
| `vidro` | booleano | `true` / `false` |  | Liga o efeito VIDRO LÍQUIDO (fundo translúcido + `backdrop-filter`). Sem `true`, os demais `vidro_*` são ignorados. |
| `vidro_opacidade` | inteiro | 0..100 |  | Alfa do fundo de vidro, em % (0..100). Padrão com vidro ligado: 30. |
| `vidro_desfoque` | inteiro | 0..40 |  | Desfoque do fundo atrás do vidro, em px (0..40). Padrão: 14. |
| `vidro_saturacao` | inteiro | 100..200 |  | Saturação do fundo atrás do vidro, em % (100..200). Padrão: 160. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone no hover. |
| `imagem` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Imagem DENTRO do botão/entrada: URL de mídia (galeria ou `https://`). |
| `imagem_alt` | texto | ≤300 |  | Texto alternativo da imagem do botão. |
| `imagem_posicao` | enum | `inicio` · `fim` · `topo` |  | Onde fica a imagem: `inicio` (padrão), `fim` ou `topo`. |
| `imagem_tamanho` | enum | `p` · `m` · `g` |  | Tamanho da imagem: `p`, `m` (padrão) ou `g`. |
| `imagem_forma` | enum | `quadrada` · `arredondada` · `circulo` |  | `quadrada`, `arredondada` (padrão) ou `circulo`. |
| `icone_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Ícone PERSONALIZADO do início: URL de mídia (vira `<img>`). Vence o glifo `icone`; cores de ícone não se aplicam. |
| `icone_dir_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Ícone personalizado do fim (ver `icone_img`). |
| `cor_icone_inicio` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone do início (vence `cor_icone`). |
| `url_rastreio` | objeto ou null |  |  | Objeto do encurtador de links (`link_id`, `codigo`, `destino`...). Normalmente gerenciado pelo editor; ao importar para outra conta é removido. |
#### `links`

Lista de botões de link (o miolo de um link-na-bio), com visual por entrada.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `itens` | lista de objeto | ≤50 |  | Até 50 botões. Entrada sem `titulo` e sem URL válida é ignorada; sem `titulo`, a URL vira o texto do botão. |
| `estilo` | enum | `cartao` · `preenchido` · `contorno` · `fantasma` · `suave` · `sombra` | `cartao` | Aparência dos botões: `cartao` (padrão), `preenchido`, `contorno`, `fantasma`, `suave`, `sombra`. |
| `tamanho` | enum | `p` · `m` · `g` | `m` | `p`, `m` (padrão) ou `g`. |
| `largura` | enum | `total` · `conteudo` | `total` | `total`: cada botão ocupa a largura da coluna; `conteudo`: só o tamanho do conteúdo. |
| `alinhamento_texto` | enum | `centro` · `inicio` | `centro` | Alinhamento do texto do botão/cartão: `centro` ou `inicio`. |
| `efeito` | enum | `elevar` · `escala` · `brilho` · `fundo` · `sublinhado` · `nenhum` | `elevar` | Efeito no hover/foco: `elevar` (padrão), `escala`, `brilho`, `fundo`, `sublinhado`, `nenhum`. Desligado em `prefers-reduced-motion`. |
| `efeito_icone` | enum | `nenhum` · `deslizar` · `destacar` · `girar` | `nenhum` | `girar` gira o ícone do fim no hover (bola de seta); `deslizar`, `destacar`, `nenhum` (padrão). |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `espaco` | inteiro | 0..400 |  | Espaço entre os botões da lista, em px. |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `vidro` | booleano | `true` / `false` |  | Liga o efeito VIDRO LÍQUIDO (fundo translúcido + `backdrop-filter`). Sem `true`, os demais `vidro_*` são ignorados. |
| `vidro_opacidade` | inteiro | 0..100 |  | Alfa do fundo de vidro, em % (0..100). Padrão com vidro ligado: 30. |
| `vidro_desfoque` | inteiro | 0..40 |  | Desfoque do fundo atrás do vidro, em px (0..40). Padrão: 14. |
| `vidro_saturacao` | inteiro | 100..200 |  | Saturação do fundo atrás do vidro, em % (100..200). Padrão: 160. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |
| `cor_icone_inicio` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone do início (vence `cor_icone`). |
| `cor_icone_fim` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone do fim (vence `cor_icone`). |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone no hover. |
| `tamanho_icone` | inteiro | 12..64 |  | Tamanho do ícone em px. |

**Cada entrada de `links.itens[]`:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `titulo` | texto | ≤300 |  | Texto principal do botão. |
| `texto` | texto | ≤300 |  | Linha secundária sob o título do botão. |
| `url` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | Destino do link: `http`, `https`, `mailto`, `tel`, `#ancora` ou `/caminho` (nunca `//`). Vazio = sem link (o botão sai como `<span>`). |
| `icone` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Nome do ícone (`^[a-z0-9_-]{1,40}$`): clássico (`raio`, `escudo`, `check`, `seta`, `calendario`, `telefone`...), rede (`instagram`, `whatsapp`...) ou do kit (`tabler-`, `tabler-f-`, `ph-`, `hero-`, `hero-s-` + nome; sem prefixo = Lucide). Nome desconhecido não quebra a página: o ícone some (em `links` vira o ícone genérico de link). |
| `icone_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Ícone PERSONALIZADO do início: URL de mídia (vira `<img>`). Vence o glifo `icone`; cores de ícone não se aplicam. |
| `icone_dir` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Ícone do FIM (direita) do botão/entrada. Mesmas regras de `icone`. |
| `icone_dir_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Ícone personalizado do fim (ver `icone_img`). |
| `destaque` | booleano | `true` / `false` |  | Realça a entrada (visual de destaque do tema). |
| `nova_aba` | booleano | `true` / `false` |  | Abre em nova aba (`target=_blank` com `rel=noopener`). |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `hover_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda no hover. |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `padding_v` | inteiro | 0..400 |  | Respiro vertical interno em px (0..400). |
| `padding_h` | inteiro | 0..400 |  | Respiro horizontal interno em px (0..400). |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` |  | Peso da fonte, como TEXTO: `"400"`, `"500"`, `"600"`, `"700"`, `"800"`. |
| `fonte_tamanho` | inteiro | 10..72 |  | Tamanho da fonte em px (10..72). |
| `sombra` | enum | `nenhuma` · `leve` · `forte` |  | Sombra do item (vocabulário de item: leve/forte). Não misture com o de caixa. |
| `vidro` | booleano | `true` / `false` |  | Liga o efeito VIDRO LÍQUIDO (fundo translúcido + `backdrop-filter`). Sem `true`, os demais `vidro_*` são ignorados. |
| `vidro_opacidade` | inteiro | 0..100 |  | Alfa do fundo de vidro, em % (0..100). Padrão com vidro ligado: 30. |
| `vidro_desfoque` | inteiro | 0..40 |  | Desfoque do fundo atrás do vidro, em px (0..40). Padrão: 14. |
| `vidro_saturacao` | inteiro | 100..200 |  | Saturação do fundo atrás do vidro, em % (100..200). Padrão: 160. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `cor_icone_inicio` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone do início (vence `cor_icone`). |
| `cor_icone_fim` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone do fim (vence `cor_icone`). |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone no hover. |
| `imagem` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Imagem DENTRO do botão/entrada: URL de mídia (galeria ou `https://`). |
| `imagem_alt` | texto | ≤300 |  | Texto alternativo da imagem do botão. |
| `imagem_posicao` | enum | `inicio` · `fim` · `topo` |  | Onde fica a imagem: `inicio` (padrão), `fim` ou `topo`. |
| `imagem_tamanho` | enum | `p` · `m` · `g` |  | Tamanho da imagem: `p`, `m` (padrão) ou `g`. |
| `imagem_forma` | enum | `quadrada` · `arredondada` · `circulo` |  | `quadrada`, `arredondada` (padrão) ou `circulo`. |
| `url_rastreio` | objeto ou null |  |  | Objeto do encurtador de links (`link_id`, `codigo`, `destino`...). Normalmente gerenciado pelo editor; ao importar para outra conta é removido. |
#### `cartoes`

Galeria de cartões (foto, título, texto, tag, ícone, link) em grade, carrossel ou lista.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `itens` | lista de objeto | ≤50 |  | Até 50 cartões. |
| `layout` | enum | `grade` · `carrossel` · `lista` | `grade` | `grade` (padrão), `carrossel` (rolagem com snap, sem JS) ou `lista` (miniatura + texto). |
| `colunas` | inteiro | 1..4 |  | Colunas da grade (1..4). |
| `largura_cartao` | inteiro | 96..400 |  | Largura de cada cartão no carrossel, em px (96..400). |
| `proporcao` | enum | `auto` · `1:1` · `4:3` · `3:4` · `16:9` · `9:16` · `4:5` | `auto` | Proporção da caixa: `auto` (padrão) ou largura:altura. |
| `ajuste` | enum | `cobrir` · `conter` | `cobrir` | `cobrir` (padrão: preenche cortando) ou `conter` (mostra inteira). |
| `legenda` | enum | `abaixo` · `sobre` · `nenhuma` | `abaixo` | `abaixo` (padrão), `sobre` (texto sobre a foto, com degradê automático) ou `nenhuma`. |
| `miniatura` | inteiro | 56..96 |  | Lado da miniatura no layout `lista`, em px (56..96). |
| `forma_miniatura` | enum | `quadrada` · `arredondada` · `circulo` | `arredondada` | Forma da miniatura da `lista`: `quadrada`, `arredondada` (padrão), `circulo`. |
| `moldura` | enum | `nenhuma` · `polaroid` | `nenhuma` | `nenhuma` (padrão) ou `polaroid`. |
| `inclinar` | inteiro | 0..12 |  | Inclinação alternada do conjunto, em graus (0..12), típica da moldura `polaroid`. |
| `rotulo` | texto | ≤300 |  | Rótulo acessível (`aria-label`) da galeria. |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `raio_sup_esq` | inteiro | 0..200 |  | Raio do canto superior esquerdo. Com ao menos um canto presente, o renderer emite os quatro; canto ausente usa `raio` (ou 0). Sentido horário: sup_esq, sup_dir, inf_dir, inf_esq. |
| `raio_sup_dir` | inteiro | 0..200 |  | Raio do canto superior direito (ver `raio_sup_esq`). |
| `raio_inf_dir` | inteiro | 0..200 |  | Raio do canto inferior direito (ver `raio_sup_esq`). |
| `raio_inf_esq` | inteiro | 0..200 |  | Raio do canto inferior esquerdo (ver `raio_sup_esq`). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `sombra` | enum | `nenhuma` · `leve` · `forte` |  | Sombra do item (vocabulário de item: leve/forte). Não misture com o de caixa. |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `hover_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda no hover. |
| `gap` | inteiro | 0..400 |  | Espaço entre os itens da coluna, em px (padrão 16). Em `tags`/`cartoes`: espaço entre os elementos. |
| `efeito` | enum | `elevar` · `escala` · `brilho` · `nenhum` | `nenhum` | Efeito no hover/foco: `elevar`, `escala`, `brilho`, `nenhum` (padrão). |
| `alinhamento_texto` | enum | `centro` · `inicio` | `inicio` | Alinhamento do texto do botão/cartão: `centro` ou `inicio`. |
| `tamanho_icone` | inteiro | 12..64 |  | Tamanho do ícone em px. |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone no hover. |
| `vidro` | booleano | `true` / `false` |  | Liga o efeito VIDRO LÍQUIDO (fundo translúcido + `backdrop-filter`). Sem `true`, os demais `vidro_*` são ignorados. |
| `vidro_opacidade` | inteiro | 0..100 |  | Alfa do fundo de vidro, em % (0..100). Padrão com vidro ligado: 30. |
| `vidro_desfoque` | inteiro | 0..40 |  | Desfoque do fundo atrás do vidro, em px (0..40). Padrão: 14. |
| `vidro_saturacao` | inteiro | 100..200 |  | Saturação do fundo atrás do vidro, em % (100..200). Padrão: 160. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |

**Cada entrada de `cartoes.itens[]`:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` |  | Foto do cartão (URL de mídia). |
| `alt` | texto | ≤300 |  | Texto alternativo (acessibilidade e SEO). Descreva a imagem; vazio só para imagem decorativa. |
| `titulo` | texto | ≤300 |  | Título do cartão. |
| `texto` | texto | ≤300 |  | Texto do cartão. |
| `tag` | texto | ≤60 |  | Etiqueta curta do cartão (até 60). |
| `icone` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Nome do ícone (`^[a-z0-9_-]{1,40}$`): clássico (`raio`, `escudo`, `check`, `seta`, `calendario`, `telefone`...), rede (`instagram`, `whatsapp`...) ou do kit (`tabler-`, `tabler-f-`, `ph-`, `hero-`, `hero-s-` + nome; sem prefixo = Lucide). Nome desconhecido não quebra a página: o ícone some (em `links` vira o ícone genérico de link). |
| `url` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | Destino do link: `http`, `https`, `mailto`, `tel`, `#ancora` ou `/caminho` (nunca `//`). Vazio = sem link (o botão sai como `<span>`). |
| `nova_aba` | booleano | `true` / `false` |  | Abre em nova aba (`target=_blank` com `rel=noopener`). |
| `rotacao` | inteiro | -15..15 |  | Rotação deste cartão em graus (-15..15). Vence `inclinar` do conjunto. |
| `cor_fim` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Liga o degradê do fundo do cartão: `cor` é o início e `cor_fim` o fim. |
| `angulo` | inteiro | 0..360 |  | Ângulo do degradê, em graus (0..360). |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `hover_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda no hover. |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `padding_v` | inteiro | 0..400 |  | Respiro vertical interno em px (0..400). |
| `padding_h` | inteiro | 0..400 |  | Respiro horizontal interno em px (0..400). |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` |  | Peso da fonte, como TEXTO: `"400"`, `"500"`, `"600"`, `"700"`, `"800"`. |
| `fonte_tamanho` | inteiro | 10..72 |  | Tamanho da fonte em px (10..72). |
| `sombra` | enum | `nenhuma` · `leve` · `forte` |  | Sombra do item (vocabulário de item: leve/forte). Não misture com o de caixa. |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone no hover. |
| `vidro` | booleano | `true` / `false` |  | Liga o efeito VIDRO LÍQUIDO (fundo translúcido + `backdrop-filter`). Sem `true`, os demais `vidro_*` são ignorados. |
| `vidro_opacidade` | inteiro | 0..100 |  | Alfa do fundo de vidro, em % (0..100). Padrão com vidro ligado: 30. |
| `vidro_desfoque` | inteiro | 0..40 |  | Desfoque do fundo atrás do vidro, em px (0..40). Padrão: 14. |
| `vidro_saturacao` | inteiro | 100..200 |  | Saturação do fundo atrás do vidro, em % (100..200). Padrão: 160. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |
| `url_rastreio` | objeto ou null |  |  | Objeto do encurtador de links (`link_id`, `codigo`, `destino`...). Normalmente gerenciado pelo editor; ao importar para outra conta é removido. |
#### `abas`

Abas; cada aba é um painel com itens aninhados (um nível só).

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `itens` | lista de objeto | ≤20 |  | Até 20 abas. Cada uma: `titulo` (obrigatório, não vazio) e `itens` aninhados. |
| `aberta` | inteiro | 0..19 |  | Índice (0 = primeira) da aba aberta de início. Tem de existir. |
| `rotulo` | texto | ≤300 |  | Rótulo acessível (`aria-label`) da lista de abas. |
| `estilo` | enum | `linha` · `pilula` · `cartao` | `linha` | Aparência da barra: `linha` (padrão), `pilula`, `cartao`. |
| `alinhamento` | enum | `inicio` · `centro` · `fim` · `esticar` | `inicio` | Alinhamento da barra de abas; `esticar` reparte a largura. |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `cor_ativa` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Fundo da aba ativa. |
| `cor_texto_ativa` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Texto da aba ativa. |
| `cor_borda_ativa` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Borda da aba ativa. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `padding_v` | inteiro | 0..400 |  | Respiro vertical interno em px (0..400). |
| `padding_h` | inteiro | 0..400 |  | Respiro horizontal interno em px (0..400). |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` |  | Peso da fonte, como TEXTO: `"400"`, `"500"`, `"600"`, `"700"`, `"800"`. |
| `fonte_tamanho` | inteiro | 10..72 |  | Tamanho da fonte em px (10..72). |
| `gap` | inteiro | 0..400 |  | Espaço entre os itens da coluna, em px (padrão 16). Em `tags`/`cartoes`: espaço entre os elementos. |
| `painel_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Fundo da área de conteúdo do painel. |
| `painel_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Texto da área de conteúdo do painel. |
| `painel_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Borda da área de conteúdo do painel. |
| `painel_borda` | inteiro | 0..20 |  | Espessura da borda do painel (0..20). |
| `painel_raio` | inteiro | 0..200 |  | Raio do painel (0..200). |
| `painel_padding` | inteiro | 0..400 |  | Respiro interno do painel em px. |

**Cada entrada de `abas.itens[]`:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `titulo` | texto | ≤200 |  | Título da aba (obrigatório). |
| `itens` | lista de itens aninhados | ≤20 · tipos: `titulo`, `texto`, `imagem`, `botao`, `tags`, `links`, `cartoes`, `redes`, `menu`, `video`, `divisor`, `espacador`, `icone`, `selo`, `contador`, `marca` |  | Até 20 abas. Cada uma: `titulo` (obrigatório, não vazio) e `itens` aninhados. |
#### `acordeao`

Acordeão (sanfona); com `faq: true` gera `FAQPage` no JSON-LD da página.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `itens` | lista de objeto | ≤20 |  | Até 20 painéis. Cada um: `titulo` (obrigatório, não vazio), `aberto` e `itens` aninhados. |
| `um_por_vez` | booleano | `true` / `false` | `false` | Abrir um painel fecha os outros. |
| `faq` | booleano | `true` / `false` |  | Gera `FAQPage` no JSON-LD. Exige texto de resposta em cada painel (itens `texto`/`titulo`), até 4000 caracteres; até 50 perguntas na página. |
| `nivel` | inteiro | 2..6 |  | Nível do cabeçalho de cada pergunta (2..6). |
| `estilo` | enum | `cartao` · `linha` · `simples` | `cartao` | Aparência: `cartao` (padrão), `linha`, `simples`. |
| `indicador` | enum | `seta` · `mais` · `nenhum` | `seta` | Marcador de aberto/fechado: `seta` (padrão), `mais` ou `nenhum`. |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo/principal (token da paleta ou hex). Vazio = a do tema. |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto. Herda da caixa/página quando vazia. |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da borda. |
| `cor_aberto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Fundo do painel aberto. |
| `cor_texto_aberto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Texto do painel aberto. |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor de fundo ao passar o mouse/foco. |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do texto no hover. |
| `raio` | inteiro | 0..200 |  | Raio dos cantos em px (0..200). |
| `borda` | inteiro | 0..20 |  | Espessura da borda em px (0..20). |
| `padding_v` | inteiro | 0..400 |  | Respiro vertical interno em px (0..400). |
| `padding_h` | inteiro | 0..400 |  | Respiro horizontal interno em px (0..400). |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` |  | Peso da fonte, como TEXTO: `"400"`, `"500"`, `"600"`, `"700"`, `"800"`. |
| `fonte_tamanho` | inteiro | 10..72 |  | Tamanho da fonte em px (10..72). |
| `gap` | inteiro | 0..400 |  | Espaço entre os itens da coluna, em px (padrão 16). Em `tags`/`cartoes`: espaço entre os elementos. |
| `painel_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Fundo da área de conteúdo do painel. |
| `painel_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Texto da área de conteúdo do painel. |
| `painel_padding` | inteiro | 0..400 |  | Respiro interno do painel em px. |

**Cada entrada de `acordeao.itens[]`:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `titulo` | texto | ≤200 |  | Pergunta/título do painel (obrigatório). |
| `aberto` | booleano | `true` / `false` |  | Painel aberto de início. Com `um_por_vez`, no máximo um. |
| `itens` | lista de itens aninhados | ≤20 · tipos: `titulo`, `texto`, `imagem`, `botao`, `tags`, `links`, `cartoes`, `redes`, `menu`, `video`, `divisor`, `espacador`, `icone`, `selo`, `contador`, `marca` |  | Até 20 painéis. Cada um: `titulo` (obrigatório, não vazio), `aberto` e `itens` aninhados. |
#### `redes`

Ícones de redes sociais (Instagram, WhatsApp...) com link.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `itens` | lista de objeto | ≤50 |  | Até 50 redes. |
| `tamanho` | enum | `p` · `m` · `g` |  | Tamanho dos ícones: `p`, `m` ou `g`. |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do(s) ícone(s). Vazio herda a cor do texto. |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do INÍCIO: `nenhum`, `circulo`, `quadrado`. |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do início. |
| `icone_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner em px (24..72). |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` |  | Contêiner atrás do ícone do FIM: `nenhum`, `circulo`, `quadrado`. |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do contêiner do ícone do fim. |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 |  | Lado do contêiner do fim em px (24..72). |

**Cada entrada de `redes.itens[]`:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `rede` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Nome da rede: `instagram`, `x`, `facebook`, `linkedin`, `youtube`, `tiktok`, `whatsapp`, `telegram`, `email`, `site`, `github`, `pinterest`. Outro nome vira o ícone genérico de link. |
| `url` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | Destino do link: `http`, `https`, `mailto`, `tel`, `#ancora` ou `/caminho` (nunca `//`). Vazio = sem link (o botão sai como `<span>`). |
| `url_rastreio` | objeto ou null |  |  | Objeto do encurtador de links (`link_id`, `codigo`, `destino`...). Normalmente gerenciado pelo editor; ao importar para outra conta é removido. |
#### `menu`

Menu de navegação (links de texto), horizontal ou vertical; pode colapsar no celular.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `itens` | lista de objeto | ≤50 |  | Até 50 links. |
| `orientacao` | enum | `horizontal` · `vertical` | `horizontal` | `horizontal` (padrão) ou `vertical`. |
| `colapsar_celular` | booleano | `true` / `false` | `false` | No celular o menu vira um botão que abre/fecha. |

**Cada entrada de `menu.itens[]`:**

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `rotulo` | texto | ≤300 |  | Texto do link do menu. |
| `url` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | Destino do link: `http`, `https`, `mailto`, `tel`, `#ancora` ou `/caminho` (nunca `//`). Vazio = sem link (o botão sai como `<span>`). |
| `url_rastreio` | objeto ou null |  |  | Objeto do encurtador de links (`link_id`, `codigo`, `destino`...). Normalmente gerenciado pelo editor; ao importar para outra conta é removido. |
#### `formulario`

Embute um formulário do Asender (campos reais, anti-spam e captura de lead).

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `form_id` | id | `^[A-Za-z0-9_-]{1,64}$` ou vazio |  | Id do formulário (criado em `/v1/formularios`). Vazio = "ainda não configurado" (nada é desenhado). Id de outra conta é removido na importação. |
| `rotulo` | texto | ≤300 |  | Texto do botão de envio do formulário embutido (sobrepõe o do formulário). |
#### `video`

Vídeo incorporado (`<iframe>`) a partir de uma URL de embed.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `url` | url de link | ≤2048 · http/https/mailto/tel, `#ancora`, `/caminho` |  | URL de EMBED (ex.: `https://www.youtube.com/embed/<id>`). Mesma regra de href (http/https/mailto/tel, `#âncora`, `/caminho`). Sem irmã `url_rastreio`. |
| `titulo` | texto | ≤300 |  | Título acessível do `<iframe>`. |
#### `divisor`

Linha divisória horizontal.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor da linha. |
| `espessura` | inteiro | 1..20 |  | Espessura da linha em px (1..20). |
| `estilo` | enum | `solida` · `tracejada` · `pontilhada` |  | Objeto de estilo (ver a tabela do contexto). |
| `largura` | inteiro | 10..100 |  | Largura da linha em % da coluna (10..100). |
#### `espacador`

Espaço vertical em branco.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `altura` | inteiro | 0..400 |  | Altura do espaço em px (0..400). |
| `altura_celular` | inteiro | 0..400 |  | Altura do espaço no celular, em px. |
#### `icone`

Um ícone avulso (kit de ícones ou ícone clássico).

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `nome` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio |  | Rótulo livre, só para a árvore do editor. |
| `tamanho` | inteiro | 12..256 |  | Lado do ícone em px (12..256). |
| `cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) |  | Cor do ícone. |
#### `selo`

Selo (pílula de destaque com um texto curto).

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `texto` | texto | ≤300 |  | Texto do selo. |
#### `contador`

Contagem regressiva até um prazo.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `prazo` | texto | ≤64 |  | Data-hora final em RFC 3339 (ex.: `2026-12-31T23:59:00-03:00`). Ilegível = só o rótulo. |
| `rotulo` | texto | ≤300 |  | Texto que acompanha a contagem. |
#### `marca`

Logo e/ou nome da conta (vindos do kit de marca efetivo); útil em cabeçalhos.

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `mostrar_logo` | booleano | `true` / `false` | `true` | Mostra o logo do kit de marca (padrão `true`). |
| `mostrar_nome` | booleano | `true` / `false` | `true` | Mostra o nome da conta (padrão `true`). |
| `altura_logo` | inteiro | 16..200 |  | Altura do logo em px (16..200). |
#### `html`

HTML cru. PRIVILEGIADO: só quem tem o nível elevado grava; sem ele a escrita é barrada (403).

| Prop | Tipo | Valores / faixa | Padrão | Descrição |
|---|---|---|---|---|
| `html` | texto | ≤200000 |  | HTML cru (até 200000 caracteres). Privilegiado; exige nível elevado. |
### 3.6 Campos visuais compartilhados

Os mesmos nomes aparecem em vários tipos e têm o mesmo significado. A tabela abaixo é
gerada: lista todo campo presente em três ou mais tipos.

| Campo | Tipo | Valores / faixa | Presente em |
|---|---|---|---|
| `alinhamento` | enum | `herdar` · `inicio` · `centro` · `fim` | `item` |
| `alinhamento` | enum | `inicio` · `centro` · `fim` | `tags` |
| `alinhamento` | enum | `inicio` · `centro` · `fim` · `esticar` | `abas` |
| `cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `imagem`, `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links`, `cartoes`, `redes` |
| `cor_icone_inicio` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links` |
| `cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `pagina`, `secao`, `coluna`, `item`, `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `espacamento` | inteiro | 0..6 | `titulo`, `texto`, `botao` |
| `fonte_peso` | enum | `400` · `500` · `600` · `700` · `800` | `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `fonte_tamanho` | inteiro | 10..72 | `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `gap` | inteiro | 0..400 | `coluna`, `tags`, `cartoes`, `abas`, `acordeao` |
| `hover_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `hover_cor_borda` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links`, `cartoes` |
| `hover_cor_icone` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links`, `cartoes` |
| `hover_cor_texto` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `icone` | nome (ícone/rede) | `^[a-z0-9_-]{1,40}$` ou vazio | `botao`, `tags`, `links`, `cartoes` |
| `icone_dir_fundo` | enum | `nenhum` · `circulo` · `quadrado` | `botao`, `tags`, `links`, `cartoes`, `redes` |
| `icone_dir_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links`, `cartoes`, `redes` |
| `icone_dir_fundo_tamanho` | inteiro | 24..72 | `botao`, `tags`, `links`, `cartoes`, `redes` |
| `icone_dir_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` | `botao`, `tags`, `links` |
| `icone_fundo` | enum | `nenhum` · `circulo` · `quadrado` | `botao`, `tags`, `links`, `cartoes`, `redes` |
| `icone_fundo_cor` | cor ou vazio | `#rrggbb`, `#rrggbbaa` ou token (ver *Cores*) | `botao`, `tags`, `links`, `cartoes`, `redes` |
| `icone_fundo_tamanho` | inteiro | 24..72 | `botao`, `tags`, `links`, `cartoes`, `redes` |
| `icone_img` | url de mídia | ≤2048 · http(s) com host ou `/caminho` | `botao`, `tags`, `links` |
| `imagem` | url de mídia | ≤2048 · http(s) com host ou `/caminho` | `botao`, `tags`, `links` |
| `imagem` | objeto |  | `fundo` |
| `imagem_alt` | texto | ≤300 | `botao`, `tags`, `links` |
| `imagem_forma` | enum | `quadrada` · `arredondada` · `circulo` | `botao`, `tags`, `links` |
| `imagem_posicao` | enum | `inicio` · `fim` · `topo` | `botao`, `tags`, `links` |
| `imagem_tamanho` | enum | `p` · `m` · `g` | `botao`, `tags`, `links` |
| `largura` | enum | `contida` · `total` | `secao` |
| `largura` | inteiro | 0..12 | `coluna` |
| `largura` | inteiro | 16..2400 | `imagem` |
| `largura` | enum | `total` · `conteudo` | `links` |
| `largura` | inteiro | 10..100 | `divisor` |
| `largura` | inteiro | 0..20 | `borda` |
| `nova_aba` | booleano | `true` / `false` | `botao`, `tags`, `links`, `cartoes` |
| `padding_h` | inteiro | 0..400 | `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `padding_v` | inteiro | 0..400 | `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `raio` | inteiro | 0..200 | `secao`, `coluna`, `imagem`, `botao`, `tags`, `links`, `cartoes`, `abas`, `acordeao` |
| `raio_inf_dir` | inteiro | 0..200 | `secao`, `coluna`, `imagem`, `botao`, `cartoes` |
| `raio_inf_esq` | inteiro | 0..200 | `secao`, `coluna`, `imagem`, `botao`, `cartoes` |
| `raio_sup_dir` | inteiro | 0..200 | `secao`, `coluna`, `imagem`, `botao`, `cartoes` |
| `raio_sup_esq` | inteiro | 0..200 | `secao`, `coluna`, `imagem`, `botao`, `cartoes` |
| `sombra` | enum | `nenhuma` · `suave` · `media` · `forte` | `secao`, `coluna` |
| `sombra` | enum | `nenhuma` · `leve` · `forte` | `imagem`, `botao`, `tags`, `links`, `cartoes` |
| `tamanho` | const ou inteiro | `0` ou 8..96 | `pagina` |
| `tamanho` | const ou inteiro | `0` ou 32..240 | `pagina` |
| `tamanho` | enum | `auto` · `p` · `m` · `g` · `gg` | `titulo`, `texto` |
| `tamanho` | enum | `p` · `m` · `g` | `botao`, `links`, `redes` |
| `tamanho` | inteiro | 12..256 | `icone` |
| `tamanho` | enum | `cobrir` · `conter` · `auto` | `fundo` |
| `tamanho_icone` | inteiro | 10..48 | `tags` |
| `tamanho_icone` | inteiro | 12..64 | `links`, `cartoes` |
| `transformar` | enum | `nenhum` · `caixa_alta` · `caixa_baixa` · `capitalizar` | `titulo`, `texto`, `botao` |
| `url_rastreio` | objeto ou null |  | `botao`, `tags`, `links`, `cartoes`, `redes`, `menu` |
| `vidro` | booleano | `true` / `false` | `botao`, `tags`, `links`, `cartoes` |
| `vidro_desfoque` | inteiro | 0..40 | `botao`, `tags`, `links`, `cartoes` |
| `vidro_opacidade` | inteiro | 0..100 | `botao`, `tags`, `links`, `cartoes` |
| `vidro_saturacao` | inteiro | 100..200 | `botao`, `tags`, `links`, `cartoes` |
Como pensar neles:

- **Cores.** Hex `#rrggbb`/`#rrggbbaa` ou um token (`acento`, `texto`, `suave`, `fundo`,
  `superficie`, `borda`, `transparente`). Prefira tokens quando quiser que a página siga o kit de
  marca; use hex para cores fixas. Nunca `red`, `rgb(...)`, `#fff` ou texto livre.
- **Vidro líquido.** `vidro: true` liga fundo translúcido com `backdrop-filter`. Ajuste com
  `vidro_opacidade` (0..100, padrão 30), `vidro_desfoque` (0..40 px, padrão 14) e
  `vidro_saturacao` (100..200, padrão 160). Vale em `botao`, `links`, `tags` e `cartoes` (item e
  entradas). **Não** existe em `titulo`, `texto` etc. (prop desconhecida).
- **Raio.** `raio` (0..200) arredonda todos os cantos; `raio_sup_esq`, `raio_sup_dir`,
  `raio_inf_dir`, `raio_inf_esq` fixam cada canto (sentido horário). Com ao menos um canto
  presente, o canto ausente usa `raio`. Em `imagem`, `raio` presente vence `forma`.
- **Sombra.** Caixas (seção, coluna, conteúdo): `nenhuma`, `suave`, `media`, `forte`. Itens
  (imagem, botão, entradas, cartões): `nenhuma`, `leve`, `forte`. Os dois vocabulários **não**
  se misturam.
- **Espaçamento.** `padding` e `margem` são objetos `{topo, direita, base, esquerda}` em px
  (0..400); `padding_v`/`padding_h` são o respiro interno de botões/entradas; `gap` é o espaço
  entre elementos. Lado omitido = 0.
- **Tipografia.** `transformar` (`nenhum`, `caixa_alta`, `caixa_baixa`, `capitalizar`) e
  `espacamento` (0..6 px entre letras) em `titulo`, `texto` e `botao`; `fonte_peso` (texto:
  `"400"`..`"800"`) e `fonte_tamanho` (10..72 px) em botões e entradas; `tamanho`
  (`p`/`m`/`g`/`gg`) em título e texto. Fontes de página: seção 3.3.
- **Ícones de kit.** `icone` e `icone_dir` são nomes, não URLs: clássicos (`raio`, `escudo`,
  `coracao`, `estrela`, `check`, `seta`, `relogio`, `calendario`, `telefone`, `local`,
  `usuario`, `carrinho`, `presente`, `chat`, `cadeado`, `foguete`, `grafico`, `mais`), redes
  (`instagram`, `x`, `facebook`, `linkedin`, `youtube`, `tiktok`, `whatsapp`, `telegram`, `email`,
  `site`, `github`, `pinterest`) e os kits: **Lucide** sem prefixo (`mountain`, `arrow-right`...;
  1942 ícones), **Tabler** `tabler-<nome>` (5826) e `tabler-f-<nome>` (preenchidos), **Phosphor**
  `ph-<nome>` (1434) e **Heroicons** `hero-<nome>` / `hero-s-<nome>` (648). Os nomes são os dos
  kits originais em minúsculas e com hífen. Um nome que o renderer não conhece **não é erro**: o
  ícone some (em `links` vira o ícone genérico de link), então confira o nome.
- **Ícone de mídia (personalizado).** `icone_img` / `icone_dir_img` aceitam uma URL de mídia e
  **vencem** o glifo `icone`. Vira um `<img>`; as props de cor de ícone não se aplicam.
- **Contêiner do ícone.** `icone_fundo` / `icone_dir_fundo` (`circulo` ou `quadrado`) desenham uma
  forma atrás do ícone, com `_cor` e `_tamanho` (24..72 px). Em `redes` só vale no item, não nas
  entradas.
- **Imagem dentro do botão.** `imagem`, `imagem_alt`, `imagem_posicao`, `imagem_tamanho`,
  `imagem_forma` em `botao` e nas entradas de `links`/`tags`.
- **Moldura da imagem.** Em `imagem`: `borda`, `cor_borda`, `sombra`, `cor_fundo` e `padding`
  (0..40) entre a borda e a foto.
- **Subir.** `estilo.subir` (0..200 px) puxa o item sobre o anterior (margem de topo negativa
  que substitui a margem de topo).
- **Camadas de fundo.** `fundo.cor_base` fica sob as demais camadas; `fundo.sobreposicao`
  é uma película por cima (cor **ou** degradê, nunca os dois, com `opacidade` 0..100) e vale sobre
  cor, degradê e imagem. Exemplo: imagem de fundo com película escura:

```json
{ "tipo": "imagem", "cor_base": "#111111",
  "imagem": { "url": "https://exemplo.test/capa.jpg", "tamanho": "cobrir", "posicao": "centro" },
  "sobreposicao": { "gradiente": { "de": "#000000", "para": "transparente", "angulo": 180 }, "opacidade": 60 } }
```

### 3.7 Marcação inline em `titulo.texto` e `texto.texto`

Dentro do texto de um título ou parágrafo (e **só** nesses dois campos) valem duas marcações.
Todo o resto é texto: HTML não é interpretado (`<` e `&` são escapados), então não envie tags.

| Marcação | Resultado |
| --- | --- |
| `[rótulo](https://exemplo.test)` | link `<a rel="noopener noreferrer">`. Endereço permitido: `http://`, `https://`, `mailto:`, `tel:` |
| `[[trecho]]` | trecho em destaque (`span.pg-destaque`); a cor vem de `destaque_cor` |

Regras: sem aninhamento; o rótulo não pode ter `[` ou `]`; o endereço vai até o primeiro `)`,
sem espaço, aspas, `<`, `>`, `\` ou crase, até 2048 caracteres; em `http(s)` o que vem depois de
`//` não pode começar com `/`. **Link com endereço não permitido reprova a validação**
(`ErrPropInvalida`, apontando `...props.texto`); não use `javascript:`, `data:` nem caminho
relativo na marcação (use um item `botao` ou `links` para isso). Quebras de linha são mantidas.

```json
{ "id": "t1", "tipo": "titulo",
  "props": { "texto": "Organize seus pedidos sem [[planilhas]]", "nivel": 1, "destaque_cor": "acento" } }
{ "id": "t2", "tipo": "texto",
  "props": { "texto": "Veja o [portfólio](https://exemplo.test/portfolio) ou escreva para [oi@exemplo.test](mailto:oi@exemplo.test)." } }
```

### 3.8 Formulários embutidos

O item `formulario` renderiza um formulário real do Asender (campos, anti-spam, captura de
lead). Ele **referencia** um formulário existente pelo `form_id`; a ordem é:

1. Crie o formulário: `POST /v1/formularios` (sessão **ou** API key `forms:write`):

```bash
curl -sS -X POST "$API/v1/formularios" "${H[@]}" -d '{
  "nome": "Contato do site",
  "external_id": "site-contato",
  "campos": [
    { "nome": "nome",  "rotulo": "Nome",   "tipo": "texto", "obrigatorio": true },
    { "nome": "email", "rotulo": "E-mail", "tipo": "email", "obrigatorio": true },
    { "nome": "mensagem", "rotulo": "Mensagem", "tipo": "texto_longo" }
  ],
  "texto_botao": "Enviar",
  "mensagem_pos_envio": "Recebemos, obrigado."
}'
# -> 201 { "id": "<form-id>", "external_id": "site-contato", ... }
```

2. Use o `id` devolvido no item: `{ "tipo": "formulario", "props": { "form_id": "<form-id>" } }`.
3. Páginas **publicadas** mostram o formulário na hora; capturas viram leads no CRM. Fora de
   produção, use endereços `@exemplo.test` em testes: nada sai para ninguém.

`form_id` vazio significa "ainda não configurado" (o item não desenha nada). Ao **importar** uma
página para outra conta, `form_id` que a conta de destino não tem é zerado, com aviso. O tipo
`formulario` **não** pode ficar dentro de abas/acordeão. Campos, destinos e envio de leads por
chave: [guia de Páginas](https://developers.asender.net/apis/pages.html#formularios-o-contrato-de-campos).

### 3.9 Abas, acordeão e FAQ (JSON-LD)

`abas` e `acordeao` guardam os painéis em `props.itens`. Cada painel tem `titulo`
(obrigatório, não vazio) e `itens`: objetos de item **completos** (`id`, `tipo`, `props`
obrigatórios) dos tipos permitidos em painel (`titulo`, `texto`, `imagem`, `botao`, `tags`,
`links`, `cartoes`, `redes`, `menu`, `video`, `divisor`, `espacador`, `icone`, `selo`,
`contador`, `marca`). Nunca `abas`, `acordeao`, `html`, `formulario` (`ErrEstruturaInvalida`).

- `abas.aberta` é o índice (0 = primeira) da aba aberta de início e tem de existir.
- `acordeao.aberto` marca painéis abertos; com `um_por_vez: true` no máximo um.
- Sem JavaScript todo o conteúdo fica visível; com JS há abas e sanfona acessíveis (WAI-ARIA,
  teclado).
- **FAQ:** `acordeao` com `faq: true` gera um nó `FAQPage` no JSON-LD da página publicada.
  Cada painel é uma pergunta (`titulo`) e a **resposta** é o texto dos itens `texto`/`titulo` do
  painel: precisa existir, ter até 4000 caracteres, e a página aceita no máximo **50** perguntas
  somadas. `abas` não gera schema.org.

### 3.10 SEO e meta da página

O SEO **não** mora no documento: é uma rota própria, `GET`/`PUT /v1/paginas/{id}/seo` (sessão ou chave: `pages:read` / `pages:write`), e
vale **sem publicar nova versão** (na próxima resolução do runtime). Campos: `titulo` (até 120),
`descricao` (até 320), `canonical_url`, `noindex`, `og_titulo`, `og_descricao`, `og_imagem_url`
(só `https`), `og_imagem_alt`, `og_imagem_largura`/`og_imagem_altura` (juntas, 1..10000). Vazio volta
ao padrão do runtime (título da página, primeiro texto, primeira imagem).

```bash
curl -sS -X PUT "$API/v1/paginas/<pagina-id>/seo" "${H[@]}" -d '{
  "titulo": "Lançamento | Minha marca", "descricao": "Conheça a novidade de 2026.",
  "og_imagem_url": "https://exemplo.test/og.jpg", "og_imagem_alt": "Capa do lançamento",
  "og_imagem_largura": 1200, "og_imagem_altura": 630
}'
```

`PUT` substitui todos os campos de uma vez: leia com `GET`, altere e devolva.

## 4. Validação e erros comuns

O servidor valida **tudo** na escrita (`POST /v1/paginas`, `POST /v1/paginas/{id}/versoes`,
importação). O rascunho (seção 6.2) só confere a forma, de propósito.

### 4.1 O formato do erro

Recusa de documento v2 = `422` com três campos:

```json
{
  "erro": "documento: prop de item inválida: secoes[0].colunas[0].itens[0].props.url",
  "codigo": "ErrPropInvalida",
  "caminho": "secoes[0].colunas[0].itens[0].props.url"
}
```

`caminho` aponta o nó culpado (índices de array entre colchetes); sem nó, vale `versao`,
`secoes` ou `documento`. O servidor devolve o **primeiro** erro; corrija e reenvie até passar.
Os códigos:

| `codigo` | Quando | Como corrigir |
|---|---|---|
| `ErrMalformado` | JSON inválido, campo desconhecido em estrutura/estilo, ou lixo depois do objeto. | Remova o campo citado; confira vírgulas e aspas. Só use os campos das tabelas. |
| `ErrVersao` | `versao` diferente de 2. | Envie `"versao": 2` (número, não texto). |
| `ErrSemSecoes` | `secoes` vazia ou ausente. | Inclua ao menos uma seção. |
| `ErrLimite` | Algum teto foi excedido (itens, colunas, entradas de lista, FAQ...). | Reduza ou divida em seções; veja a tabela de limites. |
| `ErrSemColunas` | Seção sem coluna. | Toda seção precisa de 1..12 colunas. |
| `ErrID` | `id` com forma inválida ou repetido. | Use `^[A-Za-z0-9_-]{1,64}$` e ids ÚNICOS no documento inteiro (seção, coluna, item e itens de painel). |
| `ErrAncora` | `ancora` inválida ou repetida. | Use `^[a-z][a-z0-9-]{0,63}$`, única na página. |
| `ErrTipoDesconhecido` | `tipo` de item fora da lista. | Use um dos 20 tipos (tabela de tipos). |
| `ErrPropInvalida` | Prop inexistente no tipo, valor fora da faixa/enum, URL fora da allowlist, cor inválida, link da marcação recusado... | Leia o `caminho`; confira a tabela do tipo (nome, tipo, faixa). |
| `ErrEstiloInvalido` | Valor de `estilo` inválido (fundo, borda, raio, fonte fora da allowlist, cor, faixa...). | Leia o `caminho`; confira as tabelas de estilo. |
| `ErrEstruturaInvalida` | Valor estrutural inválido (enum de comportamento/dispositivo, peso de coluna, tipo proibido dentro de painel...). | Leia o `caminho`; dentro de abas/acordeão só entram tipos permitidos (nunca `abas`, `acordeao`, `html`, `formulario`). |
Outros status das rotas de página: `400` corpo inválido (campo desconhecido no **corpo** da
requisição, como `tenant_id`, também é `400`), `401` sem credencial (ou rota que não aceita chave), `403` item `html` sem nível ou
chave sem escopo, `404` página inexistente **ou de outra conta**, `409` endereço em uso,
`413` corpo grande demais, `422` regra de negócio (domínio não verificado, título vazio).

### 4.2 Regras que valem para todo valor

- **Campo desconhecido é recusado** em todo nível (documento, seção, coluna, item, estilo,
  props e entradas de lista). O erro nomeia o campo.
- **Texto vale em code points**, não bytes nem UTF-16: os limites `≤N` contam caracteres.
- **Inteiros são inteiros.** `1.5`, `"12"` e `true` no lugar de número são `ErrPropInvalida`.
- **Cores** só nos formatos do tipo `cor` (seção 3.4). Nada de nome de cor CSS ou função.
- **URL de link** (`url`, `link`, `menu.itens[].url`, `video.url`): vazia, `#ancora`
  (`^[a-z][a-z0-9-]{0,63}$`), `/caminho` (**nunca** `//`) ou esquema `http`, `https`, `mailto`,
  `tel`; até 2048 caracteres; sem caractere de controle. `javascript:`, `data:`, `vbscript:` e
  protocolo relativo `//host` são recusados.
- **URL de mídia** (`imagem.url`, `fundo.imagem.url`, `icone_img`, `img`, `imagem`...): vazia,
  `/caminho` (nunca `//`) ou `http(s)://host/...`; sem aspas, apóstrofo, parênteses, barra
  invertida, espaço, `<`, `>` nem controle. Isso existe porque a URL vai para dentro de um
  `url("...")` de CSS.
- **Valores fechados em CSS.** Não existe estilo livre: tudo é enum, faixa numérica ou cor
  validada. Tentativas de injeção (`red;}body{...}`, `</style><script>`, `url(...)`) caem em
  `ErrPropInvalida`/`ErrEstiloInvalido`.
- **`html`** é privilegiado: o item `html` exige nível elevado (`403` sem ele), e a página
  continua editável sem o item.
- **`<prop>_rastreio`** (ex.: `url_rastreio`) é o objeto do encurtador e só existe ao lado de uma
  prop de URL de link; **não o envie** (o editor o gerencia). Em `video` não existe.
- **Limites.** Veja a tabela 3.1; estourar é `ErrLimite`.

### 4.3 Exemplos reais do corpus de testes

Estes são casos do corpus hostil que os três validadores (Go, TS e schema) rodam em CI
(`asender_docs/contratos/fixtures/pages-v1-v2/validacao.json`, centenas de casos). Cada um
mostra o código e o fragmento enviado:

| Caso (corpus `validacao.json`) | `codigo` | O que foi enviado (fragmento) |
|---|---|---|
| `versao-1` | `ErrVersao` | `{"versao":1,"secoes":[{"id":"a","colunas":[{"id":"ac","itens":[]}]}]}` |
| `sem-secoes` | `ErrSemSecoes` | `{"versao":2,"secoes":[]}` |
| `treze-colunas` | `ErrLimite` | `{"versao":2,"secoes":[{"id":"a","colunas":[{"id":"c0","itens":[]},{"id":"c1","itens":[]},{"id":"c2","itens":[]},{"id":"c3","itens":[]},{"id":"c4","itens":[]},{"id":"c5","itens":[]},{"id":"c6","itens":[]},{"id":"c7","itens":[]},{"id":"c8"...` |
| `id-repetido` | `ErrID` | `{"id":"a","tipo":"texto","props":{}}` |
| `id-com-espaco` | `ErrID` | `{"versao":2,"secoes":[{"id":"a b","colunas":[{"id":"a bc","itens":[]}]}]}` |
| `ancora-repetida` | `ErrAncora` | `{"versao":2,"secoes":[{"id":"a","colunas":[{"id":"ac","itens":[]}],"ancora":"x"},{"id":"b","colunas":[{"id":"bc","itens":[]}],"ancora":"x"}]}` |
| `tipo-desconhecido` | `ErrTipoDesconhecido` | `{"id":"b","tipo":"hero","props":{}}` |
| `prop-desconhecida` | `ErrPropInvalida` | `{"id":"b","tipo":"titulo","props":{"style":"color:red"}}` |
| `url-javascript` | `ErrPropInvalida` | `{"id":"b","tipo":"botao","props":{"url":"javascript:alert(1)"}}` |
| `url-protocolo-relativo` | `ErrPropInvalida` | `{"id":"b","tipo":"botao","props":{"url":"//evil.test"}}` |
| `midia-data` | `ErrPropInvalida` | `{"id":"b","tipo":"imagem","props":{"url":"data:image/png;base64,AAAA"}}` |
| `cor-livre-prop` | `ErrPropInvalida` | `{"id":"b","tipo":"botao","props":{"cor":"red;x:y"}}` |
| `botao-cor-icone-style` | `ErrPropInvalida` | `{"id":"b","tipo":"botao","props":{"rotulo":"Ir","cor_icone":"</style><script>"}}` |
| `botao-vidro-opacidade-101` | `ErrPropInvalida` | `{"id":"b","tipo":"botao","props":{"rotulo":"Ir","vidro_opacidade":101}}` |
| `titulo-nao-aceita-vidro` | `ErrPropInvalida` | `{"id":"b","tipo":"titulo","props":{"texto":"x","vidro":true}}` |
| `l4-sobreposicao-cor-e-gradiente` | `ErrEstiloInvalido` | `{"versao":2,"secoes":[{"id":"a","estilo":{"fundo":{"tipo":"nenhum","sobreposicao":{"cor":"#000000","gradiente":{"tipo":"linear","de":"#ffffff","para":"transparente","angulo":90},"opacidade":50}}},"colunas":[{"id":"ac","itens":[]}]}]}` |
| `pagina-fonte-titulos-nome-do-kit` | `ErrEstiloInvalido` | `{"versao":2,"estilo":{"fonte_titulos":"Open Sans"},"secoes":[{"id":"a","colunas":[{"id":"ac","itens":[]}]}]}` |
| `pagina-fonte-titulos-injecao-css` | `ErrEstiloInvalido` | `{"versao":2,"estilo":{"fonte_titulos":"inter;}body{display:none}"},"secoes":[{"id":"a","colunas":[{"id":"ac","itens":[]}]}]}` |
| `abas-item-aninhado-abas` | `ErrEstruturaInvalida` | `{"id":"ab","tipo":"abas","props":{"itens":[{"titulo":"A","itens":[{"id":"n","tipo":"abas","props":{}}]}]}}` |
| `abas-item-aninhado-formulario` | `ErrEstruturaInvalida` | `{"id":"ab","tipo":"abas","props":{"itens":[{"titulo":"A","itens":[{"id":"n","tipo":"formulario","props":{"form_id":"f1"}}]}]}}` |
| `acordeao-faq-sem-resposta` | `ErrPropInvalida` | `{"id":"ac1","tipo":"acordeao","props":{"faq":true,"itens":[{"titulo":"Pergunta?","itens":[{"id":"b","tipo":"botao","props":{"rotulo":"x"}}]}]}}` |
| `acordeao-dois-abertos-um-por-vez` | `ErrPropInvalida` | `{"id":"ac1","tipo":"acordeao","props":{"um_por_vez":true,"itens":[{"titulo":"A","itens":[],"aberto":true},{"titulo":"B","itens":[],"aberto":true}]}}` |
| `l7-titulo-href-javascript` | `ErrPropInvalida` | `{"id":"b","tipo":"titulo","props":{"texto":"[x](javascript:alert(1))"}}` |
| `l3-subir-201` | `ErrEstiloInvalido` | `{"id":"b","tipo":"texto","props":{"texto":"a"},"estilo":{"subir":201}}` |
| `lista-longa` | `ErrLimite` | `{"id":"b","tipo":"menu","props":{"itens":[{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},{"rotulo":"x"},...` |
| `estilo-campo-desconhecido` | `ErrMalformado` | `{"id":"i1","tipo":"marca","props":{"mostrar_logo":true,"mostrar_nome":false,"altura_logo":40}}` |
### 4.4 Como consertar, por classe

| Sintoma | Causa provável | Conserto |
| --- | --- | --- |
| `ErrMalformado` | campo inventado ou vírgula sobrando | remova o campo; releia a tabela do nível |
| `ErrPropInvalida` com `caminho` em `props.<x>` | `x` não existe no tipo, ou valor fora da faixa/enum | confira nome, tipo e faixa na tabela do tipo |
| `ErrPropInvalida` em `props.texto` | link da marcação `[x](y)` com endereço não permitido | use `https://`, `mailto:` ou `tel:` |
| `ErrEstiloInvalido` | cor, raio, fonte, sombra ou fundo inválido | veja 3.3/3.4; fonte só da allowlist |
| `ErrID` | id repetido (inclusive entre seção e item) | gere ids únicos no documento inteiro |
| `ErrEstruturaInvalida` em painel | `abas`/`acordeao`/`html`/`formulario` dentro de painel | tire o item do painel |
| `ErrLimite` | lista, colunas ou FAQ acima do teto | divida em seções ou reduza |
| `403` | item `html` sem nível | remova o item `html` |

### 4.5 O laço de validação do agente

1. Gere o JSON.
2. Valide localmente contra o schema (qualquer validador JSON Schema 2020-12). O schema
   **não** confere ids únicos, âncoras únicas, o teto de 1000 itens, as regras de painel, o
   limite de FAQ nem a marcação inline; esses o servidor confere (confira ids e âncoras você mesmo).
3. Envie (`POST /v1/paginas` ou `POST /v1/paginas/{id}/versoes`).
4. `422`? Leia `codigo` + `caminho`, corrija somente aquele nó e volte ao passo 3. Não reescreva
   o documento inteiro a cada erro.
5. `201`? Confira a página renderizada (a `url_publica` só abre a versão publicada) antes de
   publicar.

## 5. Mídia

Uma imagem entra no documento **por URL**. Dois tipos servem:

1. **Galeria da conta** (recomendado). Envie o arquivo e use o `url` devolvido:

```bash
# upload (multipart, campo "arquivo"); 201 novo, 200 se o MESMO conteúdo já existia (dedup por hash)
curl -sS -X POST "$API/v1/midias" -H "Authorization: Bearer $KEY" \
  -F 'arquivo=@capa.jpg'
# -> { "id":"<midia-id>", "nome":"capa.jpg", "mime":"image/jpeg", "tamanho":123456,
#      "url":"https://.../v1/public/midias/<midia-id>", ... }

# importar por URL (o servidor baixa, com defesa contra SSRF)
curl -sS -X POST "$API/v1/midias/de-url" "${H[@]}" -d '{ "url": "https://exemplo.test/foto.png", "nome": "foto" }'
```

   Use exatamente o campo `url` da resposta (`.../v1/public/midias/<id>`) em `imagem.url`,
   `fundo.imagem.url`, `icone_img`, `cartoes.itens[].img` etc. A leitura é pública e anônima (a
   página publicada precisa dela). Variantes redimensionadas: `.../v1/public/midias/<id>/w/<largura>`
   (o renderer usa no `srcset`). Só **imagens** (JPG, PNG, GIF, WebP, AVIF, SVG; o tipo é decidido
   pelo conteúdo, não pelo nome; SVG é sanitizado; antivírus se configurado). `GET /v1/midias`
   lista a galeria; `DELETE /v1/midias/{id}` apaga (não apague mídia que uma página usa).
2. **Externa** `https://...` : aceita pelo validador, mas a página passa a depender do host de
   terceiros (some se ele apagar). Para algo que importa, suba para a galeria.

Vídeo **não** é mídia da galeria: o item `video` recebe uma URL de embed (ex.:
`https://www.youtube.com/embed/<id>`).

**Cópia na importação.** `POST /v1/paginas/importar` e a galeria de templates **baixam de novo**
cada imagem referenciada (imagem de item, galeria, fundo de seção/coluna/página, `*_img`,
`cartoes[].img`, imagem de botão...) para a galeria da conta de destino e trocam as URLs; apagar a
origem depois não quebra o destino. `url` de **link** e de botão nunca é baixada. O que não puder
ser copiado mantém a URL original e aparece no relatório (`mantido_original` + motivo). Tetos:
10 MB por arquivo, 50 MB por importação, 60 URLs únicas.

## 6. Fluxos de trabalho

### 6.1 Criar do zero

1. (Opcional) `POST /v1/formularios` se a página tem formulário (seção 3.8).
2. Suba as imagens (seção 5) e anote os `url`.
3. Monte o documento (receitas na seção 7) e valide.
4. `POST /v1/paginas` com `titulo`, `slug` (`^[a-z0-9]+(-[a-z0-9]+)*$`), opcional `dominio`, e o
   `template`. Resposta `201` traz `id`, `url_publica`, `ultima_versao: 1`, `versao_publicada: 0`.
5. `PUT /v1/paginas/{id}/seo` (opcional).
6. Revisão humana (a página ainda não está no ar).
7. `POST /v1/paginas/{id}/publicar` com `{"versao": 1}`.

### 6.2 Editar com segurança (rascunho, versão, publicação)

**Semântica.** Uma página tem **versões** imutáveis (numeradas, só crescem), um ponteiro de
**publicada** e, no máximo, um **rascunho**: o auto-save do editor, uma cópia de trabalho que
**não** é versão e **não** está no ar. Publicar só move o ponteiro; versões antigas continuam e
publicar uma delas de novo é o **rollback**.

```bash
# 1) ler o estado: a última versão (ou ?versao=N) e os contadores
curl -sS "$API/v1/paginas/<id>" "${H[@]}"
# -> { "pagina": {..., "ultima_versao": 3, "versao_publicada": 2, "url_publica": "..."},
#      "template": { "versao": 2, ... }, "versao": 3 }

# 2) existe rascunho de alguém? 204 = não; 200 = sim, com o instante da última gravação
curl -sS -i "$API/v1/paginas/<id>/rascunho" "${H[@]}"
# -> 200 { "template": {...}, "rascunho_em": "2026-10-09T12:00:00.123456Z" }   |   204

# 3) gravar o SEU rascunho com controle de concorrência
curl -sS -X PUT "$API/v1/paginas/<id>/rascunho?base=<rascunho_em lido, ou vazio se era 204>" "${H[@]}" \
  -d '{ "template": { "versao": 2, "secoes": [ ... ] } }'
# -> 200 { "rascunho_em": "..." }
# -> 409 { "erro":"o rascunho foi alterado em outra aba", "codigo":"RascunhoConflito",
#          "rascunho": { "template": {...do servidor...}, "rascunho_em": "..." } }

# 4) promover a versão (aqui o documento é validado por inteiro: 422 se inválido)
curl -sS -X POST "$API/v1/paginas/<id>/versoes" "${H[@]}" -d '{ "template": { ... } }'   # -> 201 {"versao": 4}

# 5) publicar a versão pelo NÚMERO
curl -sS -X POST "$API/v1/paginas/<id>/publicar" "${H[@]}" -d '{ "versao": 4 }'          # -> 200
```

- `?base=` ausente grava sem condição (clientes antigos); `?base=` vazio diz "eu esperava que não
  houvesse rascunho"; `?base=<rascunho_em>` diz "eu vi esta gravação". Se outra gravação
  aconteceu no meio, o servidor responde `409` com o rascunho dele e **não sobrescreve nada**:
  mantenha os dois lados, mescle e tente de novo com o novo `rascunho_em`.
- O rascunho **só confere a forma** (objeto JSON até 512 KiB); a validação completa acontece em
  `POST /versoes`. Salvar versão **não apaga** o rascunho (o editor humano é quem o descarta,
  `DELETE /v1/paginas/{id}/rascunho`).
- Cada `POST /versoes` cria a versão seguinte; ninguém sobrescreve a versão de outro. Se duas
  pessoas salvam ao mesmo tempo, as duas versões existem.

**Nunca perca trabalho humano (regras para o agente):**

1. **Nunca sobrescreva página publicada sem ordem expressa.** Para alterar uma página que está no
   ar, trabalhe em versão nova (não publique), ou duplique (`6.6`), edite a cópia e peça revisão.
2. **Rascunho presente = trabalho humano em andamento.** Se `GET .../rascunho` devolveu `200`, **não**
   o substitua: parta dele (ele é o estado mais novo), grave com `?base=<rascunho_em>`, ou pare e
   informe. Nunca use `DELETE .../rascunho` por conta própria.
3. **Publique pelo número** (`{"versao": N}`), a versão que você acabou de salvar e validar; não
   publique "a última" às cegas (uma pessoa pode ter salvado outra no meio).
4. Para desfazer, publique a versão anterior (`versao_publicada` antes de você mexer).
5. Conflito (`409`)? Leia o corpo, preserve os dois lados e decida com o humano; nunca force.
6. Guarde o `ultima_versao`/`versao_publicada` que você leu e confira antes de publicar.

### 6.3 Importar e exportar (envelopes)

O arquivo exportado pelo editor (e os 15 link-bios de referência em `asender_archive/link-bios/`)
tem este envelope (`asender_pages_template: 2`, até 256 KB):

```json
{
  "asender_pages_template": 2,
  "nome": "Minha landing",
  "descricao": "opcional",
  "seo": { "titulo": "Minha landing", "descricao": "...", "og_titulo": "..." },
  "template": { "versao": 2, "secoes": [ ... ] }
}
```

`seo` é opcional e não leva `canonical_url`. Para **importar por API**, desembrulhe o envelope e
chame `POST /v1/paginas/importar`, que valida como a criação, **copia a mídia para a conta**,
cria a página **despublicada** e grava o SEO:

```bash
curl -sS -X POST "$API/v1/paginas/importar" "${H[@]}" -d '{
  "slug": "minha-landing", "titulo": "Minha landing",
  "template": { "versao": 2, "secoes": [ ... ] },
  "seo": { "titulo": "Minha landing" }
}'
# -> 201 { "pagina": {...}, "importacao": { "itens":[...], "avisos":[...], "copiadas":3, "ja_na_conta":0,
#                                           "mantidas":0, "copia_disponivel":true, "seo_aplicado":true } }
```

Se alguma imagem não pôde ser copiada, `POST /v1/paginas/{id}/midias/copiar` tenta de novo (grava
versão nova só se algo mudou). `409` se o endereço (`slug` + domínio) já existe (checado **antes**
de copiar). Para **exportar**: `GET /v1/paginas/{id}` e monte o envelope com o `template`.

### 6.4 Ações em massa

`POST /v1/paginas/lote` (sessão): `publicar`, `despublicar`, `duplicar`, `mudar_dominio`, até 100
páginas por chamada, resultado por página (sem tudo-ou-nada), `simular: true` para ver o efeito sem
escrever. Detalhes e política de rascunho (`pular` / `publicar_salva`) no
[guia de Páginas](https://developers.asender.net/apis/pages.html#acoes-em-massa-publicar-despublicar-duplicar-mudar-dominio).

### 6.5 Mudar o domínio (301 do endereço antigo)

`PUT /v1/paginas/{id}/dominio` com `{"dominio_id": "...", "caminho": "novo-slug"}` (sessão ou API
key `pages:write`; `dominio_id: ""` = host da plataforma, `caminho: ""` mantém o slug). Se a página
já esteve no ar, o endereço **antigo** passa a responder `301` (308 para métodos que não são
GET/HEAD) para o novo, preservando a query string; repetir o pedido é idempotente. `409` com
`motivo: caminho_em_uso` ou `pagina_inicial`; `422` com `dominio_nao_verificado` ou
`caminho_invalido`. Domínio próprio exige posse **verificada** (TXT) antes de qualquer uso.

### 6.6 Duplicar

`POST /v1/paginas/lote` com `{"acao":"duplicar","ids":["<id>"]}` cria uma cópia **despublicada**
(slug com `-copia`). É a forma segura de iterar sobre uma página que está no ar: edite a cópia,
revise, publique a cópia e, se for o caso, troque os endereços com `PUT .../dominio`.

### 6.7 O que a API não faz

Não existe exclusão de página nem exclusão em massa, nem listagem de versões (use
`ultima_versao` e `GET /v1/paginas/{id}?versao=N`). Páginas v1 antigas continuam lidas, mas o
conteúdo novo deve ser v2.

## 7. Receitas completas

Todas validam no schema, no validador Go e no validador TS (teste de CI). As imagens usam o
domínio de teste `exemplo.test`: **troque** pelos `url` da sua galeria. Os `id`s são só
exemplos.

### 7.1 Link na bio

Uma coluna estreita, avatar, nome, bio com marcação inline, lista de links com vidro, redes
sociais e rodapé; tema escuro com degradê e textura.

```json
{
  "versao": 2,
  "estilo": {
    "tema": "escuro",
    "fonte_titulos": "montserrat",
    "fonte_texto": "inter",
    "fundo": {
      "tipo": "gradiente",
      "gradiente": {
        "tipo": "linear",
        "de": "#0f172a",
        "para": "#1e293b",
        "angulo": 160
      }
    },
    "padrao": {
      "tipo": "pontos",
      "opacidade": 6,
      "tamanho": 24
    }
  },
  "secoes": [
    {
      "id": "bio",
      "nome": "Perfil e links",
      "estilo": {
        "largura": "contida",
        "largura_max": 480,
        "padding": {
          "topo": 48,
          "direita": 16,
          "base": 48,
          "esquerda": 16
        }
      },
      "colunas": [
        {
          "id": "bio-col",
          "alinhamento_horizontal": "centro",
          "gap": 16,
          "itens": [
            {
              "id": "bio-foto",
              "tipo": "imagem",
              "props": {
                "url": "https://exemplo.test/avatar.jpg",
                "alt": "Foto da Ana Souza",
                "forma": "circulo",
                "largura": 112,
                "proporcao": "1:1",
                "borda": 3,
                "cor_borda": "acento"
              }
            },
            {
              "id": "bio-nome",
              "tipo": "titulo",
              "props": {
                "texto": "Ana Souza",
                "nivel": 1,
                "tamanho": "g"
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "bio-resumo",
              "tipo": "texto",
              "props": {
                "texto": "Designer de [[interfaces]] e marcas. Veja o [portfólio](https://exemplo.test/portfolio).",
                "variante": "suave",
                "destaque_cor": "acento"
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "bio-links",
              "tipo": "links",
              "props": {
                "estilo": "suave",
                "tamanho": "g",
                "efeito": "elevar",
                "raio": 16,
                "vidro": true,
                "vidro_opacidade": 30,
                "itens": [
                  {
                    "titulo": "Portfólio",
                    "texto": "Projetos recentes",
                    "url": "https://exemplo.test/portfolio",
                    "icone": "site",
                    "nova_aba": true,
                    "destaque": true
                  },
                  {
                    "titulo": "Agende uma conversa",
                    "url": "https://exemplo.test/agenda",
                    "icone": "calendario",
                    "icone_fundo": "circulo",
                    "cor": "acento",
                    "cor_texto": "#0f172a"
                  },
                  {
                    "titulo": "Fale no WhatsApp",
                    "url": "https://wa.me/5511900000000",
                    "icone": "whatsapp",
                    "nova_aba": true
                  },
                  {
                    "titulo": "E-mail",
                    "url": "mailto:ana@exemplo.test",
                    "icone": "email"
                  }
                ]
              }
            },
            {
              "id": "bio-redes",
              "tipo": "redes",
              "props": {
                "tamanho": "m",
                "itens": [
                  {
                    "rede": "instagram",
                    "url": "https://instagram.com/exemplo"
                  },
                  {
                    "rede": "linkedin",
                    "url": "https://linkedin.com/in/exemplo"
                  },
                  {
                    "rede": "github",
                    "url": "https://github.com/exemplo"
                  }
                ]
              }
            },
            {
              "id": "bio-rodape",
              "tipo": "texto",
              "props": {
                "texto": "© 2026 Ana Souza",
                "variante": "suave",
                "tamanho": "p"
              },
              "estilo": {
                "alinhamento": "centro",
                "margem": {
                  "topo": 16
                }
              }
            }
          ]
        }
      ]
    }
  ]
}
```
### 7.2 Landing com hero, cartões e FAQ

Cabeçalho fixo com menu e âncoras, hero em duas colunas, três cartões em grade, FAQ (`acordeao`
com `faq: true`, gera JSON-LD) e chamada final.

```json
{
  "versao": 2,
  "estilo": {
    "tema": "claro",
    "fonte_titulos": "poppins",
    "fonte_texto": "inter",
    "fundo": {
      "tipo": "cor",
      "cor": "#ffffff"
    }
  },
  "secoes": [
    {
      "id": "topo",
      "nome": "Cabeçalho",
      "comportamento": "fixa_topo",
      "estilo": {
        "fundo": {
          "tipo": "cor",
          "cor": "#ffffff"
        },
        "borda": {
          "largura": 1,
          "cor": "borda",
          "lados": [
            "base"
          ]
        },
        "padding": {
          "topo": 12,
          "direita": 24,
          "base": 12,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "topo-marca",
          "largura": 1,
          "alinhamento_vertical": "centro",
          "itens": [
            {
              "id": "topo-logo",
              "tipo": "marca",
              "props": {
                "mostrar_logo": true,
                "mostrar_nome": true,
                "altura_logo": 32
              }
            }
          ]
        },
        {
          "id": "topo-menu",
          "largura": 2,
          "alinhamento_vertical": "centro",
          "alinhamento_horizontal": "fim",
          "itens": [
            {
              "id": "topo-nav",
              "tipo": "menu",
              "props": {
                "orientacao": "horizontal",
                "colapsar_celular": true,
                "itens": [
                  {
                    "rotulo": "Benefícios",
                    "url": "#beneficios"
                  },
                  {
                    "rotulo": "Perguntas",
                    "url": "#faq"
                  },
                  {
                    "rotulo": "Contato",
                    "url": "#contato"
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "id": "hero",
      "nome": "Hero",
      "ancora": "inicio",
      "layout_celular": "empilhar",
      "estilo": {
        "fundo": {
          "tipo": "gradiente",
          "gradiente": {
            "tipo": "linear",
            "de": "#eef2ff",
            "para": "#ffffff",
            "angulo": 180
          }
        },
        "padding": {
          "topo": 80,
          "direita": 24,
          "base": 80,
          "esquerda": 24
        },
        "padding_celular": {
          "topo": 40,
          "direita": 16,
          "base": 40,
          "esquerda": 16
        },
        "alinhamento_vertical": "centro"
      },
      "colunas": [
        {
          "id": "hero-texto",
          "largura": 6,
          "gap": 20,
          "itens": [
            {
              "id": "hero-selo",
              "tipo": "selo",
              "props": {
                "texto": "Novo · versão 2"
              }
            },
            {
              "id": "hero-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Organize seus pedidos sem [[planilhas]]",
                "nivel": 1,
                "tamanho": "gg",
                "destaque_cor": "acento"
              }
            },
            {
              "id": "hero-sub",
              "tipo": "texto",
              "props": {
                "texto": "Cadastre, acompanhe e entregue. Tudo em um só lugar, em minutos.",
                "tamanho": "g",
                "variante": "suave"
              }
            },
            {
              "id": "hero-cta",
              "tipo": "botao",
              "props": {
                "rotulo": "Começar grátis",
                "url": "#contato",
                "variante": "solido",
                "tamanho": "g",
                "icone_dir": "seta"
              }
            },
            {
              "id": "hero-cta2",
              "tipo": "botao",
              "props": {
                "rotulo": "Ver como funciona",
                "url": "#beneficios",
                "variante": "texto",
                "tamanho": "m"
              }
            }
          ]
        },
        {
          "id": "hero-imagem",
          "largura": 6,
          "alinhamento_vertical": "centro",
          "itens": [
            {
              "id": "hero-foto",
              "tipo": "imagem",
              "props": {
                "url": "https://exemplo.test/produto.jpg",
                "alt": "Tela do aplicativo mostrando a lista de pedidos",
                "forma": "arredondada",
                "proporcao": "4:3",
                "sombra": "forte"
              }
            }
          ]
        }
      ]
    },
    {
      "id": "beneficios",
      "nome": "Benefícios",
      "ancora": "beneficios",
      "estilo": {
        "padding": {
          "topo": 64,
          "direita": 24,
          "base": 64,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "ben-col",
          "gap": 24,
          "alinhamento_horizontal": "centro",
          "itens": [
            {
              "id": "ben-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Por que usar",
                "nivel": 2
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "ben-cartoes",
              "tipo": "cartoes",
              "props": {
                "layout": "grade",
                "colunas": 3,
                "efeito": "elevar",
                "raio": 16,
                "sombra": "leve",
                "alinhamento_texto": "inicio",
                "icone_fundo": "circulo",
                "itens": [
                  {
                    "icone": "raio",
                    "titulo": "Rápido",
                    "texto": "Cadastre um pedido em menos de dez segundos.",
                    "tag": "Produtividade"
                  },
                  {
                    "icone": "escudo",
                    "titulo": "Seguro",
                    "texto": "Seus dados ficam separados dos de outras contas.",
                    "tag": "Confiança"
                  },
                  {
                    "icone": "grafico",
                    "titulo": "Claro",
                    "texto": "Relatórios simples para decidir o que fazer amanhã.",
                    "tag": "Controle"
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "id": "faq",
      "nome": "Perguntas frequentes",
      "ancora": "faq",
      "estilo": {
        "largura": "contida",
        "largura_max": 760,
        "padding": {
          "topo": 64,
          "direita": 24,
          "base": 64,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "faq-col",
          "gap": 24,
          "itens": [
            {
              "id": "faq-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Perguntas frequentes",
                "nivel": 2
              }
            },
            {
              "id": "faq-acordeao",
              "tipo": "acordeao",
              "props": {
                "faq": true,
                "um_por_vez": true,
                "nivel": 3,
                "estilo": "cartao",
                "indicador": "seta",
                "itens": [
                  {
                    "titulo": "Preciso instalar alguma coisa?",
                    "aberto": true,
                    "itens": [
                      {
                        "id": "faq-r1",
                        "tipo": "texto",
                        "props": {
                          "texto": "Não. Funciona no navegador, no computador ou no celular."
                        }
                      }
                    ]
                  },
                  {
                    "titulo": "Posso cancelar quando quiser?",
                    "itens": [
                      {
                        "id": "faq-r2",
                        "tipo": "texto",
                        "props": {
                          "texto": "Sim. Não há fidelidade e você exporta seus dados a qualquer momento."
                        }
                      }
                    ]
                  },
                  {
                    "titulo": "Como falo com o suporte?",
                    "itens": [
                      {
                        "id": "faq-r3",
                        "tipo": "texto",
                        "props": {
                          "texto": "Escreva para [suporte@exemplo.test](mailto:suporte@exemplo.test); respondemos em até um dia útil."
                        }
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      "id": "final",
      "nome": "Chamada final",
      "ancora": "contato",
      "estilo": {
        "fundo": {
          "tipo": "cor",
          "cor": "acento"
        },
        "padding": {
          "topo": 56,
          "direita": 24,
          "base": 56,
          "esquerda": 24
        }
      },
      "colunas": [
        {
          "id": "final-col",
          "gap": 16,
          "alinhamento_horizontal": "centro",
          "itens": [
            {
              "id": "final-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Pronto para começar?",
                "nivel": 2
              },
              "estilo": {
                "alinhamento": "centro"
              }
            },
            {
              "id": "final-botao",
              "tipo": "botao",
              "props": {
                "rotulo": "Criar minha conta",
                "url": "https://exemplo.test/cadastro",
                "variante": "contorno",
                "tamanho": "g",
                "nova_aba": true
              }
            }
          ]
        }
      ]
    }
  ]
}
```
### 7.3 Página com formulário

Crie o formulário (seção 3.8), copie o `id` e troque `SUBSTITUA_PELO_ID_DO_FORMULARIO`.

```json
{
  "versao": 2,
  "estilo": {
    "tema": "claro",
    "fonte_titulos": "manrope",
    "fonte_texto": "inter"
  },
  "secoes": [
    {
      "id": "contato",
      "nome": "Contato",
      "ancora": "contato",
      "estilo": {
        "largura": "contida",
        "largura_max": 560,
        "padding": {
          "topo": 64,
          "direita": 16,
          "base": 64,
          "esquerda": 16
        }
      },
      "colunas": [
        {
          "id": "contato-col",
          "gap": 16,
          "itens": [
            {
              "id": "contato-titulo",
              "tipo": "titulo",
              "props": {
                "texto": "Fale com a gente",
                "nivel": 1
              }
            },
            {
              "id": "contato-texto",
              "tipo": "texto",
              "props": {
                "texto": "Deixe seu e-mail e retornamos em até um dia útil.",
                "variante": "suave"
              }
            },
            {
              "id": "contato-form",
              "tipo": "formulario",
              "props": {
                "form_id": "SUBSTITUA_PELO_ID_DO_FORMULARIO",
                "rotulo": "Enviar mensagem"
              }
            },
            {
              "id": "contato-lgpd",
              "tipo": "texto",
              "props": {
                "texto": "Usamos seus dados só para responder a esta mensagem.",
                "variante": "suave",
                "tamanho": "p"
              }
            }
          ]
        }
      ]
    }
  ]
}
```
## 8. Checklist e prompt para agentes

### 8.1 Checklist

- [ ] Tenho um token de sessão (páginas) ou uma API key com o escopo certo (formulários/domínio).
- [ ] O JSON tem `versao: 2` e só campos das tabelas da seção 3.
- [ ] Todo `id` é único no documento (seção, coluna, item e itens de painel) e casa `^[A-Za-z0-9_-]{1,64}$`.
- [ ] Âncoras únicas, `^[a-z][a-z0-9-]{0,63}$`; links `#x` apontam para âncoras que existem.
- [ ] URLs: link só `http/https/mailto/tel`, `#ancora` ou `/caminho`; mídia só `http(s)` ou `/caminho`.
- [ ] Cores em hex ou token; fontes da allowlist; inteiros dentro das faixas.
- [ ] Imagens enviadas para a galeria (ou `https://` externa consciente).
- [ ] `form_id` de formulário existente (ou vazio de propósito).
- [ ] Antes de editar: li o rascunho; não vou sobrescrever rascunho humano nem página publicada.
- [ ] Salvei versão, li o `422` se veio, e publico **pelo número** só com autorização.
- [ ] Guardei a versão publicada anterior para rollback.

### 8.2 Prompt para colar no agente

```text
Você cria e edita páginas do Asender Pages pela API https://api.pages.asender.net.
Fonte da verdade: https://developers.asender.net/guias/pages-documento-v2.html (e llms-full.txt).

REGRAS
1. Escreva SEMPRE documentos {"versao": 2, "secoes": [...]} (seção > colunas > itens). Cada seção tem
   "id" e "colunas"; cada coluna tem "id" e "itens"; cada item tem "id", "tipo" e "props" (objeto).
2. Use SOMENTE os campos documentados para cada tipo (titulo, texto, imagem, botao, tags, links, cartoes,
   abas, acordeao, redes, menu, formulario, video, divisor, espacador, icone, selo, contador, marca, html).
   Campo desconhecido é recusado. Não use o tipo "html" (privilegiado).
3. "id": ^[A-Za-z0-9_-]{1,64}$, ÚNICO no documento inteiro (inclusive itens dentro de abas/acordeão).
   "ancora" de seção: ^[a-z][a-z0-9-]{0,63}$, única.
4. Cores: "#rrggbb", "#rrggbbaa" ou token (acento, texto, suave, fundo, superficie, borda, transparente).
   Nunca nomes de cor CSS, rgb() ou CSS livre. Fontes (estilo.fonte_titulos/fonte_texto): somente
   comfortaa, urbanist, montserrat, inter, poppins, open-sans, nunito, playfair-display, merriweather,
   dm-sans, manrope, raleway.
5. URLs de link: http, https, mailto, tel, "#ancora" ou "/caminho" (nunca "//" nem javascript:).
   URLs de mídia: https://host/... ou /caminho, sem aspas, espaços ou parênteses. Imagens: suba por
   POST /v1/midias (multipart, campo "arquivo") e use o campo "url" devolvido.
6. Texto de titulo/texto aceita [rótulo](https://...) e [[destaque]]; nada de HTML.
7. Limites: 200 seções, 12 colunas/seção, 100 itens/coluna, 1000 itens/página, listas até 50 entradas,
   abas/acordeão até 20 painéis (um nível, sem html/formulario/abas/acordeao dentro).

FLUXO
- Criar: POST /v1/paginas {"titulo","slug","template"} -> nasce DESPUBLICADA.
- Editar: GET /v1/paginas/{id} (template + ultima_versao + versao_publicada); GET /v1/paginas/{id}/rascunho.
  Se houver rascunho (200), é trabalho humano: parta dele e grave com PUT .../rascunho?base=<rascunho_em>
  (409 RascunhoConflito = preserve os dois lados, não force). Para versionar: POST .../versoes {"template"}.
- Publicar: SOMENTE com autorização do usuário, pelo número: POST .../publicar {"versao": N}.
  Nunca sobrescreva uma página publicada sem ordem expressa; prefira duplicar (POST /v1/paginas/lote
  {"acao":"duplicar","ids":[...]}) e editar a cópia. Rollback = publicar a versão anterior.
- Nunca chame DELETE .../rascunho. Não há exclusão de página.

VALIDAÇÃO
- Valide o JSON contra o schema (pages-documento-v2.schema.json) antes de enviar.
- Se vier 422 {"erro","codigo","caminho"}: corrija SOMENTE o nó em "caminho" conforme "codigo" e reenvie
  (ErrPropInvalida/ErrEstiloInvalido = valor ou campo fora do contrato; ErrID/ErrAncora = repetido ou
  mal formado; ErrLimite = teto; ErrEstruturaInvalida = tipo proibido em painel ou enum). Repita até 201.
- Em testes use apenas e-mails @exemplo.test e imagens de exemplo.test; nunca dados reais de terceiros.
```

## 9. Manutenção deste guia

As seções de referência (3.1 a 3.6, 4.1, 4.3 e 7) são **geradas**. Mudou o contrato do documento
(schema, Go, TS)? Rode:

```bash
node scripts/docs-pages/gerar-referencia.mjs           # reescreve os blocos gerados deste arquivo
node scripts/docs-pages/gerar-referencia.mjs --check   # CI: falha se o guia está defasado
node --test scripts/docs-pages/documento-v2.test.mjs   # guia em dia + receitas no schema
```

e commite este arquivo. As notas em prosa das tabelas (finalidade de cada tipo, descrição e padrão
de cada prop) ficam em `scripts/docs-pages/referencia-notas.mjs`; o gerador reprova nota sobre
prop que saiu do schema. Receitas: `asender_docs/apis/pages/exemplos-v2/*.json`; cada uma é
validada contra o schema (node), o validador Go (`receitas_docs_test.go`) e o validador TS
(`receitas-docs.test.ts`).


### GET /
304 quando o `If-None-Match` bate; senão o bundle, com cache de uma hora e `X-Content-Type-Options: nosniff`.
Onde é usada: rota `/chat.js` do runtime.
Entradas: w; r.
Efeitos: nenhum — é leitura de bytes já em memória. **Não há CORS aqui, e é de propósito.** Um `<script src>` não precisa de CORS para executar, e liberar `Access-Control-Allow-Origin: *` neste arquivo só abriria a leitura do conteúdo por `fetch` de qualquer origem sem ganho nenhum. Quem precisa de CORS é a API do chat, e lá a origem é conferida contra a chave de site — não liberada em `*`. `ifNoneMatchCasa` (comparação FRACA, RFC 9110 §13.1.2), não `==`: a borda comprime este script on-the-fly e rebaixa o `ETag` forte para `W/"…"` na resposta — o navegador devolve esse `W/` na revisita, e `==` contra o forte nunca batia (achado em `embed.js`, forms-rapidos 2026-10-01; mesma causa aqui, mesmo remédio — ver `etag_match.go`).

curl -X GET 'https://api.pages.asender.net/' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /
resolve a página pela mesma rota que a serviu, monta a submissão com `Modo = pagina` e chama o MESMO pipeline dos outros dois modos.
Onde é usada: POST no caminho da própria página.
Efeitos: os do pipeline (banco, outbox). O tenant e o form vêm da PÁGINA resolvida no servidor, nunca do corpo: o form da página é HTML público, e qualquer um pode reenviá-lo com outro `form_id`. Resolver pelo host+caminho é o que impede postar no formulário de outro tenant.

curl -X POST 'https://api.pages.asender.net/' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /_f/{arquivo}
304 quando o `If-None-Match` bate; senão o bundle, com cache de uma hora e `X-Content-Type-Options: nosniff`.
Onde é usada: rota `/chat.js` do runtime.
Entradas: w; r.
Efeitos: nenhum — é leitura de bytes já em memória. **Não há CORS aqui, e é de propósito.** Um `<script src>` não precisa de CORS para executar, e liberar `Access-Control-Allow-Origin: *` neste arquivo só abriria a leitura do conteúdo por `fetch` de qualquer origem sem ganho nenhum. Quem precisa de CORS é a API do chat, e lá a origem é conferida contra a chave de site — não liberada em `*`. `ifNoneMatchCasa` (comparação FRACA, RFC 9110 §13.1.2), não `==`: a borda comprime este script on-the-fly e rebaixa o `ETag` forte para `W/"…"` na resposta — o navegador devolve esse `W/` na revisita, e `==` contra o forte nunca batia (achado em `embed.js`, forms-rapidos 2026-10-01; mesma causa aqui, mesmo remédio — ver `etag_match.go`).

curl -X GET 'https://api.pages.asender.net/_f/arquivo_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /{slug}
resolve a página pela mesma rota que a serviu, monta a submissão com `Modo = pagina` e chama o MESMO pipeline dos outros dois modos.
Onde é usada: POST no caminho da própria página.
Efeitos: os do pipeline (banco, outbox). O tenant e o form vêm da PÁGINA resolvida no servidor, nunca do corpo: o form da página é HTML público, e qualquer um pode reenviá-lo com outro `form_id`. Resolver pelo host+caminho é o que impede postar no formulário de outro tenant.

curl -X POST 'https://api.pages.asender.net/slug_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /asender-sw.js
304 quando o `If-None-Match` bate; senão o bundle, com cache de uma hora e `X-Content-Type-Options: nosniff`.
Onde é usada: rota `/chat.js` do runtime.
Entradas: w; r.
Efeitos: nenhum — é leitura de bytes já em memória. **Não há CORS aqui, e é de propósito.** Um `<script src>` não precisa de CORS para executar, e liberar `Access-Control-Allow-Origin: *` neste arquivo só abriria a leitura do conteúdo por `fetch` de qualquer origem sem ganho nenhum. Quem precisa de CORS é a API do chat, e lá a origem é conferida contra a chave de site — não liberada em `*`. `ifNoneMatchCasa` (comparação FRACA, RFC 9110 §13.1.2), não `==`: a borda comprime este script on-the-fly e rebaixa o `ETag` forte para `W/"…"` na resposta — o navegador devolve esse `W/` na revisita, e `==` contra o forte nunca batia (achado em `embed.js`, forms-rapidos 2026-10-01; mesma causa aqui, mesmo remédio — ver `etag_match.go`).

curl -X GET 'https://api.pages.asender.net/asender-sw.js' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /chat.js
304 quando o `If-None-Match` bate; senão o bundle, com cache de uma hora e `X-Content-Type-Options: nosniff`.
Onde é usada: rota `/chat.js` do runtime.
Entradas: w; r.
Efeitos: nenhum — é leitura de bytes já em memória. **Não há CORS aqui, e é de propósito.** Um `<script src>` não precisa de CORS para executar, e liberar `Access-Control-Allow-Origin: *` neste arquivo só abriria a leitura do conteúdo por `fetch` de qualquer origem sem ganho nenhum. Quem precisa de CORS é a API do chat, e lá a origem é conferida contra a chave de site — não liberada em `*`. `ifNoneMatchCasa` (comparação FRACA, RFC 9110 §13.1.2), não `==`: a borda comprime este script on-the-fly e rebaixa o `ETag` forte para `W/"…"` na resposta — o navegador devolve esse `W/` na revisita, e `==` contra o forte nunca batia (achado em `embed.js`, forms-rapidos 2026-10-01; mesma causa aqui, mesmo remédio — ver `etag_match.go`).

curl -X GET 'https://api.pages.asender.net/chat.js' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /collect
Ingerir um lote de eventos de comportamento (anônimo, credencial de pixel)
Onde é usada: rota pública, a de maior volume do sistema depois da própria página.
Efeitos: publica no broker; NUNCA escreve no banco. # Responde 204 quase sempre, e isso é deliberado Credencial inválida é 403 (o cliente precisa saber que aquele HTML está velho). Fora isso — evento inválido, tipo desconhecido, lote parcialmente ruim — a resposta é 204 e o que dava para aproveitar foi publicado. O pixel roda no browser de terceiros: transformar um evento malformado em erro visível não conserta nada e enche o console de quem só quer ver a página.
Respostas: 204 aceito; 400 corpo inválido; 403 credencial ou origem inválida; 429 excesso (rate-limit por credencial × IP); 503 coleta indisponível agora

curl -X POST 'https://api.pages.asender.net/collect' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /f/{formID}
Enviar uma submissão pelo snippet (anônimo)
Onde é usada: rota pública, chamada de outro domínio pelo navegador.
Efeitos: os do pipeline. Aqui não há API key: quem chama é o navegador do visitante, e uma key no snippet seria segredo no cliente (§13.4). A defesa é a allowlist de origem, verificada NO SERVIDOR — o header `Origin` é posto pelo navegador e não pode ser forjado por script da própria página.
Parâmetros: formID (path, obrigatório)
Respostas: 200 aceito (ou spam, indistinguível); 400 corpo malformado; 403 origem não autorizada para este formulário; 404 formulário não encontrado; 503 não consegui resolver a conta do formulário agora

curl -X POST 'https://api.pages.asender.net/f/formID_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /f/{formID}/agendamento/slots
HorariosDoAgendamentoLegado é o alias de `GET /f/{formID}/agendamento/slots` (ADR-0152 D3):
Onde é usada: JS do snippet antigo em cache em páginas de cliente.

curl -X GET 'https://api.pages.asender.net/f/formID_AQUI/agendamento/slots' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /f/{formID}/carimbo
Obter o carimbo de tempo anti-spam do snippet (anônimo)
Onde é usada: chamado pelo `formulario_antispam.js` ao carregar o snippet (cross-origin, com `Origin`) e pela página nativa (same-origin, sem `Origin`).
Efeitos: nenhum além da resposta — nada é gravado. # Por que conferir a origem, se um bot forja o cabeçalho Fora do navegador o `Origin` é forjável, e a allowlist não detém bot aqui (nem no POST). Ela mantém a rota com a MESMA política do envio: um site que não pode postar no formulário também não lê o carimbo dele. `no-store` porque um carimbo servido de cache mediria o tempo desde o primeiro visitante.
Parâmetros: formID (path, obrigatório)
Respostas: 200 carimbo emitido; 403 origem não autorizada para este formulário; 404 formulário não encontrado ou carimbo desligado; 503 não consegui resolver a conta do formulário agora

curl -X GET 'https://api.pages.asender.net/f/formID_AQUI/carimbo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /f/{formID}/embed.js
devolve o loader com o HTML atual do formulário embutido como string JSON.
Onde é usada: `<script src=".../f/{id}/embed.js" async>` colado no site do cliente (o `snippet_js` do painel).
Efeitos: nenhum além da resposta. # Sem checagem de origem aqui `<script src>` não manda `Origin`, e o HTML não é segredo: é o mesmo que o modo HTML entrega para colar à vista. A política de origem continua onde age — no carimbo e no POST, que o HTML injetado chama. # JSON como literal JS `json.Marshal` escapa `<`, `>`, `&` e U+2028/U+2029: o HTML não fecha o `<script>` e não quebra a string. # Cache HTTP com revalidação (forms-rapidos, 2026-10-01) `max-age=60, stale-while-revalidate=600`: o navegador reusa a resposta por 1 min sem perguntar nada (a maioria das visitas de um mesmo site, no mesmo minuto, não paga NADA); depois disso, por até 10 min, ainda serve o que tem na hora enquanto revalida em paralelo (quem não implementa `stale-while-revalidate` cai para a validação normal, sem quebrar). Não é `max-age` longo e cego: o formulário muda quando o dono publica, e 1 min é curto o bastante para "editei e já vale" continuar parecendo imediato. `public` porque o HTML não é segredo (§ "sem checagem de origem" acima) nem varia por visitante — é o mesmo snippet pra qualquer um que peça aquele `formID`. `ETag` é o hash dos bytes já montados (`embedCache`, por formID) — forte (mesmo conteúdo byte a byte, mesmo valor) e barato de comparar: o Go só lê o `If-None-Match` do pedido, nunca remonta o snippet para decidir o 304. # Comparação FRACA, nunca `==` (achado em hml, 2026-10-01) A borda (nginx) comprime o `embed.js` on-the-fly e, ao fazer isso, REBAIXA o `ETag` forte que o runtime manda para fraco (`W/"…"`) — comportamento padrão do módulo de gzip dela, que não garante equivalência byte-a-byte entre o corpo comprimido e o cru. O navegador devolve esse `W/"…"` no `If-None-Match` da revisita; comparar com `==` contra o `etag` FORTE deste handler nunca batia, e toda revisita baixava o corpo inteiro de novo — a compressão/cache da rodada 1/2 chegavam a produção, só a comparação estava errada. `ifNoneMatchCasa` (RFC 9110 §13.1.2) ignora o prefixo `W/` de QUALQUER lado — é a única comparação válida para `If-None-Match` (a forte só existiria para `If-Match`/`Range`), então o mesmo código já cobre um Caddy que algum dia fizer o mesmo rebaixamento.

curl -X GET 'https://api.pages.asender.net/f/formID_AQUI/embed.js' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /f/{formID}/endereco
Consultar o endereço de um CEP para o widget de endereço (anônimo)
Onde é usada: `formulario_endereco.js` do snippet e da página.
Efeitos: uma ida ao core no miss do cache. # Respostas 200 endereço; 404 sem consulta ligada, formulário sem endereço ou CEP não encontrado; 403 origem recusada; 422 país/CEP inválidos; 429 teto; 503 core fora. Nenhuma delas trava o formulário: o widget fica manual.
Parâmetros: formID (path, obrigatório); pais (query, obrigatório); cep (query, obrigatório)
Respostas: 200 endereço encontrado (sem número e complemento); 403 origem não autorizada para este formulário; 404 CEP não encontrado, formulário sem endereço ou consulta desligada; 422 país fora dos aceitos ou CEP fora do formato do país; 429 consultas demais (Retry-After); 503 consulta indisponível agora (o endereço fica manual)

curl -X GET 'https://api.pages.asender.net/f/formID_AQUI/endereco' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /f/{formID}/eventos
Registrar eventos do funil do formulário embutido (anônimo)
Onde é usada: tela de depuração da instrumentação.
Efeitos: uma leitura.
Parâmetros: formID (path, obrigatório)
Respostas: 204 eventos registrados; 400 lote inválido; 403 origem não autorizada para este formulário; 404 formulário não encontrado ou funil desligado; 429 limite de eventos excedido; 503 banco indisponível

curl -X POST 'https://api.pages.asender.net/f/formID_AQUI/eventos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /f/{formID}/scheduling/slots
mesma política de origem do `POST /f/{formID}` (sem `Origin` passa; com `Origin`, a allowlist do formulário) e o mesmo guard de conta (`tenantDoFormulario`, no roteador); CORS; teto por IP; janela de consulta; o campo no formulário; a janela do formulário; e o proxy.
Onde é usada: o seletor de horário do snippet e da página. # Respostas 200 `{fuso, slots:[{inicio,fim}]}` (UTC, `Cache-Control: no-store`); 403 origem recusada; 404 formulário sem campo de agendamento; 410 formulário fechado (como a submissão); 422 janela inválida; 429 teto; 503 RFC 9457 `agenda-indisponivel`. Nenhuma trava o resto do formulário.

curl -X GET 'https://api.pages.asender.net/f/formID_AQUI/scheduling/slots' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /favicon.ico
redireciona (302) para o favicon do site (o de SEO, senão o da marca) quando o dono do host configurou um https; senão para o padrão `/favicon.svg`.
Onde é usada: rota pública, pedida pelo navegador e pelo buscador por convenção.
Efeitos: uma leitura no `asender_pages_api` (quando há fonte). 302 e não 301: o favicon do site muda quando o cliente troca a marca, e um 301 ficaria gravado no navegador do visitante para sempre. Falha na consulta cai no padrão — favicon nunca vale um erro.

curl -X GET 'https://api.pages.asender.net/favicon.ico' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /favicon.svg
o SVG fixo, cacheável por um dia.
Onde é usada: rota pública; é o `<link rel="icon">` da página sem favicon (seo.go do renderizador).
Efeitos: nenhum.

curl -X GET 'https://api.pages.asender.net/favicon.svg' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /pixel.{versao:[0-9a-f]{16}}.js
GET /pixel.{versao}.js — o mesmo script de `Script`, com `CacheScriptVersionado` quando a versão pedida é a servida e `CacheScriptVersaoAntiga` quando não é.
Onde é usada: o `<script src>` de toda página publicada (renderizador, `PixelSrc`).
Efeitos: escreve o script. Versão antiga NÃO vira 404 nem redirect: um 404 desligaria a analytics da página em cache até ela expirar, e um redirect custaria uma ida à rede a mais no caminho de quem só queria o script.

curl -X GET 'https://api.pages.asender.net/pixel.versao:[0-9a-f]{16_AQUI}.js' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /pixel.js
O script do pixel (anônimo)
Onde é usada: HTML publicado antes do endereço versionado (`ScriptVersionado`) e o snippet do pixel de terceiros, que não pode trocar de endereço a cada deploy.
Efeitos: escreve o script. Cache de 1 hora com ETag: o script muda com o deploy, e revalidar de hora em hora custa um 304. `immutable` seria errado — o conteúdo muda no mesmo caminho. `ifNoneMatchCasa` (comparação FRACA, RFC 9110 §13.1.2), não `==`: a borda comprime este script on-the-fly e rebaixa o `ETag` forte para `W/"…"` na resposta — o navegador devolve esse `W/` na revisita, e `==` contra o forte nunca batia (achado em `embed.js`, forms-rapidos 2026-10-01; mesma causa aqui, mesmo remédio — ver `etag_match.go`).
Respostas: 200 o script; 304 não modificado (ETag)

curl -X GET 'https://api.pages.asender.net/pixel.js' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /r/{slug}
Resolver um link curto (anônimo)
Onde é usada: rota pública do runtime, nos hosts da conta (substitui o `Redirect.Servir` da 012 no server.go).
Parâmetros: slug (path, obrigatório)
Respostas: 302 redireciona ao destino; 404 link inexistente ou inativo

curl -X GET 'https://api.pages.asender.net/r/slug_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /r/{slug}
Resolver um link curto (anônimo)
Onde é usada: rota `/chat.js` do runtime.
Entradas: w; r.
Efeitos: nenhum — é leitura de bytes já em memória. **Não há CORS aqui, e é de propósito.** Um `<script src>` não precisa de CORS para executar, e liberar `Access-Control-Allow-Origin: *` neste arquivo só abriria a leitura do conteúdo por `fetch` de qualquer origem sem ganho nenhum. Quem precisa de CORS é a API do chat, e lá a origem é conferida contra a chave de site — não liberada em `*`. `ifNoneMatchCasa` (comparação FRACA, RFC 9110 §13.1.2), não `==`: a borda comprime este script on-the-fly e rebaixa o `ETag` forte para `W/"…"` na resposta — o navegador devolve esse `W/` na revisita, e `==` contra o forte nunca batia (achado em `embed.js`, forms-rapidos 2026-10-01; mesma causa aqui, mesmo remédio — ver `etag_match.go`).
Parâmetros: slug (path, obrigatório)
Respostas: 302 redireciona ao destino; 404 link inexistente ou inativo

curl -X GET 'https://api.pages.asender.net/r/slug_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /r/{slug}
Resolver um link curto (anônimo)
Onde é usada: rota `/chat.js` do runtime.
Entradas: w; r.
Efeitos: nenhum — é leitura de bytes já em memória. **Não há CORS aqui, e é de propósito.** Um `<script src>` não precisa de CORS para executar, e liberar `Access-Control-Allow-Origin: *` neste arquivo só abriria a leitura do conteúdo por `fetch` de qualquer origem sem ganho nenhum. Quem precisa de CORS é a API do chat, e lá a origem é conferida contra a chave de site — não liberada em `*`. `ifNoneMatchCasa` (comparação FRACA, RFC 9110 §13.1.2), não `==`: a borda comprime este script on-the-fly e rebaixa o `ETag` forte para `W/"…"` na resposta — o navegador devolve esse `W/` na revisita, e `==` contra o forte nunca batia (achado em `embed.js`, forms-rapidos 2026-10-01; mesma causa aqui, mesmo remédio — ver `etag_match.go`).
Parâmetros: slug (path, obrigatório)
Respostas: 302 redireciona ao destino; 404 link inexistente ou inativo

curl -X GET 'https://api.pages.asender.net/r/slug_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /replay
Gravar um lote de jornada (anônimo, credencial de pixel)
Onde é usada: rota pública, chamada pelo pixel a cada poucos segundos de uma sessão gravada.
Efeitos: publica no broker; NUNCA escreve no banco. Responde 204 quase sempre, como o `/collect`: credencial inválida é 403 (o HTML está velho), e o resto é aproveitado. O pixel roda no browser de terceiros, e transformar um lote parcialmente ruim em erro visível não conserta nada.
Respostas: 204 aceito; 400 corpo inválido; 403 credencial ou origem inválida; 429 excesso (rate-limit por credencial × IP); 503 gravação indisponível agora

curl -X POST 'https://api.pages.asender.net/replay' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /robots.txt
libera a indexação e aponta o sitemap do MESMO host — ou fecha o host inteiro (`Disallow: /`) quando ele não deve ir à busca (ver `fechado`).
Onde é usada: rota pública.
Efeitos: uma leitura no `asender_pages_api` (quando há fonte). # Por que liberar é o padrão A página existe para ser achada: é landing page de campanha, e quem a publica quer tráfego. Fechar o host é DECISÃO — do cliente (noindex do site), do estado (nada publicado e indexável) ou da política (`PAGES_INDEXACAO`) —, nunca o default da plataforma. Falha ao consultar o `asender_pages_api` LIBERA: um blip não pode tirar o site de um cliente da busca (o cache curto de 5 min do documento fechado vale pelo mesmo motivo). O noindex de UMA página não vira `Disallow`: o buscador precisa conseguir ler a página para ver o `noindex` dela — bloqueada no robots, ela pode continuar no índice pelos links que apontam para ela. O sitemap é apontado com o HOST da requisição, e não com um domínio configurado: cada cliente tem o dele, e um endereço fixo aqui mandaria o buscador de todo mundo para o sitemap de um só.

curl -X GET 'https://api.pages.asender.net/robots.txt' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /sitemap.xml
lista as páginas PUBLICADAS e INDEXÁVEIS daquele host (sem noindex, sem canônica externa; a home do domínio pela raiz). Host fechado pela política ou site com noindex global → documento vazio.
Onde é usada: rota pública.
Efeitos: uma leitura no `asender_pages_api`. # Host sem página responde XML VAZIO, e não 404 Um 404 no sitemap faz o buscador registrar erro e tentar de novo; um documento vazio diz "não há nada para indexar aqui", que é a verdade. E o host que ainda não tem página publicada é o caso mais comum logo depois de alguém cadastrar um domínio. # Rascunho não entra A consulta do `asender_pages_api` filtra por versão publicada. Listar rascunho entregaria ao buscador o endereço de uma página que o cliente ainda não quis mostrar — e o buscador não esquece.

curl -X GET 'https://api.pages.asender.net/sitemap.xml' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/ab
Resultado do teste A/B por variante
Onde é usada: tela do experimento.
Efeitos: uma leitura.
Parâmetros: pagina (query); de (query); ate (query); experimento (query); variantes (query); desde (query); minimo (query); prob (query); piso (query); autobalancear (query)
Respostas: 200 ok; 400 parâmetros do experimento inválidos; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/ab' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/breakdown
Quebra por dimensão
Onde é usada: tela de origens.
Efeitos: uma leitura.
Parâmetros: dimensao (query); pagina (query); de (query); ate (query); limite (query)
Respostas: 200 ok; 400 dimensão/janela inválidas; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/breakdown' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/events
Eventos brutos
Onde é usada: tela de depuração da instrumentação.
Efeitos: uma leitura.
Parâmetros: pagina (query); limite (query); de (query); ate (query)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/events' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/heatmap
Mapa de calor
Onde é usada: tela de mapa de calor.
Efeitos: uma leitura. # As posições são PORCENTAGEM, e não pixel Pixel absoluto é da tela de quem clicou: o mesmo botão sai em x=320 no celular e x=980 no monitor. A célula em porcentagem compara telas diferentes — que é a única pergunta que um mapa de calor responde.
Parâmetros: pagina (query); lado (query); de (query); ate (query)
Respostas: 200 ok; 400 lado inválido; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/heatmap' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/live
Instantâneo em tempo real
Onde é usada: cabeçalho da tela ao vivo, no primeiro carregamento.
Efeitos: uma leitura. Existe além do stream porque quem abre a tela precisa ver ALGO antes do primeiro evento chegar. Sem isso, uma conta com movimento baixo mostraria tela vazia por minutos e pareceria quebrada.
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/live' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/live/stream
Stream em tempo real (SSE)
Onde é usada: tela ao vivo.
Efeitos: mantém uma conexão aberta e uma inscrição no hub. # SSE, e não WebSocket O fluxo é de mão única (servidor → tela) e o cliente é um navegador. SSE atravessa proxy comum, reconecta sozinho e cabe em quatro linhas de JS; WebSocket traria um protocolo inteiro para carregar dado que só desce.
Respostas: 200 fluxo de eventos; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/live/stream' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/overview
Visão geral do publicado
Onde é usada: tela inicial de analytics.
Efeitos: duas leituras. Funil e atribuição juntos porque a tela mostra os dois lado a lado, e duas requisições poderiam ler janelas diferentes — o total da atribuição não fecharia com o topo do funil, e o número "errado" seria o certo.
Parâmetros: pagina (query); de (query); ate (query)
Respostas: 200 ok; 400 janela inválida (RFC3339, teto 92 dias); 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/relatorio
Relatório filtrado (totais, série diária e dimensão)
Onde é usada: aba "Analytics" do formulário no painel.
Efeitos: nove leituras sob o tenant. Um formulário de outra conta casa zero linha na RLS: o relatório sai zerado, que é o desfecho correto (a existência do form não vaza nem por 403).
Parâmetros: dimensao (query); de (query); ate (query); pagina (query); utm_source (query); utm_medium (query); utm_campaign (query); pais (query); dispositivo (query); formulario (query); limite (query)
Respostas: 200 ok; 400 dimensão/filtro/janela inválidos (RFC3339, teto 92 dias); 401 Sem sessão / credencial ausente ou inválida.; 501 relatório indisponível neste ambiente

curl -X GET 'https://api.pages.asender.net/v1/analytics/relatorio' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/session/{id}
Eventos de uma sessão
Onde é usada: tela de sessão — o que aquela visita fez, em ordem.
Efeitos: uma leitura. Sessão de outra conta responde lista VAZIA, e não 404: o id de sessão é opaco e gerado no browser, e distinguir "não existe" de "não é sua" transformaria a rota num oráculo de existência de sessão alheia.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 400 sessão inválida; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/session/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/traffic-quality
Qualidade do tráfego
Onde é usada: tela de qualidade — "esse tráfego pago é gente?".
Efeitos: uma leitura.
Parâmetros: de (query); ate (query)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/analytics/traffic-quality' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/campos-nativos
GET /v1/campos-nativos → `{campos, grupos, paises}`.
Onde é usada: construtor de formulário (paleta de campos nativos, seletor de país) e o diálogo de destinos (alvos do mapa). Sessão do painel exigida pela rota.
Efeitos: nenhum — lê o catálogo embutido. Sem tenant na pergunta: o catálogo é o mesmo para toda conta. O 401 sem conta na sessão é só coerência com as rotas vizinhas.

curl -X GET 'https://api.pages.asender.net/v1/campos-nativos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/configuracoes/marca
Obter a marca da conta
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/configuracoes/marca' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/configuracoes/marca
Definir a marca da conta
Onde é usada: clientes do contrato anterior à 037. O corpo NÃO tem `tenant_id`: a conta vem da sessão, e o campo desconhecido é recusado (400) — o silêncio faria quem tentou achar que funcionou.
Respostas: 200 gravada; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 403 sem o papel de editor no Pages (PEP nível 20); 422 valor inválido — a mensagem nomeia o campo

curl -X PUT 'https://api.pages.asender.net/v1/configuracoes/marca' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/configuracoes/marca/efetivo
Kit de marca efetivo de uma página/host
Onde é usada: autopreenchimento dos widgets do construtor e a geração por IA.
Parâmetros: pagina (query); dominio (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/configuracoes/marca/efetivo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/configuracoes/marca/kits
Listar os kits de marca da conta
Onde é usada: tela de marca e seletores de kit (domínios, editor).
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/configuracoes/marca/kits' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/configuracoes/marca/kits
Criar (ou duplicar) um kit de marca
Onde é usada: botões "novo kit" e "duplicar" da tela.
Respostas: 201 criado; 400 corpo inválido (inclui campo desconhecido, ex. tenant_id); 401 Sem sessão / sem tenant na sessão.; 403 sem o papel de editor no Pages; 404 kit de origem (duplicar_de) não existe nesta conta; 409 já existe um kit com esse nome; 422 campo inválido (a mensagem nomeia o campo) ou limite de kits

curl -X POST 'https://api.pages.asender.net/v1/configuracoes/marca/kits' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/configuracoes/marca/kits/{id}
Obter um kit de marca
Onde é usada: formulário de edição do kit.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 não existe — ou é de outra conta (mesma resposta)

curl -X GET 'https://api.pages.asender.net/v1/configuracoes/marca/kits/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/configuracoes/marca/kits/{id}
Salvar um kit de marca (nome e dados de uma vez)
Onde é usada: botão salvar da tela de marca. `duplicar_de` aqui é recusado (400).
Parâmetros: id (path, obrigatório)
Respostas: 200 gravado; 400 corpo inválido (campo desconhecido; duplicar_de só na criação); 401 Sem sessão / sem tenant na sessão.; 403 sem o papel de editor no Pages; 404 não existe — ou é de outra conta; 409 já existe um kit com esse nome; 422 campo inválido — a mensagem nomeia o campo

curl -X PUT 'https://api.pages.asender.net/v1/configuracoes/marca/kits/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/configuracoes/marca/kits/{id}
Apagar um kit de marca
Onde é usada: menu do kit na tela.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagado; 401 Sem sessão / sem tenant na sessão.; 403 sem o papel de editor no Pages; 404 não existe — ou é de outra conta; 409 kit padrão ou em uso

curl -X DELETE 'https://api.pages.asender.net/v1/configuracoes/marca/kits/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/configuracoes/marca/kits/{id}/padrao
Tornar um kit o padrão da conta
Onde é usada: menu do kit na tela.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 sem o papel de editor no Pages; 404 não existe — ou é de outra conta

curl -X POST 'https://api.pages.asender.net/v1/configuracoes/marca/kits/id_AQUI/padrao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/configuracoes/marca/vinculos
Onde cada kit vale (domínios e páginas)
Onde é usada: lista de páginas do painel.
Efeitos: uma leitura sob o tenant da sessão.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/configuracoes/marca/vinculos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/configuracoes/marca/vinculos/dominios/{id}
Escolher o kit de um domínio
Onde é usada: seletor de kit por domínio.
Parâmetros: id (path, obrigatório)
Respostas: 204 gravado; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 403 sem o papel de editor no Pages; 404 domínio ou kit não existe nesta conta

curl -X PUT 'https://api.pages.asender.net/v1/configuracoes/marca/vinculos/dominios/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/configuracoes/marca/vinculos/paginas/{id}
Escolher o kit de uma página
Onde é usada: seletor de kit por página.
Parâmetros: id (path, obrigatório)
Respostas: 204 gravado; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 403 sem o papel de editor no Pages; 404 página ou kit não existe nesta conta

curl -X PUT 'https://api.pages.asender.net/v1/configuracoes/marca/vinculos/paginas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/configuracoes/seo
Obter o SEO do site (um host da conta)
Onde é usada: tela "SEO do site".
Efeitos: uma leitura. Host de outra conta (ou não verificado) → 404.
Parâmetros: dominio (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 host não é um domínio verificado desta conta

curl -X GET 'https://api.pages.asender.net/v1/configuracoes/seo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/configuracoes/seo
Definir a indexação do site (um host da conta)
Onde é usada: tela "SEO do site".
Efeitos: uma escrita; muda robots, sitemap e `<head>` de todo o host.
Parâmetros: dominio (query)
Respostas: 200 gravado; 400 corpo inválido (inclui campo desconhecido, ex. tenant_id); 401 Sem sessão / sem tenant na sessão.; 404 host não é um domínio verificado desta conta; 422 campo que mora no kit de marca veio preenchido — a mensagem diz onde editá-lo

curl -X PUT 'https://api.pages.asender.net/v1/configuracoes/seo' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/cotas
Uso e teto de domínios da conta, pelo plano
Onde é usada: medidor de cota da tela de domínios.
Efeitos: uma leitura na plataforma (cache 60 s) e uma no banco.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 503 plataforma indisponível para conferir o plano

curl -X GET 'https://api.pages.asender.net/v1/cotas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/dominios
Listar domínios da conta
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Respostas: 200 ok (o padrão primeiro); 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/dominios' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/dominios
Adicionar domínio (gera o TXT de posse)
Onde é usada: tela de domínios.
Efeitos: uma escrita. # O domínio nasce NÃO verificado E é isso que impede o pior desfecho do produto: sem a prova de DNS, qualquer conta declararia `banco.com.br` e passaria a receber certificado TLS para esse nome — servindo uma página de captura no domínio de outra pessoa, com cadeado verde.
Respostas: 201 criado; 401 Sem sessão / sem tenant na sessão.; 402 limite do plano atingido para a classe do domínio; 409 host já cadastrado; 422 host inválido, reservado, sufixo público ou sob o domínio dos grátis; 503 limite do plano indisponível para conferir agora

curl -X POST 'https://api.pages.asender.net/v1/dominios' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/dominios/{id}
Remover domínio
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 removido; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/dominios/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/dominios/{id}/cloudflare
Estado do DNS automático na Cloudflare
Onde é usada: cartão do domínio na tela de domínios.
Efeitos: consultas DNS; no máximo um GET (cacheado) à Cloudflare.
Parâmetros: id (path, obrigatório)
Respostas: 200 estado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 429 muitas tentativas

curl -X GET 'https://api.pages.asender.net/v1/dominios/id_AQUI/cloudflare' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/dominios/{id}/cloudflare/aplicar
Aplicar na Cloudflare os registros do Asender
Onde é usada: botão "Aplicar registros na Cloudflare". Depois, a tela chama o `verificar` de sempre.
Efeitos: chamadas à API da Cloudflare em nome do cliente; uma linha de auditoria.
Parâmetros: id (path, obrigatório)
Respostas: 200 relatório por registro; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 sem token guardado (ou token ilegível — cole de novo); 422 token recusado; 429 muitas tentativas; 503 Cloudflare indisponível

curl -X POST 'https://api.pages.asender.net/v1/dominios/id_AQUI/cloudflare/aplicar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/dominios/{id}/cloudflare/domain-connect
URL assinada do Domain Connect (1 clique)
Onde é usada: botão "Conectar com Cloudflare".
Efeitos: consultas DNS; um GET cacheado à Cloudflare; uma linha de auditoria. # O retorno não carrega `state` A Cloudflare não suporta `state` (doc oficial). Por isso o retorno NÃO faz escrita alguma: a tela só chama o `verificar` de sempre, que é idempotente e autenticado — forjar um retorno não dá a ninguém nada além de uma verificação.
Parâmetros: id (path, obrigatório)
Respostas: 200 URL; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 Domain Connect indisponível para o domínio (ver `motivo`) ou nada a aplicar; 422 retorno inválido; 429 muitas tentativas

curl -X POST 'https://api.pages.asender.net/v1/dominios/id_AQUI/cloudflare/domain-connect' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/dominios/{id}/cloudflare/token
Guardar o token da Cloudflare (Zone → DNS → Edit)
Onde é usada: formulário "usar token" do cartão do domínio.
Efeitos: até N+1 GETs à Cloudflare; uma escrita; uma linha de auditoria. O token NUNCA volta em resposta nem em log — nem cifrado.
Parâmetros: id (path, obrigatório)
Respostas: 200 estado novo; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 422 formato inválido; 429 muitas tentativas; 503 Cloudflare indisponível ou cifra não configurada neste ambiente

curl -X PUT 'https://api.pages.asender.net/v1/dominios/id_AQUI/cloudflare/token' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/dominios/{id}/cloudflare/token
Remover o token guardado
Onde é usada: botão "remover token".
Efeitos: uma escrita e uma linha de auditoria. O token continua válido NA Cloudflare: a tela pede para o cliente revogá-lo lá.
Parâmetros: id (path, obrigatório)
Respostas: 204 removido (também quando não havia); 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 429 muitas tentativas

curl -X DELETE 'https://api.pages.asender.net/v1/dominios/id_AQUI/cloudflare/token' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/dominios/{id}/pagina-inicial
Definir a página inicial (home/apex) do domínio
Onde é usada: tela de domínios, tela da página e a API pública (`pages:write`).
Efeitos: uma escrita (duas quando a página precisa mudar de endereço). # Página de outro endereço vem para este domínio Se a página é da conta mas está noutro domínio (ou na plataforma), ela é MOVIDA para este (mesmo slug; o endereço antigo passa a responder 301 se já esteve no ar) e vira a inicial. Sem `ComMoverDePagina` (boot parcial) o comportamento antigo vale: 422. Página que é a inicial do domínio de ORIGEM responde 409 `pagina_inicial` (troque a inicial de lá antes). # Os dois 404 são indistinguíveis de propósito "Domínio não encontrado" cobre id inexistente E id de outra conta; "página não encontrada" cobre id inexistente, apagada E de outra conta. Distinguir qualquer um desses pares confirmaria a um tenant que aquele id existe na plataforma, atribuído a alguém — o mesmo raciocínio do 404 de Verificar e Apagar (dominios.go).
Parâmetros: id (path, obrigatório)
Respostas: 200 domínio com a home atualizada; 400 Parâmetro de query fora do conjunto aceito.; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 domínio OU página não encontrados (ids distintos e indistinguíveis de outra conta); 409 `motivo`: `pagina_inicial` (a página é a home de OUTRO domínio; troque a de lá antes) ou `caminho_em_uso` (o slug já é de outra página deste domínio); 422 `motivo`: `dominio_nao_verificado` ou `caminho_invalido` (ao mover a página para este domínio); 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X PUT 'https://api.pages.asender.net/v1/dominios/id_AQUI/pagina-inicial' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/dominios/{id}/pagina-inicial
Remover a página inicial do domínio
Onde é usada: tela de domínios (botão "remover página inicial").
Efeitos: uma escrita.
Parâmetros: id (path, obrigatório)
Respostas: 200 domínio com pagina_inicial: null; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X DELETE 'https://api.pages.asender.net/v1/dominios/id_AQUI/pagina-inicial' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/dominios/{id}/push
Coleta de Web Push nativa do domínio (ADR-0102)
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: id (path, obrigatório)
Respostas: 200 estado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X GET 'https://api.pages.asender.net/v1/dominios/id_AQUI/push' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/dominios/{id}/push
Ligar ou configurar a coleta de Web Push do domínio
Onde é usada: botão salvar do editor.
Efeitos: cria uma versão.
Parâmetros: id (path, obrigatório)
Respostas: 200 configuração gravada; 400 Parâmetro de query fora do conjunto aceito.; 401 Sem sessão / sem tenant na sessão.; 403 sem papel de editor; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 domínio ainda não verificado; 422 valor inválido (chave

curl -X PUT 'https://api.pages.asender.net/v1/dominios/id_AQUI/push' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/dominios/{id}/push
Desligar a coleta de Web Push do domínio
Onde é usada: botão "Desligar" do pages_front.
Parâmetros: id (path, obrigatório)
Respostas: 204 desligado; 401 Sem sessão / sem tenant na sessão.; 403 sem papel de editor; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/dominios/id_AQUI/push' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/dominios/{id}/verificar
Verificar os 3 passos (TXT, apontamento e certificado)
Onde é usada: botão "verificar agora" da tela de domínios.
Efeitos: consultas DNS, um handshake TLS com a nossa borda e escritas. # 200 com o estado de cada passo, e não 422 no primeiro que falha A tela é em passos: o cliente publica o TXT e o CNAME de uma vez, e precisa ver qual dos dois ainda falta. Recusar com 422 no TXT esconderia o estado do apontamento — que foi exatamente a queixa ("só tem opção do TXT"). O 503 continua para quando NADA pôde ser consultado: aí a resposta certa é "tente de novo", não um estado. # A posse já provada não é reconsultada O cliente costuma apagar o TXT depois de verificar. Reconsultar transformaria essa limpeza num erro vermelho no passo 1 de um domínio que está no ar.
Parâmetros: id (path, obrigatório)
Respostas: 200 estado dos 3 passos; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 DNS indisponível para checar agora

curl -X POST 'https://api.pages.asender.net/v1/dominios/id_AQUI/verificar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/email/midias
Biblioteca de imagens do e-mail marketing (listar)
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Parâmetros: limite (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 sem acesso ao produto emailmarketing

curl -X GET 'https://api.pages.asender.net/v1/email/midias' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/email/midias
Biblioteca de imagens do e-mail marketing (enviar)
Onde é usada: botão de upload do editor.
Efeitos: escreve no disco e no banco. # A ordem é DISCO e depois BANCO Se o disco falhar, nada foi gravado e o erro é honesto. A ordem inversa deixaria uma linha apontando para um arquivo inexistente, e o visitante receberia erro numa página publicada. O caso duplicado não grava nada: a mídia já está lá, com os mesmos bytes.
Respostas: 200 já existia (deduplicada por conteúdo); 201 enviada; 400 campo `arquivo` ausente; 401 Sem sessão / sem tenant na sessão.; 404 sem acesso (nível operador) ao produto emailmarketing; 413 arquivo grande demais; 422 tipo não aceito ou recusado pelo antivírus; 503 antivírus sem responder (reenvie; vem `Retry-After`)

curl -X POST 'https://api.pages.asender.net/v1/email/midias' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/forms/{formID}/submissions
Enviar uma submissão de um formulário (modo API)
Onde é usada: rota autenticada do runtime.
Efeitos: os do pipeline (banco, outbox). O tenant vem do CONTEXTO, posto pelo middleware que validou a API key — nunca do corpo (§37: confiar em tenant_id do cliente). É isso que faz a key de um tenant não alcançar o form de outro.
Parâmetros: formID (path, obrigatório); Idempotency-Key (header)
Respostas: 200 duplicada — o `id_externo` (ou `Idempotency-Key`) já foi recebido neste formulário; nada de novo gravado e o `lead_id` é o do envio original; 201 lead criado; 400 recusado: corpo inválido, campo não declarado ou inválido, consentimento exigido ausente, `ocorrido_em` fora da janela; 401 Sem sessão / credencial ausente ou inválida.; 403 A chave não tem o escopo `forms:write`.; 404 formulário não encontrado (ou de outra conta); 429 limite por conta excedido (300 por minuto por padrão). Aguarde `Retry-After` segundos.; 502 não consegui registrar agora; tente de novo com o mesmo `id_externo`; 503 não consegui validar a chave agora; tente de novo

curl -X POST 'https://api.pages.asender.net/v1/forms/formID_AQUI/submissions' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/forms/externo/{externalID}/submissions
Enviar uma submissão pelo id externo do formulário (modo API)
Onde é usada: rota do modo API, para integradores que guardam o id deles, não o nosso.
Efeitos: uma chamada ao pages_api para resolver; depois os do pipeline. 404 quando o pages_api não conhece o id (para a conta da chave); 503 quando não dá para perguntar — recarregar resolve, e o lead não é aceito às cegas.
Parâmetros: externalID (path, obrigatório); Idempotency-Key (header)
Respostas: 200 duplicada — o `id_externo` (ou `Idempotency-Key`) já foi recebido neste formulário; nada de novo gravado e o `lead_id` é o do envio original; 201 lead criado; 400 recusado: corpo inválido, campo não declarado ou inválido, consentimento exigido ausente, `ocorrido_em` fora da janela; 401 Sem sessão / credencial ausente ou inválida.; 403 A chave não tem o escopo `forms:write`.; 404 formulário não encontrado (ou de outra conta); 429 limite por conta excedido (300 por minuto por padrão). Aguarde `Retry-After` segundos.; 502 não consegui registrar agora; tente de novo com o mesmo `id_externo`; 503 não consegui validar a chave agora; tente de novo

curl -X POST 'https://api.pages.asender.net/v1/forms/externo/externalID_AQUI/submissions' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/formularios
Listar formulários
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Parâmetros: external_id (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/formularios' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/formularios
Criar formulário
Onde é usada: tela de domínios.
Efeitos: uma escrita. # O domínio nasce NÃO verificado E é isso que impede o pior desfecho do produto: sem a prova de DNS, qualquer conta declararia `banco.com.br` e passaria a receber certificado TLS para esse nome — servindo uma página de captura no domínio de outra pessoa, com cadeado verde.
Parâmetros: Idempotency-Key (header)
Respostas: 201 criado (ou replay idempotente — então vem `Idempotent-Replayed`); 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 409 nome ou `external_id` já em uso; 422 definição inválida, ou `Idempotency-Key` já usada com outro corpo; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X POST 'https://api.pages.asender.net/v1/formularios' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/formularios/{formID}/analytics
Funil e conversão de um formulário
Onde é usada: aba "Analytics" do formulário no painel.
Efeitos: nove leituras sob o tenant. Um formulário de outra conta casa zero linha na RLS: o relatório sai zerado, que é o desfecho correto (a existência do form não vaza nem por 403).
Parâmetros: formID (path, obrigatório); de (query); ate (query); fuso (query)
Respostas: 200 relatório do funil; 400 parâmetro inválido; 401 sem sessão/conta

curl -X GET 'https://api.pages.asender.net/v1/formularios/formID_AQUI/analytics' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/formularios/{formID}/envios
GET /v1/formularios/{formID}/envios?limite=&cursor=&desde=&ate=.
Onde é usada: a tela de leads da ferramenta de Páginas/Formulários.
Efeitos: uma consulta; uma abertura de AES-GCM por linha; um registro de acesso a PII no log. Devolve `{"envios": [...], "proximo_cursor": ""}` — cursor vazio significa que acabou. A alternativa (omitir o campo no fim) obrigaria o cliente a distinguir ausente de vazio, e é o tipo de sutileza que vira laço infinito na tela.

curl -X GET 'https://api.pages.asender.net/v1/formularios/formID_AQUI/envios' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/formularios/{formID}/envios.csv
GET /v1/formularios/{formID}/envios.csv?desde=&ate=.
Onde é usada: botão "exportar" da tela de leads.
Efeitos: N consultas (a exportação pagina por dentro), uma abertura de AES-GCM por linha, um registro de acesso a PII no log. # Escreve direto no `ResponseWriter`, sem montar o arquivo na memória Um CSV de 10.000 leads com campos livres passa de 10 MB. Montá-lo num buffer para só então enviar duplicaria isso por requisição concorrente, e o pico aconteceria justamente quando várias pessoas exportam no mesmo dia (o dia seguinte a uma campanha). O `encoding/csv` escreve incrementalmente. O custo dessa escolha é honesto e está registrado em `falharNoMeio`: depois do primeiro byte não há mais como trocar o status.

curl -X GET 'https://api.pages.asender.net/v1/formularios/formID_AQUI/envios.csv' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/formularios/{id}
Obter formulário (com o snippet de embed e o rascunho do editor)
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/formularios/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/formularios/{id}
Atualizar (publicar) formulário
Onde é usada: edição.
Efeitos: escreve a linha.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 nome ou `external_id` já em uso; 422 definição inválida; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X PUT 'https://api.pages.asender.net/v1/formularios/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/formularios/{id}
Apagar formulário
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagado; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X DELETE 'https://api.pages.asender.net/v1/formularios/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/formularios/{id}/desarquivar
Desarquivar um formulário
Onde é usada: botão "Desarquivar" da aba Arquivados. Sessão OU chave `forms:write`.
Efeitos: um UPDATE + auditoria `restaurar` (feitos pelo repositório).
Erros: 404 não apagado ou de outra conta (indistintos, nunca 403); 409 quando um índice único (ex.: external_id) já está ocupado por outro formulário vivo.
Parâmetros: id (path, obrigatório)
Respostas: 204 desarquivado; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 outro formulário ativo ocupa o `external_id` (ou outro índice único); 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X POST 'https://api.pages.asender.net/v1/formularios/id_AQUI/desarquivar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/formularios/{id}/destinos
Listar destinos do formulário (crm/marketing/webhook)
Onde é usada: seção "Destinos" da tela do formulário.
Efeitos: uma leitura, com checagem de posse (anti-IDOR).
Parâmetros: id (path, obrigatório)
Respostas: 200 ok — os destinos (com `condicao_erro` nos quebrados) e se a conta tem o Marketing. Formulário com caixa de aceite numa conta com Marketing ganha, UMA vez, o destino Marketing com a condição "caixa marcada" (preset).; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X GET 'https://api.pages.asender.net/v1/formularios/id_AQUI/destinos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/formularios/{id}/destinos
Substituir a lista de destinos do formulário
Onde é usada: seção "Destinos" da tela do formulário, ao salvar.
Efeitos: apaga e regrava os destinos, atômico. A validação mora no domínio (`destino.ValidarListaComCampos`): tipo conhecido, mapa com alvos válidos, webhook com URL http(s), condições contra os campos do formulário e o Marketing só com "aceite marcado". O SSRF do webhook é conferido no runtime, no instante do despacho — aqui a checagem é de FORMA, a que dá mensagem clara para quem configura.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 422 destino ou condição inválidos (integracao: + codigo e local); 503 IntegracoesIndisponivel — só com destino integracao novo/alterado

curl -X PUT 'https://api.pages.asender.net/v1/formularios/id_AQUI/destinos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/formularios/{id}/rascunho
Salvar o rascunho do editor (sem publicar)
Onde é usada: botão "Salvar rascunho" do editor-página (e o salvamento automático).
Efeitos: escreve `rascunho`; o formulário no ar NÃO muda. # Só a FORMA é conferida Rascunho existe para guardar trabalho pela metade — um campo sem rótulo, uma lista sem opção. Recusá-lo pelas regras de publicação faria a pessoa perder o que fez justamente quando ainda não terminou. A borda confere que o corpo é o do PUT (nenhum campo desconhecido, tipos certos, dentro do teto) e grava a forma DECODIFICADA re-serializada: chave estranha não chega ao banco. Toda a regra de domínio roda no PUBLICAR.
Parâmetros: id (path, obrigatório)
Respostas: 200 salvo; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 413 rascunho acima do teto

curl -X PUT 'https://api.pages.asender.net/v1/formularios/id_AQUI/rascunho' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/formularios/{id}/rascunho
Descartar o rascunho do editor
Onde é usada: "Descartar alterações" do editor-página.
Efeitos: zera o rascunho; o formulário no ar não muda. Idempotente.
Parâmetros: id (path, obrigatório)
Respostas: 204 descartado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/formularios/id_AQUI/rascunho' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/formularios/agendas
Listar as agendas da conta (seletor do campo Agendamento)
Onde é usada: o campo Agendamento do builder (dropdown).
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 serviço Agenda indisponível

curl -X GET 'https://api.pages.asender.net/v1/formularios/agendas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/formularios/arquivados
Listar os formulários arquivados da conta (lixeira)
Onde é usada: aba "Arquivados" da tela de formulários. Sessão OU chave `forms:read`.
Efeitos: leituras; o tenant sai SEMPRE do contexto verificado.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/formularios/arquivados' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/formularios/externo/{external_id}
Obter formulário pelo id externo
Onde é usada: integrações por chave (forms:read) e sessão.
Efeitos: uma leitura.
Parâmetros: external_id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/formularios/externo/external_id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/formularios/externo/{external_id}
Criar ou atualizar formulário pelo id externo (upsert idempotente)
Onde é usada: integrações por chave (forms:write) e sessão.
Efeitos: escreve a linha; atualizar zera o rascunho do editor.
Parâmetros: external_id (path, obrigatório)
Respostas: 200 atualizado; 201 criado; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 409 nome já em uso; 422 definição inválida; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X PUT 'https://api.pages.asender.net/v1/formularios/externo/external_id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/formularios/gerar-com-ia
Criar um formulário a partir de uma descrição (IA)
Onde é usada: botão "gerar com IA" do editor de formulários (SÓ sessão).
Efeitos: uma chamada paga ao provedor e UMA escrita (formulário novo).
Respostas: 201 formulário criado; 400 corpo inválido ou com campo desconhecido; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 nome em uso mesmo após os sufixos automáticos; 422 descrição vazia/acima de 2000 caracteres ou idioma não suportado; 429 limite por minuto da conta ou teto de gerações do provedor; 502 o provedor falhou ou a saída veio fora do formato; 503 IA não configurada neste ambiente

curl -X POST 'https://api.pages.asender.net/v1/formularios/gerar-com-ia' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/ia/gerar-pagina
Gerar um rascunho de página por IA
Onde é usada: botão "gerar com IA" do editor.
Efeitos: uma chamada externa; NÃO grava nada. # Não grava: devolve o rascunho Gravar direto faria o modelo publicar na conta do cliente. O que sai daqui é uma sugestão que a pessoa vê no editor e salva se quiser — a versão continua nascendo do gesto dela. # Sem provedor, a rota DEGRADA 503 e não 500: é configuração ausente, e a distinção separa "o produto não tem essa função ligada" de "o produto quebrou". O resto do serviço segue de pé — nenhuma página deixa de ser servida porque não há chave de IA (piso 10).
Respostas: 200 rascunho gerado; 401 Sem sessão / sem tenant na sessão.; 422 pedido vazio/longo demais; 502 o provedor falhou ao gerar; 503 geração por IA desligada neste ambiente

curl -X POST 'https://api.pages.asender.net/v1/ia/gerar-pagina' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/leads
Enviar um lead (modo API, com API key)
Onde é usada: rota autenticada do runtime.
Efeitos: os do pipeline (banco, outbox). O tenant vem do CONTEXTO, posto pelo middleware que validou a API key — nunca do corpo (§37: confiar em tenant_id do cliente). É isso que faz a key de um tenant não alcançar o form de outro.
Parâmetros: Idempotency-Key (header)
Respostas: 200 duplicada — o `id_externo` (ou `Idempotency-Key`) já foi recebido neste formulário; nada de novo gravado e o `lead_id` é o do envio original; 201 lead criado; 400 recusado: corpo inválido, campo não declarado ou inválido, consentimento exigido ausente, `ocorrido_em` fora da janela; 401 Sem sessão / credencial ausente ou inválida.; 403 A chave não tem o escopo `forms:write`.; 404 formulário não encontrado (ou de outra conta); 429 limite por conta excedido (300 por minuto por padrão). Aguarde `Retry-After` segundos.; 502 não consegui registrar agora; tente de novo com o mesmo `id_externo`; 503 não consegui validar a chave agora; tente de novo

curl -X POST 'https://api.pages.asender.net/v1/leads' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/links
Listar links do encurtador
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Parâmetros: busca (query); pagina_id (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/links' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/links
Criar link (código curto + UTM + parâmetros + repasse)
Onde é usada: tela de domínios.
Efeitos: uma escrita. # O domínio nasce NÃO verificado E é isso que impede o pior desfecho do produto: sem a prova de DNS, qualquer conta declararia `banco.com.br` e passaria a receber certificado TLS para esse nome — servindo uma página de captura no domínio de outra pessoa, com cadeado verde.
Respostas: 200 o editor já tinha criado este link (origem pagina, mesmo bloco e destino); 201 criado; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 409 endereço /r/ já em uso; 422 destino/configuração/domínio inválidos

curl -X POST 'https://api.pages.asender.net/v1/links' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/links/{id}
Obter link
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X GET 'https://api.pages.asender.net/v1/links/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/links/{id}
Editar link (código, origem e contagem não mudam)
Onde é usada: edição.
Efeitos: escreve a linha.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 endereço /r/ já em uso; 422 destino/configuração/domínio inválidos

curl -X PUT 'https://api.pages.asender.net/v1/links/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/links/{id}
Apagar link (o código nunca é reaproveitado)
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/links/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/links/{id}/relatorio
Relatório de cliques do link
Onde é usada: tela de relatório do link.
Efeitos: leituras.
Parâmetros: id (path, obrigatório); de (query); ate (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 422 período inválido

curl -X GET 'https://api.pages.asender.net/v1/links/id_AQUI/relatorio' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/links/previa
Prévia da URL final (mesma regra do redirect)
Onde é usada: editor de link do painel (prévia ao vivo, enquanto a pessoa digita).
Efeitos: nenhum — não grava nada. A prévia vem do servidor, e não de uma terceira cópia da regra em TypeScript: o que a pessoa vê é exatamente o que o clique vai fazer.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 422 destino/configuração inválidos

curl -X POST 'https://api.pages.asender.net/v1/links/previa' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/lixeira
Lista o que a conta apagou e ainda pode restaurar (lixeira do usuário)
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Parâmetros: tipo (query); cursor (query)
Respostas: 200 Os itens apagados e o cursor da próxima página ('' = fim).; 401 Sem sessão / credencial ausente ou inválida.; 404 tipo fora da allowlist; 422 cursor inválido

curl -X GET 'https://api.pages.asender.net/v1/lixeira' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/lixeira
Lista o que a conta apagou e ainda pode restaurar (lixeira do usuário)
Onde é usada: a tela de leads da ferramenta de Páginas/Formulários.
Efeitos: uma consulta; uma abertura de AES-GCM por linha; um registro de acesso a PII no log. Devolve `{"envios": [...], "proximo_cursor": ""}` — cursor vazio significa que acabou. A alternativa (omitir o campo no fim) obrigaria o cliente a distinguir ausente de vazio, e é o tipo de sutileza que vira laço infinito na tela.
Parâmetros: tipo (query); cursor (query)
Respostas: 200 Os itens apagados e o cursor da próxima página ('' = fim).; 401 Sem sessão / credencial ausente ou inválida.; 404 tipo fora da allowlist; 422 cursor inválido

curl -X GET 'https://api.pages.asender.net/v1/lixeira' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/lixeira/{tipo}/{id}/restaurar
Restaura um item da lixeira da conta
Saídas: 204; 400 sem tenant ou sem `por`; 404 (não está na lixeira, ou é de outra conta); 409 `{"motivo":"conflito_unicidade"}`; 422 tipo desconhecido.
Parâmetros: tipo (path, obrigatório); id (path, obrigatório)
Respostas: 204 restaurado; 401 Sem sessão / credencial ausente ou inválida.; 403 restaurar kit sem o papel de editor no Pages; 404 não está na lixeira; 409 `conflito_unicidade` (endereço, host ou nome já em uso por outro item ativo), `dependencia_indisponivel` (domínio do link, ou domínio/página vinculados ao kit) ou `cota_excedida` (plano).

curl -X POST 'https://api.pages.asender.net/v1/lixeira/tipo_AQUI/id_AQUI/restaurar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/lixeira/{tipo}/{id}/restaurar
Restaura um item da lixeira da conta
Saídas: 204; 400 sem tenant/`por`; 404 (não está na lixeira, ou é de outra conta); 409 `conflito_unicidade`; 422 tipo desconhecido.
Parâmetros: tipo (path, obrigatório); id (path, obrigatório)
Respostas: 204 restaurado; 401 Sem sessão / credencial ausente ou inválida.; 403 restaurar kit sem o papel de editor no Pages; 404 não está na lixeira; 409 `conflito_unicidade` (endereço, host ou nome já em uso por outro item ativo), `dependencia_indisponivel` (domínio do link, ou domínio/página vinculados ao kit) ou `cota_excedida` (plano).

curl -X POST 'https://api.pages.asender.net/v1/lixeira/tipo_AQUI/id_AQUI/restaurar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/midias
Listar a galeria da conta
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Parâmetros: limite (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/midias' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/midias
Enviar uma imagem (multipart)
Onde é usada: botão de upload do editor.
Efeitos: escreve no disco e no banco. # A ordem é DISCO e depois BANCO Se o disco falhar, nada foi gravado e o erro é honesto. A ordem inversa deixaria uma linha apontando para um arquivo inexistente, e o visitante receberia erro numa página publicada. O caso duplicado não grava nada: a mídia já está lá, com os mesmos bytes.
Respostas: 200 já existia (deduplicada por conteúdo); 201 enviada; 400 campo `arquivo` ausente; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 413 arquivo grande demais; 422 arquivo recusado pelo antivírus; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 chave indisponível OU antivírus sem responder (reenvie; vem `Retry-After`)

curl -X POST 'https://api.pages.asender.net/v1/midias' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/midias/{id}
Apagar uma imagem (soft delete — o arquivo fica; o suporte restaura)
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagada (soft); 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/midias/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/midias/de-url
Importar uma imagem por URL
Onde é usada: colar o endereço de uma imagem no editor.
Efeitos: uma requisição a servidor de terceiro; escreve no disco e no banco. # Esta é a rota mais perigosa do serviço Ela faz o SERVIDOR buscar um endereço que o USUÁRIO escolheu — a definição de SSRF. Sem as guardas, `http://169.254.169.254/latest/meta-data/` devolveria as credenciais da instância, e `http://redis-interno:6379/` alcançaria um serviço que nunca deveria ver tráfego de fora. Toda a defesa está em `domain/midia`: allowlist de esquema e porta, recusa de IP interno, conferência REPETIDA no momento de discar (contra DNS rebinding), zero redirecionamento e teto de tamanho durante a leitura.
Respostas: 200 já existia; 201 importada; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 422 URL inválida / bloqueada; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 importação por URL desligada

curl -X POST 'https://api.pages.asender.net/v1/midias/de-url' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/paginas
Listar as páginas da conta
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/paginas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/paginas
Criar página
Onde é usada: tela de domínios.
Efeitos: uma escrita. # O domínio nasce NÃO verificado E é isso que impede o pior desfecho do produto: sem a prova de DNS, qualquer conta declararia `banco.com.br` e passaria a receber certificado TLS para esse nome — servindo uma página de captura no domínio de outra pessoa, com cadeado verde.
Respostas: 201 criada; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 403 conteúdo privilegiado (html) sem nível; 409 já existe página nesse endereço; 422 título ausente / domínio não verificado / template fora do contrato (v2: com `codigo` e `caminho`); 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X POST 'https://api.pages.asender.net/v1/paginas' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/paginas/{id}
Obter uma página (com suas versões)
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/paginas/{id}
Editar slug, domínio ou título
Onde é usada: tela de páginas do painel (renomear) e configurações da página.
Efeitos: uma escrita. # Só o que veio é tocado `nil` é "não mandado" e `&""` é "mandado vazio". Sem essa distinção, editar o título apagaria o endereço público da página — e ela sairia do ar sem ninguém ter pedido. # Validação IGUAL à da criação O slug e o título passam pelas mesmas regras do `Criar`. Um PATCH mais frouxo seria a porta dos fundos: bastaria criar válido e editar para inválido para pôr no ar um endereço que a criação recusa.
Parâmetros: id (path, obrigatório)
Respostas: 200 atualizada; 400 corpo inválido / nenhum campo; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 endereço em uso; 422 domínio não verificado / título vazio

curl -X PATCH 'https://api.pages.asender.net/v1/paginas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/paginas/{id}
Arquivar a página (soft delete — despublica e esconde; dá para desarquivar)
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 arquivada; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 arquivar indisponível neste serviço

curl -X DELETE 'https://api.pages.asender.net/v1/paginas/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/paginas/{id}/ab/desvincular
Desvincular a PRÓPRIA página do teste em que ela está (lista de páginas)
Onde é usada: ação "Desvincular do teste" da lista de páginas.
Parâmetros: id (path, obrigatório)
Respostas: 200 desvinculada; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/ab/desvincular' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/paginas/{id}/ab/pausar
Pausar o teste (rodando → pausado; todo visitante volta à página publicada)
Onde é usada: botão "Pausar" da tela de A/B.
Efeitos: uma escrita; **todo visitante volta a ver a página publicada**. A amostra fica congelada (o runtime só conta quem viu uma variante) e retomar continua a mesma medição: `iniciado_em` não muda.
Parâmetros: id (path, obrigatório)
Respostas: 200 pausado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 o teste não está rodando

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/ab/pausar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/paginas/{id}/ab/promover
Promover uma variante (e opcionalmente iniciar o teste)
Onde é usada: botão "promover vencedora" e botão "iniciar teste" da tela de A/B.
Efeitos: uma escrita; promover também põe a página vencedora na URL. # Duas operações na mesma rota, e por quê O lynz expõe `POST /v1/pages/{id}/ab/promote`, sem rota de iniciar — o teste começa ao ser promovido a "rodando". Manter uma rota só preserva a superfície do lynz, e o corpo diz qual das duas transições é pedida. # Iniciar EXIGE o experimento válido É o único ponto onde o rascunho inconsistente é barrado, e é o ponto certo: pesos que não somam 100 deixariam uma faixa do tráfego sem dono, e `Escolher` devolveria a última variante para essa fatia — um viés silencioso que o número final não denuncia.
Parâmetros: id (path, obrigatório)
Respostas: 200 promovida; 401 Sem sessão / sem tenant na sessão.; 409 já há experimento rodando; 422 variante inválida

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/ab/promover' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/paginas/{id}/ab/retomar
Retomar um teste pausado (mesma medição; o início não muda)
Onde é usada: botão "Retomar" da tela de A/B.
Efeitos: uma escrita; a distribuição volta para os visitantes novos, e quem já tinha braço fixado continua nele. Valida antes, como ao iniciar: com o teste pausado os braços puderam mudar.
Parâmetros: id (path, obrigatório)
Respostas: 200 rodando; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 o teste não está pausado, ou conflito (outro rodando / roteamento); 422 variantes inválidas

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/ab/retomar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/paginas/{id}/cliques
Cliques por destino de roteamento
Onde é usada: relatório da tela de links curtos.
Efeitos: uma leitura. Devolve o CONTADOR, e não uma lista de eventos: a pergunta é sempre "quantos", nunca "quais". Uma linha por clique transformaria o caminho mais quente do redirect num INSERT por requisição.
Parâmetros: id (path, obrigatório); dias (query)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/cliques' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/paginas/{id}/desarquivar
Desarquivar uma página (volta despublicada)
Onde é usada: botão "Desarquivar" da aba Arquivados. Sessão OU chave `forms:write`.
Efeitos: um UPDATE + auditoria `restaurar` (feitos pelo repositório).
Erros: 404 não apagado ou de outra conta (indistintos, nunca 403); 409 quando um índice único (ex.: external_id) já está ocupado por outro formulário vivo.
Parâmetros: id (path, obrigatório)
Respostas: 204 desarquivada; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 o endereço (domínio + caminho) já é de outra página; 503 lixeira indisponível neste serviço

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/desarquivar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/paginas/{id}/dominio
Mover a página de domínio e/ou de caminho
Onde é usada: PUT /v1/paginas/{id}/dominio (sessão OU chave com `pages:write`).
Efeitos: uma transação.
Parâmetros: id (path, obrigatório)
Respostas: 200 movida (ou já estava lá); 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 `motivo`: `caminho_em_uso` (o endereço já é de outra página) ou `pagina_inicial` (a página é a home do domínio de origem); 422 `motivo`: `dominio_nao_verificado` ou `caminho_invalido`; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/dominio' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/paginas/{id}/experimento
Obter o experimento da página
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/experimento' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/paginas/{id}/experimento/auto-stop
Definir o critério de decisão e o autobalanceamento (ADR-0093)
Onde é usada: painel "Critério e autobalanceamento" da tela de A/B.
Efeitos: uma escrita. Aceito com o teste RODANDO, ao contrário das variantes: nenhum destes campos reatribui visitante já contado (a atribuição é fixada por visitante) — mudam o rótulo da tela e a fatia do visitante NOVO.
Parâmetros: id (path, obrigatório)
Respostas: 200 definido; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 422 valores fora de faixa

curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/experimento/auto-stop' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/paginas/{id}/experimento/pesos
Definir a divisão de tráfego inteira, atomicamente (ADR-0093)
Onde é usada: a barra de divisão da tela de A/B ("Salvar divisão").
Efeitos: uma escrita. # Atômico, e por quê O defeito que o dono encontrou ("Soma dos pesos: 150%") nasceu de editar peso por peso: entre duas edições a soma passa por valores inválidos, e a tela não tinha como chegar a 100 sem ida e volta por variante. Aqui o conjunto chega inteiro e o domínio valida o resultado inteiro: soma exatamente 100, cada peso em 0–100 e ao menos dois braços com peso ≥ 1 (ADR-0093). # Aceito com o teste RODANDO ou PAUSADO A atribuição é fixada por visitante no runtime (cookie por experimento): o peso novo só decide quem chega DEPOIS. Encerrado recusa (409) — o tráfego já é todo da vencedora.
Parâmetros: id (path, obrigatório)
Respostas: 200 divisão gravada; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 experimento encerrado; 422 soma ≠ 100, variante faltando/a mais, peso fora de 0–100 ou menos de duas ativas

curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/experimento/pesos' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/paginas/{id}/midias/copiar
Tentar copiar de novo as mídias que ficaram na URL original
Onde é usada: botão "tentar copiar de novo" do relatório de importação.
Efeitos: downloads, galeria, no máximo uma versão nova.
Parâmetros: id (path, obrigatório)
Respostas: 200 nada mudou; 201 versão nova gravada; 401 Sem sessão / sem tenant na sessão.; 403 conteúdo privilegiado (html) sem nível; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 a cópia de mídia está indisponível neste servidor

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/midias/copiar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/paginas/{id}/publicar
Publicar uma versão
Onde é usada: botão publicar.
Efeitos: move o ponteiro da página; o visitante passa a ver esta versão.
Parâmetros: id (path, obrigatório)
Respostas: 200 publicada; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 422 essa versão não existe; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/publicar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/paginas/{id}/rascunho
Ler o rascunho pendente da página
Onde é usada: abertura do builder (recuperação).
Efeitos: nenhum.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 204 sem rascunho pendente; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/rascunho' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/paginas/{id}/rascunho
Gravar o rascunho (sem criar versão e sem publicar)
Onde é usada: botão "Salvar rascunho" do editor-página (e o salvamento automático).
Efeitos: escreve `rascunho`; o formulário no ar NÃO muda. # Só a FORMA é conferida Rascunho existe para guardar trabalho pela metade — um campo sem rótulo, uma lista sem opção. Recusá-lo pelas regras de publicação faria a pessoa perder o que fez justamente quando ainda não terminou. A borda confere que o corpo é o do PUT (nenhum campo desconhecido, tipos certos, dentro do teto) e grava a forma DECODIFICADA re-serializada: chave estranha não chega ao banco. Toda a regra de domínio roda no PUBLICAR.
Parâmetros: id (path, obrigatório); base (query)
Respostas: 200 gravado; 400 corpo inválido ou `base` ilegível; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 o rascunho mudou desde a `base` (`codigo: RascunhoConflito`); o corpo traz `rascunho` do servidor; 413 rascunho acima do teto; 428 chave de API sem `?base=`; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/rascunho' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/paginas/{id}/rascunho
Descartar o rascunho pendente
Onde é usada: "Descartar alterações" do editor-página.
Efeitos: zera o rascunho; o formulário no ar não muda. Idempotente.
Parâmetros: id (path, obrigatório)
Respostas: 204 descartado; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X DELETE 'https://api.pages.asender.net/v1/paginas/id_AQUI/rascunho' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/paginas/{id}/roteamento
Obter a regra de roteamento da página
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/roteamento' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/paginas/{id}/roteamento
Salvar a regra de roteamento
Onde é usada: botão salvar do editor.
Efeitos: cria uma versão.
Parâmetros: id (path, obrigatório)
Respostas: 200 salva; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 conflita com um experimento ativo; 422 estratégia/destinos inválidos

curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/roteamento' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/paginas/{id}/roteamento
Apagar a regra de roteamento
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagada; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/paginas/id_AQUI/roteamento' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/paginas/{id}/seo
Obter o SEO e o compartilhamento de uma página
Onde é usada: tela "SEO e compartilhamento" do painel.
Efeitos: uma leitura. Página nunca configurada responde 200 com os padrões.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 não existe — ou é de outra conta (mesma resposta); 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/seo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/paginas/{id}/seo
Definir o SEO e o compartilhamento de uma página
Onde é usada: tela "SEO e compartilhamento".
Efeitos: uma escrita; vale na próxima resolução do runtime (sem publicar).
Parâmetros: id (path, obrigatório)
Respostas: 200 gravado; 400 corpo inválido (inclui campo desconhecido, ex. tenant_id); 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 404 não existe — ou é de outra conta (mesma resposta); 422 campo inválido — a mensagem nomeia o campo (tamanho, URL fora de http/https, imagem sem https, dimensões); 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/seo' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/paginas/{id}/variantes
Listar as variantes
Onde é usada: tela de A/B.
Efeitos: uma leitura.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/paginas/{id}/variantes
Acrescentar uma PÁGINA ao teste — duplicar ou vincular (ADR-0095)
Onde é usada: botões "Criar variante" e "Vincular página existente" da tela de A/B.
Efeitos: escritas atômicas; a divisão é refeita em partes iguais. O braço é uma PÁGINA normal (aparece na lista, abre no editor, tem SEO e versões próprios); o teste só guarda a relação e o peso.
Parâmetros: id (path, obrigatório)
Respostas: 201 o experimento atualizado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 teste rodando / id de braço já usado / página já em outro teste; 422 modo inválido / página de outro domínio / id fora do formato

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/paginas/{id}/variantes/{varianteID}
Renomear o braço e/ou ligar a rota própria da página-variante
Onde é usada: tela de A/B.
Efeitos: uma escrita; aceito com o teste rodando.
Parâmetros: id (path, obrigatório); varianteID (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes/varianteID_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/paginas/{id}/variantes/{varianteID}
Desvincular a página do braço (ela continua existindo)
Onde é usada: tela de A/B.
Efeitos: escritas atômicas (ver `repo.Desvincular`): os pesos que ficam renormalizam; sobrando uma página, o teste encerra e ela fica na URL. Aceito com o teste rodando.
Parâmetros: id (path, obrigatório); varianteID (path, obrigatório)
Respostas: 200 desvinculada; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes/varianteID_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/paginas/{id}/versoes
Salvar uma nova versão (auto-save do editor)
Onde é usada: botão salvar do editor.
Efeitos: cria uma versão.
Parâmetros: id (path, obrigatório)
Respostas: 201 salva; 401 Sem sessão / sem tenant na sessão.; 403 conteúdo privilegiado (html) sem nível; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 422 template fora do contrato; v2 responde `codigo` + `caminho` do nó; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/versoes' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/paginas/ab-vinculos
Páginas da conta em teste A/B não encerrado (selo da lista)
Onde é usada: lista de páginas do painel.
Efeitos: uma leitura sob o tenant da sessão.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/paginas/ab-vinculos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/paginas/arquivadas
Listar as páginas arquivadas da conta (lixeira)
Onde é usada: aba "Arquivadas" da lista de páginas. Sessão OU chave `pages:read`.
Efeitos: uma leitura. O tenant sai SEMPRE do contexto verificado.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X GET 'https://api.pages.asender.net/v1/paginas/arquivadas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/paginas/importar
Importar um arquivo exportado, copiando a mídia para a conta
Onde é usada: "Importar template" da galeria de novo-template; reutiliza o mesmo serviço que o CLI de importação.
Efeitos: downloads de terceiros (com SSRF), arquivos e linhas na galeria, uma página e uma versão. NUNCA publica. # Falha de mídia não falha a importação Um ativo que não copia mantém a URL original e aparece no relatório; o painel oferece "tentar copiar de novo" (`RecopiarMidias`).
Respostas: 201 criada; o relatório diz o que foi copiado; 400 corpo inválido (campo desconhecido; 401 Sem sessão / sem tenant na sessão.; 403 conteúdo privilegiado (html) sem nível; 409 já existe página nesse endereço (checado antes de copiar); 422 título/template ausente, endereço inválido, SEO inválido ou template fora do contrato; 429 Escritas demais por esta chave (teto por minuto: 60 nas escritas de `pages:write`, 20 nas de `pages:publish`). Header `Retry-After: 60`.; 500 não consegui preparar a importação (por exemplo, conferir os formulários); 503 Não foi possível validar a chave agora (core fora do ar). Tente de novo.

curl -X POST 'https://api.pages.asender.net/v1/paginas/importar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/paginas/lote
Ação em massa sobre páginas (publicar, despublicar, duplicar, mudar domínio, arquivar)
Onde é usada: barra de ações em massa da lista de páginas.
Entradas: corpo JSON (campos desconhecidos recusados). O tenant vem só do contexto autenticado; cada id é resolvido DENTRO do tenant (RLS + filtro), e id de outra conta é reportado como `nao_encontrada` — nunca confirma existência.
Saídas: 200 com `{lote_id, acao, simulado, total, ok, puladas, erros, resultados[]}`; 400/422 no pedido malformado; 429 acima do ritmo.
Efeitos: escreve conforme a ação; um log `auditoria` por página com `lote_id`/`trace_id`, conta e usuário. Idempotente: publicar o que já está no ar e despublicar o que já está fora são `ok` com `sem_mudanca`. Sem tudo-ou-nada.
Respostas: 200 processado; veja `resultados` página a página; 400 corpo inválido (campo desconhecido; 401 Sem sessão / sem tenant na sessão.; 403 A chave não tem o escopo exigido pela rota (ou a rota não aceita chave). Ex.: `{"erro":"a chave não tem o escopo forms:write"}`.; 422 ação inválida, 0 ou mais de 100 ids, política de rascunho inválida ou `dominio_id` ausente em mudar_dominio; 429 acima de 12 chamadas por minuto na conta; 503 ações em massa indisponíveis (sem banco)

curl -X POST 'https://api.pages.asender.net/v1/paginas/lote' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/pixels
Listar pixels
Onde é usada: a tela de leads da ferramenta de Páginas/Formulários.
Efeitos: uma consulta; uma abertura de AES-GCM por linha; um registro de acesso a PII no log. Devolve `{"envios": [...], "proximo_cursor": ""}` — cursor vazio significa que acabou. A alternativa (omitir o campo no fim) obrigaria o cliente a distinguir ausente de vazio, e é o tipo de sutileza que vira laço infinito na tela.
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/pixels' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/pixels
Criar pixel (devolve o snippet com a credencial)
Onde é usada: tela de pixels.
Efeitos: uma escrita.
Respostas: 201 criado; 401 Sem sessão / credencial ausente ou inválida.; 422 nome inválido

curl -X POST 'https://api.pages.asender.net/v1/pixels' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/pixels/{id}
Obter um pixel
Onde é usada: tela de detalhe do pixel.
Efeitos: uma leitura.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.; 404 não encontrado

curl -X GET 'https://api.pages.asender.net/v1/pixels/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/pixels/{id}
Editar um pixel
Onde é usada: tela de detalhe.
Efeitos: uma escrita. PATCH parcial de verdade: campo ausente não é tocado. Sem isso, editar só o nome DESATIVARIA o pixel — e a coleta pararia sem ninguém ter pedido.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.; 404 não encontrado; 422 informe `nome` e/ou `ativo`

curl -X PATCH 'https://api.pages.asender.net/v1/pixels/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/pixels/{id}
Apagar um pixel
Onde é usada: tela de detalhe.
Efeitos: uma escrita; a coleta daquele pixel para.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagado; 401 Sem sessão / credencial ausente ou inválida.; 404 não encontrado

curl -X DELETE 'https://api.pages.asender.net/v1/pixels/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/pixels/{id}/conversions
Listar conversões do pixel
Onde é usada: tela de detalhe.
Efeitos: uma leitura.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/pixels/id_AQUI/conversions' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/pixels/{id}/conversions
Criar conversão
Onde é usada: tela de detalhe.
Efeitos: uma escrita.
Parâmetros: id (path, obrigatório)
Respostas: 201 criada; 401 Sem sessão / credencial ausente ou inválida.; 409 nome já em uso; 422 nome inválido

curl -X POST 'https://api.pages.asender.net/v1/pixels/id_AQUI/conversions' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /v1/pixels/{id}/conversions/{cid}
Editar conversão
Onde é usada: tela de detalhe.
Efeitos: uma escrita.
Parâmetros: id (path, obrigatório); cid (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.; 404 não encontrada; 422 informe nome, tipo e/ou seletor

curl -X PATCH 'https://api.pages.asender.net/v1/pixels/id_AQUI/conversions/cid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/pixels/{id}/conversions/{cid}
Apagar conversão
Onde é usada: tela de detalhe.
Efeitos: uma escrita.
Parâmetros: id (path, obrigatório); cid (path, obrigatório)
Respostas: 204 apagada; 401 Sem sessão / credencial ausente ou inválida.; 404 não encontrada

curl -X DELETE 'https://api.pages.asender.net/v1/pixels/id_AQUI/conversions/cid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/pixels/{id}/domains
Listar as origens autorizadas do pixel
Onde é usada: tela de detalhe.
Efeitos: uma leitura.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/pixels/id_AQUI/domains' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/pixels/{id}/domains
Autorizar uma origem para o pixel
Onde é usada: tela de detalhe.
Efeitos: uma escrita — e, a partir dela, o `/collect` ecoa CORS para aquele host.
Parâmetros: id (path, obrigatório)
Respostas: 201 adicionado; 401 Sem sessão / credencial ausente ou inválida.; 409 host já na lista

curl -X POST 'https://api.pages.asender.net/v1/pixels/id_AQUI/domains' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /v1/pixels/{id}/domains/{domainId}
Trocar uma origem autorizada
Onde é usada: tela de detalhe.
Efeitos: uma escrita.
Parâmetros: id (path, obrigatório); domainId (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / credencial ausente ou inválida.; 404 não encontrado

curl -X PATCH 'https://api.pages.asender.net/v1/pixels/id_AQUI/domains/domainId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/pixels/{id}/domains/{domainId}
Remover uma origem autorizada
Onde é usada: tela de detalhe.
Efeitos: uma escrita — a origem para de coletar na hora.
Parâmetros: id (path, obrigatório); domainId (path, obrigatório)
Respostas: 204 removido; 401 Sem sessão / credencial ausente ou inválida.; 404 não encontrado

curl -X DELETE 'https://api.pages.asender.net/v1/pixels/id_AQUI/domains/domainId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/public/midias/{id}
Servir uma imagem publicada (anônimo)
Onde é usada: a tag `<img>` de uma landing publicada.
Efeitos: abre e transmite o arquivo. # Sem sessão, e por isso com cuidado extra O id é o único parâmetro, e ele é resolvido no BANCO antes de tocar o disco: o caminho do arquivo nunca é montado com o que veio da URL. Path traversal não tem por onde entrar — e o `armazenamento` recusa id fora do formato de qualquer jeito, como segunda linha. # `X-Content-Type-Options: nosniff` é obrigatório aqui O tipo é o DETECTADO no upload, e a allowlist só tem imagem. Sem `nosniff`, o navegador pode reinterpretar o conteúdo e executar como outra coisa — e a allowlist de tipos perderia o sentido no último metro.
Parâmetros: id (path, obrigatório)
Respostas: 200 os bytes da imagem; 404 mídia não encontrada

curl -X GET 'https://api.pages.asender.net/v1/public/midias/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/public/midias/{id}/w/{largura}
Servir uma variante redimensionada da imagem (anônimo)
Onde é usada: o `srcset` do `<img>` de uma landing publicada (renderizador do runtime, imagens_v2.go).
Efeitos: uma leitura no banco; leitura do disco; no primeiro pedido, um encode e uma escrita no disco. Largura fora da allowlist é 404 ANTES de qualquer acesso ao banco ou ao disco: é o que impede o moedor de CPU (ver `midia.Larguras`). Tudo o que dá errado DEPOIS disso (tipo sem variante, imagem acima do teto, falha do encoder) serve o ORIGINAL — a imagem da landing nunca quebra por causa da otimização.
Parâmetros: id (path, obrigatório); largura (path, obrigatório); Accept (header)
Respostas: 200 os bytes da variante (ou do original; 404 largura fora da allowlist

curl -X GET 'https://api.pages.asender.net/v1/public/midias/id_AQUI/w/largura_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/redirects
Listar links curtos
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/redirects' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/redirects
Criar link curto
Onde é usada: tela de domínios.
Efeitos: uma escrita. # O domínio nasce NÃO verificado E é isso que impede o pior desfecho do produto: sem a prova de DNS, qualquer conta declararia `banco.com.br` e passaria a receber certificado TLS para esse nome — servindo uma página de captura no domínio de outra pessoa, com cadeado verde.
Respostas: 201 criado; 401 Sem sessão / sem tenant na sessão.; 409 slug já em uso; 422 destino/slug inválidos

curl -X POST 'https://api.pages.asender.net/v1/redirects' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/redirects/{id}
Obter um link curto
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X GET 'https://api.pages.asender.net/v1/redirects/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /v1/redirects/{id}
Atualizar um link curto
Onde é usada: edição.
Efeitos: escreve a linha.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 slug já em uso

curl -X PUT 'https://api.pages.asender.net/v1/redirects/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/redirects/{id}
Apagar um link curto
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X DELETE 'https://api.pages.asender.net/v1/redirects/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/redirects/{id}/cliques
Contagem de cliques do link
Onde é usada: relatório da tela de links curtos.
Efeitos: uma leitura. Devolve o CONTADOR, e não uma lista de eventos: a pergunta é sempre "quantos", nunca "quais". Uma linha por clique transformaria o caminho mais quente do redirect num INSERT por requisição.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X GET 'https://api.pages.asender.net/v1/redirects/id_AQUI/cliques' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/relatorios/visoes
Listar as visões salvas da conta
Saídas: 200 `{itens, proximo_cursor}` ("" = fim); 422 filtro inválido (cursor, limite, de/ate fora de RFC3339); 500 falha de leitura.
Efeitos: só leitura.
Respostas: 200 ok; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/relatorios/visoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/relatorios/visoes
Salvar o recorte atual como visão
Onde é usada: tela de domínios.
Efeitos: uma escrita. # O domínio nasce NÃO verificado E é isso que impede o pior desfecho do produto: sem a prova de DNS, qualquer conta declararia `banco.com.br` e passaria a receber certificado TLS para esse nome — servindo uma página de captura no domínio de outra pessoa, com cadeado verde.
Respostas: 201 criada; 400 corpo inválido (inclui campo desconhecido, ex. tenant_id); 401 Sem sessão / sem tenant na sessão.; 409 já existe visão com esse nome (sem diferenciar maiúscula); 422 recorte inválido, ou a conta já tem 50 visões

curl -X POST 'https://api.pages.asender.net/v1/relatorios/visoes' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PUT /v1/relatorios/visoes/{id}
Atualizar uma visão
Onde é usada: edição.
Efeitos: escreve a linha.
Parâmetros: id (path, obrigatório)
Respostas: 200 atualizada; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 404 não existe — ou é de outra conta (mesma resposta); 409 nome repetido; 422 recorte inválido

curl -X PUT 'https://api.pages.asender.net/v1/relatorios/visoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/relatorios/visoes/{id}
Apagar uma visão
Onde é usada: tela de domínios.
Efeitos: uma escrita. Apagar TIRA a autorização de TLS, e é o único caminho para isso — de propósito: um domínio verificado que pudesse ser "desverificado" por outro caminho sairia do ar sem ninguém entender por quê.
Parâmetros: id (path, obrigatório)
Respostas: 204 apagada; 401 Sem sessão / sem tenant na sessão.; 404 não existe — ou é de outra conta (mesma resposta)

curl -X DELETE 'https://api.pages.asender.net/v1/relatorios/visoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/replay/sessions
Listar as sessões gravadas
Onde é usada: tela de replay.
Efeitos: uma leitura.
Parâmetros: limite (query)
Respostas: 200 ok; 400 limite inválido; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/replay/sessions' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/replay/sessions/{id}/events
Eventos de uma jornada gravada
Onde é usada: player da tela de replay.
Efeitos: uma leitura. Sessão de outra conta responde lista VAZIA, e não 404: o id é opaco e gerado no browser, e distinguir "não existe" de "não é sua" transformaria a rota num oráculo de existência de sessão alheia.
Parâmetros: id (path, obrigatório)
Respostas: 200 ok; 400 sessão inválida; 401 Sem sessão / credencial ausente ou inválida.

curl -X GET 'https://api.pages.asender.net/v1/replay/sessions/id_AQUI/events' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/resumo
Resumo da ferramenta para o hub e a home (contrato comum de resumo).
Onde é usada: tela de A/B do painel.
Efeitos: uma leitura. Página SEM experimento responde 200 com o corpo vazio de variantes, e não 404: "esta página não tem teste" é uma resposta sobre o mundo, e a tela precisa dela para mostrar o botão de criar. 404 mandaria a tela tratar o caso normal como erro.
Parâmetros: periodo (query)
Respostas: 200 o resumo da ferramenta `pages`.; 400 Parâmetro de query fora do conjunto aceito.; 401 Sem sessão / sem tenant na sessão.; 403 membro da conta sem acesso a esta ferramenta.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).

curl -X GET 'https://api.pages.asender.net/v1/resumo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/subdominios-gratis
Reservar um subdomínio grátis
Onde é usada: tela de domínios.
Efeitos: uma escrita. # O domínio nasce NÃO verificado E é isso que impede o pior desfecho do produto: sem a prova de DNS, qualquer conta declararia `banco.com.br` e passaria a receber certificado TLS para esse nome — servindo uma página de captura no domínio de outra pessoa, com cadeado verde.
Respostas: 201 reservado; 400 corpo inválido; 401 Sem sessão / sem tenant na sessão.; 402 cota do plano esgotada; 409 nome em uso (ou em quarentena); 422 rótulo recusado (com `motivo`); 429 reservas demais na última hora; 503 plataforma indisponível para conferir o plano (fail-closed)

curl -X POST 'https://api.pages.asender.net/v1/subdominios-gratis' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/subdominios-gratis/{id}/trocar
Trocar o nome de um subdomínio grátis (páginas e links vão junto)
Onde é usada: ação "trocar nome" do bloco "Domínio grátis".
Efeitos: uma escrita (apaga o antigo, cria o novo, move páginas e links).
Parâmetros: id (path, obrigatório)
Respostas: 200 trocado; 401 Sem sessão / sem tenant na sessão.; 404 Recurso inexistente ou fora do escopo da sessão (não revela existência em outra conta).; 409 nome em uso; 422 rótulo recusado; 429 trocas demais na última hora

curl -X POST 'https://api.pages.asender.net/v1/subdominios-gratis/id_AQUI/trocar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/subdominios-gratis/bases
Listar as bases em que um subdomínio grátis pode ser reservado
Onde é usada: o seletor de base do bloco "Domínio grátis" (aparece só se há >1).
Respostas: 200 bases e a padrão; 401 Sem sessão / sem tenant na sessão.

curl -X GET 'https://api.pages.asender.net/v1/subdominios-gratis/bases' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/subdominios-gratis/disponivel
Conferir se um nome grátis (<rotulo>.<base>) pode ser reservado
Onde é usada: o campo "domínio grátis" da tela, enquanto a pessoa digita.
Efeitos: no máximo uma leitura. 429 acima de 30 consultas/min por conta — sem teto, a rota vira enumerador de quais nomes existem na plataforma.
Parâmetros: rotulo (query, obrigatório); base (query)
Respostas: 200 resposta (disponível ou o motivo); 401 Sem sessão / sem tenant na sessão.; 422 base desconhecida (`motivo: base_desconhecida`); 429 consultas demais

curl -X GET 'https://api.pages.asender.net/v1/subdominios-gratis/disponivel' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /version
nome do serviço, versão e o commit que gerou o binário.
Onde é usada: rota pública, usada por ops e por quem investiga incidente.
Efeitos: escreve JSON na resposta. # Por que ela é PÚBLICA, e o que ela não conta A primeira pergunta de todo incidente é "que versão está no ar?" — e ela tem de ser respondível sem credencial, porque quem investiga muitas vezes ainda não tem uma. O que sai é o que já está no `docker inspect` de quem tem acesso ao host: nome, versão e commit. Nunca configuração, nunca dependência, nunca endereço interno — isso é topologia, e topologia é do console de plataforma. A versão vem de LDFLAGS no build, e o default é `dev`: um binário sem carimbo diz `dev` em vez de mentir uma versão que ninguém emitiu.

curl -X GET 'https://api.pages.asender.net/version' \
  -H 'Authorization: Bearer SEU_TOKEN'



==============================================================================
# Plataforma  (https://api.asender.net)
==============================================================================

# Platform API

A API da **plataforma** Asender: contas (tenants) e sub-contas, membros,
convites, API keys, plano e a superfície pública de mensageria por API key. É o
que atravessa as ferramentas — a identidade e a conta são compartilhadas; cada
produto (Mail, CRM, Páginas) tem a sua própria API num endereço próprio.

- **Base URL:** `https://api.asender.net`
- **Duas superfícies, dois modos de auth:**
  - **`/v1/*`** — API pública do cliente, autenticada por **API key** e com
    **rate limit**. É a que uma integração de máquina usa.
  - **`/api/*`** — API do painel, autenticada por **sessão (OIDC/cookie)**. É a
    que o front do painel usa em nome do usuário logado.
- **Formato:** JSON. Os envelopes seguem o estilo SES (chaves `PascalCase`).
- **Envelope de erro desta API:** `{ "Error": { "Type", "Code", "Message", "Details" }, "RequestId" }`.
  A Mail API (`api.mail.asender.net`) usa outro, mais simples: `{ "error", "message" }`.
  Não trate os dois com o mesmo parser — veja as
  [Convenções](https://developers.asender.net/guias/convencoes.html#dois-envelopes-de-erro).
- **Rota que não existe aqui:** `404` e `405` em `/v1/*` também vêm no envelope
  (`Code` `NotFound` / `MethodNotAllowed`), com uma dica quando o caminho é de
  outra API (por exemplo `POST /v1/emails` é da Mail API; `/v1/dominios` é da API de Páginas).

## Autenticação

### `/v1/*` — API key ou token de app

A superfície pública de máquina aceita **duas credenciais**, sempre em
`Authorization: Bearer`:

| credencial | formato | quando usar |
| --- | --- | --- |
| **API key** (chave de servidor) | `sk_live_…` ou `sk_test_…` | integração da **sua própria conta**, de servidor para servidor. Envia mensagens e lê dados. Veja o [guia de chaves de API](https://developers.asender.net/guias/chaves-de-api.html) |
| **Token de app** (OAuth 2.1) | JWT emitido por `auth.asender.net` | um app **seu ou de terceiro** que age em nome de um usuário, na conta que ele escolheu ("Entrar com Asender"). **Só leitura** (veja os escopos abaixo). Veja o [guia Entrar com Asender](https://developers.asender.net/guias/entrar-com-asender.html) |

```
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
```

O `tenant_id` vem da credencial, nunca de parâmetro, header ou corpo. Esta
superfície é **rate-limited** (ver abaixo).

Só `Authorization: Bearer` é aceito. `X-Api-Key` e `?api_key=` foram removidos
(2026-10-07) e respondem `401`.

**`sk_live_` e `sk_test_`.** O prefixo registra o **modo** da chave, escolhido na
criação (o padrão é `live`). Hoje a única diferença é o rótulo: o modo aparece no
painel e nos [logs](#logs-de-requisicoes-get-v1-logs) (filtro `mode`), o que ajuda
a separar tráfego de teste do de produção. **Não existe sandbox**: uma chave
`sk_test_` autentica, tem os mesmos escopos e o mesmo rate limit, e a API não trata
o envio feito com ela de forma diferente. Para testar sem entregar a ninguém, use
destinatários seus. Um sandbox de verdade é **planejado**.

**Chave de servidor não vai ao navegador.** Pedido com `Origin` ou `Sec-Fetch-*`
(sinais de navegador) às rotas de envio de push, WhatsApp, Telegram e canais não
oficiais é recusado com `403 ServerKeyInBrowser`. Para registrar web push a partir
do site existe a chave pública `pk_push_…`, que só abre
[`POST /v1/push/site/devices`](#push-e-dispositivos).

**Servidor MCP.** Assistentes de IA acessam estes mesmos dados pelo servidor MCP
em `https://api.asender.net/mcp` (em implantação) — veja o
[guia MCP](https://developers.asender.net/guias/mcp.html).

### `/api/*` — sessão do usuário

A superfície do painel. O usuário autentica no Authorization Server
(`https://auth.asender.net`, OAuth 2.1 + PKCE) e a sessão trafega em cookie
`HttpOnly` — o token nunca vai para o navegador em JavaScript. O `tenant` da
requisição é resolvido **da sessão**; o header `X-Asender-Tenant` do front só é
aceito depois de provada a pertinência do usuário àquela conta. Conta alheia
responde **404**, nunca 403 (a existência da conta é informação).

### Como obter e usar uma API key

No painel, em **Administração → Chaves de API**
(`https://admin.asender.net/t/<conta>/api-keys`): crie a chave, escolha os
escopos e copie o segredo, que aparece **uma única vez**. Passo a passo no
[guia de chaves de API](https://developers.asender.net/guias/chaves-de-api.html).

O painel usa a Platform API na superfície de sessão, que também serve a quem
automatiza a emissão:

```bash
# Criar (sessão do usuário; devolve a chave em claro UMA vez)
curl -X POST 'https://api.asender.net/api/tenants/TENANT_ID/api-keys' \
  -H 'Content-Type: application/json' \
  --cookie 'asender_session=...' \
  -d '{ "name": "integração-2fa", "scopes": ["email:send"], "mode": "live" }'

# `scopes` é obrigatório (veja a tabela de escopos); sem ele a emissão responde 400.
# `mode` é opcional: "live" (padrão) ou "test".

# Listar / revogar
curl 'https://api.asender.net/api/tenants/TENANT_ID/api-keys' --cookie '...'
curl -X DELETE 'https://api.asender.net/api/tenants/TENANT_ID/api-keys/KEY_ID' --cookie '...'
```

A chave emitida aqui autentica as superfícies `/v1/*` desta API **e** as APIs de
produto (por exemplo `POST https://api.mail.asender.net/v1/emails`). Guarde-a no
servidor — nunca no bundle do navegador.

## Rate limits (`/v1/*`)

A superfície pública é limitada por **principal**, por janela fixa de 1 segundo:
a **chave** (cada `sk_…` tem o seu balde) ou, para token de app, o par
**app × conta** (um app barulhento numa conta não consome a cota do mesmo app em
outra). O teto padrão é de **100 requisições por segundo**. Toda resposta traz o
estado do balde:

| header | significado |
| --- | --- |
| `X-RateLimit-Limit` | teto de requisições na janela |
| `X-RateLimit-Remaining` | quantas restam na janela atual |
| `X-RateLimit-Reset` | epoch (segundos) em que a janela reabre |
| `Retry-After` | (só no 429) segundos até poder tentar de novo, no mínimo 1 |

Ao estourar, a resposta é **429**:

```json
{ "Error": { "Type": "Sender", "Code": "Throttling", "Message": "Rate limit exceeded." }, "RequestId": "req_…" }
```

Em `429`, espere o `Retry-After`; sem ele, use backoff exponencial com jitter.
Se o limitador estiver indisponível, a API **não bloqueia** (o controle é de
abuso, não de autorização): trate os headers como informativos, não como garantia.

`GET /v1/logs` tem um teto próprio, menor, de **5 req/s** por chave, somado ao
limite geral.

> A superfície de sessão (`/api/auth/*`) tem um teto **por IP** próprio, contra
> brute-force de login/2FA/recuperação. Não é um limite de integração — é uma
> defesa da borda de autenticação.

## Erros

Todos os erros usam o envelope estilo SES:

```json
{
  "Error": {
    "Type": "Sender",
    "Code": "ValidationError",
    "Message": "One or more fields failed validation.",
    "Details": { "Destination.ToAddresses": "must contain at least one address" }
  },
  "RequestId": "req_a1b2c3"
}
```

- `Type` é `Sender` para 4xx (o cliente errou) e `Receiver` para 5xx (o serviço
  falhou).
- `Code` é a classe estável (`ValidationError`, `AuthorizationError`,
  `Throttling`, `InternalError`, …).
- `Details` só aparece em validação, com o campo e o motivo.
- `RequestId` acompanha o pedido no rastreamento — cite-o ao abrir suporte.

| código HTTP | `Code` típico | quando |
| --- | --- | --- |
| 400 | `ValidationError` | corpo inválido; `Details` traz os campos. JSON com campo que a API não conhece nomeia o campo na mensagem (`unknown field "X"`) |
| 401 | `AuthorizationError` | credencial ausente/ inválida (chave ou sessão) |
| 403 | `InsufficientScope` | a API key não tem o escopo da rota; a mensagem nomeia o escopo exigido (ex.: `API key lacks the required scope: sms:send.`) — ver [Escopos da API key](#escopos-da-api-key) |
| 403 | `ServerKeyInBrowser` | chave `sk_…` usada de um navegador nas rotas de push, WhatsApp, Telegram e canais não oficiais — chame do seu servidor |
| 404 | `NotFound` | recurso fora do escopo do principal (inclui conta alheia) |
| 409 | `IdempotencyConflict` | a `Idempotency-Key` já foi usada com um corpo diferente — ver [Idempotência](#idempotencia-idempotency-key) |
| 422 | `ValidationError` | o corpo é válido, mas o pedido não tem destino possível (ninguém sobra após opt-out, aparelho inexistente) ou a `Idempotency-Key` é malformada |
| 422 | `RemetenteNaoVerificado` | o `Source` do e-mail não é de um domínio verificado da conta — ver [Remetente](#remetente-so-de-dominio-verificado) |
| 429 | `Throttling` | rate limit da chave (ver `X-RateLimit-*`) |
| 503 | `VerificacaoIndisponivel` | não deu para confirmar o domínio do `Source` agora; nada foi enviado — tente de novo (`Retry-After`) |
| 502 | `InternalError` | o serviço de origem falhou ao responder (conta, uso) |
| 5xx | `InternalError` | falha do serviço ou de um upstream |

O corpo é lido com **contrato estrito**: campo desconhecido é recusado com 400.

## Paginação

As coleções da plataforma paginam por **cursor** (`NextCursor` / `HasMore`),
nunca por offset — offset pula ou repete item quando o dado muda entre chamadas.
Passe o `NextCursor` de volta para a próxima página.

As rotas de **dados** (`/v1/leads`, `/v1/campaigns` etc.) e os logs usam
`snake_case` (`next_cursor`, `has_more`) e `limit` de 1 a 200; veja
[Dados](#dados-leitura-do-que-a-conta-tem).

## Superfície da API

### `/v1/*` — pública (API key ou token de app)

Todas as rotas abaixo ficam em `https://api.asender.net`, exigem **um** escopo e
respondem no envelope de erro desta API. Rota que não está nesta lista não existe
para chave (`403`, nunca "liberada por omissão").

| grupo | rotas | escopo |
| --- | --- | --- |
| **E-mail** | `POST /v1/emails/send`, `POST /v1/emails/batch`, `GET /v1/senders` | `email:send` |
| | `GET /v1/emails`, `GET /v1/emails/{id}` | `email:read` |
| **SMS** | `POST /v1/sms/send` | `sms:send` |
| **WhatsApp** (oficial, Meta) | `POST /v1/whatsapp/send` | `whatsapp:send` |
| **Canais não oficiais** | `POST /v1/telegram/send` | `telegram:send` |
| | `POST /v1/whatsweb/send` | `whatsweb:send` |
| | `POST /v1/telegramconta/send` | `telegramconta:send` |
| **Push** | `POST /v1/push/send` | `push:send` |
| | `GET`/`POST /v1/push/devices` | `push:devices` |
| | `POST /v1/push/site/devices` (navegador) | chave pública `pk_push_…` |
| **Conta** | `GET /v1/account` | qualquer chave válida (token de app: `account:read`) |
| | `GET /v1/account/usage` | `account:read` |
| | `GET /v1/me` | só token de app, escopo `openid` |
| **Logs** | `GET /v1/logs`, `GET /v1/logs/{id}` | `logs:read` |
| **Dados** (leitura) | `GET /v1/leads`, `/v1/leads/{id}` | `leads:read` |
| **Leads** (escrita) | `POST /v1/leads`, `PATCH /v1/leads/{id}` | `leads:write` (só chave) |
| | `GET /v1/forms`, `/v1/forms/{id}/submissions` | `forms:read` |
| | `GET /v1/conversions` | `conversions:read` |
| | `GET /v1/campaigns`, `/v1/campaigns/{id}`, `/v1/campaigns/{id}/report`, `/v1/reports/email/{overview,timeseries,top-emails,domains}` | `campaigns:read` |
| | `GET /v1/messaging/{sms,whatsapp,push}/messages`, `/v1/messaging/{sms,whatsapp,push}/reports/overview` | `messaging:read` |
| | `GET /v1/analytics/{overview,breakdown,timeseries,forms}` | `analytics:read` |
| | `GET /v1/conversations`, `/v1/conversations/{id}/messages` | `conversations:read` |
| | `GET /v1/journeys`, `/v1/journeys/{id}` | `journeys:read` |
| | `GET`/`POST /v1/webhooks`, `GET`/`PATCH`/`DELETE /v1/webhooks/{id}`, `POST /v1/webhooks/{id}/test` | `webhooks:manage` |
| **DNS** | `GET /v1/dns/zones`, `GET /v1/dns/zones/{zona}/records`, `GET /v1/dns/changes` | `dns:read` |
| | `POST /v1/dns/zones/{zona}/records`, `PATCH`/`DELETE /v1/dns/zones/{zona}/records/{rid}` | `dns:write` |

Os grupos são detalhados nas seções seguintes. As rotas de **dados** têm um
resumo [abaixo](#dados-leitura-do-que-a-conta-tem) e o detalhe campo a campo no
[guia Entrar com Asender](https://developers.asender.net/guias/entrar-com-asender.html)
(seção 9) e na referência OpenAPI.

#### Escopos da API key

Cada rota exige **um** escopo; a chave que não o tem recebe `403
InsufficientScope`. Uma chave de e-mail (`email:send,email:read`) **não** envia
SMS, push nem WhatsApp. Rota sem escopo declarado também é recusada. Existem
**28 escopos**; a coluna "token de app" diz quais um app OAuth também pode exercer
(só leitura; `*:send`, `mail:admin` e `*:write` são exclusivos de chave).

| escopo | libera | token de app |
| --- | --- | --- |
| `email:send` | `POST /v1/emails/send`, `POST /v1/emails/batch`, `GET /v1/senders` | não |
| `email:read` | `GET /v1/emails`, `GET /v1/emails/{id}` | sim |
| `sms:send` | `POST /v1/sms/send` | não |
| `push:send` | `POST /v1/push/send` | não |
| `push:devices` | `GET`/`POST /v1/push/devices` | não |
| `whatsapp:send` | `POST /v1/whatsapp/send` | não |
| `telegram:send` | `POST /v1/telegram/send` (bot do Telegram) | não |
| `whatsweb:send` | `POST /v1/whatsweb/send` (WhatsApp por sessão, canal não oficial) | não |
| `telegramconta:send` | `POST /v1/telegramconta/send` (conta pessoal do Telegram, canal não oficial) | não |
| `account:read` | `GET /v1/account/usage` | sim |
| `logs:read` | `GET /v1/logs`, `GET /v1/logs/{id}` (log das requisições da própria conta) | sim |
| `mail:admin` | administração de domínios e caixas do e-mail da conta, na API do mail (`GET /orgs`, `POST`/`GET /orgs/{orgID}/domains`, verificação de domínio, `POST`/`GET /domains/{id}/mailboxes`…). Não lê mensagens (`email:read`) nem envia (`email:send`) | não |
| `forms:read` | `GET /v1/forms` e `GET /v1/forms/{id}/submissions` em `api.asender.net`, e a leitura de formulários em `api.pages.asender.net` | sim |
| `forms:write` | criar, editar e apagar formulários e enviar leads (submissões), em `api.pages.asender.net` | não |
| `pages:read` | ler páginas, versões, rascunho, SEO, domínios e mídia, em `api.pages.asender.net` (não são rotas de `api.asender.net`) | não |
| `pages:write` | criar e editar páginas (versões, rascunho, SEO, importar, duplicar, mudar de domínio, mídia), em `api.pages.asender.net` | não |
| `pages:publish` | publicar e despublicar páginas (ação visível ao público; escopo separado do `pages:write`), em `api.pages.asender.net` | não |
| `leads:read` | `GET /v1/leads`, `GET /v1/leads/{id}` (contatos do CRM) | sim |
| `leads:write` | `POST /v1/leads`, `PATCH /v1/leads/{id}` (criar e atualizar contatos; não inclui leitura) | não |
| `conversions:read` | `GET /v1/conversions` | sim |
| `analytics:read` | `GET /v1/analytics/*` | sim |
| `campaigns:read` | `GET /v1/campaigns*`, `GET /v1/reports/email/*` | sim |
| `messaging:read` | `GET /v1/messaging/*` (SMS, WhatsApp e push) | sim |
| `conversations:read` | `GET /v1/conversations*` | sim |
| `journeys:read` | `GET /v1/journeys*` | sim |
| `webhooks:manage` | `/v1/webhooks*` (cadastro e teste de endpoints de webhook; o segredo `whsec_…` sai uma vez, no `POST`) | não |
| `dns:read` | `GET /v1/dns/zones`, `/v1/dns/zones/{zona}/records`, `/v1/dns/changes` (DNS da conta pela Cloudflare) | não |
| `dns:write` | `POST /v1/dns/zones/{zona}/records`, `PATCH`/`DELETE …/records/{rid}`; **não inclui leitura** | não |

`GET /v1/account` aceita qualquer chave válida. Emita chaves novas com os
escopos mínimos da integração (painel de chaves): **escopo é obrigatório** e só
vale o catálogo acima — a emissão sem escopos, ou com um valor fora do catálogo,
responde `400` com a lista válida. Uma chave sem escopo do catálogo recebe `403
InsufficientScope` em toda rota.

> **`leads:write`** vale para a chave de servidor (`POST /v1/leads`,
> `PATCH /v1/leads/{id}`, veja [Escrever leads](#escrever-leads)). **Token de app OAuth
> nunca recebe** esse escopo: o consentimento não o concede e as rotas respondem `403`.

**DNS (`/v1/dns/*`).** Só chave `sk_*` (app OAuth recebe `403`). A conexão com a Cloudflare
(o token) é feita por uma pessoa no painel, em **DNS**; a API não cria nem lê conexões. Campos e
erros em inglês; o tenant é o da chave. Controles de escrita: `?dry_run=1` devolve o plano sem
alterar nada; `X-Asender-Confirmar: <nome do registro>` é obrigatório no `DELETE` e em MX/SPF/DMARC
do apex (`428 ConfirmationRequired` sem ele); `Idempotency-Key` (24 h). Fora de produção toda
escrita responde `403 NonProductionBlocked`. Toda tentativa de escrita entra em `GET /v1/dns/changes`
com o `before`, para desfazer.

Exemplo — e-mail pela plataforma. **Serve para código de verificação/2FA, e-mail
transacional, lote e campanha**: aceita qualquer remetente de um domínio
**verificado** na conta, com o escopo `email:send` (não precisa criar caixa):

```bash
curl -X POST 'https://api.asender.net/v1/emails/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f7c1e2a-…' \
  -d '{
    "Source": "campanhas@empresa.com.br",
    "Destination": { "ToAddresses": ["cliente@exemplo.test"] },
    "Message": {
      "Subject": { "Data": "Novidades de setembro" },
      "Body": { "Html": { "Data": "<h1>Olá</h1>" } }
    }
  }'
```

Resposta `202`:

```json
{ "MessageId": "…", "MessageIds": ["…"], "Status": "queued", "ReusedIdempotency": false, "RequestId": "req_…" }
```

#### Remetente só de domínio verificado

O `Source` de `POST /v1/emails/send` e de cada item de `/v1/emails/batch` tem de
ser de um **domínio verificado nesta conta** (SPF e DKIM conferidos em
**Admin → Domínios**, `https://admin.asender.net/t/<conta>/dominios`). O e-mail
sai assinado com o DKIM do seu domínio.

Atenção: aqui basta o **domínio** estar verificado. Na Mail API
(`POST /v1/emails`) o endereço também precisa ser uma **caixa criada** no domínio.

Ver ou verificar o domínio por API: não existe `/v1/dominios` nesta API. Pelo
painel, em Admin → Domínios; por API, na Mail API com uma chave de escopo
`mail:admin`: `GET https://api.mail.asender.net/orgs`, `GET …/orgs/{id}/domains`
e `POST …/domains/{id}/verify`. (`/v1/dominios` existe só na
[API de Páginas](https://developers.asender.net/apis/pages.html), para domínios de sites.)

- Domínio não verificado (ou verificado em **outra** conta): **`422
  RemetenteNaoVerificado`**. A `Message` diz o domínio e traz o link para
  Domínios. **Nada é enfileirado nem cobrado.** No lote, o item sai com
  `Status: "failed"` e o mesmo `Code`/`Message`; os outros itens seguem.
- Verificação fora do ar: **`503 VerificacaoIndisponivel`** com `Retry-After`.
  Nada é enviado; repita o pedido (com a mesma `Idempotency-Key`).
- Se o domínio perder a verificação **depois** do `202` (DNS mudou antes do
  envio), a mensagem **não sai**: ela fica `failed` com o código
  `RemetenteNaoVerificado` (veja `GET /v1/emails/{id}`). Ela nunca é enviada
  com outro remetente.

```json
{
  "Error": {
    "Type": "Sender",
    "Code": "RemetenteNaoVerificado",
    "Message": "O domínio empresa.com.br não está verificado nesta conta (SPF e DKIM). Verifique o domínio em Admin → Domínios (https://admin.asender.net/t/acc_123/dominios), ou use um remetente de um domínio já verificado. Nada foi enviado."
  },
  "RequestId": "req_…"
}
```

> **Mudança de contrato (2026-10-02).** Até esta data, um `Source` de domínio
> não verificado era aceito com `202` e o e-mail saía com o remetente da
> plataforma (`no-reply@…`), com o seu endereço em `Reply-To`. Agora o pedido é
> **recusado** com `422 RemetenteNaoVerificado`. Se você integrava mandando um
> `Source` não verificado, verifique o domínio em Admin → Domínios ou troque o
> `Source` por um endereço de domínio verificado. Veja o
> [registro de mudanças](#registro-de-mudancas).

> **Qual e-mail usar?** Para **código de verificação/2FA (OTP) e e-mail transacional**,
> use `POST https://api.asender.net/v1/emails/send` (aqui): basta o domínio estar
> verificado. A [Mail API](https://developers.asender.net/apis/mail.html)
> (`POST https://api.mail.asender.net/v1/emails`) é para enviar **a partir de uma
> caixa corporativa que já existe**.
>
> | | `api.asender.net/v1/emails/send` | `api.mail.asender.net/v1/emails` |
> | --- | --- | --- |
> | corpo | `Source`, `Destination.ToAddresses`, `Message` (PascalCase) | `from`, `to[]`, `subject`, `text`/`html` (minúsculas) |
> | remetente | qualquer endereço de domínio **verificado** | **caixa existente** em domínio verificado |
> | sem a condição do remetente | `422 RemetenteNaoVerificado` | `422 CaixaRemetenteInexistente` |
> | escopo | `email:send` | `email:send` |
> | envelope de erro | `{ "Error": {…}, "RequestId" }` | `{ "error", "message" }` |

#### Descubra remetentes válidos (`GET /v1/senders`)

Antes de enviar, pergunte o que a chave pode usar como `from`. Escopo
`email:send` (o mesmo de quem envia); a conta é a da chave, não há parâmetro de
conta.

```bash
curl 'https://api.asender.net/v1/senders' -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx'
```

```json
{
  "Domains": [
    { "Name": "empresa.com.br", "Verified": true, "UsableFor": ["emails/send"], "DnsStatus": "ok" },
    { "Name": "novo.com.br", "Verified": false, "UsableFor": [], "DnsStatus": "pending" }
  ],
  "Mailboxes": [
    { "Address": "no-reply@empresa.com.br", "UsableFor": ["emails/send", "mail:/v1/emails"] },
    { "Address": "oi@novo.com.br", "UsableFor": ["mail:/v1/emails"] }
  ],
  "RequestId": "req_…"
}
```

- **Domínio não verificado é listado** (`Verified: false`, `UsableFor: []`) para
  você ver o que falta; usá-lo como `Source` dá `422 RemetenteNaoVerificado`.
- `DnsStatus` vem da verificação automática de DNS: `ok`, `pending` (esperando
  propagar), `outdated` (um registro mudou depois de verificado) ou `unknown`.
- Em `POST /v1/emails/send` qualquer endereço de um domínio com `emails/send`
  serve; as `Mailboxes` mostram as caixas que existem (exigidas só na Mail API).
- Só caixas **ativas** aparecem.
- Mail API fora do ar: `503 SendersUnavailable` com `Retry-After`; nunca uma
  lista parcial.

#### Logs de requisições (`GET /v1/logs`)

O log responde "o que a minha integração mandou e o que a API respondeu?". Cada
requisição feita **à API pública com uma chave da sua conta** vira um registro,
inclusive as recusadas (`400`, `403`, `429`). Escopo `logs:read`; a conta é a da
chave (não existe parâmetro de conta: um `tenant_id` na query é descartado).
Teto próprio de **5 req/s** por chave, somado ao limite geral da API.

**O que é gravado.** Método, caminho e padrão de rota, status, latência, chave
(`id` e nome) e modo (`live`/`test`), `Idempotency-Key`, código de erro do
envelope, ids de mensagem devolvidos pelo envio (`message_ids`), `request_id` e
`trace_id`. O detalhe traz também os corpos da requisição e da resposta,
**depois da redação** (abaixo).

**Redação.** Segredo não é gravado, em nenhum campo, em qualquer nível do JSON:
tokens de API (`sk_…`/`pk_…`), JWT, `Bearer …`, `Authorization`, senhas, códigos
de verificação (`code`, `otp`), PIN, CVV, números de cartão (com checagem de
Luhn) e CPF/CNPJ viram `[REDACTED]`. O **conteúdo** das mensagens (`html`,
`text`, `subject`, `body`, variáveis de template) vira um marcador
`[redacted len=<bytes> sha256=<16 hex>]`: dá para saber que existiu e conferir se
dois envios tinham o mesmo conteúdo, sem guardar o texto. **Destinatários**
(`to`, `cc`, `bcc`, `phone`…) aparecem mascarados (`c***@cliente.com.br`). Na
query só aparecem parâmetros conhecidos. Cada registro informa em
`redaction_version` qual conjunto de regras valeu. Corpos redigidos acima de
**16 KiB** são cortados (`request_body_truncated` / `response_body_truncated`).

**Retenção.** Os registros ficam guardados por tempo indeterminado; não há
rotina de expiração hoje. Um aviso antecipado precede qualquer mudança nisso.

**Filtros** (todos opcionais, combináveis): `status_class` (`2xx,3xx,4xx,5xx`),
`status`, `method`, `path` (padrão de rota exato, ex. `/v1/emails/send`),
`api_key_id` (vírgula para várias), `error_code`, `idempotency_key`,
`message_id`, `mode` (`live`/`test`), `since` e `until` (RFC 3339). Sem janela,
valem as últimas **24 h**; uma janela maior que **31 dias** é reduzida a 31 dias
antes de `until`.

**Paginação por cursor.** A lista vem do mais novo para o mais antigo, `limit`
de 1 a 100 (padrão 20). Enquanto `has_more` for `true`, repita a chamada com
`after=<next>`; `before=<cursor>` volta para os mais novos (`after` e `before`
juntos dão `400`). O cursor é opaco e assinado para a sua conta: alterado ou de
outra conta, dá `400`. (Esta rota usa `has_more`/`next` em `snake_case`, não
`HasMore`/`NextCursor`: o corpo vem do serviço de logs sem reescrita.)

```bash
# Falhas de envio das últimas 24 h
curl 'https://api.asender.net/v1/logs?status_class=4xx,5xx&path=/v1/emails/send&limit=20' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'

# Próxima página
curl 'https://api.asender.net/v1/logs?status_class=4xx,5xx&after=cur_eyJ0Ijoi…' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'
```

```json
{
  "object": "list",
  "has_more": true,
  "next": "cur_eyJ0Ijoi…",
  "data": [
    {
      "id": "log_3f9a1c0b2d4e5f60", "object": "log",
      "created_at": "2026-10-07T12:00:01Z",
      "method": "POST", "path": "/v1/emails/send", "route": "/v1/emails/send",
      "status": 422, "duration_ms": 38, "mode": "test",
      "api_key": { "id": "key_9", "name": "producao" },
      "idempotency_key": "pedido-1042", "error_code": "RemetenteNaoVerificado",
      "message_ids": [], "request_id": "req_abc123"
    }
  ]
}
```

**Do envio ao log, e de volta.** O `id` de mensagem que o envio devolve entra em
`message_ids`; para achar a requisição que criou uma mensagem, filtre por
`message_id`. Para investigar uma falha, abra o detalhe — a lista não traz corpos:

```bash
curl 'https://api.asender.net/v1/logs?message_id=msg_01HXYZ' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'

curl 'https://api.asender.net/v1/logs/log_3f9a1c0b2d4e5f60' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'
```

`request_body` e `response_body` do detalhe vêm redigidos; `null` quando a
requisição não tinha corpo.

**Erros.** `400 ValidationError` (parâmetro inválido, cursor adulterado, `after`
com `before`), `401`, `403 InsufficientScope` (chave sem `logs:read`; uma chave só
com `email:send` não lê logs), `404 NotFound` (id inexistente **ou de outra
conta**, com o mesmo corpo), `429`. Serviço de logs fora do ar: `503
ServiceUnavailable` com `Retry-After`; o resto da API continua funcionando. Os
`400`/`404` desta rota vêm no envelope do serviço de logs
(`{ "error": { "type", "code", "message" } }`, chaves em minúsculas), diferente
do `{ "Error": … }` do restante da API.

No painel, os mesmos dados (mais séries e resumo por rota e por código de erro)
ficam em `GET /api/tenants/{id}/logs`, `…/logs/{logId}`, `…/logs/series` e
`…/logs/resumo`, para quem é `owner` ou `admin` da conta.

#### Lote de e-mail (`POST /v1/emails/batch`)

Até **500 mensagens independentes** numa chamada, cada uma no mesmo formato de
`/v1/emails/send`, dentro da lista `Messages`. Escopo `email:send`. Cada item é
validado e enfileirado sozinho: **um item com erro não derruba os outros**, e o
resultado vem por índice.

```bash
curl -X POST 'https://api.asender.net/v1/emails/batch' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: lote-2026-10-20' \
  -d '{
    "Messages": [
      { "Source": "contato@empresa.com.br",
        "Destination": { "ToAddresses": ["ana@exemplo.test"] },
        "Message": { "Subject": { "Data": "Olá, Ana" }, "Body": { "Text": { "Data": "Seu pedido saiu." } } } },
      { "Source": "contato@empresa.com.br",
        "Destination": { "ToAddresses": ["bia@exemplo.test"] },
        "Message": { "Subject": { "Data": "Olá, Bia" }, "Body": { "Text": { "Data": "Seu pedido saiu." } } } }
    ]
  }'
```

Resposta `202`:

```json
{
  "Results": [
    { "Index": 0, "Status": "queued", "MessageId": "…", "MessageIds": ["…"], "ReusedIdempotency": false },
    { "Index": 1, "Status": "rejected", "Error": { "Code": "ValidationError", "Details": { "Destination.ToAddresses": "must contain at least one address" } } }
  ],
  "Count": 2
}
```

- `Status` do item: `queued` (aceito), `rejected` (falhou a validação) ou
  `failed` (o serviço recusou; por exemplo `RemetenteNaoVerificado`).
- Lista vazia ou com mais de 500 itens: `400 ValidationError`.
- O `202` quer dizer que **a requisição foi processada**, não que todos os itens
  foram aceitos: sempre confira `Status` por item.
- A `Idempotency-Key` do cabeçalho vale por item (`<chave>:<índice>`); repetir o
  lote inteiro com a mesma chave não reenvia os itens já aceitos.

#### WhatsApp (`POST /v1/whatsapp/send`)

Mesmo padrão do SMS: `202` quer dizer **enfileirado**, não entregue. Mande
**ou** `Body` (texto livre) **ou** `Template` (slug de um template aprovado pela
Meta e registrado na conta) com `Variables` posicionais.

```bash
# Abrir conversa: template aprovado
curl -X POST 'https://api.asender.net/v1/whatsapp/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1042-aviso' \
  -d '{ "To": ["+5511999990000"], "Template": "promo_outubro", "Variables": { "1": "Ana", "2": "10%" } }'
```

- **Janela de 24h.** Texto livre só chega se o destinatário escreveu para o seu
  número nas últimas 24h; fora disso a Meta recusa e a mensagem termina `failed`
  (`OutsideWindow`) — de forma assíncrona, depois do `202`. Para iniciar a
  conversa, use `Template`.
- **Template.** Slug inexistente na conta, ou `Variables` em número diferente do
  que o template exige: `422 ValidationError`, sem cobrança.
- **Opt-out.** Quem saiu do canal não recebe; a resposta traz `Suppressed` com a
  contagem. Se ninguém sobra, `422`.
- **Escopo da chave:** `whatsapp:send`. Chave de servidor usada de um navegador
  (`Origin`/`Sec-Fetch-*`) é recusada com `403 ServerKeyInBrowser`.
- **Credencial.** A conta precisa ter o WhatsApp (Meta Cloud API) configurado em
  Admin → WhatsApp; sem isso a mensagem fica `failed`.

#### SMS

`POST /v1/sms/send` responde `202` com **enfileirado**, não entregue. Corpo:
`To` (lista de números em E.164), `Body` (até 1600 caracteres), `From`, `Tags` e
`IdempotencyKey` opcionais. Escopo `sms:send`.

```bash
curl -X POST 'https://api.asender.net/v1/sms/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: codigo-1042' \
  -d '{ "To": ["+5511999990000"], "Body": "Seu código é 482910." }'
```

Resposta `202`: `{ "MessageId", "MessageIds", "Status": "queued", "ReusedIdempotency", "RequestId" }`.

#### Push e dispositivos

`POST /v1/push/send` responde `202` com **enfileirado**, não entregue. Escopo
`push:send`.

```bash
curl -X POST 'https://api.asender.net/v1/push/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: aviso-1042' \
  -d '{ "DeviceTokens": ["<token do aparelho registrado>"], "Notification": { "Title": "Pedido enviado", "Body": "Chega amanhã." } }'
```

- **Push exige `DeviceTokens`** (pelo menos um aparelho registrado em `POST
  /v1/push/devices`). **Envio por tópico não é suportado:** o campo `Topic` é
  recusado com `400 ValidationError` e `Details.Topic`, com ou sem tokens.
- Se nenhum token é um aparelho ativo da conta, ou ninguém sobra depois do
  opt-out, a resposta é `422 ValidationError` e nada é cobrado.
- Escopos: `push:send` para enviar, `push:devices` para o registro e a listagem.

**Registrar e listar aparelhos** (do **seu servidor**, com a chave `sk_…`, escopo
`push:devices`):

```bash
# Registrar (upsert: o mesmo token duas vezes não cria dois registros)
curl -X POST 'https://api.asender.net/v1/push/devices' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{ "Token": "<token FCM/APNs>", "Platform": "android", "UserRef": "cliente-77" }'

# Listar (paginação por cursor: Devices, NextCursor, HasMore; query limit e cursor)
curl 'https://api.asender.net/v1/push/devices?limit=50' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx'
```

`Platform` é `ios`, `android` ou `web`; para `web` mande `Endpoint`, `P256dh` e
`Auth` (do `PushSubscription.toJSON()` do navegador) em vez de `Token`.

**Registro direto do navegador (web push).** Nunca ponha a chave `sk_…` no site.
O site usa a **chave pública** `pk_push_…`, emitida no painel (tela de push,
junto do `manifest.json`, do service worker e do snippet já preenchidos) e
atrelada às **origens** do site que você declarou. Ela só abre uma rota:

```bash
curl -X POST 'https://api.asender.net/v1/push/site/devices?site_key=pk_push_xxxxxxxx' \
  -H 'Origin: https://www.seusite.com.br' \
  -H 'Content-Type: application/json' \
  -d '{ "Endpoint": "https://…", "P256dh": "…", "Auth": "…" }'
# 200 { "Status": "registered" }
```

Origem não declarada, chave adulterada ou plataforma diferente de `web` são
recusadas. A rota tem teto por IP (30 por minuto) e por chave (1200 por minuto).
A chave de site não é segredo, mas só vale para registrar inscrições. O guia do
[navegador](https://developers.asender.net/guias/navegador.html) mostra o snippet completo.

#### Canais não oficiais (Telegram e WhatsApp por sessão)

Três rotas de envio por canais que **não** são a API oficial da Meta. Todas
respondem `202` com `{ "MessageId", "Status": "queued" }` (enfileirado, não
entregue), aceitam `Idempotency-Key`, recusam chave de servidor vinda de navegador
(`403 ServerKeyInBrowser`) e respondem `503` com `Retry-After` se o serviço do
canal estiver fora. Cada uma tem o **seu escopo**, para você liberar só o que a
integração usa.

| rota | escopo | corpo | regra do canal |
| --- | --- | --- | --- |
| `POST /v1/telegram/send` | `telegram:send` | `ChatId` (texto ou inteiro), `Text` (até 4096), `BotId` opcional (`tgb_…`) | o destinatário precisa ter aberto o bot e enviado `/start`; senão `422 ChatNaoIniciado` |
| `POST /v1/whatsweb/send` | `whatsweb:send` | `To` (E.164, `+` e 8 a 15 dígitos), `Text` (até 4096), `SessionId` opcional (`wws_…`) | só responde a chats que já existem; senão `422 ChatInexistente` |
| `POST /v1/telegramconta/send` | `telegramconta:send` | `To` (`@usuario`, telefone ou id), `Text` (até 4096), `SessionId` opcional (`tgc_…`) | só escreve a quem a conta já tem conversa; senão `422 DialogoInexistente` |

```bash
curl -X POST 'https://api.asender.net/v1/telegram/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: aviso-1042-tg' \
  -d '{ "ChatId": "123456789", "Text": "Seu pedido saiu." }'
```

Sem `BotId`/`SessionId`, a conta usa o bot ou a sessão configurados. Bot, sessão e
número se conectam no painel da respectiva ferramenta. Erros: `400
ValidationError` (campos em `Details`), `404` (bot ou sessão não encontrado),
`409 IdempotencyConflict`. Como são canais não oficiais, estão sujeitos às regras
e aos bloqueios das plataformas; prefira o WhatsApp oficial para campanhas.

#### Conta, uso e identidade

```bash
# Dados da conta da chave (qualquer chave válida)
curl 'https://api.asender.net/v1/account' -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx'
# { "TenantId", "Name", "Plan", "Status", "ApiKeyId", "ApiKeyScope", "RequestId" }

# Consumo do mês (escopo account:read)
curl 'https://api.asender.net/v1/account/usage' -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx'
# { "Usage": { "Period", "EmailsSent", "SmsSent", "PushSent", "ApiCalls" }, "RequestId" }
```

`GET /v1/me` é **só para token de app** com o escopo `openid`: devolve quem
autorizou o app e em que conta, nunca os dados de outra:

```json
{ "user": { "id": "…", "email": "…", "name": "…" }, "account": { "id": "…", "name": "…" }, "scopes": ["leads:read"], "client_id": "…" }
```

`email` e `name` só aparecem se o token foi emitido com os escopos `email` e
`profile`. Uma chave `sk_…` recebe `403` nesta rota.

#### Dados (leitura do que a conta tem)

As rotas de **dados** são de leitura (a única escrita é a de leads, abaixo) e servem a integrações de relatório,
sincronização com BI/CRM externo e a apps de terceiro. Aceitam a chave `sk_…`
com o escopo da rota **e** o token de app (neste caso o usuário que autorizou
precisa ter acesso ao produto da conta; remover o acesso dele passa a valer em
até 60 s).

| escopo | rotas | produto exigido do usuário (token de app) |
| --- | --- | --- |
| `leads:read` | `GET /v1/leads`, `/v1/leads/{id}` | CRM |
| `leads:write` | `POST /v1/leads`, `PATCH /v1/leads/{id}` (**só chave**, nunca token de app) | — |
| `forms:read` | `GET /v1/forms`, `/v1/forms/{id}/submissions` | Páginas |
| `conversions:read` | `GET /v1/conversions` | CRM |
| `campaigns:read` | `GET /v1/campaigns`, `/{id}`, `/{id}/report`, `GET /v1/reports/email/overview`, `/timeseries`, `/top-emails`, `/domains` | E-mail Marketing |
| `messaging:read` | `GET /v1/messaging/{sms,whatsapp,push}/messages`, `…/reports/overview` | o produto do canal |
| `analytics:read` | `GET /v1/analytics/overview`, `/breakdown`, `/timeseries`, `/forms` | Páginas |
| `conversations:read` | `GET /v1/conversations`, `/v1/conversations/{id}/messages` | Atendimento |
| `journeys:read` | `GET /v1/journeys`, `/v1/journeys/{id}` | CRM |

Convenções (diferentes das rotas de mensageria acima):

- **`snake_case`** nos campos e envelope de erro `{ "error": { "type", "message" } }`
  (minúsculo), não o `{ "Error": … }` das rotas de envio.
- **Lista:** `{ "data": [...], "next_cursor": "…" | null }`. `limit` de 1 a 200
  (padrão 50); `cursor` é o `next_cursor` da página anterior, opaco.
- **Incremental:** `updated_after` onde o recurso é alterável, `created_after` onde
  é imutável (RFC 3339). Faça upsert pelo `id`.
- **Recurso único** vem como objeto, sem envelope. Id inexistente **ou de outra
  conta** é sempre `404` idêntico, nunca `403`.
- Origem do dado fora do ar: `503` com `Retry-After`, só na rota afetada.

```bash
curl -s 'https://api.asender.net/v1/leads?limit=200&updated_after=2026-10-01T00:00:00Z' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx'
# {"data":[{"id":"ctt_…","email":"…","stage":"novo"}],"next_cursor":"…"}
```

Os campos de cada recurso, a sincronização incremental recomendada e os erros
estão no [guia Entrar com Asender](https://developers.asender.net/guias/entrar-com-asender.html)
(seção 9) e na referência OpenAPI. As conversões enviadas a Meta, Google e
TikTok (`GET /v1/conversions`) são explicadas em
[Conversões e conectores](https://developers.asender.net/guias/conversoes-e-conectores.html).

#### Escrever leads

`POST /v1/leads` cria e `PATCH /v1/leads/{id}` atualiza um contato do CRM da conta da
chave. Escopo `leads:write`, **só chave**. O corpo é **fechado** (campo desconhecido,
como `tenant_id`, `id` ou os nomes em português, é `400`):

| campo | observação |
| --- | --- |
| `email`, `phone` | ao menos um na criação; guardados **cifrados**; outro lead da conta com o mesmo e-mail/telefone → `409 Conflict` |
| `first_name`, `last_name`, `job_title`, `department`, `country` (ISO-2 maiúsculo), `state`, `city`, `language`, `linkedin` | texto; no `PATCH`, `""` limpa os opcionais |
| `stage` | `novo`, `contatado`, `qualificado`, `cliente`, `descartado` |
| `tags` | até 50; no `PATCH` a lista **substitui** a atual |
| `custom_fields` | até 60 chaves de texto; no `PATCH` mescla e `""` remove a chave |

```bash
curl -s https://api.asender.net/v1/leads \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Idempotency-Key: formulario-evento-8841' \
  -H 'Content-Type: application/json' \
  -d '{"email":"ana@exemplo.com","first_name":"Ana","tags":["evento"]}'
# 201 {"id":"ctt_…","email":"ana@exemplo.com","first_name":"Ana","stage":"novo",…}
```

`Idempotency-Key` (24 h por conta e rota): repetir a chave com o mesmo corpo devolve o
**mesmo resultado** (`Idempotent-Replayed: true`) sem criar outro lead; a mesma chave com
outro corpo é `422 IdempotencyKeyReused`; chamada anterior ainda em curso, `409
IdempotencyInProgress` (`Retry-After`). `PATCH` em lead inexistente **ou de outra conta** é
`404` idêntico. A origem do lead fica registrada como `api`. Os mesmos recursos estão no
[servidor MCP](https://developers.asender.net/guias/mcp.html) (`asender_leads_create`,
`asender_leads_update`).

#### Idempotência (`Idempotency-Key`)

Mande `Idempotency-Key` (1 a 128 caracteres de `[A-Za-z0-9._:-]`; o header vale
mais que o campo `IdempotencyKey` do corpo) em todo envio que possa ser repetido
por retry. Chave fora desse formato é recusada com `422 ValidationError` (nunca é
ignorada em silêncio).

| você manda | resposta |
| --- | --- |
| chave nova | `202`, `ReusedIdempotency: false` |
| a **mesma chave e o mesmo corpo** | `202` com os ids da mensagem **original** e `ReusedIdempotency: true` — nada é reenviado nem cobrado de novo |
| a **mesma chave com corpo diferente** | **`409 IdempotencyConflict`** — o corpo novo **não** é enviado e a mensagem original não muda |

```json
{
  "Error": {
    "Type": "Sender",
    "Code": "IdempotencyConflict",
    "Message": "The Idempotency-Key was already used with a different request body. Send a new key for a new message, or resend the original payload to replay it."
  },
  "RequestId": "req_…"
}
```

O "mesmo corpo" ignora a ordem dos campos e o campo `IdempotencyKey`. No lote de
e-mail a chave vale por item (`<chave>:<índice>`) e cada item traz
`ReusedIdempotency`. A comparação de corpo vale hoje para **SMS, push,
WhatsApp e os canais não oficiais**; no e-mail, até o canal migrar para a ferramenta dedicada, o replay
devolve o `202` original sem comparar o corpo — use uma chave nova por mensagem
nova.

### `/api/*` — painel (sessão)

- **Contas** — `GET/POST /api/tenants`, `GET/PATCH/DELETE /api/tenants/{id}`,
  árvore de sub-contas (`/api/tenants/tree`, `children`, `parent`, `quota`).
- **Membros** — `GET/POST /api/tenants/{id}/members`, `DELETE …/{userId}`.
- **Convites** — `GET/POST /api/tenants/{id}/invitations`, `DELETE …/{token}`,
  `POST /api/invitations/accept` (não exige pertinência — quem aceita ainda não
  pertence).
- **API keys** — `GET/POST /api/tenants/{id}/api-keys`, `DELETE …/{keyId}`.
- **Logs da API** — `GET /api/tenants/{id}/logs`, `…/logs/{logId}`, `…/logs/series`, `…/logs/resumo` (somente `owner` e `admin`; `developer` e `viewer` levam 403).
- **Plano** — `GET/PUT /api/tenants/{id}/plano`, créditos avulsos, uso.
- **Identidade da sessão** — `/api/auth/me`, e-mails de recuperação,
  dispositivos, segundo fator, sessões (piso 17).

Em toda rota `/api/tenants/{id}/…` o `{id}` vem do cliente e é autorizado contra
a pertinência do usuário **antes** de qualquer hop ao core; conta alheia responde
404.

> **Superfície interna (não pública).** O controle de plataforma —
> suporte, moderação, risco e quota — é **plano de controle**, serviço-a-serviço
> na malha privada. Não é uma superfície de integração e **não** é documentado
> aqui; ele existe atrás do BFF, que é o que responde em `api.asender.net`.

## Registro de mudanças

| data | mudança | quem é afetado |
| --- | --- | --- |
| 2026-10-02 | **Quebra de contrato.** `POST /v1/emails/send` e `/v1/emails/batch` recusam `Source` de domínio não verificado com `422 RemetenteNaoVerificado` (antes: `202` e envio com o remetente da plataforma + `Reply-To`). Verificação fora → `503 VerificacaoIndisponivel`. Mensagem cujo domínio perde a verificação depois do `202` fica `failed`, nunca sai com outro remetente. | Integrações que mandavam `Source` de domínio não verificado. |
| 2026-10-06 | **Idempotência e push.** `Idempotency-Key` repetida com corpo diferente passa a dar `409 IdempotencyConflict` em SMS, push e WhatsApp (antes: `202` com o id da 1ª mensagem); `ReusedIdempotency` passa a vir `true` no replay de SMS e push (antes: sempre `false`). `POST /v1/push/send` recusa `Topic` com `400 ValidationError` (envio por tópico nunca funcionou: respondia `422`). JSON com campo desconhecido nomeia o campo na mensagem do `400`. | Integrações que reusavam a chave para corpos diferentes ou enviavam push por `Topic`. |
| 2026-10-07 | **Quebra de contrato: chaves sem escopo deixam de funcionar.** Toda API key precisa de escopos do catálogo. Chave sem lista de escopos, `full_access`, `send_only` ou com `emails:*` recebe `403 InsufficientScope` em toda rota (exceto `GET /v1/account`); a emissão de chave sem escopos, ou com valor fora do catálogo, responde `400 ValidationError` com a lista válida. | Quem usa chave emitida antes desta data sem escopo do catálogo: gere outra no painel de chaves, com os escopos mínimos. |
| 2026-10-07 | **Erros de rota em `/v1/*`.** `404` e `405` agora vêm no envelope `{ "Error": { "Type", "Code", "Message" }, "RequestId" }` (`Code` `NotFound` / `MethodNotAllowed`), com `Allow` no 405 e uma dica quando o caminho é de outra API (`POST /v1/emails` é da Mail API; `/v1/dominios` é da API de Páginas). Antes: `404 page not found` em texto e `405` sem corpo. | Clientes que tratavam o corpo do 404/405 como texto. |
| 2026-10-07 | **Novo: `GET /v1/senders`.** Lista os domínios (com `Verified` e `DnsStatus`) e as caixas ativas que a chave pode usar como `from`; escopo `email:send`. | Quem precisava descobrir remetentes válidos antes de enviar. |
| 2026-10-07 | **Novo: log de requisições da API.** `GET /v1/logs` e `GET /v1/logs/{id}` mostram o que a sua integração mandou e o que a API respondeu (corpos redigidos, filtros, paginação por cursor, ligação com `message_ids`). Novo escopo `logs:read`; chaves existentes **não** o ganham — emita uma chave com o escopo para ler. | Quem quer depurar integrações sem pedir logs ao suporte. |
| 2026-10-20 | **Guia completo.** Escopos `telegram:send`, `whatsweb:send`, `telegramconta:send` e os de leitura de dados (`leads:read`, `conversions:read`, `analytics:read`, `campaigns:read`, `messaging:read`, `conversations:read`, `journeys:read`) documentados; rotas de canais não oficiais, `GET /v1/me`, `/v1/push/site/devices`, rotas de dados, token de app OAuth e o MCP (em implantação) acrescentados. Sem mudança de contrato. | Quem integra: o catálogo agora tem 24 escopos. |
| 2026-10-20 | **Novo: escrita de leads.** `POST /v1/leads` e `PATCH /v1/leads/{id}` (escopo `leads:write`, só chave, com `Idempotency-Key`); o MCP ganha `asender_emails_send`, `asender_leads_create` e `asender_leads_update`. Aditivo: nada existente muda. | Quem integra: o catálogo passa a ter 28 escopos; app OAuth continua sem escrita. |


### GET /
Identidade do serviço.
Respostas: 200 OK

curl -X GET 'https://api.asender.net/' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /.well-known/oauth-protected-resource
Protected Resource Metadata (RFC 9728) da API REST `https://api.asender.net`.
Onde é usada: server.registrarMCP (raiz e /mcp).
Respostas: 200 OK

curl -X GET 'https://api.asender.net/.well-known/oauth-protected-resource' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /.well-known/oauth-protected-resource/mcp
Protected Resource Metadata (RFC 9728) do servidor MCP `https://api.asender.net/mcp`.
Onde é usada: server.registrarMCP (raiz e /mcp).
Respostas: 200 OK; 404 MCP desligado.

curl -X GET 'https://api.asender.net/.well-known/oauth-protected-resource/mcp' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/auth/2fa
Segunda etapa do login — confirma o código do segundo fator.
Onde é usada: tela `/2fa`, para onde o login manda quem tem segundo fator.
Efeitos: cria sessão no asender-auth. # Por que esta rota é PÚBLICA Quem chega aqui ainda não tem sessão — é justamente o que ela está tentando obter. Exigir sessão tornaria o 2FA impossível de completar: a armadilha de aplicar a mesma guarda em toda rota "porque é mais seguro". O que protege é o par (TICKET de desafio, código): o ticket é assinado pelo Login e prova que a senha bateu neste fluxo (um `user_id` cru não abre mais nada — rodada 3, H-1), e o código vale 30 segundos. Sem esta rota, o login de quem tem 2FA ficava sem passo seguinte — a conta ficava inacessível pelo painel.
Respostas: 200 OK; 401 `TwoFactorFailed` (código errado), `TwoFactorSuperseded` (código
substituído por um mais novo — use o e-mail mais recente),
`TwoFactorCodeExpired` (código vencido — peça outro) ou
`TwoFactorExpired` (o ticket do login venceu — recomece o login).; 429 `TooManyAttempts` — freio do código; `Retry-After` (segundos) e
`Details.RetryAfterSeconds` quando o prazo é conhecido.; 502 `InternalError` — o auth não respondeu.

curl -X POST 'https://api.asender.net/api/auth/2fa' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/auth/2fa
Estado do segundo fator do usuário da sessão.
Onde é usada: tela de segurança do painel.
Efeitos: uma leitura no asender-auth. Responde o estado CONFIRMADO, e não "existe segredo": um setup interrompido deixa segredo gravado sem confirmação, e mostrar "2FA ligado" aí faria a pessoa acreditar numa proteção que o login não exige.
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X GET 'https://api.asender.net/api/auth/2fa' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/auth/2fa/disable
Troca o app pelo e-mail (não desliga o 2º fator).
Onde é usada: tela de segurança.
Efeitos: o login deixa de exigir o segundo fator. Exige a SENHA, e não o código: aceitar o próprio TOTP para removê-lo faria o fator se autorizar sozinho.
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X POST 'https://api.asender.net/api/auth/2fa/disable' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/2fa/resend
Reenvia o código de e-mail do 2º fator (método `email`).
Onde é usada: botão "reenviar" da tela `/2fa` (método 'email').
Efeitos: um e-mail (o guard do auth decide se sai fora de prd); rate-limited no auth (cap por janela). # PÚBLICA, pelo mesmo motivo do /api/auth/2fa Quem está no passo do código ainda não tem sessão. O que protege é o TICKET de desafio (prova a senha deste login) — sem ele, 401. O 429 do upstream é repassado como 429: quem pediu demais precisa saber que basta esperar.
Respostas: 200 Código reenviado.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 429 Muitos pedidos de código.

curl -X POST 'https://api.asender.net/api/auth/2fa/resend' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/2fa/setup
Inicia a ativação do segundo fator.
Onde é usada: tela de segurança.
Efeitos: grava o segredo PENDENTE de confirmação. # A senha é a invariante do piso 17, e ela para AQUI se faltar Para mexer num fator é preciso apresentar um fator diferente dele. O serviço recusa senha vazia, e o gateway recusa antes — não por desconfiança do serviço, mas porque um corpo sem senha é pedido malformado, e mandá-lo adiante gastaria uma viagem para receber a mesma recusa.
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X POST 'https://api.asender.net/api/auth/2fa/setup' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/2fa/verify
Confirma a ativação do segundo fator.
Onde é usada: tela de segurança, depois de ler o QR.
Efeitos: o login passa a EXIGIR o segundo fator.
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X POST 'https://api.asender.net/api/auth/2fa/verify' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/ativacao/estado
Passo da ativação obrigatória do 2º fator (conta gerenciada, primeiro acesso).
Respostas: 200 Etapa `senha` ou `fator`.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `ActivationExpired` — refazer o login.; 409 `NothingToActivate`.

curl -X POST 'https://api.asender.net/api/auth/ativacao/estado' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/ativacao/senha
Troca a senha temporária (passo 1 da ativação).
Respostas: 200 OK; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `ActivationExpired`.; 409 `NothingToActivate`.

curl -X POST 'https://api.asender.net/api/auth/ativacao/senha' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/ativacao/totp/confirm
Confirma o código do app e devolve a sessão plena (passo 3).
Respostas: 200 `{Token, UserId, ExpiresAt, RecoveryCodes}`.; 401 `TwoFactorFailed` ou `ActivationExpired`.; 409 `PasswordChangeRequired` ou `NothingToActivate`.; 429 Freio do 2º fator.

curl -X POST 'https://api.asender.net/api/auth/ativacao/totp/confirm' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/ativacao/totp/setup
Gera o segredo/QR do app autenticador (passo 2). Exige a senha já trocada.
Respostas: 200 `{Secret, OtpauthUrl}`.; 401 `ActivationExpired`.; 409 `PasswordChangeRequired` ou `NothingToActivate`.

curl -X POST 'https://api.asender.net/api/auth/ativacao/totp/setup' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/login
Autentica e devolve o token de sessão.
Respostas: 200 Sessão criada, ou 2FA pendente.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Conta bloqueada ou desabilitada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/auth/login' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/logout
Revoga a sessão do Bearer apresentado. IDEMPOTENTE.
Onde é usada: chamado pelas rotas `/api/auth/logout` dos DOIS frontends (dashboard e backoffice), que depois apagam o próprio cookie HttpOnly.
Entradas: header `Authorization: Bearer <jwt de sessão>`.
Saídas: 200 `{Status:"ok"}` com a sessão revogada; 401 sem Bearer; 502 `LogoutFailed` quando o asender_auth_api não confirmou.
Efeitos: marca `auth.sessions.revoked_at` no asender-auth. DEFEITO QUE ISTO FECHA (mesma família do item 17 do _INTEGRACAO-pendente): o handler logava a falha em nível Warn e respondia **200 `{"Status":"ok"}` assim mesmo. A premissa embutida era "logout é best-effort, o cliente só precisa apagar o cookie" — errada pelo mesmo motivo que a do backoffice: com a revogação por `sid` no asender_auth_api, é a resposta desta rota que diz se a sessão morreu ou não. Afirmar `ok` sem revogar dá ao chamador (e à tela) a garantia de que a sessão acabou quando ela continua aceita, e ainda apaga o rastro: quem lê 200 não procura o Warn no log. Por que 502 e não 500: a falha é do upstream (asender-auth fora, ou erro de banco na revogação), não desta camada — mesmo tratamento dado a todo erro de upstream do BFF. Falta de credencial continua sendo 401 do próprio handler: esta rota fica FORA do grupo SessionAuth de propósito (ver server.go).
Respostas: 200 Revogado, ou já estava — inclusive para um Bearer que nunca foi sessão.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.

curl -X POST 'https://api.asender.net/api/auth/logout' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/auth/me
Principal da sessão.
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.

curl -X GET 'https://api.asender.net/api/auth/me' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /api/auth/me
Altera o NOME do usuário da sessão.
Onde é usada: tela de perfil do painel.
Efeitos: escreve no asender_auth_api. # E-mail não muda por aqui (achado F1 do plano da "Minha conta") Este PATCH trocava o e-mail PRIMÁRIO sem reautenticação: sessão sequestrada → troca o e-mail → "esqueci a senha" chega ao atacante. O e-mail agora só muda pelo fluxo `/api/me/emails*` (reauth por fator ≠ senha, verificação do endereço novo, aviso a todos os verificados). `Email` no corpo → 400 `UseEmailsEndpoint`, antes de qualquer hop — inclusive junto com um Name válido (aceitar o nome e ignorar o e-mail em silêncio faria o painel achar que trocou).
Respostas: 200 OK; 400 `UseEmailsEndpoint` (veio `Email`), `ValidationError` (Name vazio) ou campo desconhecido.; 401 credencial ausente ou inválida; 502 auth indisponível.

curl -X PATCH 'https://api.asender.net/api/auth/me' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/auth/me/emails
E-mails de recuperação do usuário logado.
Respostas: 200 OK (corpo repassado do asender_auth_api).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/auth/me/emails' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/auth/me/emails
Acrescenta um e-mail de recuperação ao usuário logado.
Respostas: 200 OK (status/corpo repassados do asender_auth_api).; 400 Corpo não é JSON válido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/auth/me/emails' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/auth/me/emails/{id}
Remove um e-mail de recuperação do usuário logado.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK (status/corpo repassados do asender_auth_api).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X DELETE 'https://api.asender.net/api/auth/me/emails/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/auth/me/emails/{id}/primary
Promove um e-mail do usuário logado a primário.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK (status/corpo repassados do asender_auth_api).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/auth/me/emails/id_AQUI/primary' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/me/emails/{id}/verify/resend
Reenvia a verificação de um e-mail do usuário logado.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK (status/corpo repassados do asender_auth_api).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/auth/me/emails/id_AQUI/verify/resend' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/me/verify/resend
Reenvia o e-mail de verificação do usuário da sessão.
Onde é usada: aviso "confirme seu e-mail" do painel.
Efeitos: um e-mail (o guard do auth decide se ele sai fora de prd). O 429 do upstream é REPASSADO como 429: quem pediu demais precisa saber que basta esperar, e um 502 aqui mandaria a pessoa procurar defeito onde não há.
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X POST 'https://api.asender.net/api/auth/me/verify/resend' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/passkey/login/finish
Termina o login com chave de acesso e devolve a sessão (formato do /api/auth/2fa).
Respostas: 200 `{Token, UserId, ExpiresAt}` — o authfront grava o cookie HttpOnly.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `PasskeyRecusada` (qualquer recusa da credencial — sem oráculo) ou `DesafioExpirado`.; 429 Teto por IP.; 502 auth indisponível ou sem token na resposta.; 503 `PasskeyIndisponivel`.

curl -X POST 'https://api.asender.net/api/auth/passkey/login/finish' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/passkey/login/start
Começa o login SEM senha com chave de acesso (público, teto por IP do auth).
Onde é usada: botão "Entrar com chave de acesso" do authfront (via route handler server-side).
Respostas: 200 `{desafio_id, opcoes}`.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 429 Teto por IP.; 502 auth indisponível.; 503 `PasskeyIndisponivel`.

curl -X POST 'https://api.asender.net/api/auth/passkey/login/start' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/password-reset
Inicia a recuperação de senha (resposta neutra, não vaza se a conta existe).
Onde é usada: tela pública `/forgot-password`.
Efeitos: um e-mail de recuperação (o guard do auth decide se sai fora de prd, piso 18). Nenhuma sessão é criada. # PÚBLICA e com resposta NEUTRA Quem pede recuperação não tem sessão — é o ponto. A resposta é sempre a mesma, exista ou não o e-mail: dizer "esse e-mail não existe" entregaria a base de usuários a quem testa endereços (enumeração). O token do link NUNCA volta no corpo — o `AuthClient.PasswordResetRequest` o descarta ainda no cliente; quem recebe o link é a caixa de e-mail. Vive no MESMO teto por IP das demais rotas públicas de auth (server.go), que fecha o brute-force/spam deste endpoint.
Respostas: 200 aceito (mesma resposta exista ou não o e-mail); 400 e-mail ausente ou malformado

curl -X POST 'https://api.asender.net/api/auth/password-reset' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/password-reset/confirm
Redefine a senha pelo token do link (+ código 2FA quando a conta tem segundo fator).
Onde é usada: tela pública `/reset-password`, que recebe `?token=` do link do e-mail.
Efeitos: grava a senha nova e DERRUBA todas as sessões abertas do usuário (lá no auth). Nenhuma sessão nova é criada — a pessoa faz login em seguida. # PÚBLICA, e os 401 são separados pelo Code Quem redefine a senha não tem sessão (esqueceu a senha). O auth responde 401 para TRÊS situações distintas — token inválido/expirado, 2FA exigido e 2FA incorreto — cada uma com um `Code` próprio no envelope. Separá-las é o que permite à tela pedir o código quando falta, sem transformar "código errado" em "link inválido". Senha fraca vem como 400 (mesma política do cadastro: mínimo 12 + HIBP) e sobe como 422 com a razão, para a pessoa saber o que corrigir.
Respostas: 200 senha redefinida; sessões do usuário derrubadas; 400 token ou nova senha ausentes; 401 token inválido/expirado, 2FA exigido ou 2FA incorreto (distinguidos pelo Error.Code); 422 nova senha não atende à política (mínimo 12 + HIBP)

curl -X POST 'https://api.asender.net/api/auth/password-reset/confirm' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/password-reset/send-otp
Dispara o código do 2º fator (canal e-mail) do reset em curso.
Onde é usada: tela pública `/reset-password`, ao montar com um `?token=` válido e no botão "reenviar".
Efeitos: um e-mail com o código (o guard do auth decide se sai fora de prd, piso 18). Nenhuma sessão é criada. # PÚBLICA, resposta NEUTRA, no MESMO teto por IP Como o resto do reset, é pública e responde sempre igual (não confirma se o token/conta existe — anti-enumeração). Vive no rate-limit por IP das rotas públicas de auth (server.go), que — somado ao cap de reenvio do próprio auth — impede que vire amplificador de e-mail (piso 18). Falha do upstream vira 502 (idêntico para qualquer token, não vaza enumeração) e vai ao log.
Respostas: 200 Aceito (resposta neutra `{"Status":"sent"}`; não confirma o token).; 400 Token ausente.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/auth/password-reset/send-otp' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/register
Cria o usuário e, quando pode, o tenant raiz dele.
Respostas: 201 Usuário e conta criados.; 202 Usuário criado, conta NÃO. O `Reason` diz por quê e o cliente
encaminha para o onboarding.; 400 `400 ValidationError` — JSON inválido, campo desconhecido, e-mail ou
senha fora da regra. Com `ConviteToken`: `InviteInvalid` (convite
inexistente, aceito ou expirado) ou `InviteEmailMismatch` (e-mail do
cadastro diferente do convite). Nos dois, nenhum usuário é criado.; 409 `409 Conflict` — email já registrado, slug em uso.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/auth/register' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/auth/sessions
Dispositivos e sessões ativas do usuário.
Onde é usada: tela de segurança do painel.
Efeitos: uma leitura no asender-auth. O token repassado é o da REQUISIÇÃO, e é ele que define de quem é a lista. Não existe parâmetro de usuário: um `?user_id=` seria a rota mais barata do sistema para descobrir de onde outra pessoa se conecta.
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X GET 'https://api.asender.net/api/auth/sessions' \
  -H 'Authorization: Bearer SEU_TOKEN'

### DELETE /api/auth/sessions/{id}
Revoga uma sessão específica.
Onde é usada: botão "remover" da tela de segurança.
Efeitos: a sessão para de autenticar imediatamente. # Por que a sessão de suporte NÃO passa por aqui A sessão de suporte é somente leitura (ADR-0017), e o middleware de suporte já recusa escrita. Isto é uma escrita — e derrubar o dispositivo de um cliente durante uma sessão de suporte é exatamente o poder que o ADR tira de quem entra na conta alheia.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X DELETE 'https://api.asender.net/api/auth/sessions/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/auth/verify
Confirma o e-mail a partir do token do link.
Onde é usada: tela `/verify`, com o token da URL.
Efeitos: carimba `email_verified_at` no auth. # Também é PÚBLICA Quem abre o link do e-mail pode estar em outro navegador, ou nem ter sessão. Exigir login para verificar o e-mail cria a dependência circular clássica — e a pessoa que mais precisa verificar é justamente a que ainda não conseguiu entrar.
Respostas: 200 OK; 401 link inválido; 409 email_em_uso — o endereço já está verificado em outra conta (token intacto)

curl -X POST 'https://api.asender.net/api/auth/verify' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/auth/verify/resend
Reenvia o link de confirmação sem sessão (202 neutro, teto por IP).
Onde é usada: tela `/verify` quando o link falhou e o navegador não tem sessão.
Efeitos: no máximo um e-mail (guard do piso 18 no auth). # PÚBLICA, resposta NEUTRA, no MESMO teto por IP 202 idêntico exista ou não pendência para o endereço (o auth só envia se houver pendência viva). O 429 é por IP, igual para qualquer endereço.
Respostas: 202 aceito (mesma resposta exista ou não pendência); 400 e-mail ausente ou malformado; 429 teto por IP

curl -X POST 'https://api.asender.net/api/auth/verify/resend' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/busca
Busca federada do hub: um termo procurado em todas as ferramentas da pessoa na conta.
Onde é usada: a busca do cabeçalho do hub (`asender_plataforma_front`, components/busca-do-app.tsx).
Erros: 400 termo; 401 sem sessão; 404 conta alheia (resolveSessionTenant — nunca 403, que seria oráculo); 502 se o PDP não responde (sem ele não há como saber o que a pessoa pode ver: nega).
Parâmetros: X-Asender-Tenant (header); q (query, obrigatório)
Respostas: 200 OK; 400 `ValidationError` — q com menos de 2 ou mais de 100 caracteres, ou com caractere de controle.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `NoTenant` — o usuário ainda não pertence a conta nenhuma.; 404 Conta alheia no `X-Asender-Tenant` (mesma resposta de inexistente).; 429 `Throttling` — teto por principal.; 502 core ou PDP (auth) indisponível — sem eles não há como saber o que a pessoa vê.

curl -X GET 'https://api.asender.net/api/busca' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/campaigns
Campanhas do tenant, com status e progresso.
Onde é usada: dashboard de marketing.
Entradas: `limit` (allowlist). Parâmetro fora da lista é 422 nomeando-o, nunca listagem sem filtro em silêncio.
Saídas: 200 com `{Campaigns:[...]}` (array, nunca null).
Parâmetros: limit (query)
Respostas: 200 OK — `{Campaigns:[...]}` (array, nunca null).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/campaigns' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/campaigns
Cria uma campanha em rascunho (draft).
Onde é usada: wizard "nova campanha" da tela de campanhas.
Saídas: 201 com `{Campaign}`; 422 em validação (campo ruim ou template/lista inexistente). NÃO dispara nada — campanha nasce em `draft`.
Efeitos: escreve em messages.campaigns.
Respostas: 201 Criada — `{Campaign}` em draft.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 503 `VerificacaoIndisponivel` — o domínio do remetente não pôde ser conferido agora; nada foi gravado.

curl -X POST 'https://api.asender.net/api/campaigns' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/campaigns/{id}
Detalhe de uma campanha, com contadores.
Onde é usada: tela de detalhe/progresso da campanha.
Saídas: 200 com `{Campaign}`; 404 quando o id não existe NO TENANT — campanha de outro tenant também é 404, para não confirmar existência alheia (§22.8).
Parâmetros: id (path, obrigatório)
Respostas: 200 OK — `{Campaign}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/campaigns/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /api/campaigns/{id}
Edita uma campanha (só enquanto em draft ou paused).
Onde é usada: edição na tela de campanhas.
Saídas: 200 com `{Campaign}`; 404 se não existir; 422 se não estiver em draft ou se algum campo/ref for inválido.
Efeitos: escreve em messages.campaigns.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK — `{Campaign}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 Fora de draft, campo/ref inválido, ou `RemetenteNaoVerificado` (domínio do From não verificado nesta conta).; 503 `VerificacaoIndisponivel` — o domínio do remetente não pôde ser conferido agora; nada foi gravado.

curl -X PATCH 'https://api.asender.net/api/campaigns/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/campaigns/{id}/cancel
Cancela a campanha (draft/scheduled/paused→cancelled). Sem corpo.
Onde é usada: botão "cancelar" da tela de campanhas.
Saídas: 200 com `{Campaign}`; 404 se não existir; 422 se o status atual não permitir cancelamento (ex.: já enviada).
Efeitos: escreve em messages.campaigns.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK — `{Campaign}` em cancelled.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 Status atual não permite cancelamento (ex.: já enviada).

curl -X POST 'https://api.asender.net/api/campaigns/id_AQUI/cancel' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/campaigns/{id}/schedule
Agenda a campanha (draft/paused→scheduled). NÃO envia.
Onde é usada: botão "agendar" da tela de campanhas.
Entradas: `ScheduledAt` em RFC 3339 (ex.: `2026-09-10T14:00:00Z`). A borda valida a FORMA aqui (data não-parseável é 422 sem hop); o asender_mkt_api é quem valida a REGRA (data futura, lista/template presentes).
Saídas: 200 com `{Campaign}`; 404 se não existir; 422 em data malformada, passada/ausente ou campanha fora de draft.
Efeitos: escreve em messages.campaigns.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK — `{Campaign}` em scheduled.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 Data malformada/passada/ausente, campanha fora de draft/paused, ou `RemetenteNaoVerificado` — o domínio do From perdeu a verificação desde o rascunho (fica como está). Reagendar a `paused` é retomá-la: `PauseReason` é limpo e os lotes já aceitos não saem de novo.; 503 `VerificacaoIndisponivel` — o domínio do remetente não pôde ser conferido agora.

curl -X POST 'https://api.asender.net/api/campaigns/id_AQUI/schedule' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/campaigns/remetentes
Domínios verificados que podem assinar o remetente da campanha (seletor do wizard).
Onde é usada: wizard de campanha do asender_mkt_front.
Saídas: 200 `{Dominios:[...], LinkDominios}` (lista vazia é válida); 503 `VerificacaoIndisponivel` repassado intacto com a fonte fora.
Efeitos: uma chamada ao asender_mkt_api (que consulta o asender_mail_api).
Respostas: 200 Os domínios verificados.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 `503 VerificacaoIndisponivel` — a verificação do domínio do remetente
não respondeu. Fail-closed: nada foi enfileirado. Repita depois do
`Retry-After` (com a mesma `Idempotency-Key`).

curl -X GET 'https://api.asender.net/api/campaigns/remetentes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/contacts
Audiência do tenant.
Onde é usada: tela de audiência do dashboard.
Entradas: `q`, `list_id`, `tag`, `cursor`, `limit` (allowlist).
Saídas: 200 com `{Contacts, NextCursor, HasMore}`.
Parâmetros: X-Asender-Tenant (header); q (query); list_id (query); tag (query); cursor (query); limit (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/contacts' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/contacts
Cria um contato.
Onde é usada: formulário de novo contato da tela de audiência.
Saídas: 201 com `{Contact}`; 422 em validação (email/telefone inválidos).
Efeitos: escreve em messages.contacts.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 Criado.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X POST 'https://api.asender.net/api/contacts' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/contacts/{id}
A ficha de UM contato da audiência, com o consentimento por canal.
Onde é usada: a ficha `/audience/contacts/{id}` do asender_mkt_front, aberta pela busca global (hub e cabeçalho do Marketing); registrada em server.go no grupo `exigirMarketing`.
Saídas: 200 `{Contact}`; 401 sem sessão; 404 se o contato não é do tenant (o mesmo 404 de inexistente); 502 com o upstream fora.
Efeitos: nenhum.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/contacts/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /api/contacts/{id}
altera parcialmente um contato do tenant da SESSÃO — hoje o caminho do editor de consentimento por canal.
Onde é usada: tela de audiência do hub, ao revogar ou restaurar um canal.
Saídas: 200 com `{Contact}`; 404 quando o contato não é do tenant; 422 em validação (canal fora dos quatro, corpo vazio).
Efeitos: escreve em messages.contacts e no consentimento por canal. # O tenant vem da SESSÃO, e o id vai na ROTA `resolveSessionTenant` resolve a conta do token verificado; o corpo nunca escolhe em quem se escreve (piso 3). É o que faz `PATCH /api/contacts/<id do vizinho>` ser 404 em vez de edição alheia — a checagem é do `asender_mkt_api`, com o tenant que ESTE handler passou. # Por que `map[string]any` e não uma struct PATCH é PARCIAL. Uma struct com campos zero-value não distingue "não mandou" de "mandou vazio", e aqui a diferença decide se o consentimento de um canal muda ou fica como está. Repassar o corpo cru deixa a decisão com quem tem a regra — o `asender_mkt_api` — em vez de duplicá-la no BFF, que é como as duas cópias do filtro de descadastro divergiram antes (ver o contrato da audiência).

curl -X PATCH 'https://api.asender.net/api/contacts/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/contacts/{id}
Remove o contato do tenant.
Saídas: 204; 404 fora do tenant.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 Removido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X DELETE 'https://api.asender.net/api/contacts/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/contacts/{id}/consent-proofs
Provas de consentimento do contato.
Saídas: 200 `{Proofs:[{Source,FormId,Texto,BaseLegal,ConcedidoEm}]}`; 404 fora do tenant.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/contacts/id_AQUI/consent-proofs' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/contacts/{id}/lists
Listas a que o contato pertence.
Saídas: 200 `{Lists}`; 404 fora do tenant.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/contacts/id_AQUI/lists' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/contacts/bulk
Importa até 5000 contatos, com upsert pela identidade natural.
Onde é usada: importador CSV da tela de audiência.
Saídas: 200 com `{Created, Updated, Errors, Contacts, Suppressed, AddedToList, Tagged}`; 422 quando a lista vem vazia ou acima do teto.
Efeitos: escreve em messages.contacts.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 Lote processado.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X POST 'https://api.asender.net/api/contacts/bulk' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/contacts/tags
Aplica tags a contatos (até 500 ids e 10 tags).
Onde é usada: seleção múltipla da tela de audiência.
Saídas: 200 `{Applied|Removed, NotFound}`; 422 em corpo vazio/acima do teto.
Efeitos: escreve nas tags dos contatos (no mkt_api).
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 OK; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X POST 'https://api.asender.net/api/contacts/tags' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/contacts/tags
Remove tags de contatos (DELETE com corpo; até 500 ids e 10 tags).
Onde é usada: seleção múltipla da tela de audiência.
Saídas: 200 `{Applied|Removed, NotFound}`; 422 em corpo vazio/acima do teto.
Efeitos: escreve nas tags dos contatos (no mkt_api).
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 OK; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X DELETE 'https://api.asender.net/api/contacts/tags' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/contratacao
Auto-contratação de plano (self-service); registra pagamento pendente.
Onde é usada: a tela `/contratar` do dashboard (self-service).
Saídas: 200 `{Status:"pendente",PagamentoId,Produtos,Plano}`; 422 validação; 403 conta com outro dono; 502 quando um upstream falha.
Respostas: 200 Pagamento pendente registrado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 422 Produto/plano inválido, ou nenhum produto escolhido.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/contratacao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/enderecos/consulta
Endereço de um CEP/zipcode (widget CampoEndereco dos fronts).
Onde é usada: GET /api/enderecos/consulta?pais=BR&cep=01310100.
Efeitos: uma chamada ao core (que tem cache de 30 dias).
Parâmetros: pais (query, obrigatório); cep (query, obrigatório)
Respostas: 200 Achado (sem número/complemento).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 CEP não encontrado ou país sem cobertura.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 Provedores fora; campos seguem manuais.

curl -X GET 'https://api.asender.net/api/enderecos/consulta' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/flags
As feature flags avaliadas para a conta da sessão.
Respostas: 200 OK

curl -X GET 'https://api.asender.net/api/flags' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/invitations/{token}/preview
Prévia do convite pelo token do link — PÚBLICA, teto por IP.
Onde é usada: a tela do link de convite dos fronts, ANTES de login/cadastro; registrada no grupo público com teto por IP em server.go.
Entradas: `{token}` do caminho — o token do link.
Saídas: 200 `{Email, TenantName, Role, Status, HasAccount}`; 404 `NotFound` para token desconhecido; 502 quando o core não respondeu.
Efeitos: uma leitura no core e, se pendente, uma no auth. Por que é pública: quem abre o link ainda não tem sessão. O token é CSPRNG e é a própria credencial do convite — só quem o recebeu por e-mail vê o e-mail do PRÓPRIO convite. Por isso a resposta não devolve o token, nem o id público da conta, nem quem convidou: só o necessário para a tela decidir o botão. `HasAccount` é complemento, não requisito (piso 10): auth fora → `null`, e a tela oferece os dois caminhos. Convite não pendente também leva `null` — não há decisão de botão a tomar, e não se consulta o auth à toa.
Parâmetros: token (path, obrigatório)
Respostas: 200 Convite encontrado.; 404 `404 NotFound` — token desconhecido.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/invitations/token_AQUI/preview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/invitations/accept
Aceita um convite e vincula o usuário à conta.
Onde é usada: tela de convite.
Efeitos: uma escrita no core. # Esta rota NÃO passa por contaAutorizada E não pode: quem aceita ainda NÃO pertence à conta — exigir pertinência aqui tornaria o convite impossível de aceitar. Quem autoriza é o TOKEN, que o core valida (existente, não expirado, não usado), e o usuário vem da sessão.
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X POST 'https://api.asender.net/api/invitations/accept' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/lists
Cria uma lista de contatos.
Onde é usada: tela de audiência.
Saídas: 201 com `{List}`; 422 em validação.
Efeitos: escreve em messages.contact_lists.
Parâmetros: X-Asender-Tenant (header)
Respostas: 201 Criada (ou atualizada pelo slug).; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X POST 'https://api.asender.net/api/lists' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/lists
Listas de contatos com contagem de membros.
Onde é usada: tela de audiência.
Saídas: 200 com `{Lists}`.
Parâmetros: X-Asender-Tenant (header); cursor (query); limit (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/lists' \
  -H 'Authorization: Bearer SEU_TOKEN'

### DELETE /api/lists/{id}
Remove a lista (os contatos permanecem).
Saídas: 204; 404 fora do tenant.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 204 Removida.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X DELETE 'https://api.asender.net/api/lists/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/lists/{id}/contacts
Membros de uma lista, paginados por cursor.
Onde é usada: expansão de lista da tela de audiência e do composer de envio do asender_mkt_front, via `/api/proxy`; registrada em server.go no grupo `exigirMarketing`.
Entradas: `{id}` (public id da lista); query `cursor`, `limit` (allowlist; `limit` fora de 1..100 é 422 — nunca cortado sem aviso).
Saídas: 200 `{Contacts, NextCursor, HasMore}`; 401 sem sessão; 404 se a lista não é do tenant; 422 em query inválida; 502 com o upstream fora.
Efeitos: nenhum (só leitura).
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório); cursor (query); limit (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/lists/id_AQUI/contacts' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/lists/{id}/members
Anexa contatos a uma lista.
Onde é usada: tela de audiência (seleção múltipla).
Saídas: 200 com `{Added}`; 404 se a lista não é do tenant; 422 se a lista de ids vem vazia.
Efeitos: escreve em messages.contact_list_members.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 OK; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X POST 'https://api.asender.net/api/lists/id_AQUI/members' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/lists/{id}/members
Tira contatos de uma lista (DELETE com corpo; até 500 ids).
Saídas: 200 `{Removed, NotFound}`; 404 lista fora do tenant; 422 corpo vazio ou acima de 500 ids.
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 OK; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X DELETE 'https://api.asender.net/api/lists/id_AQUI/members' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/me
Minha conta: usuário, fatores e reauth vigente (repasse de GET /v1/me).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X GET 'https://api.asender.net/api/me' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /api/me
Troca o nome (repasse de PATCH /v1/me).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X PATCH 'https://api.asender.net/api/me' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/me/codigos-recuperacao
Gera 10 códigos de recuperação (reauth totp|email_otp).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{codigos:[10]}` no formato XXXX-XXXX-XXXX (auth MeCodigos), mostrados uma vez; os anteriores deixam de valer.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/codigos-recuperacao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/me/convites
Convites pendentes/expirados para os e-mails VERIFICADOS do usuário.
Onde é usada: seção Convites da "Minha conta" (auth_front `/conta/convites`).
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 503 `IdentityUnavailable` — auth fora (nunca lista vazia mentindo); `InvitationsUnavailable` — core fora.

curl -X GET 'https://api.asender.net/api/me/convites' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/convites/{id}/aceitar
Aceita convite por public_id (idempotente; herda acessos).
Onde é usada: cartão do convite. Idempotente (duplo clique = mesmo member).
Efeitos: pertinência no core + herança de acessos no auth (falha da herança não desfaz o aceite — mesma regra do link) + linha de auditoria no log.
Parâmetros: id (path, obrigatório)
Respostas: 200 Idempotente. `user_id` é o da SESSÃO e os e-mails são os verificados do auth — nada vem do corpo. Depois do aceite, a mesma herança de acessos do link (owner/admin herdam as ferramentas).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 Inexistente, de outro e-mail, id fora do formato `cvt_…` ou usuário sem e-mail verificado (mesma resposta).; 409 `Declined` ou `AlreadyAccepted`.; 410 `Expired` ou `Revoked`.; 429 `Throttling` — teto de 30 decisões de convite (aceitar+recusar) por usuário por hora, com `Retry-After`.; 502 core indisponível.; 503 `IdentityUnavailable` — auth fora.

curl -X POST 'https://api.asender.net/api/me/convites/id_AQUI/aceitar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/me/convites/{id}/recusar
Recusa convite (idempotente).
Onde é usada: cartão do convite. Idempotente.
Parâmetros: id (path, obrigatório)
Respostas: 204 Recusado (idempotente).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 Inexistente, de outro e-mail ou id fora do formato (mesma resposta).; 409 `AlreadyAccepted`.; 429 `Throttling` — mesmo teto do aceitar (30/h por usuário, somados).; 502 core indisponível.; 503 `IdentityUnavailable` — auth fora.

curl -X POST 'https://api.asender.net/api/me/convites/id_AQUI/recusar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/me/convites/contagem
Quantos convites pendentes (badge). Falha → `{pendentes:null}` 200.
Onde é usada: badge do AppHeader e faixa do hub (Frente E), em polling de 60s. QUALQUER falha (auth, core, sessão) vira 200 `{pendentes:null}`: o badge some e nada mais quebra (piso 10). Duas idas leves (auth + COUNT indexado).
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.

curl -X GET 'https://api.asender.net/api/me/convites/contagem' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/me/emails
E-mails da conta.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X GET 'https://api.asender.net/api/me/emails' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/emails
Adiciona e-mail — 202 neutro sempre (reauth totp se tiver, senão email_otp).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 202 Neutro: `{ok:true}` exista ou não o endereço.; 400 `ValidationError` (endereço inválido) ou `InvalidRequest` (campo desconhecido).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 429 `TooManyAttempts` — 10 e-mails adicionados por dia.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/emails' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/me/emails/{id}
Remove e-mail (reauth totp se tiver, senão email_otp).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Parâmetros: id (path, obrigatório)
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X DELETE 'https://api.asender.net/api/me/emails/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/emails/{id}/primario
Torna o e-mail primário (mesma reauth).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Parâmetros: id (path, obrigatório)
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/emails/id_AQUI/primario' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/me/emails/{id}/reenviar
Reenvia a verificação.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Parâmetros: id (path, obrigatório)
Respostas: 204 Link reenviado (ou nada a fazer: já verificado).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 422 `EnderecoNaoRecebe` — o servidor do destinatário recusou o endereço de vez.; 429 `TooManyAttempts` — cap de reenvio por janela.; 502 auth indisponível, ou `EnvioRecusado` (recusa permanente por política do destino).

curl -X POST 'https://api.asender.net/api/me/emails/id_AQUI/reenviar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/me/eventos
Trilha de segurança paginada (só `antes` e `limite` atravessam).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Parâmetros: antes (query); limite (query)
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 400 `InvalidRequest` — cursor `antes` ou `limite` inválido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X GET 'https://api.asender.net/api/me/eventos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/me/fatores
Inventário de fatores + remoções pendentes (leitura).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{fatores:{senha,email_otp,totp,codigos_restantes,passkeys}, remocoes_pendentes:[{id,fator,executar_em}]}` (auth MeFatores; array vazio quando não há).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 Rota fora da allowlist do contrato.; 502 auth indisponível.

curl -X GET 'https://api.asender.net/api/me/fatores' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/me/passkeys
Chaves de acesso (passkeys) da conta (leitura; sem chave pública nem credential id).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{passkeys:[{id,nome,criado_em,usado_em,sincronizada,rp_id}]}` (auth MePasskeys).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `SessaoNecessaria` (credencial sem sessão do auth).; 404 Rota fora da allowlist do contrato.; 502 auth indisponível.

curl -X GET 'https://api.asender.net/api/me/passkeys' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /api/me/passkeys/{id}
Renomeia uma chave de acesso (sem reauth).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{passkey}` (repassado).; 400 `ValidationError`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `SessaoNecessaria` ou `ImpersonationReadOnly`.; 404 Inexistente ou de outra pessoa (indistinguíveis), ou rota fora da allowlist.; 502 auth indisponível.

curl -X PATCH 'https://api.asender.net/api/me/passkeys/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/me/passkeys/{id}
Remove uma chave de acesso (reauth email_otp|totp|codigo_recuperacao; último forte agenda 24h).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{removida:true}` — saiu na hora.; 202 `{id, fator:"passkey", agendado_para, passkey_id}` — último fator forte: remoção em 24h, cancelável.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` ou `ImpersonationReadOnly`.; 404 Inexistente ou de outra pessoa (indistinguíveis), ou rota fora da allowlist.; 409 `MinimoDeFatores`.; 502 auth indisponível.

curl -X DELETE 'https://api.asender.net/api/me/passkeys/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/passkeys/registro/finish
Grava a chave de acesso (resposta do autenticador).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 201 `{passkey}` (repassado).; 400 `DesafioExpirado`, `PasskeyRecusada` ou `ValidationError`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` ou `ImpersonationReadOnly`.; 404 Rota fora da allowlist do contrato.; 409 `PasskeyJaRegistrada`.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/passkeys/registro/finish' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/me/passkeys/registro/start
Começa o cadastro de uma chave de acesso (reauth email_otp|senha|totp|passkey).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{desafio_id, opcoes}` para navigator.credentials.create (repassado).; 400 `OrigemRecusada` / corpo inválido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Details.metodos_aceitos`/`metodos`) ou `ImpersonationReadOnly`.; 404 Rota fora da allowlist do contrato.; 502 auth indisponível.; 503 `PasskeyIndisponivel`.

curl -X POST 'https://api.asender.net/api/me/passkeys/registro/start' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/me/reauth/confirm
Confirma a reautenticação na sessão (repasse; 429 com Retry-After).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/reauth/confirm' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/me/reauth/start
Inicia a reautenticação (repasse).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 202 Prova preparada; `destinos` e `enviado_para` para `email_otp`; `desafio_id` e `opcoes` (WebAuthn, base64url) para `passkey` (formato no description).; 400 `MetodoIndisponivel` (método que a conta não tem, ou `email_id` alheio/pendente/inexistente).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 429 `TooManyAttempts` — cap de códigos por janela.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/reauth/start' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/me/remocoes/{id}
Cancela a remoção agendada.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Parâmetros: id (path, obrigatório)
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X DELETE 'https://api.asender.net/api/me/remocoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/senha
Troca a senha (reauth senha atual|email_otp|totp|passkey|codigo_recuperacao — P4).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/senha' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/me/senhas-app
allowlist → corpo → auth `/v1/me/<resto>` → status e corpo como vieram (inclusive o 403 `ReauthRequired` com `metodos_aceitos`, que a tela precisa ler intacto) + `Retry-After` do 429.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.

curl -X GET 'https://api.asender.net/api/me/senhas-app' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/senhas-app
allowlist → corpo → auth `/v1/me/<resto>` → status e corpo como vieram (inclusive o 403 `ReauthRequired` com `metodos_aceitos`, que a tela precisa ler intacto) + `Retry-After` do 429.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.

curl -X POST 'https://api.asender.net/api/me/senhas-app' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/me/senhas-app/{id}
allowlist → corpo → auth `/v1/me/<resto>` → status e corpo como vieram (inclusive o 403 `ReauthRequired` com `metodos_aceitos`, que a tela precisa ler intacto) + `Retry-After` do 429.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.

curl -X DELETE 'https://api.asender.net/api/me/senhas-app/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/me/sessoes
Sessões vivas do usuário.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X GET 'https://api.asender.net/api/me/sessoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### DELETE /api/me/sessoes/{id}
Revoga uma sessão própria.
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Parâmetros: id (path, obrigatório)
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X DELETE 'https://api.asender.net/api/me/sessoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/sessoes/encerrar-outras
Encerra as outras sessões (qualquer reauth).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 Corpo do contrato §4.2 do auth, repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/sessoes/encerrar-outras' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/me/totp
Agenda a remoção do TOTP em 24h (reauth email_otp|codigo_recuperacao).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 202 `{id, fator, agendado_para}` (auth MeRemocaoAgendada); idempotente.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 409 `NotEnabled` ou `MinimoDeFatores` (ficaria com menos de 2 fatores).; 502 auth indisponível.

curl -X DELETE 'https://api.asender.net/api/me/totp' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/me/totp/confirm
Liga o TOTP (reauth email_otp|senha).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{ok, codigos_recuperacao}` (auth MeTOTPConfirmado): 10 códigos XXXX-XXXX-XXXX na 1ª ativação, vazio se já havia códigos vivos.; 400 `InvalidCode`, `TOTPNaoIniciado` ou `InvalidRequest`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 409 `AlreadyEnabled`.; 429 `TooManyAttempts` (freio por usuário, o mesmo do login).; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/totp/confirm' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/me/totp/setup
Gera TOTP pendente (reauth email_otp|senha).
Onde é usada: grupo SessionAuth+Impersonacao do BFF (server/server_me.go). Erros próprios: 404 rota fora do contrato; 400 corpo inválido; 401 sem token; 502 auth fora.
Respostas: 200 `{otpauth_url, secret}` (auth MeTOTPSetup), repassado sem reinterpretação.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ReauthRequired` (com `Error.Details.metodos_aceitos`, `Error.Details.metodos` — cada método da política com `disponivel` e o `motivo` do indisponível, ex. `EmailNaoVerificado` (P5) — e, quando `email_otp` é aceito, `Error.Details.destinos` [{email_id, mascarado, primario}]), `ReauthIndisponivel`, `SessaoNecessaria` (leitura de segurança — e-mails, fatores, sessões, trilha — com credencial sem sessão do auth) ou `ImpersonationReadOnly` (sessão de suporte não escreve).; 404 Rota fora da allowlist do contrato, ou recurso inexistente/alheio.; 409 `AlreadyEnabled` (app já ativo).; 502 auth indisponível.

curl -X POST 'https://api.asender.net/api/me/totp/setup' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/messages
Histórico de envios do tenant corrente.
Onde é usada: tela de histórico do dashboard.
Entradas: Channel/Status/Q/Cursor/Limit são aceitos em snake_case (`channel`, `status`, `q`, `cursor`, `limit`) e repassados por allowlist — nenhum outro parâmetro atravessa.
Saídas: 200 com `{Messages, NextCursor, HasMore}`; 422 em query malformada.
Parâmetros: X-Asender-Tenant (header); channel (query); status (query); q (query); cursor (query); limit (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/messages' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/messages/{id}
Detalhe do envio com timeline.
Onde é usada: tela de detalhe do envio.
Saídas: 200 com `{Message, Events}`; 404 quando o id não existe NO TENANT — mensagem de outro tenant também é 404, para não confirmar existência (§22.8).
Parâmetros: X-Asender-Tenant (header); id (path, obrigatório)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/messages/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/messages/send
Composer do dashboard — envia em qualquer canal.
Onde é usada: composer da tela de envio do dashboard.
Saídas: 202 com `{Messages, ReusedIdempotency}`; 422 quando o asender_mkt_api recusa a validação (canal inválido, destinatário vazio, corpo ausente).
Efeitos: escreve mensagens no banco de mensageria.
Parâmetros: X-Asender-Tenant (header)
Respostas: 202 Enfileirado.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 `422 RemetenteNaoVerificado` — o remetente (`Source`/`From`) de e-mail
não é de domínio verificado nesta conta (inclui domínio verificado em
OUTRA conta). `Message` para o usuário: o domínio e o link para Admin →
Domínios. Nada é enfileirado (decisão de 2026-10-02; antes o e-mail
saía com o remetente da plataforma).

`422 ValidationError` — demais recusas do upstream (template sem
variável, todos suprimidos, portão de qualidade…).; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 `503 VerificacaoIndisponivel` — a verificação do domínio do remetente
não respondeu. Fail-closed: nada foi enfileirado. Repita depois do
`Retry-After` (com a mesma `Idempotency-Key`).

curl -X POST 'https://api.asender.net/api/messages/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/public/planos
Catálogo único de planos — vitrine pública (ADR-0075).
Onde é usada: LP (www, server-side com ISR) e hub `/contratar`. Anônima.
Respostas: 200 Planos publicados, em `ordem`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` — o core não respondeu e não há cópia em
cache. A LP cai no fallback estático dela.

curl -X GET 'https://api.asender.net/api/public/planos' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/push/devices
Devices de push do tenant, para o seletor da tela de disparo.
Onde é usada: dashboard, tela `/send/push`.
Entradas: `cursor` e `limit`, na mesma allowlist dos outros List.
Saídas: 200 com `{Devices, NextCursor, HasMore}` (PascalCase, §51). Antes desta rota o caminho respondia 404 e a tela não tinha como listar: dava para disparar digitando o token à mão, mas não escolher um device existente.
Parâmetros: X-Asender-Tenant (header); cursor (query); limit (query)
Respostas: 200 Página de devices, em PascalCase.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/push/devices' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/push/site-config
Pacote de integração de Web Push para o site do cliente.
Onde é usada: tela de push do dashboard (botão de copiar/baixar cada arquivo).
Entradas: `origem` — repetível, as origens do site (1 a 10).
Saídas: 200 com `{PublicKey, ApiBase, SiteKey, Origens, Manifest, ServiceWorker, Snippet}`; 400 sem origem ou com origem inválida.
Efeitos: pode criar o par VAPID do tenant na primeira chamada (no core). ## A chave do snippet é PÚBLICA (M15) O snippet antigo mandava colar a API key de SERVIDOR num JS público. Agora ele leva uma chave de site (`pk_push_…`) que só registra inscrição de Web Push e só a partir das origens pedidas aqui — ver internal/sitekey. Sem origem declarada não há chave: uma chave sem allowlist valeria para qualquer página. ## Por que o servidor gera, em vez de documentar Os três arquivos dependem de dois valores que variam por instalação: a chave pública do tenant e a base da API. Documentação com `<SUA_CHAVE_AQUI>` produz exatamente um tipo de chamado — o do integrador que esqueceu de substituir, e cujo sintoma é "não chega notificação", sem erro em lugar nenhum. Gerando aqui, o que o cliente cola já está correto.
Parâmetros: X-Asender-Tenant (header); origem (query, obrigatório)
Respostas: 200 Artefatos prontos para o site.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 503 Segredo de assinatura da chave de site ausente.

curl -X GET 'https://api.asender.net/api/push/site-config' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/reports/overview
Funil do período com quebra por canal.
Onde é usada: dashboard de relatórios (cards do topo).
Entradas: `from`/`to` em ISO-8601 UTC; ausentes = últimos 30 dias (default resolvido pelo asender_mkt_api, não duplicado aqui).
Saídas: 200 com `{Totals, Rates, ByChannel}` — as chaves de ByChannel seguem sendo `email`/`sms`/`push`, porque ali são dado e não nome de campo.
Parâmetros: X-Asender-Tenant (header); from (query); to (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/reports/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/reports/timeseries
Série temporal por bucket e canal.
Onde é usada: dashboard de relatórios (gráfico principal).
Entradas: `from`, `to`, `channel` (email|sms|push), `interval` (hour|day|week|month; default day). Valor fora da allowlist é 422 — filtro descartado em silêncio mente para quem consulta.
Saídas: 200 com `{Points:[...]}`.
Parâmetros: X-Asender-Tenant (header); from (query); to (query); channel (query); interval (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/reports/timeseries' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/reports/top-templates
Ranking de templates por volume, com taxas.
Onde é usada: dashboard de relatórios (tabela lateral).
Entradas: `from`, `to`, `limit` (1..100).
Saídas: 200 com `{Templates:[...]}`.
Parâmetros: X-Asender-Tenant (header); from (query); to (query); limit (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/reports/top-templates' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/resumo
Home do hub: o resumo de cada ferramenta que a pessoa acessa na conta.
Onde é usada: a home do hub (`asender_plataforma_front`, `/t/<conta>`).
Erros: 400 período inválido; 401 sem sessão; 404 conta alheia (via resolveSessionTenant — nunca 403, que seria oráculo); 502 se o PDP não responde (sem ele não há como saber o que a pessoa pode ver: nega).
Parâmetros: periodo (query)
Respostas: 200 OK; 400 `ValidationError` — periodo fora de 7d|30d|90d.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `NoTenant` — o usuário ainda não pertence a conta nenhuma.; 404 Conta alheia no `X-Asender-Tenant` (mesma resposta de inexistente).; 429 `Throttling` — teto por principal.; 502 core ou PDP (auth) indisponível — sem eles não há como saber o que a pessoa vê.

curl -X GET 'https://api.asender.net/api/resumo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/resumo/marketing
Home do marketing: o `/v1/resumo` do asender_mkt_api, repassado sem reinterpretação.
Onde é usada: rota dentro do PEP do produto `marketing` (server_resumo.go) — quem não acessa o marketing nem chega aqui.
Erros: 400 período; 404 conta alheia; os do mkt_api propagados por writeUpstreamError.
Parâmetros: periodo (query)
Respostas: 200 O payload do `/v1/resumo` do marketing, verbatim.; 400 `ValidationError` — periodo fora de 7d|30d|90d.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `NoTenant`.; 404 Conta alheia, ou sem acesso ao produto `marketing` (PEP).; 429 `Throttling` — teto por principal.; 502 mkt_api ou core indisponível.

curl -X GET 'https://api.asender.net/api/resumo/marketing' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/suporte/catalogo
Categorias, produtos, impactos e limites do formulário de chamado.
Onde é usada: tela de abrir chamado (admin e app).
Respostas: 200 `{categorias, produtos, impactos, limites}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 atendimento indisponível

curl -X GET 'https://api.asender.net/api/suporte/catalogo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/suporte/chamados
Chamados do usuário (`escopo=usuario`) ou da conta (`escopo=conta`, exige governança).
Onde é usada: a busca do cabeçalho do hub (`asender_plataforma_front`, components/busca-do-app.tsx).
Erros: 400 termo; 401 sem sessão; 404 conta alheia (resolveSessionTenant — nunca 403, que seria oráculo); 502 se o PDP não responde (sem ele não há como saber o que a pessoa pode ver: nega).
Parâmetros: escopo (query); estado (query); categoria (query); produto (query); q (query); limite (query); antes (query)
Respostas: 200 `{chamados: Chamado[], proximo?}`.; 400 `ValidationError` — filtro ou cursor inválido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `SemGovernanca` (escopo conta sem ser admin) ou `NoTenant`.; 404 Conta alheia.; 502 atendimento indisponível

curl -X GET 'https://api.asender.net/api/suporte/chamados' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/suporte/chamados
Abre um chamado.
Parâmetros: Idempotency-Key (header)
Respostas: 200 Replay da mesma `Idempotency-Key`.; 201 Chamado criado (`Location` aponta para `/api/suporte/chamados/{protocolo}`).; 400 `ValidationError` — campo desconhecido ou JSON inválido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ImpersonationReadOnly` ou `NoTenant`.; 404 Conta alheia.; 409 `LimiteDeChamadosAbertos` ou `IdempotencyConflict`.; 422 `ValidationError` do atendimento.; 429 `Throttling`.; 502 atendimento indisponível

curl -X POST 'https://api.asender.net/api/suporte/chamados' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/suporte/chamados/{protocolo}
Um chamado do usuário (ou da conta, para quem governa).
Parâmetros: protocolo (path, obrigatório)
Respostas: 200 Chamado com `solicitante` e `conta`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 502 atendimento indisponível

curl -X GET 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /api/suporte/chamados/{protocolo}/avaliacao
Avalia o atendimento (nota 1..5), idempotente por ciclo.
Parâmetros: protocolo (path, obrigatório)
Respostas: 200 Avaliação registrada.; 400 `ValidationError` — campo desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ImpersonationReadOnly`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `AindaNaoResolvido`.; 422 `ValidationError` — nota fora de 1..5.; 502 atendimento indisponível

curl -X PUT 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/avaliacao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/suporte/chamados/{protocolo}/fechar
Fecha o chamado.
Parâmetros: protocolo (path, obrigatório)
Respostas: 200 Chamado atualizado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ImpersonationReadOnly`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `ChamadoFechado`.; 502 atendimento indisponível

curl -X POST 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/fechar' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/suporte/chamados/{protocolo}/itens
Linha do tempo pública do chamado (mensagens e eventos).
Parâmetros: protocolo (path, obrigatório); limite (query); antes (query)
Respostas: 200 `{itens: (mensagem|evento)[], proximo?}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 502 atendimento indisponível

curl -X GET 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/itens' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /api/suporte/chamados/{protocolo}/leitura
Marca as respostas da equipe como lidas.
Parâmetros: protocolo (path, obrigatório)
Respostas: 204 Marcado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ImpersonationReadOnly`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 502 atendimento indisponível

curl -X PUT 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/leitura' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/suporte/chamados/{protocolo}/mensagens
Responde ao chamado (JSON ou multipart com até 3 anexos).
Onde é usada: o campo de resposta da tela do chamado.
Parâmetros: protocolo (path, obrigatório)
Respostas: 201 `{id, criada_em, estado}`.; 400 `ValidationError` — campo não permitido ou anexos demais.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ImpersonationReadOnly`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `ChamadoFechado`.; 413 `PayloadTooLarge`.; 415 `TipoDeAnexoNaoAceito`.; 429 `Throttling`.; 502 atendimento indisponível

curl -X POST 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/mensagens' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/suporte/chamados/{protocolo}/mensagens/{msgId}/anexos/{anexoId}
Baixa um anexo (streaming).
Parâmetros: protocolo (path, obrigatório); msgId (path, obrigatório); anexoId (path, obrigatório)
Respostas: 200 Os bytes do anexo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `AnexoBloqueado`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `AnexoEmVerificacao` (com `Retry-After`).; 502 atendimento indisponível

curl -X GET 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/mensagens/msgId_AQUI/anexos/anexoId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/suporte/chamados/{protocolo}/reabrir
Reabre o chamado dentro da janela.
Parâmetros: protocolo (path, obrigatório)
Respostas: 200 Chamado atualizado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `ImpersonationReadOnly`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `JanelaDeReaberturaExpirada`.; 502 atendimento indisponível

curl -X POST 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/reabrir' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/suporte/chamados/contagem
Indicadores do menu (aguardando você, respostas não lidas, abertos).
Parâmetros: escopo (query)
Respostas: 200 `{aguardando_voce, respostas_nao_lidas, abertos}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `SemGovernanca`.; 404 Conta alheia.; 502 atendimento indisponível

curl -X GET 'https://api.asender.net/api/suporte/chamados/contagem' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tags
Tags do tenant com a contagem de contatos.
Onde é usada: filtro/gestão de tags da ferramenta emailmarketing.
Entradas: `limit` (allowlist).
Saídas: 200 `{Tags:[{Name,ContactCount}]}`.
Parâmetros: X-Asender-Tenant (header); limit (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/tags' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/templates
Templates do tenant.
Onde é usada: dashboard.
Saídas: 200 com `{Templates}`.
Parâmetros: X-Asender-Tenant (header); limit (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/templates' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/templates
Cria ou atualiza um template pelo par (tenant, slug).
Onde é usada: editor de templates do dashboard.
Saídas: 200 com `{Template}`; 422 em validação do asender_messages.
Efeitos: escreve em messages.templates.
Parâmetros: X-Asender-Tenant (header)
Respostas: 200 Gravado (upsert — 200 tanto na criação quanto na atualização).; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X POST 'https://api.asender.net/api/templates' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants
Vínculos de tenant do usuário logado.
Onde é usada: dashboard (topbar/tenant-switcher, settings/account) e backoffice (useTenantForest).
Saídas: 200 com `{Tenants:[{Id,Name,Slug,Status,...}]}`; 502 se o core está fora. DEFEITO QUE ISTO FECHA (T3 §3.5): a rota devolvia o payload do core CRU (`tenants[].id`), enquanto TODO o resto de `/api/*` — inclusive a rota vizinha `/api/tenants/tree` — responde PascalCase (API_DESIGN.md §51). Quem seguia o contrato lia `Tenants` e recebia `undefined`; quem "fazia funcionar" passava a ler `tenants` e ficava preso ao formato interno do core.
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/tenants' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants
Cria um tenant RAIZ pertencente ao usuário logado.
Onde é usada: fluxo de cadastro (AuthHandler.Register faz o equivalente internamente) e recuperação manual quando o provisionamento automático falhou.
Entradas: `{Name, Slug}` — allowlist explícita, ver tenantCreateInput.
Saídas: 201 com `{Tenant:{Id,...}}` em PascalCase; 400 JSON inválido OU campo fora da allowlist; 422 nome vazio; o status 4xx do core preservado; 502 quando o core está fora.
Efeitos: escreve no asender-core. O `owner_user_id` vem SEMPRE do principal verificado, nunca do corpo.
Respostas: 201 Tenant criado. **O objeto vem NO TOPO, sem a chave `Tenant`** — o
`asender_plataforma_api` responde o tenant sem chave de recurso nesta rota e o
BFF só pascaliza o que recebeu. É inconsistente com
`POST /api/tenants/{id}/children` e com `POST /api/auth/register`,
que devolvem `{"Tenant":{...}}`. Documentado como está no ar.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/tenants' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants/{id}/api-keys
Lista as API keys da conta.
Onde é usada: GET /api/tenants/{id}/api-keys.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK (corpo repassado do asender_plataforma_api).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/api-keys' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/api-keys
Emite uma API key na conta (o texto puro volta UMA vez).
Onde é usada: POST /api/tenants/{id}/api-keys.
Parâmetros: id (path, obrigatório)
Respostas: 201 Chave criada (corpo do core; 400 `ValidationError`: `scopes` ausente, vazio ou com valor fora do catálogo; a mensagem lista os escopos válidos.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 name ausente.

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/api-keys' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/api-keys/{keyId}
Revoga uma API key da conta.
Onde é usada: DELETE /api/tenants/{id}/api-keys/{keyId}.
Parâmetros: id (path, obrigatório); keyId (path, obrigatório)
Respostas: 204 Revogada.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/api-keys/keyId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/atividade
A trilha de ATIVIDADE da própria conta (admin/owner), ADR-0114.
Onde é usada: aba "Atividade" da tela /auditoria do admin.asender.
Efeitos: só leitura.
Parâmetros: id (path, obrigatório); ator (query); servico (query); recurso_tipo (query); recurso_id (query); acao (query); de (query); ate (query); limite (query); cursor (query); formato (query)
Respostas: 200 OK; 400 filtro ou cursor inválido; 403 papel sem governança da conta; 404 conta alheia

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/atividade' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/channels/whatsapp/credentials
Credencial de WhatsApp da conta, MASCARADA.
Onde é usada: GET /api/tenants/{id}/channels/whatsapp/credentials.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK (corpo repassado do core, com o token mascarado).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 Id de conta vazio no caminho.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/credentials' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PUT /api/tenants/{id}/channels/whatsapp/credentials
Cadastra/substitui a credencial de WhatsApp da conta.
Onde é usada: PUT /api/tenants/{id}/channels/whatsapp/credentials.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK (corpo repassado do core, com o token mascarado).; 400 Corpo não é JSON válido ou traz campo desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Papel de leitura (`viewer`) não altera a conta.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 phone_id ou access_token ausente/vazio.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X PUT 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/credentials' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants/{id}/channels/whatsapp/numbers
Números de WhatsApp da conta (vários por conta; o padrão primeiro).
Onde é usada: a tela de canais do admin e o seletor de remetente do zapify.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK — `{numbers: [...]}` repassado do core.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/channels/whatsapp/numbers
Adiciona um número de WhatsApp à conta.
Parâmetros: id (path, obrigatório)
Respostas: 201 Criado (eco do core, token mascarado).; 400 Corpo inválido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Papel de leitura.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `NumeroEmUso`.; 422 phone_id ausente.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /api/tenants/{id}/channels/whatsapp/numbers/{numero}
Edita um número (nome, WABA, token, ativo).
Respostas: 200 OK (eco do core, token mascarado).; 400 Corpo inválido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `PadraoComOutros`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X PATCH 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/channels/whatsapp/numbers/{numero}
Remove um número — pede confirmação se houver conversas abertas.
Onde é usada: "Remover" na tela de canais.
Parâmetros: confirm (query)
Respostas: 204 Removido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `ConversasAbertas` (confirme) ou `PadraoComOutros`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/channels/whatsapp/numbers/{numero}/default
Define o número como remetente padrão.
Parâmetros: id (path, obrigatório); numero (path, obrigatório)
Respostas: 200 OK (o novo padrão).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `NumeroInativo`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI/default' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/tenants/{id}/channels/whatsapp/numbers/{numero}/test
Testar conexão do número com a Meta (simulado fora de produção).
Parâmetros: id (path, obrigatório); numero (path, obrigatório)
Respostas: 200 `{ok, simulated, display_number?, verified_name?, detail?}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 503 Validação indisponível / Graph API fora.

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI/test' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /api/tenants/{id}/children
Cria uma sub-conta sob um tenant administrado pelo usuário.
Onde é usada: tela de hierarquia de tenants.
Entradas: `{Name, Slug, MonthlyQuota}` — MonthlyQuota nulo/ausente significa herdar do ancestral mais próximo com valor.
Saídas: 201 com `{Tenant}`; 404 se `{id}` não é acessível; 422 quando o core recusa (slug duplicado, ciclo detectado pelo trigger de closure).
Efeitos: escreve no asender-core (conta + closure + membro owner = usuário da sessão + evento `platform.tenant.created`, numa transação lá).
Parâmetros: id (path, obrigatório)
Respostas: 201 Sub-conta criada.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Papel efetivo na conta não governa a árvore (`GovernanceRole`): só
`owner`/`admin` (direto ou do ancestral concedente) criam, movem ou
mudam cota de sub-conta — `developer`/`viewer` não (2026-10-04).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `409 Conflict` — email já registrado, slug em uso.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/children' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants/{id}/dns/alteracoes
Histórico das alterações de DNS da conta.
Parâmetros: id (path, obrigatório); zona (query); pagina (query); por_pagina (query)
Respostas: 200 OK: `{alteracoes, total, pagina, por_pagina}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).; default Erro RFC 9457 (`application/problem+json`) do serviço de DNS, repassado com o `codigo` estável (ZonaNaoEncontrada, ForaDePrd, RegistroProtegido, ConfirmacaoNecessaria, LimiteExcedido, ...).

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/dns/alteracoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/dns/conexoes
Lista as conexões Cloudflare da conta (nunca devolve o token).
Parâmetros: id (path, obrigatório)
Respostas: 200 OK: `{conexoes:[{id, provedor, rotulo, token_final, zonas, criado_por, criado_em}]}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/dns/conexoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/dns/conexoes
Conecta um token da Cloudflare à conta.
Parâmetros: id (path, obrigatório); Idempotency-Key (header)
Respostas: 201 Criada: a conexão, sem o token.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).; default Erro RFC 9457 (`application/problem+json`) do serviço de DNS, repassado com o `codigo` estável (ZonaNaoEncontrada, ForaDePrd, RegistroProtegido, ConfirmacaoNecessaria, LimiteExcedido, ...).

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/dns/conexoes' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/dns/conexoes/{cid}
Apaga uma conexão (o token cifrado é apagado).
Parâmetros: id (path, obrigatório); cid (path, obrigatório); Idempotency-Key (header)
Respostas: 200 OK: `{apagada: true, id}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).; default Erro RFC 9457 (`application/problem+json`) do serviço de DNS, repassado com o `codigo` estável (ZonaNaoEncontrada, ForaDePrd, RegistroProtegido, ConfirmacaoNecessaria, LimiteExcedido, ...).

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/dns/conexoes/cid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/dns/zonas
Zonas de todas as conexões da conta.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK: `{zonas:[{id, nome, conexao_id}], avisos:[{conexao_id, codigo}]}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/dns/zonas' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/dns/zonas/{zona}/registros
Registros de uma zona.
Parâmetros: id (path, obrigatório); zona (path, obrigatório); tipo (query); nome (query); pagina (query); por_pagina (query)
Respostas: 200 OK: `{registros, total, pagina, por_pagina}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).; default Erro RFC 9457 (`application/problem+json`) do serviço de DNS, repassado com o `codigo` estável (ZonaNaoEncontrada, ForaDePrd, RegistroProtegido, ConfirmacaoNecessaria, LimiteExcedido, ...).

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/dns/zonas/zona_AQUI/registros' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/dns/zonas/{zona}/registros
Cria um registro (aceita `?seco=1`).
Parâmetros: id (path, obrigatório); zona (path, obrigatório); seco (query); X-Asender-Confirmar (header); Idempotency-Key (header)
Respostas: 200 OK (plano com `seco`); sem `seco` o serviço responde 201 com `{registro}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).; default Erro RFC 9457 (`application/problem+json`) do serviço de DNS, repassado com o `codigo` estável (ZonaNaoEncontrada, ForaDePrd, RegistroProtegido, ConfirmacaoNecessaria, LimiteExcedido, ...).

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/dns/zonas/zona_AQUI/registros' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /api/tenants/{id}/dns/zonas/{zona}/registros/{rid}
Altera parcialmente um registro (aceita `?seco=1`).
Parâmetros: id (path, obrigatório); zona (path, obrigatório); rid (path, obrigatório); seco (query); X-Asender-Confirmar (header); Idempotency-Key (header)
Respostas: 200 OK: `{registro}` ou o plano.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).; default Erro RFC 9457 (`application/problem+json`) do serviço de DNS, repassado com o `codigo` estável (ZonaNaoEncontrada, ForaDePrd, RegistroProtegido, ConfirmacaoNecessaria, LimiteExcedido, ...).

curl -X PATCH 'https://api.asender.net/api/tenants/id_AQUI/dns/zonas/zona_AQUI/registros/rid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/dns/zonas/{zona}/registros/{rid}
Apaga um registro (exige X-Asender-Confirmar).
Parâmetros: id (path, obrigatório); zona (path, obrigatório); rid (path, obrigatório); seco (query); X-Asender-Confirmar (header); Idempotency-Key (header)
Respostas: 200 OK: `{apagado: registro}` ou o plano.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`403 AdminRole`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 dns_api fora do ar (`ServiceUnavailable`, com `Retry-After`).; default Erro RFC 9457 (`application/problem+json`) do serviço de DNS, repassado com o `codigo` estável (ZonaNaoEncontrada, ForaDePrd, RegistroProtegido, ConfirmacaoNecessaria, LimiteExcedido, ...).

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/dns/zonas/zona_AQUI/registros/rid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/envios-api
Destinatários dos envios feitos pela API (endereço completo, estado e motivo).
Onde é usada: API pública do cliente.
Entradas: `status`, `q`, `cursor`, `limit` (allowlist). `channel` do cliente é IGNORADO: nesta rota o canal é do contrato, não do parâmetro.
Saídas: 200 com `{Messages, NextCursor, HasMore}`; 422 em query malformada.
Parâmetros: id (path, obrigatório); status (query); q (query); cursor (query); limit (query); ids (query)
Respostas: 200 OK.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 AdminRole` — o usuário pertence à conta mas não é `owner` nem `admin`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 Parâmetro desconhecido ou inválido.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 Serviço de mensagens indisponível.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/envios-api' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/importaveis
As outras contas que o usuário governa e pode importar para a árvore de {id}.
Onde é usada: seletor flutuante do diálogo "Importar conta existente" (admin).
Saídas: 200 `{Contas:[...]}` em ordem de nome; 403/404 como as mutações.
Efeitos: leituras no core (pertinência, descendência, ancestrais por conta).
Parâmetros: id (path, obrigatório)
Respostas: 200 A lista, em ordem de nome.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `GovernanceRole`: o usuário não governa `{id}`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/importaveis' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/invitations
Convites pendentes da conta.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/invitations' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/invitations
Convida alguém para a conta.
Onde é usada: tela de equipe.
Efeitos: uma escrita no core (e, quando houver envio, um e-mail).
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/invitations' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/invitations/{token}
Cancela um convite pendente.
Onde é usada: tela de equipe.
Efeitos: uma escrita no core.
Parâmetros: id (path, obrigatório); token (path, obrigatório)
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/invitations/token_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/logo/{variante}
Imagem do logo da empresa (lançador e cabeçalho dos fronts).
Onde é usada: GET /api/tenants/{id}/logo/{variante}. Cache: `private` (é imagem atrás de sessão — um cache compartilhado não pode guardá-la). Com `?v=` igual à versão atual, a URL é imutável e vale por um ano; sem `?v=` (ou com versão velha), uma hora.
Parâmetros: id (path, obrigatório); variante (path, obrigatório); v (query)
Respostas: 200 PNG; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logo/variante_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/logs
Log de requisições da API da conta (painel, sem corpos).
Parâmetros: id (path, obrigatório); limit (query); after (query); before (query); status_class (query); status (query); method (query); path (query); api_key_id (query); error_code (query); idempotency_key (query); message_id (query); mode (query); since (query); until (query)
Respostas: 200 OK (corpo repassado do serviço de logs, em snake_case).; 400 `400 ValidationError` — parâmetro inválido, cursor adulterado ou de outra
conta, `after` com `before`. Corpo repassado do serviço de logs
(`LogsErrorEnvelope`).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 AdminRole` — o usuário pertence à conta mas não é `owner` nem `admin`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` — o serviço de logs não respondeu. Repita depois
do `Retry-After`; o resto da API segue funcionando.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logs' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/logs/{logId}
Detalhe de uma requisição (corpos redigidos).
Parâmetros: id (path, obrigatório); logId (path, obrigatório)
Respostas: 200 OK (corpo repassado do serviço de logs, em snake_case).; 400 `400 ValidationError` — parâmetro inválido, cursor adulterado ou de outra
conta, `after` com `before`. Corpo repassado do serviço de logs
(`LogsErrorEnvelope`).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 AdminRole` — o usuário pertence à conta mas não é `owner` nem `admin`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` — o serviço de logs não respondeu. Repita depois
do `Retry-After`; o resto da API segue funcionando.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logs/logId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/logs/resumo
Resumo agregado da conta: total, taxa de erro, p50/p95, por rota e por código.
Parâmetros: id (path, obrigatório); since (query); until (query); mode (query)
Respostas: 200 OK (corpo repassado do serviço de logs, em snake_case).; 400 `400 ValidationError` — parâmetro inválido, cursor adulterado ou de outra
conta, `after` com `before`. Corpo repassado do serviço de logs
(`LogsErrorEnvelope`).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 AdminRole` — o usuário pertence à conta mas não é `owner` nem `admin`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` — o serviço de logs não respondeu. Repita depois
do `Retry-After`; o resto da API segue funcionando.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logs/resumo' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/logs/series
Série temporal de requisições por classe de status.
Parâmetros: id (path, obrigatório); bucket (query); since (query); until (query); mode (query)
Respostas: 200 OK (corpo repassado do serviço de logs, em snake_case).; 400 `400 ValidationError` — parâmetro inválido, cursor adulterado ou de outra
conta, `after` com `before`. Corpo repassado do serviço de logs
(`LogsErrorEnvelope`).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 AdminRole` — o usuário pertence à conta mas não é `owner` nem `admin`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` — o serviço de logs não respondeu. Repita depois
do `Retry-After`; o resto da API segue funcionando.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logs/series' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/members
Membros da conta.
Onde é usada: tela de equipe.
Efeitos: uma leitura no core.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/members' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/members
Vincula um usuário à conta.
Onde é usada: tela de equipe.
Efeitos: uma escrita no core.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/members' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/members/{userId}
Desvincula um usuário da conta.
Onde é usada: tela de equipe.
Efeitos: uma escrita no core.
Parâmetros: id (path, obrigatório); userId (path, obrigatório)
Respostas: 200 OK; 401 credencial ausente ou inválida

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/members/userId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/movimento/previa
Prévia de mover/importar uma conta, sem escrever nada.
Onde é usada: passo "confirmar" do diálogo "Importar conta existente" do admin. Segurança: a MESMA autorização do PATCH — a prévia não pode virar oráculo sobre contas que o usuário não governa.
Saídas: 200 `{Preview:{...}}`; 403/404/422 como no PATCH.
Parâmetros: id (path, obrigatório); ParentId (query)
Respostas: 200 A prévia.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `GovernanceRole` ou `ParentNotGoverned` (ver o PATCH /parent).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/movimento/previa' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/oauth-apps
Lista os apps OAuth ("Entrar com Asender") da conta.
Onde é usada: a busca do cabeçalho do hub (`asender_plataforma_front`, components/busca-do-app.tsx).
Erros: 400 termo; 401 sem sessão; 404 conta alheia (resolveSessionTenant — nunca 403, que seria oráculo); 502 se o PDP não responde (sem ele não há como saber o que a pessoa pode ver: nega).
Parâmetros: id (path, obrigatório)
Respostas: 200 OK: `{apps:[app]}` (corpo do auth).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Membro sem papel owner/admin (`PapelInsuficiente`).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/oauth-apps
Cria um app OAuth na conta (o client_secret volta UMA vez).
Parâmetros: id (path, obrigatório)
Respostas: 201 Criado: `{app, client_secret?, aviso}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem papel owner/admin.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `LimiteDeApps`.; 413 Corpo acima de 64 KiB.; 422 Validação do auth.; 429 `MuitasCriacoes` (Retry-After).

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants/{id}/oauth-apps/{app}
Detalhe de um app OAuth da conta.
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 200 OK: `{app}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem papel owner/admin.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /api/tenants/{id}/oauth-apps/{app}
Edita campos do app (nome, site_url, logo_url, redirect_uris, escopos).
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 200 OK: `{app}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 Validação do auth.

curl -X PATCH 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/oauth-apps/{app}
Exclui (desativa) o app e revoga grants e refresh tokens.
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 204 Excluído.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/oauth-apps/{app}/revisao
Pede a revisão do app pela equipe.
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 200 OK: `{app}` em `em_revisao`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `EstadoInvalido`.; 422 `RevisaoIncompleta` (site_url vazio).

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI/revisao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants/{id}/oauth-apps/{app}/revisoes
Histórico de revisões do app.
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 200 OK: `{revisoes:[…]}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI/revisoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/oauth-apps/{app}/segredo
Gira o client_secret (o novo volta UMA vez).
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 200 OK: `{client_id, client_secret, aviso}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 `AppPublico`.

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI/segredo' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants/{id}/oauth-apps/{app}/testadores
Lista os testadores do app (limite 25).
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 200 OK: `{testadores:[…], limite}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI/testadores' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /api/tenants/{id}/oauth-apps/{app}/testadores
Convida um testador (por `email` ou `user_id`).
Parâmetros: id (path, obrigatório); app (path, obrigatório)
Respostas: 201 Convidado: `{testador}`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `UsuarioNaoEncontrado` ou conta/app inexistente.; 409 `LimiteDeTestadores`.

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI/testadores' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /api/tenants/{id}/oauth-apps/{app}/testadores/{usr}
Remove um testador do app.
Parâmetros: id (path, obrigatório); app (path, obrigatório); usr (path, obrigatório)
Respostas: 204 Removido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/oauth-apps/app_AQUI/testadores/usr_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /api/tenants/{id}/parent
Move o tenant para outro pai, importa uma conta como sub-conta, ou promove a raiz.
Onde é usada: tela "Contas e sub-contas" do admin (mover e "Importar conta existente"). Segurança: autoriza os TRÊS lados (ver o doc do arquivo).
Saídas: 200 com `{Tenant, Moved, PaiAnterior}` (`Moved:false` = já estava lá, nada gravado); 404 se a conta ou o destino não é acessível; 403 `GovernanceRole`/`ParentNotGoverned`; 409 movimento concorrente; 422 ciclo, auto-pai ou destino inativo.
Efeitos: reescreve a closure no core e grava a trilha (ator = usuário da sessão, origem `sessao`) + evento `platform.tenant.moved`.
Parâmetros: id (path, obrigatório)
Respostas: 200 Movido (a closure foi reescrita) ou já estava lá (`Moved:false`).; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `GovernanceRole`/`ReadOnlyRole`: o papel efetivo na conta ou no
destino não governa a árvore (só `owner`/`admin`).
`ParentNotGoverned`: a conta está sob uma conta que o usuário não
governa — só quem governa o pai atual a tira de lá.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 409 Outro movimento mudou o pai da conta entre a leitura e a escrita (`Conflict`); nada foi gravado — recarregue.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X PATCH 'https://api.asender.net/api/tenants/id_AQUI/parent' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /api/tenants/{id}/quota
Define ou limpa a quota mensal do tenant.
Onde é usada: tela de hierarquia de tenants.
Entradas: `{MonthlyQuota}` — número define o teto; `null` volta a herdar do ancestral. A chave é OBRIGATÓRIA: aceitar corpo sem ela faria um nome de campo digitado errado limpar a quota em silêncio.
Saídas: 200 com `{Tenant}`; 404 se `{id}` não é acessível; 422 em valor inválido.
Efeitos: escreve no asender-core.
Parâmetros: id (path, obrigatório)
Respostas: 200 Quota gravada; `EffectiveQuota` já recalculada.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Papel efetivo na conta não governa a árvore (`GovernanceRole`): só
`owner`/`admin` (direto ou do ancestral concedente) criam, movem ou
mudam cota de sub-conta — `developer`/`viewer` não (2026-10-04).; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X PATCH 'https://api.asender.net/api/tenants/id_AQUI/quota' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /api/tenants/{id}/suppressions
Supressões da conta e as globais que afetam seus envios (ADR-0153 D7).
Onde é usada: aba "Atividade" da tela /auditoria do admin.asender.
Efeitos: só leitura.
Parâmetros: id (path, obrigatório); state (query); origin (query); q (query); cursor (query); limit (query)
Respostas: 200 `{itens: SupressaoConta[], proximo_cursor?, globais: SupressaoEntrada[]}` (globais só sem cursor).; 400 valor de filtro longo demais; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `AdminRole` — não é owner nem admin.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 502 core indisponível

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/suppressions' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/suppressions/{sid}
Detalhe de uma supressão da conta com a trilha (owner/admin).
Onde é usada: detalhe na tela de supressões da conta.
Efeitos: uma leitura ao core com o ator.
Parâmetros: id (path, obrigatório); sid (path, obrigatório)
Respostas: 200 `{entrada, eventos[]}`.; 400 sid inválido; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `AdminRole`.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 502 core indisponível

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/suppressions/sid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/{id}/supressao-global/consulta
A conta consulta se um e-mail está em supressão global (só leitura).
Onde é usada: selo "Supressão global" dos fronts de conta (mail e e-mail marketing).
Parâmetros: id (path, obrigatório); email (query, obrigatório)
Respostas: 200 suprimido, desde quando, origem e teste_disponivel_em; 400 e-mail inválido; 404 conta alheia

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/supressao-global/consulta' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /api/tenants/tree
Subárvore do tenant corrente, em pré-ordem.
Onde é usada: dashboard (settings/tenants) e backoffice.
Entradas: `depth` — inteiro positivo; valor não numérico é 422, não "sem limite" silencioso.
Saídas: 200 com `{TenantId, Tree:[...]}`; 404 se o tenant pedido não é acessível.
Parâmetros: X-Asender-Tenant (header); depth (query)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 NoTenant` — sessão válida de um usuário sem NENHUM vínculo de tenant.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/api/tenants/tree' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /mcp
Não há stream SSE (servidor stateless).
Onde é usada: server.routes.
Respostas: 405 Method Not Allowed (`Allow: POST, OPTIONS`).

curl -X GET 'https://api.asender.net/mcp' \
  -H 'Authorization: Bearer SEU_TOKEN'

### DELETE /mcp
Não há sessão para encerrar (servidor stateless).
Onde é usada: server.routes.
Respostas: 405 Method Not Allowed (`Allow: POST, OPTIONS`).

curl -X DELETE 'https://api.asender.net/mcp' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /mcp
Servidor MCP remoto (Streamable HTTP stateless, JSON-RPC 2.0, somente leitura).
Onde é usada: server.routes (depois de auth e rate limit).
Respostas: 200 Resposta JSON-RPC (`result` ou `error`).; 202 Notificação ou resposta do cliente aceita; 400 JSON inválido; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Origin não permitido.; 413 Corpo acima de 1 MiB.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.

curl -X POST 'https://api.asender.net/mcp' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/account
Conta da API key usada (ou do app OAuth, com `ClientId`), mais o contexto da credencial.
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/v1/account' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/account/usage
Contadores de consumo do tenant no período corrente.
Onde é usada: superfície pública `/v1`, consumida por integrações de cliente.
Saídas: 200 com `{Usage:{Period,EmailsSent,SmsSent,PushSent,ApiCalls}}`; 404 se o tenant da API key não existe mais no core; 502 se o core está fora. DEFEITO QUE ISTO TAMBÉM FECHA (item 7 do briefing Y2, metade da borda): o core respondia 404 quando não havia linha em `core.usage_counters` — e o seed não cria nenhuma —, e este handler traduzia QUALQUER erro do upstream em 502. Ou seja: a rota respondia "serviço indisponível" para todo tenant que ainda não enviou nada, mandando o alerta para o time errado. O 404 do core agora só significa "tenant inexistente" (a correção principal está em asender_plataforma_api/internal/service/usage.Get) e é traduzido como 404, não 502. DEFEITO QUE ISTO FECHA (T3 §3.6): o payload do core saía CRU sob `Usage` (`{"Usage":{"sent":42}}`), fora do contrato PascalCase da API pública (API_DESIGN.md §51). O cliente que segue o contrato lê `Usage.Sent` e recebe `undefined` — mesma classe de divergência de fronteira do GET /api/tenants.
Respostas: 200 Consumo do período. Tenant sem nenhum envio devolve os contadores em
zero, com `UpdatedAt: null` — ausência de linha é consumo zero, não
ausência de recurso.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 Core fora **ou** tenant sem contador de uso (ver `x-asender-divergence`).

curl -X GET 'https://api.asender.net/v1/account/usage' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/breakdown
Janela agrupada por uma dimensão.
Saídas: 200 `{from,to,dimension,data,next_cursor:null}`.
Parâmetros: dimension (query); limit (query); from (query); to (query); page_id (query); form_id (query); source (query); medium (query); campaign (query); country (query); device (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/analytics/breakdown' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/forms
Resumo de formulários ou funil de um formulário.
Saídas: 200; 400; 401; 503 com Retry-After.
Parâmetros: limit (query); from (query); to (query); page_id (query); form_id (query); source (query); medium (query); campaign (query); country (query); device (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/analytics/forms' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/overview
Totais de tráfego e conversão da janela.
Onde é usada: apps e chaves com `analytics:read`.
Saídas: 200 `{from,to,totals}`; 400 janela/filtro inválido; 401; 503 com Retry-After se o runtime estiver fora.
Efeitos: uma leitura no runtime.
Parâmetros: from (query); to (query); page_id (query); form_id (query); source (query); medium (query); campaign (query); country (query); device (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/analytics/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/analytics/timeseries
Série diária (America/Sao_Paulo).
Saídas: 200 `{from,to,interval,timezone,data,next_cursor:null}`; erros como o overview.
Parâmetros: from (query); to (query); page_id (query); form_id (query); source (query); medium (query); campaign (query); country (query); device (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/analytics/timeseries' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/campaigns
Campanhas de e-mail da conta (incremental).
Saídas: 200 `{data, next_cursor}`; 400; 503 (canal não cortado); 502.
Parâmetros: limit (query); cursor (query); updated_after (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/campaigns' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/campaigns/{id}
Uma campanha.
Saídas: 200 com o objeto da campanha (recurso único, sem envelope); 404 (inclusive de outra conta).
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 404 `404 NotFound` — o recurso não existe **ou é de outra conta** (mesma resposta).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/campaigns/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/campaigns/{id}/report
Contadores de entrega e engajamento de uma campanha.
Saídas: 200 `{data:{campaign_id,totals}}`.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 404 `404 NotFound` — o recurso não existe **ou é de outra conta** (mesma resposta).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/campaigns/id_AQUI/report' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/conversations
Conversas da conta (incremental).
Onde é usada: a busca do cabeçalho do hub (`asender_plataforma_front`, components/busca-do-app.tsx).
Erros: 400 termo; 401 sem sessão; 404 conta alheia (resolveSessionTenant — nunca 403, que seria oráculo); 502 se o PDP não responde (sem ele não há como saber o que a pessoa pode ver: nega).
Parâmetros: updated_after (query); limit (query); cursor (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/conversations' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/conversations/{id}/messages
Mensagens de uma conversa.
Saídas: 200 `{data,next_cursor}`; 400; 401; 404; 503 com Retry-After.
Parâmetros: id (path, obrigatório); created_after (query); limit (query); cursor (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 404 `404 NotFound` — o recurso não existe **ou é de outra conta** (mesma resposta).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/conversations/id_AQUI/messages' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/conversions
Conversões enviadas (ou não) às plataformas de anúncios, e o desfecho.
Saídas: 200 envelope; 400 parâmetro/cursor inválido; 503 se o CRM não responde.
Parâmetros: limit (query); cursor (query); created_after (query)
Respostas: 200 OK; 400 `InvalidParameter`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 CRM indisponível.

curl -X GET 'https://api.asender.net/v1/conversions' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/dns/changes
Histórico das alterações de DNS da conta.
Parâmetros: zone (query); page (query); per_page (query)
Respostas: 200 Alterações e total.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem o escopo (`InsufficientScope`), chave de app OAuth, conta suspensa, escrita fora de produção (`NonProductionBlocked`) ou o token Cloudflare sem permissão na zona (`ProviderPermissionDenied`). `Error.Details.Code` traz o código estável do serviço de DNS.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 Serviço de DNS fora do ar ou a Cloudflare indisponível (`ServiceUnavailable`/`ProviderUnavailable`); tente de novo depois de `Retry-After`.

curl -X GET 'https://api.asender.net/v1/dns/changes' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/dns/zones
Lista as zonas de DNS da conta.
Respostas: 200 Zonas e avisos, em inglês e snake_case.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem o escopo (`InsufficientScope`), chave de app OAuth, conta suspensa, escrita fora de produção (`NonProductionBlocked`) ou o token Cloudflare sem permissão na zona (`ProviderPermissionDenied`). `Error.Details.Code` traz o código estável do serviço de DNS.; 404 Zona, registro ou conexão inexistente **ou de outra conta** (`NotFound`, idêntico nos dois casos).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 Serviço de DNS fora do ar ou a Cloudflare indisponível (`ServiceUnavailable`/`ProviderUnavailable`); tente de novo depois de `Retry-After`.

curl -X GET 'https://api.asender.net/v1/dns/zones' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/dns/zones/{zona}/records
Lista os registros de uma zona.
Parâmetros: type (query); name (query); page (query); per_page (query)
Respostas: 200 Registros e total.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem o escopo (`InsufficientScope`), chave de app OAuth, conta suspensa, escrita fora de produção (`NonProductionBlocked`) ou o token Cloudflare sem permissão na zona (`ProviderPermissionDenied`). `Error.Details.Code` traz o código estável do serviço de DNS.; 404 Zona, registro ou conexão inexistente **ou de outra conta** (`NotFound`, idêntico nos dois casos).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 Serviço de DNS fora do ar ou a Cloudflare indisponível (`ServiceUnavailable`/`ProviderUnavailable`); tente de novo depois de `Retry-After`.

curl -X GET 'https://api.asender.net/v1/dns/zones/zona_AQUI/records' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/dns/zones/{zona}/records
Cria um registro de DNS na zona.
Parâmetros: dry_run (query); X-Asender-Confirmar (header); Idempotency-Key (header)
Respostas: 200 Com `dry_run`, o plano (nada foi alterado).; 201 Registro criado.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem o escopo (`InsufficientScope`), chave de app OAuth, conta suspensa, escrita fora de produção (`NonProductionBlocked`) ou o token Cloudflare sem permissão na zona (`ProviderPermissionDenied`). `Error.Details.Code` traz o código estável do serviço de DNS.; 404 Zona, registro ou conexão inexistente **ou de outra conta** (`NotFound`, idêntico nos dois casos).; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 Recusado pelas regras do DNS: `ProtectedRecord` (NS no apex), `ProviderRejected` (a Cloudflare não aceitou), `IdempotencyKeyReused`. `Error.Details` traz `Code` e `Detail`.; 428 `ConfirmationRequired`: envie `X-Asender-Confirmar` com o nome do registro (ou use `dry_run=1` para pré-visualizar).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 Serviço de DNS fora do ar ou a Cloudflare indisponível (`ServiceUnavailable`/`ProviderUnavailable`); tente de novo depois de `Retry-After`.

curl -X POST 'https://api.asender.net/v1/dns/zones/zona_AQUI/records' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### PATCH /v1/dns/zones/{zona}/records/{rid}
Altera um registro de DNS (parcial).
Parâmetros: dry_run (query); X-Asender-Confirmar (header); Idempotency-Key (header)
Respostas: 200 Registro alterado (`record`), ou o plano quando há `dry_run`.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem o escopo (`InsufficientScope`), chave de app OAuth, conta suspensa, escrita fora de produção (`NonProductionBlocked`) ou o token Cloudflare sem permissão na zona (`ProviderPermissionDenied`). `Error.Details.Code` traz o código estável do serviço de DNS.; 404 Zona, registro ou conexão inexistente **ou de outra conta** (`NotFound`, idêntico nos dois casos).; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 422 Recusado pelas regras do DNS: `ProtectedRecord` (NS no apex), `ProviderRejected` (a Cloudflare não aceitou), `IdempotencyKeyReused`. `Error.Details` traz `Code` e `Detail`.; 428 `ConfirmationRequired`: envie `X-Asender-Confirmar` com o nome do registro (ou use `dry_run=1` para pré-visualizar).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 Serviço de DNS fora do ar ou a Cloudflare indisponível (`ServiceUnavailable`/`ProviderUnavailable`); tente de novo depois de `Retry-After`.

curl -X PATCH 'https://api.asender.net/v1/dns/zones/zona_AQUI/records/rid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/dns/zones/{zona}/records/{rid}
Apaga um registro de DNS.
Parâmetros: dry_run (query); X-Asender-Confirmar (header); Idempotency-Key (header)
Respostas: 200 Apagado (`deleted`), ou o plano quando há `dry_run`.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem o escopo (`InsufficientScope`), chave de app OAuth, conta suspensa, escrita fora de produção (`NonProductionBlocked`) ou o token Cloudflare sem permissão na zona (`ProviderPermissionDenied`). `Error.Details.Code` traz o código estável do serviço de DNS.; 404 Zona, registro ou conexão inexistente **ou de outra conta** (`NotFound`, idêntico nos dois casos).; 422 Recusado pelas regras do DNS: `ProtectedRecord` (NS no apex), `ProviderRejected` (a Cloudflare não aceitou), `IdempotencyKeyReused`. `Error.Details` traz `Code` e `Detail`.; 428 `ConfirmationRequired`: envie `X-Asender-Confirmar` com o nome do registro (ou use `dry_run=1` para pré-visualizar).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 Serviço de DNS fora do ar ou a Cloudflare indisponível (`ServiceUnavailable`/`ProviderUnavailable`); tente de novo depois de `Retry-After`.

curl -X DELETE 'https://api.asender.net/v1/dns/zones/zona_AQUI/records/rid_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/emails
Histórico de emails do tenant da API key.
Onde é usada: API pública do cliente.
Entradas: `status`, `q`, `cursor`, `limit` (allowlist). `channel` do cliente é IGNORADO: nesta rota o canal é do contrato, não do parâmetro.
Saídas: 200 com `{Messages, NextCursor, HasMore}`; 422 em query malformada.
Parâmetros: status (query); q (query); cursor (query); limit (query); created_after (query)
Respostas: 200 Página de mensagens.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/v1/emails' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/emails/{id}
Um email com corpo, metadata e timeline de eventos.
Onde é usada: API pública do cliente.
Saídas: 200 com `{Message, Events}`; 404 quando o id não é do tenant (o asender_mkt_api já responde 404 nesse caso, sem confirmar existência) ou quando o id aponta para outro canal — nesta rota só email existe. DEFEITO QUE ESTE HANDLER FECHA (T4 LOW-10 / item 6 do briefing Y2 — oráculo de enumeração): os dois 404 tinham mensagens DIFERENTES. Id inexistente devolvia "Resource not found." (vindo do writeUpstreamError) e id existente no próprio tenant, mas de outro canal, devolvia "Email not found.". Status igual, corpo distinto: bastava comparar a string para descobrir, sem autorização para aquele recurso, QUAIS ids existem — e ainda de brinde o canal deles. O escopo do vazamento era o próprio tenant (id de outro tenant já respondia "Resource not found."), o que mantém a severidade baixa, mas o §22.8 exige que existente-mas-negado e inexistente sejam INDISTINGUÍVEIS. Agora as duas saídas usam a mesma constante.
Parâmetros: id (path, obrigatório)
Respostas: 200 Detalhe.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.

curl -X GET 'https://api.asender.net/v1/emails/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/emails/batch
Até 500 emails independentes numa chamada.
Onde é usada: API pública do cliente.
Saídas: 202 com `{Results, Count}`; cada item traz MessageId ou Error.
Efeitos: escrita no serviço de mensageria por item aceito.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Lote processado (com ou sem itens rejeitados).; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.

curl -X POST 'https://api.asender.net/v1/emails/batch' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/emails/send
Enfileira um email (payload compatível com SES SendEmail).
Onde é usada: API pública do cliente (autenticada por API key).
Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency, Suppressed?}`; 400 em validação local; 422 quando o asender_mkt_api recusa — com o código `RemetenteNaoVerificado` quando o Source não é de domínio verificado da conta (2026-10-02: antes o e-mail saía com o remetente da plataforma); 503 `VerificacaoIndisponivel` quando a verificação está fora; 502 se ele está fora.
Efeitos: escrita no serviço de mensageria. Idempotente por IdempotencyKey.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Aceito e persistido; a entrega é assíncrona. Destinatários suprimidos vêm em `Suppressed[]`. Com o serviço de mensageria indisponível, `Status: accepted` (spool durável; replay com a mesma `Idempotency-Key`).; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 409 `409 IdempotencyConflict` — a `Idempotency-Key` já foi usada com um corpo
DIFERENTE. Nada foi enviado. Use uma chave nova, ou reenvie o corpo
original para obter o replay (`ReusedIdempotency: true`).; 422 `422 SuppressedRecipient` — TODOS os destinatários estão suprimidos; nada
foi enfileirado. `Message` traz o(s) texto(s) humano(s) e
`Details.Suppressed[]` a lista `{Email, Reason, Message}`.

`422 RemetenteNaoVerificado` — o remetente não é de domínio verificado
nesta conta (ver `RemetenteOuInvalido`). `422 ValidationError` — demais
recusas do upstream.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.; 503 `503 VerificacaoIndisponivel` — a verificação do domínio do remetente
não respondeu. Fail-closed: nada foi enfileirado. Repita depois do
`Retry-After` (com a mesma `Idempotency-Key`).

curl -X POST 'https://api.asender.net/v1/emails/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/forms
Formulários da conta e o schema dos seus campos.
Saídas: 200 envelope; 400 parâmetro inválido; 503 se o pages_api não responde.
Parâmetros: limit (query); cursor (query)
Respostas: 200 OK; 400 `InvalidParameter`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 Pages indisponível.

curl -X GET 'https://api.asender.net/v1/forms' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/forms/{id}/submissions
Envios de um formulário, do mais antigo ao mais novo.
Saídas: 200 envelope; 400 parâmetro/cursor inválido; 404 formulário inexistente ou de outra conta; 503 se pages_api ou runtime não respondem.
Parâmetros: id (path, obrigatório); limit (query); cursor (query); created_after (query)
Respostas: 200 OK; 400 `InvalidParameter`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 404 Formulário não encontrado.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 Pages ou runtime indisponível.

curl -X GET 'https://api.asender.net/v1/forms/id_AQUI/submissions' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/journeys
Jornadas da conta (incremental).
Onde é usada: a busca do cabeçalho do hub (`asender_plataforma_front`, components/busca-do-app.tsx).
Erros: 400 termo; 401 sem sessão; 404 conta alheia (resolveSessionTenant — nunca 403, que seria oráculo); 502 se o PDP não responde (sem ele não há como saber o que a pessoa pode ver: nega).
Parâmetros: updated_after (query); limit (query); cursor (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/journeys' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/journeys/{id}
Uma jornada.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 404 `404 NotFound` — o recurso não existe **ou é de outra conta** (mesma resposta).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/journeys/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/leads
Leads da conta, em ordem de atualização (sincronização incremental).
Saídas: 200 envelope; 400 parâmetro/cursor inválido; 503 se o CRM não responde.
Parâmetros: limit (query); cursor (query); updated_after (query)
Respostas: 200 OK; 400 `InvalidParameter`.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 CRM indisponível (`ServiceUnavailable`, `Retry-After`).

curl -X GET 'https://api.asender.net/v1/leads' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/leads
Cria um lead na conta.
Saídas: 201 com o lead; 400 corpo inválido; 409 `Conflict` (já existe lead com esse e-mail/telefone) ou `IdempotencyInProgress`; 422 `IdempotencyKeyReused`; 403 token OAuth; 413; 503 se o CRM não responde.
Parâmetros: Idempotency-Key (header)
Respostas: 201 Lead criado (ou resultado guardado, se for repetição da mesma `Idempotency-Key`).; 400 `ValidationError`: campo desconhecido, tipo errado, e-mail/telefone/etapa/país inválido ou nenhum identificador.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 409 `Conflict` (já existe lead com esse e-mail/telefone) ou `IdempotencyInProgress` (`Retry-After`).; 413 `PayloadTooLarge` (corpo acima de 256 KiB).; 422 `IdempotencyKeyReused` ou `Idempotency-Key` malformada (`ValidationError`).; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 CRM indisponível (`ServiceUnavailable`, `Retry-After`).

curl -X POST 'https://api.asender.net/v1/leads' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/leads/{id}
Um lead pelo id público.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 404 Lead não encontrado.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 CRM indisponível.

curl -X GET 'https://api.asender.net/v1/leads/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/leads/{id}
Atualiza parcialmente um lead.
Parâmetros: id (path, obrigatório); Idempotency-Key (header)
Respostas: 200 Lead atualizado (ou resultado guardado, se for repetição da mesma `Idempotency-Key`).; 400 `ValidationError` (corpo vazio, campo desconhecido ou valor inválido).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 404 Lead não encontrado (inexistente ou de outra conta).; 409 `IdempotencyInProgress` (`Retry-After`).; 413 `PayloadTooLarge`.; 422 `IdempotencyKeyReused` ou `Idempotency-Key` malformada.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 CRM indisponível.

curl -X PATCH 'https://api.asender.net/v1/leads/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/logs
Log das requisições feitas à API com as chaves da conta (sem corpos).
Onde é usada: API pública do cliente.
Entradas: `status`, `q`, `cursor`, `limit` (allowlist). `channel` do cliente é IGNORADO: nesta rota o canal é do contrato, não do parâmetro.
Saídas: 200 com `{Messages, NextCursor, HasMore}`; 422 em query malformada.
Parâmetros: limit (query); after (query); before (query); status_class (query); status (query); method (query); path (query); api_key_id (query); error_code (query); idempotency_key (query); message_id (query); mode (query); since (query); until (query)
Respostas: 200 OK; 400 `400 ValidationError` — parâmetro inválido, cursor adulterado ou de outra
conta, `after` com `before`. Corpo repassado do serviço de logs
(`LogsErrorEnvelope`).; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 InsufficientScope` (chave sem `logs:read`) ou `403 TenantSuspended`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` — o serviço de logs não respondeu. Repita depois
do `Retry-After`; o resto da API segue funcionando.

curl -X GET 'https://api.asender.net/v1/logs' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/logs/{id}
Detalhe de uma requisição, com os corpos já redigidos.
Parâmetros: id (path, obrigatório)
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 InsufficientScope` (chave sem `logs:read`) ou `403 TenantSuspended`.; 404 `404 NotFound` — id inexistente **ou de outra conta** (corpo idêntico, sem
oráculo de existência). Corpo repassado do serviço de logs.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 ServiceUnavailable` — o serviço de logs não respondeu. Repita depois
do `Retry-After`; o resto da API segue funcionando.

curl -X GET 'https://api.asender.net/v1/logs/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/me
Quem autorizou o app OAuth, em que conta e com que escopos (só token OAuth, escopo openid).
Onde é usada: GET /v1/me, depois do PublicAuth + dados.ExigirProduto("").
Erros: 401 sem principal OAuth; 502 se o core falha.
Respostas: 200 OK (JSON em snake_case, sem RequestId); 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 Sem o escopo openid, chave sk_* (rota só de OAuth) ou usuário sem acesso à conta.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/v1/me' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/messaging/push/messages
Mensagens de push enviadas pela conta (incremental).
Parâmetros: limit (query); cursor (query); created_after (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/messaging/push/messages' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/messaging/push/reports/overview
Panorama de push da conta.
Parâmetros: days (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/messaging/push/reports/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/messaging/sms/messages
Mensagens de SMS enviadas pela conta (incremental).
Parâmetros: limit (query); cursor (query); created_after (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/messaging/sms/messages' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/messaging/sms/reports/overview
Panorama de SMS da conta.
Parâmetros: days (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/messaging/sms/reports/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/messaging/whatsapp/messages
Mensagens de WhatsApp enviadas pela conta (incremental).
Parâmetros: limit (query); cursor (query); created_after (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/messaging/whatsapp/messages' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/messaging/whatsapp/reports/overview
Panorama de WhatsApp da conta.
Parâmetros: days (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/messaging/whatsapp/reports/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/push/devices
Registra (upsert por token) um device de push.
Onde é usada: SDK do cliente, na primeira abertura do app / renovação do token.
Saídas: 200 com `{Device}` (upsert: o mesmo token duas vezes não cria dois registros); 400 em validação local; 422 quando o upstream recusa a plataforma.
Efeitos: escrita no serviço de mensageria. # Chave de servidor vinda do navegador é recusada (M15) O snippet antigo mandava colar a API key de SERVIDOR no site. Pedido com `Origin`/`Sec-Fetch-*` aqui significa exatamente isso: a chave está num JavaScript público. Recusa com 403 `ServerKeyInBrowser` e loga em Warn com o id da chave, para o dono ser avisado e rotacioná-la. Sem janela de compatibilidade: esta rota nunca respondeu CORS, então nenhum site conseguiu usá-la do navegador com sucesso — não há base instalada a preservar (ADR 0057). O caminho do navegador é `POST /v1/push/site/devices`, com a chave de site.
Respostas: 200 Device registrado ou reativado.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `TenantSuspended` (tenant não-`active`) ou `ServerKeyInBrowser`
(API key de servidor usada a partir de navegador).; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.

curl -X POST 'https://api.asender.net/v1/push/devices' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/push/devices
Lista os devices de push da conta da API key.
Onde é usada: SDK/integração do cliente e diagnóstico de entrega.
Entradas: `cursor`, `limit`.
Saídas: 200 com `{Devices, NextCursor, HasMore}`; 422 em query malformada. O tenant vem do Principal, NUNCA da query: aceitar `tenant_id` do cliente aqui seria vazamento cross-tenant direto.
Parâmetros: cursor (query); limit (query)
Respostas: 200 Página de devices, em PascalCase.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.

curl -X GET 'https://api.asender.net/v1/push/devices' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/push/send
Enfileira um push para aparelhos registrados (DeviceTokens).
Onde é usada: API pública do cliente (autenticada por API key).
Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency}`; 400 em validação local; 422 quando o asender_mkt_api recusa; 502 se ele está fora.
Efeitos: escrita no serviço de mensageria. Idempotente por IdempotencyKey.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Aceito e persistido; a entrega é assíncrona. Com o serviço dono indisponível, `Status: accepted` (spool durável, replay com a mesma `Idempotency-Key`).; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 409 `409 IdempotencyConflict` — a `Idempotency-Key` já foi usada com um corpo
DIFERENTE. Nada foi enviado. Use uma chave nova, ou reenvie o corpo
original para obter o replay (`ReusedIdempotency: true`).; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/v1/push/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/push/site/devices
Registra a inscrição de Web Push do visitante, a partir do navegador.
Onde é usada: snippet de push colado no site do cliente (`asenderSubscribePush`).
Saídas: 200 `{Status: "registered"}`; 400 validação; 401 principal ausente ou tenant inexistente; 403 tenant suspenso; 5xx de upstream mapeado.
Efeitos: escrita em messages.push_devices. A resposta NÃO devolve o device: quem chama é um visitante anônimo, e o registro interno (ids, contato, tenant) não é assunto dele.
Parâmetros: site_key (query, obrigatório); Origin (header, obrigatório)
Respostas: 200 Inscrição registrada ou reativada.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `OriginNotAllowed` (origem ausente/não declarada) ou `TenantSuspended`.; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 Segredo de verificação da chave de site ausente.

curl -X POST 'https://api.asender.net/v1/push/site/devices' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/reports/email/domains
Desempenho por domínio/provedor de destino.
Onde é usada: overview, breakdown, timeseries e forms (lista).
Parâmetros: from (query); to (query); period (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/reports/email/domains' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/reports/email/overview
Panorama de e-mail da conta.
Onde é usada: overview, breakdown, timeseries e forms (lista).
Parâmetros: days (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/reports/email/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/reports/email/timeseries
Série temporal de e-mail.
Onde é usada: overview, breakdown, timeseries e forms (lista).
Parâmetros: from (query); to (query); period (query); granularity (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/reports/email/timeseries' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/reports/email/top-emails
E-mails com melhor (ou maior) desempenho.
Onde é usada: overview, breakdown, timeseries e forms (lista).
Parâmetros: from (query); to (query); period (query); order (query); limit (query); min_delivered (query)
Respostas: 200 OK; 400 `400 InvalidParameter` — janela, filtro, `limit`, `cursor`, `dimension` ou parâmetro desconhecido.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403` — credencial sem o escopo da rota (`InsufficientScope`), conta suspensa (`TenantSuspended`)
ou, para app OAuth, o usuário que autorizou o app não tem mais acesso à conta ou ao produto
(`Forbidden`). Chave `sk_*` recebe o envelope legado (`ErrorEnvelope`); app OAuth recebe `DataError`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 UpstreamError` — a ferramenta de origem respondeu com erro; o corpo dela nunca é repassado.; 503 `503 ServiceUnavailable` com `Retry-After` — a fonte dos dados está fora; o resto da API não é afetado.

curl -X GET 'https://api.asender.net/v1/reports/email/top-emails' \
  -H 'Authorization: Bearer SEU_TOKEN'

### GET /v1/senders
Remetentes que a chave pode usar como `from` (domínios e caixas da conta).
Onde é usada: superfície pública /v1, escopo email:send (RouteScopes).
Saídas: 200; 401 sem tenant no contexto; 503 com Retry-After se o mail falhar.
Efeitos: leituras no mail_api; falha vai ao log com o request id.
Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `503 SendersUnavailable` — o diretório de remetentes (Mail API) não
respondeu. Repita depois do `Retry-After`.

curl -X GET 'https://api.asender.net/v1/senders' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/sms/send
Enfileira um SMS.
Onde é usada: API pública do cliente (autenticada por API key).
Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency, Suppressed?}`; 400 em validação local; 422 quando o asender_mkt_api recusa — com o código `RemetenteNaoVerificado` quando o Source não é de domínio verificado da conta (2026-10-02: antes o e-mail saía com o remetente da plataforma); 503 `VerificacaoIndisponivel` quando a verificação está fora; 502 se ele está fora.
Efeitos: escrita no serviço de mensageria. Idempotente por IdempotencyKey.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Aceito e persistido; a entrega é assíncrona. Com o serviço dono indisponível, `Status: accepted` (spool durável, replay com a mesma `Idempotency-Key`).; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 409 `409 IdempotencyConflict` — a `Idempotency-Key` já foi usada com um corpo
DIFERENTE. Nada foi enviado. Use uma chave nova, ou reenvie o corpo
original para obter o replay (`ReusedIdempotency: true`).; 422 `422 ValidationError` — semântica inválida: parâmetro de query fora da
allowlist (nomeando o parâmetro), `from > to`, `depth` negativa, corpo
de PATCH sem o campo obrigatório, ou recusa do upstream repassada.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/v1/sms/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/telegram/send
Envia uma mensagem de texto por Telegram, pelo bot da conta.
Onde é usada: API pública do cliente (autenticada por API key).
Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency, Suppressed?}`; 400 em validação local; 422 quando o asender_mkt_api recusa — com o código `RemetenteNaoVerificado` quando o Source não é de domínio verificado da conta (2026-10-02: antes o e-mail saía com o remetente da plataforma); 503 `VerificacaoIndisponivel` quando a verificação está fora; 502 se ele está fora.
Efeitos: escrita no serviço de mensageria. Idempotente por IdempotencyKey.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Aceito e enfileirado; a entrega é assíncrona.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `InsufficientScope` (a chave não tem `telegram:send`), `TenantSuspended` ou `ServerKeyInBrowser`.; 404 `NotFound`: o `BotId` não existe nesta conta.; 409 `409 IdempotencyConflict` — a `Idempotency-Key` já foi usada com um corpo
DIFERENTE. Nada foi enviado. Use uma chave nova, ou reenvie o corpo
original para obter o replay (`ReusedIdempotency: true`).; 422 `ChatNaoIniciado`: esse chat nunca enviou `/start` ao bot (ou `ValidationError` na chave `Idempotency-Key`). Nada é enviado.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `ServiceUnavailable`: o canal de Telegram está fora do ar ou não está configurado. Traz `Retry-After`; repita depois.

curl -X POST 'https://api.asender.net/v1/telegram/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/telegramconta/send
Envia uma mensagem de texto pela conta do Telegram (não por bot).
Onde é usada: API pública do cliente (autenticada por API key).
Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency, Suppressed?}`; 400 em validação local; 422 quando o asender_mkt_api recusa — com o código `RemetenteNaoVerificado` quando o Source não é de domínio verificado da conta (2026-10-02: antes o e-mail saía com o remetente da plataforma); 503 `VerificacaoIndisponivel` quando a verificação está fora; 502 se ele está fora.
Efeitos: escrita no serviço de mensageria. Idempotente por IdempotencyKey.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Aceito e enfileirado; a entrega é assíncrona.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `InsufficientScope` (a chave não tem `telegramconta:send`), `TenantSuspended` ou `ServerKeyInBrowser`.; 404 `NotFound`: o `SessionId` não existe nesta conta.; 409 `409 IdempotencyConflict` — a `Idempotency-Key` já foi usada com um corpo
DIFERENTE. Nada foi enviado. Use uma chave nova, ou reenvie o corpo
original para obter o replay (`ReusedIdempotency: true`).; 422 `DialogoInexistente`: a conta não tem conversa com esse destino. Nada é enviado. Também `ValidationError` na chave `Idempotency-Key`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `ServiceUnavailable`: o canal está fora do ar ou não está configurado. Traz `Retry-After`; repita depois.

curl -X POST 'https://api.asender.net/v1/telegramconta/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/webhooks
Lista os endpoints de webhook da conta da API key.
Onde é usada: API pública do cliente.
Entradas: `status`, `q`, `cursor`, `limit` (allowlist). `channel` do cliente é IGNORADO: nesta rota o canal é do contrato, não do parâmetro.
Saídas: 200 com `{Messages, NextCursor, HasMore}`; 422 em query malformada.
Respostas: 200 Endpoints da conta, em PascalCase.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/v1/webhooks' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/webhooks
Cadastra um endpoint de webhook.
Onde é usada: fluxo de cadastro (AuthHandler.Register faz o equivalente internamente) e recuperação manual quando o provisionamento automático falhou.
Entradas: `{Name, Slug}` — allowlist explícita, ver tenantCreateInput.
Saídas: 201 com `{Tenant:{Id,...}}` em PascalCase; 400 JSON inválido OU campo fora da allowlist; 422 nome vazio; o status 4xx do core preservado; 502 quando o core está fora.
Efeitos: escreve no asender-core. O `owner_user_id` vem SEMPRE do principal verificado, nunca do corpo.
Respostas: 201 Endpoint criado; o `Secret` só aparece nesta resposta.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 413 `413 PayloadTooLarge` — corpo acima de 2 MiB.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/v1/webhooks' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /v1/webhooks/{id}
Um endpoint de webhook da conta.
Respostas: 200 O endpoint.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X GET 'https://api.asender.net/v1/webhooks/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### PATCH /v1/webhooks/{id}
Altera URL, eventos e/ou estado de um endpoint.
Onde é usada: API pública, escopo `webhooks:manage`.
Respostas: 200 O endpoint atualizado.; 400 `400 ValidationError` — JSON inválido, campo desconhecido (a mensagem nomeia o campo: `unknown field "X"`) ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X PATCH 'https://api.asender.net/v1/webhooks/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### DELETE /v1/webhooks/{id}
Apaga um endpoint de webhook.
Onde é usada: API pública, escopo `webhooks:manage`.
Respostas: 204 Apagado. Sem corpo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X DELETE 'https://api.asender.net/v1/webhooks/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

### POST /v1/webhooks/{id}/test
Envia um evento `webhook.test` assinado a UM endpoint.
Onde é usada: API pública, escopo `webhooks:manage`.
Parâmetros: id (path, obrigatório)
Respostas: 200 Resultado do envio de teste.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `403 TenantSuspended` — a API key é válida mas o tenant não está `active`. Fail closed: status vazio também barra.; 404 `404 NotFound`. **Cobre dois casos de propósito:** o recurso não existe,
ou existe e não é seu. Diferenciar seria oráculo de enumeração.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/v1/webhooks/id_AQUI/test' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/whatsapp/send
Enfileira uma mensagem de WhatsApp (texto livre ou template).
Onde é usada: API pública do cliente (autenticada por API key).
Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency, Suppressed?}`; 400 em validação local; 422 quando o asender_mkt_api recusa — com o código `RemetenteNaoVerificado` quando o Source não é de domínio verificado da conta (2026-10-02: antes o e-mail saía com o remetente da plataforma); 503 `VerificacaoIndisponivel` quando a verificação está fora; 502 se ele está fora.
Efeitos: escrita no serviço de mensageria. Idempotente por IdempotencyKey.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Aceito e enfileirado; a entrega é assíncrona.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `TenantSuspended` (conta não ativa) ou `ServerKeyInBrowser` (chave de servidor usada de um navegador).; 409 `409 IdempotencyConflict` — a `Idempotency-Key` já foi usada com um corpo
DIFERENTE. Nada foi enviado. Use uma chave nova, ou reenvie o corpo
original para obter o replay (`ReusedIdempotency: true`).; 422 `ValidationError`: template inexistente na conta, variáveis em número errado, ou todos os destinatários fora do canal (opt-out). Nada é enfileirado nem cobrado.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 502 `502 InternalError` — upstream inalcançável ou 5xx. O motivo real fica
no log com `RequestId`; o cliente recebe mensagem genérica.

curl -X POST 'https://api.asender.net/v1/whatsapp/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### POST /v1/whatsweb/send
Envia uma mensagem de texto pelo WhatsApp da conta, via sessão do WhatsApp Web (canal não oficial).
Onde é usada: API pública do cliente (autenticada por API key).
Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency, Suppressed?}`; 400 em validação local; 422 quando o asender_mkt_api recusa — com o código `RemetenteNaoVerificado` quando o Source não é de domínio verificado da conta (2026-10-02: antes o e-mail saía com o remetente da plataforma); 503 `VerificacaoIndisponivel` quando a verificação está fora; 502 se ele está fora.
Efeitos: escrita no serviço de mensageria. Idempotente por IdempotencyKey.
Parâmetros: Idempotency-Key (header)
Respostas: 202 Aceito e enfileirado; a entrega é assíncrona.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou
expirada.; 403 `InsufficientScope` (a chave não tem `whatsweb:send`), `TenantSuspended` ou `ServerKeyInBrowser`.; 404 `NotFound`: o `SessionId` não existe nesta conta.; 409 `409 IdempotencyConflict` — a `Idempotency-Key` já foi usada com um corpo
DIFERENTE. Nada foi enviado. Use uma chave nova, ou reenvie o corpo
original para obter o replay (`ReusedIdempotency: true`).; 422 `ChatInexistente`: esse número nunca escreveu para este WhatsApp. Nada é enviado. Também `ValidationError` na chave `Idempotency-Key`.; 429 `429 Throttling` — rate limit por API key/usuário. Acompanha `Retry-After`.; 503 `ServiceUnavailable`: o canal está fora do ar ou não está configurado. Traz `Retry-After`; repita depois.

curl -X POST 'https://api.asender.net/v1/whatsweb/send' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

### GET /version
Versão e commit do binário em execução.
Onde é usada: rota pública, usada por ops e por quem investiga incidente. Pública porque a primeira pergunta de todo incidente é "que versão está no ar?", e ela tem de ser respondível sem credencial — quem investiga muitas vezes ainda não tem uma. O que sai é só isso: nunca configuração, nunca endereço interno, que é topologia e pertence ao console de plataforma.
Respostas: 200 OK

curl -X GET 'https://api.asender.net/version' \
  -H 'Authorization: Bearer SEU_TOKEN'



==============================================================================
# Atendimento  (interno)
==============================================================================

Em breve. Caixa de entrada de atendimento: conversas, timeline, estado, atribuição, filas e equipe. A API própria desta ferramenta ainda não é aberta a integradores.
Hoje, pela API pública (https://api.asender.net): ler conversas e mensagens em GET /v1/conversations e GET /v1/conversations/{id}/messages (escopo conversations:read) e responder pelos canais da caixa com POST /v1/telegram/send, /v1/whatsweb/send e /v1/telegramconta/send (escopos telegram:send, whatsweb:send e telegramconta:send).



==============================================================================
# E-mail Marketing  (interno)
==============================================================================

Em breve. Campanhas e templates de e-mail marketing, com supressão, limite de envio e cota. A API própria desta ferramenta ainda não é aberta a integradores.
Hoje, pela API pública (https://api.asender.net): enviar e-mail com POST /v1/emails/send e /v1/emails/batch (até 500 mensagens), consultar envios em GET /v1/emails, e ler campanhas e relatórios de e-mail em GET /v1/campaigns e GET /v1/reports/email/*. Escopos: email:send, email:read e campaigns:read.



==============================================================================
# Push  (interno)
==============================================================================

Em breve. Web Push: aparelhos inscritos, envio com supressão, limite de envio e cota. A API própria desta ferramenta ainda não é aberta a integradores.
Hoje, pela API pública (https://api.asender.net): enviar push com POST /v1/push/send, registrar e listar aparelhos em POST e GET /v1/push/devices (do navegador do visitante, com a chave pk_push_ em POST /v1/push/site/devices) e ler mensagens e o panorama em GET /v1/messaging/push/messages e GET /v1/messaging/push/reports/overview. Escopos: push:send, push:devices e messaging:read.



==============================================================================
# SMS  (interno)
==============================================================================

Em breve. Campanhas e envio de SMS, com supressão, limite de envio e cota. A API própria desta ferramenta ainda não é aberta a integradores.
Hoje, pela API pública (https://api.asender.net): enviar SMS com POST /v1/sms/send e ler mensagens e o panorama em GET /v1/messaging/sms/messages e GET /v1/messaging/sms/reports/overview. Escopos: sms:send e messaging:read.



==============================================================================
# WhatsApp  (interno)
==============================================================================

Em breve. Envio de WhatsApp (API oficial), com templates, supressão, limite de envio e cota. A API própria desta ferramenta ainda não é aberta a integradores.
Hoje, pela API pública (https://api.asender.net): enviar WhatsApp (texto livre ou template) com POST /v1/whatsapp/send e ler mensagens e o panorama em GET /v1/messaging/whatsapp/messages e GET /v1/messaging/whatsapp/reports/overview. Escopos: whatsapp:send e messaging:read.



==============================================================================
# SCHEMAS (OpenAPI)
==============================================================================

{
  "platform_ProtectedResourceMetadata": {
    "type": "object",
    "description": "Documento RFC 9728.",
    "properties": {
      "resource": {
        "type": "string",
        "examples": [
          "https://api.asender.net/mcp"
        ]
      },
      "authorization_servers": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "https://auth.asender.net"
          ]
        ]
      },
      "scopes_supported": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "bearer_methods_supported": {
        "type": "array",
        "items": {
          "type": "string",
          "const": "header"
        }
      },
      "resource_documentation": {
        "type": "string",
        "examples": [
          "https://developers.asender.net/guias/mcp.html"
        ]
      },
      "resource_name": {
        "type": "string",
        "const": "Asender"
      }
    }
  },
  "platform_DataError": {
    "type": "object",
    "required": [
      "error"
    ],
    "description": "Envelope de erro das rotas de dados (onda 2): `{\"error\":{\"type\",\"message\"}}`. As rotas legadas de envio mantêm o envelope `ErrorEnvelope`.",
    "properties": {
      "error": {
        "type": "object",
        "required": [
          "type",
          "message"
        ],
        "properties": {
          "type": {
            "type": "string",
            "examples": [
              "InvalidParameter"
            ],
            "description": "Código estável: `InvalidParameter`, `NotFound`, `Forbidden`, `InsufficientScope`, `AuthorizationError`, `UpstreamError`, `ServiceUnavailable`."
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "platform_DataObject": {
    "type": "object",
    "description": "Documento agregado `{\"data\": {...}}` (relatórios). Chaves em inglês `snake_case`; contadores inteiros, taxas entre 0 e 1.",
    "properties": {
      "data": {
        "type": "object",
        "additionalProperties": true
      }
    }
  },
  "platform_Campaign": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "status": {
        "type": "string"
      },
      "subject": {
        "type": "string"
      },
      "from": {
        "type": "string"
      },
      "template": {
        "type": [
          "string",
          "null"
        ]
      },
      "list_id": {
        "type": [
          "string",
          "null"
        ]
      },
      "segment_id": {
        "type": [
          "string",
          "null"
        ]
      },
      "scheduled_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "recipients": {
        "type": "integer"
      },
      "sent": {
        "type": "integer"
      },
      "failed": {
        "type": "integer"
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "updated_at": {
        "type": "string",
        "format": "date-time"
      },
      "started_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "finished_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "pause_reason": {
        "type": [
          "string",
          "null"
        ]
      },
      "recurrence_cron": {
        "type": [
          "string",
          "null"
        ]
      },
      "recurrence_tz": {
        "type": [
          "string",
          "null"
        ]
      },
      "recurrence_until": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      }
    }
  },
  "platform_CampaignList": {
    "type": "object",
    "required": [
      "data",
      "next_cursor"
    ],
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_Campaign"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_MessagingMessage": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "to": {
        "type": "string"
      },
      "status": {
        "type": "string"
      },
      "queued_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "segments": {
        "type": "integer",
        "description": "Só SMS."
      },
      "title": {
        "type": "string",
        "description": "Só push."
      }
    }
  },
  "platform_MessagingMessageList": {
    "type": "object",
    "required": [
      "data",
      "next_cursor"
    ],
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_MessagingMessage"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_DataCounts": {
    "type": "object",
    "properties": {
      "visits": {
        "type": "integer"
      },
      "pageviews": {
        "type": "integer"
      },
      "conversions": {
        "type": "integer"
      },
      "conversion_rate": {
        "type": "number",
        "description": "conversões ÷ visitas (4 casas)."
      },
      "form_views": {
        "type": "integer"
      },
      "form_starts": {
        "type": "integer"
      },
      "form_submissions": {
        "type": "integer"
      }
    }
  },
  "platform_DataAnalyticsOverview": {
    "type": "object",
    "properties": {
      "from": {
        "type": "string",
        "format": "date-time"
      },
      "to": {
        "type": "string",
        "format": "date-time"
      },
      "totals": {
        "$ref": "#/components/schemas/platform_DataCounts"
      }
    }
  },
  "platform_DataAnalyticsSeries": {
    "type": "object",
    "properties": {
      "from": {
        "type": "string",
        "format": "date-time"
      },
      "to": {
        "type": "string",
        "format": "date-time"
      },
      "interval": {
        "type": "string",
        "enum": [
          "day"
        ]
      },
      "timezone": {
        "type": "string",
        "examples": [
          "America/Sao_Paulo"
        ]
      },
      "data": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/platform_DataCounts"
            },
            {
              "type": "object",
              "properties": {
                "date": {
                  "type": "string",
                  "format": "date"
                }
              }
            }
          ]
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_DataAnalyticsBreakdown": {
    "type": "object",
    "properties": {
      "from": {
        "type": "string",
        "format": "date-time"
      },
      "to": {
        "type": "string",
        "format": "date-time"
      },
      "dimension": {
        "type": "string"
      },
      "data": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/platform_DataCounts"
            },
            {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string"
                }
              }
            }
          ]
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_DataAnalyticsForms": {
    "description": "Sem `form_id`: `data` (resumo por formulário). Com `form_id`: o funil (`totals`, `series`, `by_source`, `by_device`, `by_page`, `field_abandonment`).",
    "type": "object",
    "properties": {
      "from": {
        "type": "string",
        "format": "date-time"
      },
      "to": {
        "type": "string",
        "format": "date-time"
      },
      "form_id": {
        "type": "string"
      },
      "data": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "form_id": {
              "type": "string"
            },
            "views": {
              "type": "integer"
            },
            "starts": {
              "type": "integer"
            },
            "submissions": {
              "type": "integer"
            },
            "conversion_rate": {
              "type": "number"
            }
          }
        }
      },
      "totals": {
        "type": "object",
        "additionalProperties": true
      },
      "series": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "by_source": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "by_device": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "by_page": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "field_abandonment": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_DataConversation": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "examples": [
          "cnv_0123456789abcdef"
        ]
      },
      "channel": {
        "type": "string",
        "examples": [
          "chat"
        ]
      },
      "status": {
        "type": "string",
        "enum": [
          "aberto",
          "pendente",
          "resolvido",
          "fechado"
        ]
      },
      "priority": {
        "type": "string",
        "enum": [
          "baixa",
          "normal",
          "alta",
          "urgente"
        ]
      },
      "subject": {
        "type": "string"
      },
      "lead_id": {
        "type": [
          "string",
          "null"
        ],
        "description": "Id público do lead: o MESMO de `GET /v1/leads` (`id`)."
      },
      "assigned_to": {
        "type": [
          "string",
          "null"
        ]
      },
      "queue_id": {
        "type": [
          "string",
          "null"
        ]
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "updated_at": {
        "type": "string",
        "format": "date-time",
        "description": "Última atividade (inclui mensagem nova)."
      },
      "closed_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "message_count": {
        "type": "integer"
      }
    }
  },
  "platform_DataConversationList": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_DataConversation"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_DataMessage": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "examples": [
          "msg_0123456789abcdef"
        ]
      },
      "direction": {
        "type": "string",
        "enum": [
          "inbound",
          "outbound"
        ]
      },
      "author_type": {
        "type": "string",
        "enum": [
          "contact",
          "agent",
          "bot",
          "device",
          "api"
        ]
      },
      "type": {
        "type": "string",
        "enum": [
          "text"
        ]
      },
      "text": {
        "type": "string"
      },
      "delivery_status": {
        "type": [
          "string",
          "null"
        ]
      },
      "sent_at": {
        "type": "string",
        "format": "date-time"
      },
      "attachment_count": {
        "type": "integer"
      }
    }
  },
  "platform_DataMessageList": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_DataMessage"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_DataJourney": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "name": {
        "type": "string"
      },
      "active": {
        "type": "boolean"
      },
      "kind": {
        "type": "string",
        "enum": [
          "marketing",
          "bot"
        ]
      },
      "trigger": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "args": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "steps": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "number": {
              "type": "integer"
            },
            "type": {
              "type": "string",
              "enum": [
                "esperar",
                "agir",
                "condicao"
              ]
            },
            "action": {
              "type": "string"
            },
            "wait_seconds": {
              "type": "integer"
            }
          }
        }
      },
      "stats": {
        "type": "object",
        "properties": {
          "entries": {
            "type": "integer"
          },
          "in_progress": {
            "type": "integer"
          },
          "exits": {
            "type": "integer"
          }
        }
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "updated_at": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_DataJourneyList": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_DataJourney"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_LimitePlano": {
    "type": "object",
    "description": "Teto de um plano num domínio de quota. `null` = sem limite na escala.",
    "required": [
      "dia",
      "mes"
    ],
    "properties": {
      "dia": {
        "type": [
          "integer",
          "null"
        ],
        "format": "int64"
      },
      "mes": {
        "type": [
          "integer",
          "null"
        ],
        "format": "int64"
      }
    }
  },
  "platform_PlanoCatalogo": {
    "type": "object",
    "description": "Um plano publicado do catálogo único (ADR-0075).",
    "required": [
      "slug",
      "nome",
      "descricao",
      "preco_centavos",
      "periodo",
      "destaque",
      "cta",
      "ordem",
      "limites"
    ],
    "properties": {
      "slug": {
        "type": "string",
        "examples": [
          "basico",
          "pro",
          "business"
        ]
      },
      "nome": {
        "type": "string"
      },
      "descricao": {
        "type": "string"
      },
      "preco_centavos": {
        "type": [
          "integer",
          "null"
        ],
        "format": "int64",
        "minimum": 0,
        "description": "Preço em centavos da `moeda` do topo. `null` = sob consulta."
      },
      "periodo": {
        "type": "string",
        "enum": [
          "mes",
          "ano"
        ]
      },
      "destaque": {
        "type": "boolean"
      },
      "cta": {
        "type": "string",
        "enum": [
          "contratar",
          "contato"
        ]
      },
      "ordem": {
        "type": "integer"
      },
      "limites": {
        "type": "object",
        "description": "Domínio de quota (email_corporativo, email_marketing, sms…) → teto.",
        "additionalProperties": {
          "$ref": "#/components/schemas/platform_LimitePlano"
        }
      }
    }
  },
  "platform_CatalogoPlanos": {
    "type": "object",
    "required": [
      "moeda",
      "planos"
    ],
    "properties": {
      "moeda": {
        "type": "string",
        "minLength": 3,
        "maxLength": 3,
        "examples": [
          "BRL"
        ]
      },
      "planos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_PlanoCatalogo"
        }
      }
    }
  },
  "platform_LogsErrorEnvelope": {
    "type": "object",
    "description": "Envelope de erro do serviço de logs (repassado sem reescrita; chaves em minúsculas).",
    "properties": {
      "error": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "examples": [
              "ValidationError"
            ]
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "platform_LogResumo": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "examples": [
          "log_3f9a1c0b2d4e5f60"
        ]
      },
      "object": {
        "type": "string",
        "enum": [
          "log"
        ]
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "method": {
        "type": "string"
      },
      "path": {
        "type": "string",
        "description": "Caminho como chamado (sem a query)."
      },
      "route": {
        "type": "string",
        "description": "Padrão de rota (ex.: `/v1/emails/{id}`)."
      },
      "status": {
        "type": "integer"
      },
      "duration_ms": {
        "type": "integer"
      },
      "mode": {
        "type": "string",
        "enum": [
          "live",
          "test"
        ]
      },
      "api_key": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "idempotency_key": {
        "type": "string"
      },
      "error_code": {
        "type": "string",
        "description": "Código do envelope de erro; vazio em sucesso."
      },
      "message_ids": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Ids de mensagem devolvidos pelo envio."
      },
      "request_id": {
        "type": "string"
      }
    }
  },
  "platform_LogDetalhe": {
    "allOf": [
      {
        "$ref": "#/components/schemas/platform_LogResumo"
      },
      {
        "type": "object",
        "properties": {
          "service": {
            "type": "string"
          },
          "query": {
            "type": "string",
            "description": "Query string, já redigida."
          },
          "trace_id": {
            "type": "string"
          },
          "request_body": {
            "description": "Corpo da requisição redigido (JSON ou texto); `null` se não havia.",
            "nullable": true
          },
          "request_body_truncated": {
            "type": "boolean"
          },
          "response_body": {
            "description": "Corpo da resposta redigido; `null` se não havia.",
            "nullable": true
          },
          "response_body_truncated": {
            "type": "boolean"
          },
          "request_size": {
            "type": "integer"
          },
          "response_size": {
            "type": "integer"
          },
          "redaction_version": {
            "type": "integer"
          }
        }
      }
    ]
  },
  "platform_DataOrigem": {
    "type": "object",
    "description": "Atribuição do lead ou da conversão.",
    "properties": {
      "name": {
        "type": "string",
        "description": "Fonte declarada do lead (ex.: google, indicação)."
      },
      "utm_source": {
        "type": "string"
      },
      "utm_medium": {
        "type": "string"
      },
      "utm_campaign": {
        "type": "string"
      },
      "utm_term": {
        "type": "string"
      },
      "utm_content": {
        "type": "string"
      },
      "referrer": {
        "type": "string"
      },
      "domain": {
        "type": "string"
      },
      "form_id": {
        "type": "string"
      }
    }
  },
  "platform_Lead": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Id público do lead: o mesmo `lead_id` de conversões e conversas."
      },
      "first_name": {
        "type": "string"
      },
      "last_name": {
        "type": "string"
      },
      "email": {
        "type": "string"
      },
      "phone": {
        "type": "string"
      },
      "company": {
        "type": "string"
      },
      "job_title": {
        "type": "string"
      },
      "stage": {
        "type": "string",
        "description": "Etapa do funil no CRM (valor definido pela conta)."
      },
      "lifecycle": {
        "type": "string",
        "enum": [
          "lead",
          "contact"
        ]
      },
      "source": {
        "$ref": "#/components/schemas/platform_DataOrigem"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "custom_fields": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Campos personalizados da conta: as chaves são da conta e não são traduzidas."
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "updated_at": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_LeadCreate": {
    "type": "object",
    "additionalProperties": false,
    "description": "Corpo fechado de `POST /v1/leads`: ao menos `email` ou `phone`. Não existe `id`, `tenant_id`, dono, empresa, consentimento nem origem/UTM.",
    "anyOf": [
      {
        "required": [
          "email"
        ]
      },
      {
        "required": [
          "phone"
        ]
      }
    ],
    "properties": {
      "email": {
        "type": "string",
        "maxLength": 320,
        "description": "Identificador do lead; guardado cifrado. Não pode ser vazio quando enviado."
      },
      "phone": {
        "type": "string",
        "maxLength": 32,
        "description": "Formato internacional, 8 a 15 dígitos (ex.: `+55 11 91234-5678`); guardado cifrado."
      },
      "first_name": {
        "type": "string",
        "maxLength": 120
      },
      "last_name": {
        "type": "string",
        "maxLength": 256,
        "description": "`\"\"` limpa (PATCH)."
      },
      "job_title": {
        "type": "string",
        "maxLength": 256
      },
      "department": {
        "type": "string",
        "maxLength": 256
      },
      "country": {
        "type": "string",
        "pattern": "^[A-Z]{2}$",
        "description": "ISO 3166-1 alpha-2 em maiúsculas."
      },
      "state": {
        "type": "string",
        "maxLength": 256
      },
      "city": {
        "type": "string",
        "maxLength": 256
      },
      "language": {
        "type": "string",
        "maxLength": 256
      },
      "linkedin": {
        "type": "string",
        "maxLength": 256
      },
      "stage": {
        "type": "string",
        "enum": [
          "novo",
          "contatado",
          "qualificado",
          "cliente",
          "descartado"
        ],
        "description": "Etapa do funil (os mesmos valores que a leitura devolve). Padrão na criação: `novo`."
      },
      "tags": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "description": "No PATCH a lista SUBSTITUI a atual (vazia limpa)."
      },
      "custom_fields": {
        "type": "object",
        "maxProperties": 60,
        "additionalProperties": {
          "type": "string",
          "maxLength": 2000
        },
        "description": "Chaves de até 80 caracteres. No PATCH mescla; valor `\"\"` remove a chave."
      }
    }
  },
  "platform_LeadUpdate": {
    "type": "object",
    "additionalProperties": false,
    "minProperties": 1,
    "description": "Corpo fechado de `PATCH /v1/leads/{id}`: ao menos um campo; o que não vem é preservado.",
    "properties": {
      "email": {
        "type": "string",
        "maxLength": 320,
        "description": "Identificador do lead; guardado cifrado. Não pode ser vazio quando enviado."
      },
      "phone": {
        "type": "string",
        "maxLength": 32,
        "description": "Formato internacional, 8 a 15 dígitos (ex.: `+55 11 91234-5678`); guardado cifrado."
      },
      "first_name": {
        "type": "string",
        "maxLength": 120
      },
      "last_name": {
        "type": "string",
        "maxLength": 256,
        "description": "`\"\"` limpa (PATCH)."
      },
      "job_title": {
        "type": "string",
        "maxLength": 256
      },
      "department": {
        "type": "string",
        "maxLength": 256
      },
      "country": {
        "type": "string",
        "pattern": "^[A-Z]{2}$",
        "description": "ISO 3166-1 alpha-2 em maiúsculas."
      },
      "state": {
        "type": "string",
        "maxLength": 256
      },
      "city": {
        "type": "string",
        "maxLength": 256
      },
      "language": {
        "type": "string",
        "maxLength": 256
      },
      "linkedin": {
        "type": "string",
        "maxLength": 256
      },
      "stage": {
        "type": "string",
        "enum": [
          "novo",
          "contatado",
          "qualificado",
          "cliente",
          "descartado"
        ],
        "description": "Etapa do funil (os mesmos valores que a leitura devolve). Padrão na criação: `novo`."
      },
      "tags": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "description": "No PATCH a lista SUBSTITUI a atual (vazia limpa)."
      },
      "custom_fields": {
        "type": "object",
        "maxProperties": 60,
        "additionalProperties": {
          "type": "string",
          "maxLength": 2000
        },
        "description": "Chaves de até 80 caracteres. No PATCH mescla; valor `\"\"` remove a chave."
      }
    }
  },
  "platform_LeadList": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_Lead"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_FormField": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "label": {
        "type": "string"
      },
      "type": {
        "type": "string"
      },
      "required": {
        "type": "boolean"
      },
      "options": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "key": {
        "type": "string"
      }
    }
  },
  "platform_Form": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "external_id": {
        "type": "string"
      },
      "requires_consent": {
        "type": "boolean"
      },
      "legal_basis": {
        "type": "string"
      },
      "fields": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_FormField"
        }
      }
    }
  },
  "platform_FormList": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_Form"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_FormSubmission": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "form_id": {
        "type": "string"
      },
      "mode": {
        "type": "string",
        "enum": [
          "page",
          "snippet",
          "api"
        ]
      },
      "fields": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Valores digitados, em claro; as chaves são as do formulário e não são traduzidas."
      },
      "undecipherable": {
        "type": "boolean"
      },
      "source": {
        "type": "object",
        "properties": {
          "utm_source": {
            "type": "string"
          },
          "utm_medium": {
            "type": "string"
          },
          "utm_campaign": {
            "type": "string"
          },
          "referrer": {
            "type": "string"
          }
        }
      },
      "consent": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string"
          },
          "legal_basis": {
            "type": "string"
          },
          "at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        }
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Quando o envio foi recebido; base de `created_after`."
      }
    }
  },
  "platform_FormSubmissionList": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_FormSubmission"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_Conversion": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "lead_id": {
        "type": "string"
      },
      "type": {
        "type": "string",
        "enum": [
          "sent",
          "ignored",
          "result"
        ]
      },
      "event": {
        "type": "string"
      },
      "event_ref": {
        "type": "string"
      },
      "value": {
        "type": "string"
      },
      "currency": {
        "type": "string"
      },
      "platform": {
        "type": "string",
        "description": "meta_capi, google_ads ou tiktok_events."
      },
      "delivery_status": {
        "type": "string",
        "description": "O desfecho da entrega à plataforma (ex.: enviado, simulado, falhou, morta, ignorada_sem_consentimento)."
      },
      "reason": {
        "type": "string"
      },
      "source": {
        "$ref": "#/components/schemas/platform_DataOrigem"
      },
      "occurred_at": {
        "type": "string",
        "format": "date-time"
      },
      "created_at": {
        "type": "string",
        "format": "date-time",
        "description": "Quando o fato foi registrado; base de `created_after`."
      }
    }
  },
  "platform_ConversionList": {
    "type": "object",
    "properties": {
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_Conversion"
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "platform_LogsList": {
    "type": "object",
    "required": [
      "object",
      "has_more",
      "next",
      "data"
    ],
    "properties": {
      "object": {
        "type": "string",
        "enum": [
          "list"
        ]
      },
      "has_more": {
        "type": "boolean"
      },
      "next": {
        "type": "string",
        "description": "Cursor para `after`; vazio quando `has_more` é `false`."
      },
      "data": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_LogResumo"
        }
      }
    }
  },
  "platform_LogsSerie": {
    "type": "object",
    "properties": {
      "bucket": {
        "type": "string"
      },
      "data": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "t": {
              "type": "string",
              "format": "date-time"
            },
            "2xx": {
              "type": "integer"
            },
            "3xx": {
              "type": "integer"
            },
            "4xx": {
              "type": "integer"
            },
            "5xx": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "platform_LogsResumo": {
    "type": "object",
    "properties": {
      "total": {
        "type": "integer"
      },
      "errors_4xx": {
        "type": "integer"
      },
      "errors_5xx": {
        "type": "integer"
      },
      "error_rate": {
        "type": "number",
        "description": "(4xx+5xx)/total, de 0 a 1."
      },
      "p50_ms": {
        "type": "number"
      },
      "p95_ms": {
        "type": "number"
      },
      "by_route": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "method": {
              "type": "string"
            },
            "route": {
              "type": "string"
            },
            "total": {
              "type": "integer"
            },
            "errors": {
              "type": "integer"
            },
            "error_rate": {
              "type": "number"
            },
            "p95_ms": {
              "type": "number"
            }
          }
        }
      },
      "by_error_code": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            },
            "count": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "platform_ErrorEnvelope": {
    "type": "object",
    "required": [
      "Error",
      "RequestId"
    ],
    "properties": {
      "Error": {
        "type": "object",
        "required": [
          "Type",
          "Code",
          "Message"
        ],
        "properties": {
          "Type": {
            "type": "string",
            "enum": [
              "Sender",
              "Receiver"
            ],
            "description": "Derivado do status: 4xx→Sender, 5xx→Receiver. O SDK decide retry por aqui."
          },
          "Code": {
            "type": "string",
            "examples": [
              "ValidationError",
              "AuthorizationError",
              "NotFound",
              "TenantSuspended",
              "NoTenant",
              "Conflict",
              "PayloadTooLarge",
              "Throttling",
              "InternalError"
            ]
          },
          "Message": {
            "type": "string"
          },
          "Details": {
            "description": "Presente só na validação SES do `/v1/*`: mapa campo → motivo. Omitido quando vazio.",
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "platform_FrotaPontos": {
    "type": "array",
    "description": "Serie de ate 72 pontos (passo 300 s); buracos ficam ausentes, sem interpolacao. Cpu/Ram/Disco em percentual 0-100; carga em razao por nucleo.",
    "items": {
      "type": "object",
      "properties": {
        "T": {
          "type": "integer",
          "format": "int64",
          "description": "Segundos Unix UTC."
        },
        "V": {
          "type": "number"
        }
      }
    }
  },
  "platform_RequestIdEnvelope": {
    "type": "object",
    "required": [
      "RequestId"
    ],
    "properties": {
      "RequestId": {
        "type": "string",
        "description": "Presente em TODA resposta de sucesso. Espelha o header\n`X-Request-Id`. **Divergência:** um `X-Request-Id` mandado pelo\ncliente é ecoado cru e vira o correlation id do log\n(RELATORIO-FINAL §3 item 15)."
      }
    }
  },
  "platform_CursorPage": {
    "type": "object",
    "properties": {
      "NextCursor": {
        "type": "integer",
        "description": "Cursor da próxima página; 0 quando acabou."
      },
      "HasMore": {
        "type": "boolean"
      }
    }
  },
  "platform_Channel": {
    "type": "string",
    "enum": [
      "email",
      "sms",
      "push"
    ]
  },
  "platform_MessageStatus": {
    "type": "string",
    "enum": [
      "queued",
      "sending",
      "sent",
      "delivered",
      "bounced",
      "failed",
      "opened",
      "clicked",
      "suppressed"
    ],
    "description": "`suppressed` — o Asender decidiu NÃO enviar (supressão global; ver\n`SuppressionReason`). Não é falha nem bounce e não entra nessas taxas."
  },
  "platform_SuppressionReason": {
    "type": "string",
    "description": "Por que o envio foi suprimido (ADR-0134 D4). `Message`/`ErrorMessage` trazem o texto humano correspondente.",
    "enum": [
      "tld_inexistente",
      "dominio_de_teste",
      "dominio_inexistente",
      "dominio_sem_correio",
      "caixa_inexistente",
      "recusas_repetidas",
      "manual",
      "supressao_global",
      "descadastro"
    ],
    "x-enum-descriptions": {
      "tld_inexistente": "O TLD do domínio não existe na lista da IANA.",
      "dominio_de_teste": "Domínio reservado para teste (.test, .invalid, .example, example.*…).",
      "dominio_inexistente": "O domínio não existe (sem MX nem A).",
      "dominio_sem_correio": "O domínio declara que não recebe e-mail (null MX).",
      "caixa_inexistente": "A caixa não existe (recusada pelo provedor).",
      "recusas_repetidas": "O endereço recusou 2 envios em 30 dias.",
      "manual": "Endereço na supressão global por entrada manual.",
      "supressao_global": "Destinatário na supressão global (origem desconhecida/legado).",
      "descadastro": "O destinatário se descadastrou de e-mails desta conta."
    }
  },
  "platform_SuppressedRecipient": {
    "type": "object",
    "required": [
      "Email",
      "Reason",
      "Message"
    ],
    "properties": {
      "Email": {
        "type": "string"
      },
      "Reason": {
        "$ref": "#/components/schemas/platform_SuppressionReason"
      },
      "Message": {
        "type": "string",
        "description": "Texto humano em português; pode ser exibido ao usuário final."
      },
      "MessageId": {
        "type": "string",
        "description": "Id da linha `suppressed` persistida (consultável em `GET /v1/emails/{id}` e na tela Envios do painel). Ausente se a persistência estava indisponível."
      }
    }
  },
  "platform_ErrorEnvelopeSuppressed": {
    "type": "object",
    "required": [
      "Error",
      "RequestId"
    ],
    "description": "Como `ErrorEnvelope`, mas `Details` pode trazer `Suppressed[]` (código `SuppressedRecipient`).",
    "properties": {
      "Error": {
        "type": "object",
        "required": [
          "Type",
          "Code",
          "Message"
        ],
        "properties": {
          "Type": {
            "type": "string",
            "enum": [
              "Sender",
              "Receiver"
            ]
          },
          "Code": {
            "type": "string",
            "examples": [
              "SuppressedRecipient",
              "RemetenteNaoVerificado",
              "ValidationError"
            ]
          },
          "Message": {
            "type": "string"
          },
          "Details": {
            "type": "object",
            "properties": {
              "Suppressed": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/platform_SuppressedRecipient"
                }
              }
            },
            "additionalProperties": true
          }
        }
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "platform_Message": {
    "type": "object",
    "description": "Projeção de listagem: SEM corpo (payload grande em lista é desperdício).",
    "properties": {
      "Id": {
        "type": "string"
      },
      "TenantId": {
        "type": "string"
      },
      "Channel": {
        "$ref": "#/components/schemas/platform_Channel"
      },
      "Status": {
        "$ref": "#/components/schemas/platform_MessageStatus"
      },
      "From": {
        "type": "string"
      },
      "To": {
        "type": "string"
      },
      "Subject": {
        "type": "string"
      },
      "Provider": {
        "type": [
          "string",
          "null"
        ]
      },
      "ProviderMessageId": {
        "type": [
          "string",
          "null"
        ]
      },
      "ErrorCode": {
        "type": [
          "string",
          "null"
        ]
      },
      "ErrorMessage": {
        "type": [
          "string",
          "null"
        ],
        "description": "Texto humano (em suprimidos, o texto do motivo — nunca JSON cru)."
      },
      "SuppressionReason": {
        "description": "Só em `Status: suppressed`.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/platform_SuppressionReason"
          },
          {
            "type": "null"
          }
        ]
      },
      "QueuedAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "SentAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "DeliveredAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "FailedAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "OpenedAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "ClickedAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_MessagePage": {
    "allOf": [
      {
        "$ref": "#/components/schemas/platform_RequestIdEnvelope"
      },
      {
        "$ref": "#/components/schemas/platform_CursorPage"
      },
      {
        "type": "object",
        "properties": {
          "Messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/platform_Message"
            }
          }
        }
      }
    ]
  },
  "platform_MessageDetail": {
    "allOf": [
      {
        "$ref": "#/components/schemas/platform_RequestIdEnvelope"
      },
      {
        "type": "object",
        "properties": {
          "Message": {
            "allOf": [
              {
                "$ref": "#/components/schemas/platform_Message"
              },
              {
                "type": "object",
                "properties": {
                  "BodyText": {
                    "type": "string"
                  },
                  "BodyHtml": {
                    "type": "string"
                  },
                  "Metadata": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "VALOR OPACO — chaves internas passam intactas (não são pascalizadas)."
                  }
                }
              }
            ]
          },
          "Events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "Type": {
                  "type": "string"
                },
                "OccurredAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "Payload": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "Valor opaco."
                }
              }
            }
          }
        }
      }
    ]
  },
  "platform_SendEmailRequest": {
    "type": "object",
    "required": [
      "Source",
      "Destination",
      "Message"
    ],
    "properties": {
      "Source": {
        "type": "string",
        "format": "email"
      },
      "Destination": {
        "type": "object",
        "properties": {
          "ToAddresses": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "CcAddresses": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "BccAddresses": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          }
        },
        "description": "Ao menos um endereço somando To+Cc+Bcc."
      },
      "Message": {
        "type": "object",
        "required": [
          "Subject",
          "Body"
        ],
        "properties": {
          "Subject": {
            "type": "object",
            "properties": {
              "Data": {
                "type": "string",
                "minLength": 1
              },
              "Charset": {
                "type": "string"
              }
            }
          },
          "Body": {
            "type": "object",
            "description": "Ao menos um de Text.Data ou Html.Data.",
            "properties": {
              "Text": {
                "type": "object",
                "properties": {
                  "Data": {
                    "type": "string"
                  },
                  "Charset": {
                    "type": "string"
                  }
                }
              },
              "Html": {
                "type": "object",
                "properties": {
                  "Data": {
                    "type": "string"
                  },
                  "Charset": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "ReplyToAddresses": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        }
      },
      "ReturnPath": {
        "type": "string",
        "format": "email"
      },
      "IdempotencyKey": {
        "type": "string",
        "description": "É ESTE campo que funciona, não o header."
      },
      "Tags": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        }
      }
    }
  },
  "platform_BatchResult": {
    "type": "object",
    "properties": {
      "Index": {
        "type": "integer"
      },
      "Status": {
        "type": "string",
        "enum": [
          "queued",
          "accepted",
          "rejected",
          "failed"
        ],
        "description": "`accepted`: serviço de mensageria indisponível; item no spool durável, reenviado com `IdempotencyKey` (`<chave>:<índice>` ou gerada)."
      },
      "MessageId": {
        "type": "string"
      },
      "MessageIds": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "type": "string",
        "description": "Só com `Status: accepted`."
      },
      "ReusedIdempotency": {
        "type": "boolean"
      },
      "Error": {
        "type": "object",
        "properties": {
          "Code": {
            "type": "string",
            "description": "Ex.: `ValidationError`, `RemetenteNaoVerificado`, `IdempotencyConflict`, `InternalError`."
          },
          "Message": {
            "type": "string"
          },
          "Details": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "platform_Template": {
    "type": "object",
    "properties": {
      "Id": {
        "type": "string"
      },
      "TenantId": {
        "type": "string"
      },
      "Slug": {
        "type": "string"
      },
      "Name": {
        "type": "string"
      },
      "Channel": {
        "$ref": "#/components/schemas/platform_Channel"
      },
      "Subject": {
        "type": "string"
      },
      "BodyHtml": {
        "type": "string"
      },
      "BodyText": {
        "type": "string"
      },
      "Variables": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Valor opaco — não pascalizado."
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_ContactInput": {
    "type": "object",
    "additionalProperties": false,
    "description": "Ao menos um de Email ou Phone.",
    "properties": {
      "Email": {
        "type": "string"
      },
      "Phone": {
        "type": "string"
      },
      "Name": {
        "type": "string"
      },
      "Attributes": {
        "type": "object",
        "additionalProperties": true,
        "description": "Valor opaco."
      },
      "Subscribed": {
        "type": "boolean",
        "default": true
      }
    }
  },
  "platform_Contact": {
    "type": "object",
    "properties": {
      "Id": {
        "type": "string"
      },
      "TenantId": {
        "type": "string"
      },
      "Email": {
        "type": "string"
      },
      "Phone": {
        "type": "string"
      },
      "Name": {
        "type": "string"
      },
      "Attributes": {
        "type": "object",
        "additionalProperties": true
      },
      "Tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Sempre array (vazio sem tags), nunca null."
      },
      "Subscribed": {
        "type": "boolean"
      },
      "UnsubscribedAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_ContactTagsBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "ContactIds",
      "Tags"
    ],
    "properties": {
      "ContactIds": {
        "type": "array",
        "minItems": 1,
        "maxItems": 500,
        "items": {
          "type": "string"
        }
      },
      "Tags": {
        "type": "array",
        "minItems": 1,
        "maxItems": 10,
        "items": {
          "type": "string"
        }
      }
    }
  },
  "platform_ContactList": {
    "type": "object",
    "properties": {
      "Id": {
        "type": "string"
      },
      "TenantId": {
        "type": "string"
      },
      "Name": {
        "type": "string"
      },
      "Slug": {
        "type": "string"
      },
      "Description": {
        "type": "string"
      },
      "MemberCount": {
        "type": "integer"
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_CampaignBody": {
    "type": "object",
    "description": "Payload PascalCase de POST/PATCH `/api/campaigns`. O casing público\nespelha o do front 1:1; a tradução para snake_case do asender_mkt_api é\ncampo a campo (toInput), para que nada inesperado do cliente chegue ao\nupstream (mass assignment, §37 item 14).\n\n**O público é UM dos dois:** `ListId` (associação estática) ou\n`SegmentoId` (consulta viva, resolvida no disparo). O asender_mkt_api\nrecusa os dois preenchidos pelo CHECK `campaigns_um_publico_apenas`, e o\nBFF omite do corpo o que não foi escolhido.",
    "required": [
      "Name",
      "Channel"
    ],
    "properties": {
      "Name": {
        "type": "string"
      },
      "Channel": {
        "type": "string",
        "enum": [
          "email",
          "sms",
          "push",
          "whatsapp"
        ]
      },
      "TemplateId": {
        "type": "string"
      },
      "ListId": {
        "type": "string",
        "description": "id público da lista (`lst_…`); exclusivo com SegmentoId."
      },
      "SegmentoId": {
        "type": "string",
        "description": "id público do segmento (`seg_…`); exclusivo com ListId."
      },
      "Subject": {
        "type": "string"
      },
      "FromAddress": {
        "type": "string"
      }
    }
  },
  "platform_DnsZone": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string",
        "examples": [
          "acme.com"
        ]
      },
      "connection_id": {
        "type": "string",
        "examples": [
          "dnc_0123456789abcdef"
        ]
      }
    }
  },
  "platform_DnsZones": {
    "type": "object",
    "required": [
      "zones"
    ],
    "properties": {
      "zones": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_DnsZone"
        }
      },
      "warnings": {
        "type": "array",
        "description": "Conexões cuja consulta à Cloudflare falhou (as zonas delas vêm do cache).",
        "items": {
          "type": "object",
          "properties": {
            "connection_id": {
              "type": "string"
            },
            "code": {
              "type": "string",
              "examples": [
                "ProvedorIndisponivel"
              ]
            }
          }
        }
      }
    }
  },
  "platform_DnsRecord": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "type": {
        "type": "string",
        "examples": [
          "TXT"
        ]
      },
      "name": {
        "type": "string",
        "examples": [
          "_dmarc.acme.com"
        ]
      },
      "content": {
        "type": "string"
      },
      "ttl": {
        "type": "integer",
        "description": "1 = automático."
      },
      "priority": {
        "type": "integer",
        "description": "Só no MX."
      },
      "proxied": {
        "type": "boolean"
      },
      "comment": {
        "type": "string",
        "maxLength": 60,
        "description": "Criado pela Asender: `asender:<ator>`."
      }
    }
  },
  "platform_DnsRecords": {
    "type": "object",
    "required": [
      "records"
    ],
    "properties": {
      "records": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_DnsRecord"
        }
      },
      "total": {
        "type": "integer"
      },
      "page": {
        "type": "integer"
      },
      "per_page": {
        "type": "integer"
      }
    }
  },
  "platform_DnsRecordCreate": {
    "type": "object",
    "required": [
      "type",
      "name",
      "content"
    ],
    "additionalProperties": false,
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "A",
          "AAAA",
          "CNAME",
          "TXT",
          "MX",
          "NS"
        ]
      },
      "name": {
        "type": "string",
        "description": "'@', nome relativo à zona ou FQDN."
      },
      "content": {
        "type": "string"
      },
      "ttl": {
        "type": "integer",
        "description": "1 (automático) ou 60 a 86400; padrão 1."
      },
      "priority": {
        "type": "integer",
        "description": "Obrigatório só no MX."
      },
      "proxied": {
        "type": "boolean"
      },
      "comment": {
        "type": "string",
        "maxLength": 60
      }
    }
  },
  "platform_DnsRecordUpdate": {
    "type": "object",
    "minProperties": 1,
    "additionalProperties": false,
    "description": "`type` e `name` são imutáveis.",
    "properties": {
      "content": {
        "type": "string"
      },
      "ttl": {
        "type": "integer"
      },
      "priority": {
        "type": "integer"
      },
      "proxied": {
        "type": "boolean"
      },
      "comment": {
        "type": "string",
        "maxLength": 60
      }
    }
  },
  "platform_DnsPlan": {
    "type": "object",
    "description": "Resultado de `dry_run`: nada foi alterado na Cloudflare.",
    "required": [
      "dry_run",
      "action"
    ],
    "properties": {
      "dry_run": {
        "type": "boolean",
        "const": true
      },
      "action": {
        "type": "string",
        "enum": [
          "create",
          "update",
          "delete"
        ]
      },
      "before": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/platform_DnsRecord"
          },
          {
            "type": "null"
          }
        ]
      },
      "after": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/platform_DnsRecord"
          },
          {
            "type": "null"
          }
        ]
      },
      "requires_confirmation": {
        "type": "boolean",
        "description": "Se verdadeiro, a escrita real exige `X-Asender-Confirmar`."
      },
      "confirm": {
        "type": "string",
        "description": "O valor exato a enviar em `X-Asender-Confirmar`."
      }
    }
  },
  "platform_DnsChange": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "connection_id": {
        "type": "string"
      },
      "zone_id": {
        "type": "string"
      },
      "zone_name": {
        "type": "string"
      },
      "action": {
        "type": "string",
        "enum": [
          "create",
          "update",
          "delete"
        ]
      },
      "before": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/platform_DnsRecord"
          },
          {
            "type": "null"
          }
        ]
      },
      "after": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/platform_DnsRecord"
          },
          {
            "type": "null"
          }
        ]
      },
      "actor": {
        "type": "string",
        "description": "Id da chave ou do usuário."
      },
      "source": {
        "type": "string",
        "enum": [
          "tela",
          "api",
          "mcp"
        ]
      },
      "trace_id": {
        "type": "string"
      },
      "result": {
        "type": "string",
        "enum": [
          "ok",
          "failed",
          "dry_run"
        ]
      },
      "error": {
        "type": "string"
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_DnsChanges": {
    "type": "object",
    "required": [
      "changes"
    ],
    "properties": {
      "changes": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/platform_DnsChange"
        }
      },
      "total": {
        "type": "integer"
      },
      "page": {
        "type": "integer"
      },
      "per_page": {
        "type": "integer"
      }
    }
  },
  "platform_DnsProblema": {
    "type": "object",
    "description": "RFC 9457 do serviço de DNS (rotas de painel).",
    "required": [
      "type",
      "title",
      "status",
      "codigo"
    ],
    "properties": {
      "type": {
        "type": "string"
      },
      "title": {
        "type": "string"
      },
      "status": {
        "type": "integer"
      },
      "detail": {
        "type": "string"
      },
      "codigo": {
        "type": "string",
        "description": "Identificador estável (PascalCase)."
      },
      "instance": {
        "type": "string"
      },
      "trace_id": {
        "type": "string"
      }
    }
  },
  "platform_Webhook": {
    "type": "object",
    "required": [
      "Id",
      "Url",
      "Events",
      "Active"
    ],
    "properties": {
      "Id": {
        "type": "string",
        "examples": [
          "whk_83fcaff4b496c6e6"
        ]
      },
      "Url": {
        "type": "string",
        "format": "uri"
      },
      "Events": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Padrões assinados: `*`, `<família>.*` ou tipo exato do catálogo."
      },
      "Active": {
        "type": "boolean"
      },
      "ConsecutiveFailures": {
        "type": "integer"
      },
      "LastDeliveryAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_WebhookCreate": {
    "type": "object",
    "required": [
      "Url",
      "Events"
    ],
    "additionalProperties": false,
    "properties": {
      "Url": {
        "type": "string",
        "maxLength": 2048,
        "description": "https em produção; sem destino interno."
      },
      "Events": {
        "type": "array",
        "minItems": 1,
        "maxItems": 32,
        "uniqueItems": true,
        "items": {
          "type": "string",
          "examples": [
            "*",
            "email.*",
            "email.failed"
          ],
          "description": "`*`, `email.*`, `sms.*`, `whatsapp.*`, `push.*`, `mail.*` ou um de: email.queued, email.failed, sms.sent, sms.failed, whatsapp.sent, whatsapp.failed, push.delivered, push.failed, mail.sent, mail.received."
        }
      },
      "Active": {
        "type": "boolean",
        "default": true
      }
    }
  },
  "platform_WebhookUpdate": {
    "type": "object",
    "minProperties": 1,
    "additionalProperties": false,
    "properties": {
      "Url": {
        "type": "string",
        "maxLength": 2048
      },
      "Events": {
        "type": "array",
        "minItems": 1,
        "maxItems": 32,
        "uniqueItems": true,
        "items": {
          "type": "string"
        }
      },
      "Active": {
        "type": "boolean"
      }
    }
  },
  "platform_WebhookCreated": {
    "allOf": [
      {
        "$ref": "#/components/schemas/platform_RequestIdEnvelope"
      },
      {
        "$ref": "#/components/schemas/platform_Webhook"
      },
      {
        "type": "object",
        "required": [
          "Secret"
        ],
        "properties": {
          "Secret": {
            "type": "string",
            "examples": [
              "whsec_0123456789abcdef"
            ],
            "description": "Segredo de assinatura. Aparece SÓ nesta resposta."
          },
          "PlaintextWarning": {
            "type": "string"
          }
        }
      }
    ]
  },
  "platform_WebhookTestResult": {
    "allOf": [
      {
        "$ref": "#/components/schemas/platform_RequestIdEnvelope"
      },
      {
        "type": "object",
        "required": [
          "WebhookId",
          "EventId",
          "EventType",
          "Delivered",
          "StatusCode",
          "Reason",
          "DurationMs"
        ],
        "properties": {
          "WebhookId": {
            "type": "string"
          },
          "EventId": {
            "type": "string",
            "description": "Também vai em `Asender-Webhook-Id`."
          },
          "EventType": {
            "type": "string",
            "const": "webhook.test"
          },
          "Delivered": {
            "type": "boolean"
          },
          "StatusCode": {
            "type": "integer"
          },
          "Reason": {
            "type": "string",
            "enum": [
              "",
              "non_2xx",
              "transport_error",
              "destination_blocked",
              "non_production_blocked"
            ]
          },
          "DurationMs": {
            "type": "integer"
          }
        }
      }
    ]
  },
  "platform_Device": {
    "type": "object",
    "properties": {
      "Id": {
        "type": "string"
      },
      "TenantId": {
        "type": "string"
      },
      "ContactId": {
        "type": "string"
      },
      "Token": {
        "type": "string"
      },
      "Platform": {
        "type": "string",
        "enum": [
          "ios",
          "android",
          "web"
        ]
      },
      "Active": {
        "type": "boolean"
      },
      "LastSeenAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_Tenant": {
    "type": "object",
    "description": "Projeção do asender_plataforma_api (`tenantPayload`), pascalizada.",
    "properties": {
      "Id": {
        "type": "string"
      },
      "Name": {
        "type": "string"
      },
      "Slug": {
        "type": "string"
      },
      "Status": {
        "type": "string",
        "enum": [
          "active",
          "suspended"
        ]
      },
      "TrialEndsAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "Metadata": {
        "type": "object",
        "additionalProperties": true,
        "description": "Valor opaco."
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_TenantNode": {
    "type": "object",
    "description": "Nó de árvore (`tenantNodePayload` do core), pascalizado.",
    "properties": {
      "Id": {
        "type": "string"
      },
      "Name": {
        "type": "string"
      },
      "Slug": {
        "type": "string"
      },
      "Status": {
        "type": "string"
      },
      "Kind": {
        "type": "string",
        "enum": [
          "root",
          "leaf"
        ]
      },
      "Depth": {
        "type": "integer",
        "description": "Profundidade absoluta na árvore."
      },
      "RelativeDepth": {
        "type": "integer",
        "description": "Profundidade relativa ao nó consultado — use para indentar."
      },
      "ParentId": {
        "type": [
          "string",
          "null"
        ]
      },
      "MonthlyQuota": {
        "type": [
          "integer",
          "null"
        ],
        "description": "`null` = herda."
      },
      "EffectiveQuota": {
        "type": [
          "integer",
          "null"
        ],
        "description": "Valor que realmente vale; `null` = sem limite em nenhum ancestral."
      },
      "ChildrenCount": {
        "type": "integer"
      },
      "CreatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_Usage": {
    "type": "object",
    "properties": {
      "Period": {
        "type": "string",
        "examples": [
          "2026-07"
        ]
      },
      "EmailsSent": {
        "type": "integer"
      },
      "SmsSent": {
        "type": "integer"
      },
      "PushSent": {
        "type": "integer"
      },
      "ApiCalls": {
        "type": "integer"
      },
      "UpdatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "platform_ReportCounters": {
    "type": "object",
    "description": "`Total` é o volume do período; `Queued` é BACKLOG (o que ainda não saiu).",
    "properties": {
      "Total": {
        "type": "integer"
      },
      "Queued": {
        "type": "integer"
      },
      "Sent": {
        "type": "integer"
      },
      "Delivered": {
        "type": "integer"
      },
      "Bounced": {
        "type": "integer"
      },
      "Failed": {
        "type": "integer"
      },
      "Opened": {
        "type": "integer"
      },
      "Clicked": {
        "type": "integer"
      }
    }
  },
  "platform_ReportRates": {
    "type": "object",
    "description": "`Delivery = Delivered/Sent`, `Bounce = Bounced/Sent`,\n`Open = Opened/Delivered`, `Click = Clicked/Delivered`.\nDenominador zero devolve `0` (nunca `null`, nunca `NaN`).",
    "properties": {
      "Delivery": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "Bounce": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "Open": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "Click": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    }
  },
  "platform_ReportPeriod": {
    "type": "object",
    "description": "Janela efetivamente usada, já com o default aplicado. `To` é EXCLUSIVO.",
    "properties": {
      "From": {
        "type": "string",
        "format": "date-time"
      },
      "To": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "mail_ContaGerenciada": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "nome": {
        "type": "string"
      },
      "email": {
        "type": "string"
      },
      "estado": {
        "type": "string"
      },
      "bloqueada": {
        "type": "boolean"
      },
      "gerenciada_por_tenant": {
        "type": "string"
      },
      "ultimo_acesso_em": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      }
    }
  },
  "mail_MotivoDaAcao": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "motivo"
    ],
    "properties": {
      "motivo": {
        "type": "string",
        "minLength": 5,
        "maxLength": 500,
        "description": "razão da ação",
        "gravada na trilha": null
      }
    }
  },
  "mail_ResultadoDaAcao": {
    "type": "object",
    "properties": {
      "conta": {
        "type": "object"
      },
      "senha_temporaria": {
        "type": "string",
        "description": "só em senha-temporaria; mostrada UMA vez"
      },
      "sessoes_encerradas": {
        "type": "integer"
      },
      "removidos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "reenrolment_obrigatorio": {
        "type": "boolean"
      },
      "revogadas": {
        "type": "integer"
      }
    }
  },
  "mail_EnderecoRetido": {
    "type": "object",
    "description": "Um endereço sem caixa que recebeu e-mail e está retido na quarentena.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "endereco": {
        "type": "string"
      },
      "dominio": {
        "type": "string"
      },
      "domain_id": {
        "type": "string",
        "format": "uuid"
      },
      "local_part": {
        "type": "string"
      },
      "estado": {
        "type": "string",
        "enum": [
          "pendente",
          "aceita",
          "descartada"
        ]
      },
      "mensagens": {
        "type": "integer",
        "description": "mensagens ainda retidas"
      },
      "bytes": {
        "type": "integer",
        "format": "int64"
      },
      "remetentes": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "até 10 remetentes distintos"
      },
      "primeiro_em": {
        "type": "string",
        "format": "date-time"
      },
      "ultimo_em": {
        "type": "string",
        "format": "date-time"
      },
      "total_recebidas": {
        "type": "integer",
        "description": "total que já chegou para o endereço"
      },
      "mailbox_id": {
        "type": "string",
        "format": "uuid",
        "description": "a caixa criada",
        "quando aceito": null
      }
    }
  },
  "mail_MensagemRetida": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "estado": {
        "type": "string",
        "enum": [
          "retida",
          "entregue",
          "descartada"
        ]
      },
      "mail_from": {
        "type": "string"
      },
      "remetente": {
        "type": "string"
      },
      "assunto": {
        "type": "string"
      },
      "tamanho": {
        "type": "integer",
        "format": "int64"
      },
      "recebido_em": {
        "type": "string",
        "format": "date-time"
      },
      "av_status": {
        "type": "string"
      },
      "av_assinatura": {
        "type": "string"
      }
    }
  },
  "mail_ResultadoAceiteQuarentena": {
    "type": "object",
    "properties": {
      "endereco": {
        "type": "string"
      },
      "mailbox_id": {
        "type": "string",
        "format": "uuid"
      },
      "caixa_criada": {
        "type": "boolean"
      },
      "movidas": {
        "type": "integer"
      },
      "restam": {
        "type": "integer",
        "description": "ainda retidas (0 = endereço fechado como aceita)"
      }
    }
  },
  "mail_DrenagemQuarentena": {
    "type": "object",
    "description": "O que ligar o autocriar fez com a quarentena do domínio.",
    "properties": {
      "enderecos": {
        "type": "integer"
      },
      "mensagens": {
        "type": "integer"
      },
      "falhas": {
        "type": "integer"
      },
      "restantes": {
        "type": "integer",
        "description": "endereços além do limite por chamada; chame de novo"
      }
    }
  },
  "mail_EstadoDNS": {
    "type": "object",
    "description": "Retrato da verificação de DNS de um domínio. `cliente` é o grupo \"clientes de e-mail\" (CNAME `autoconfig` + SRV `_imaps`/`_submissions`): é OPCIONAL, não entra no veredito `pronto` e não bloqueia a verificação.",
    "properties": {
      "posse": {
        "type": "boolean"
      },
      "mx": {
        "type": "boolean"
      },
      "spf": {
        "type": "boolean"
      },
      "dkim": {
        "type": "boolean"
      },
      "dmarc": {
        "type": "boolean"
      },
      "cliente": {
        "type": "boolean",
        "description": "o CNAME autoconfig e os SRV de IMAP/SMTP estão publicados"
      }
    }
  },
  "mail_RegistroDNS": {
    "type": "object",
    "description": "Um registro a publicar. Em `SRV`, `valor` é `prio peso porta alvo.` (formato BIND); os registros do grupo clientes de e-mail (CNAME `autoconfig` e SRV) só aparecem no modo `completo`.",
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "TXT",
          "MX",
          "CNAME",
          "SRV"
        ]
      },
      "host": {
        "type": "string"
      },
      "valor": {
        "type": "string"
      },
      "prioridade": {
        "type": "integer"
      },
      "explica": {
        "type": "string"
      }
    }
  },
  "mail_AcessoCliente": {
    "type": "object",
    "description": "Onde e como configurar um cliente de e-mail (Thunderbird, Outlook, celular) numa caixa. Nunca traz segredo: a senha de aplicativo nasce no auth.",
    "required": [
      "endereco",
      "usuario",
      "dominio",
      "dominio_verificado",
      "registros_cliente",
      "tem_grant",
      "imap",
      "smtp"
    ],
    "properties": {
      "endereco": {
        "type": "string"
      },
      "usuario": {
        "type": "string",
        "description": "o login do cliente de e-mail (o endereço completo)"
      },
      "dominio": {
        "type": "string"
      },
      "dominio_verificado": {
        "type": "boolean"
      },
      "registros_cliente": {
        "type": "boolean",
        "description": "o DNS de configuração automática do domínio está publicado"
      },
      "tem_grant": {
        "type": "boolean",
        "description": "a pessoa tem concessão nesta caixa (o IMAP só autoriza por concessão)"
      },
      "imap": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string"
          },
          "porta": {
            "type": "integer",
            "example": 993
          },
          "seguranca": {
            "type": "string",
            "enum": [
              "ssl_tls"
            ]
          }
        }
      },
      "smtp": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string"
          },
          "portas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "porta": {
                  "type": "integer",
                  "example": 465
                },
                "seguranca": {
                  "type": "string",
                  "enum": [
                    "ssl_tls",
                    "starttls"
                  ]
                }
              }
            }
          }
        }
      },
      "autoconfig_host": {
        "type": "string"
      },
      "senha_app_url": {
        "type": "string",
        "description": "link para criar a senha de aplicativo no auth (vazio sem host do auth)"
      }
    }
  },
  "mail_EstadoCloudflare": {
    "type": "object",
    "description": "O que a tela pode oferecer para o domínio na Cloudflare. O token NUNCA volta (nem cifrado). `domain_connect.motivo` explica por que o botão de 1 clique não aparece — consulta_falhou | fora_da_cloudflare | sem_domain_connect | sem_chave | template_pendente.",
    "properties": {
      "zona": {
        "type": "string",
        "example": "loja.com.br"
      },
      "na_cloudflare": {
        "type": "boolean"
      },
      "consulta_falhou": {
        "type": "boolean"
      },
      "domain_connect": {
        "type": "object",
        "properties": {
          "disponivel": {
            "type": "boolean"
          },
          "motivo": {
            "type": "string",
            "enum": [
              "consulta_falhou",
              "fora_da_cloudflare",
              "sem_domain_connect",
              "sem_chave",
              "template_pendente"
            ]
          }
        }
      },
      "token": {
        "type": "object",
        "properties": {
          "disponivel": {
            "type": "boolean",
            "description": "o ambiente tem a chave de cifra (ENCRYPTION_KEY)"
          },
          "configurado": {
            "type": "boolean"
          },
          "zona": {
            "type": "string"
          },
          "atualizado_em": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ultima_aplicacao": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/mail_AplicacaoDNS"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  },
  "mail_AplicacaoDNS": {
    "type": "object",
    "description": "Uma linha da trilha de auditoria (append-only) das ações no DNS.",
    "properties": {
      "ator": {
        "type": "string"
      },
      "metodo": {
        "type": "string",
        "enum": [
          "token",
          "domain_connect"
        ]
      },
      "evento": {
        "type": "string",
        "enum": [
          "token_salvo",
          "token_removido",
          "aplicacao",
          "url_gerada"
        ]
      },
      "zona": {
        "type": "string"
      },
      "resultado": {
        "type": "string",
        "enum": [
          "ok",
          "parcial",
          "erro"
        ]
      },
      "registros": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/mail_AcaoDNS"
        }
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "mail_CaixaComTipo": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "domain_id": {
        "type": "string",
        "format": "uuid"
      },
      "local_part": {
        "type": "string"
      },
      "display_name": {
        "type": "string"
      },
      "quota_bytes": {
        "type": "integer"
      },
      "active": {
        "type": "boolean"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "pessoal",
          "coletiva"
        ]
      },
      "origem": {
        "type": "string",
        "enum": [
          "manual",
          "automatica",
          "conta_iam",
          "legado"
        ],
        "readOnly": true
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "mail_RecusaAssinatura": {
    "type": "object",
    "required": [
      "error",
      "message"
    ],
    "properties": {
      "error": {
        "type": "string",
        "enum": [
          "CaixaInelegivel",
          "CaixaAssinada",
          "EfeitoExternoBloqueado",
          "AnexoInfectado"
        ]
      },
      "message": {
        "type": "string"
      },
      "motivo": {
        "type": "string",
        "enum": [
          "pessoal",
          "origem_conta_iam",
          "origem_desconhecida",
          "catch_all",
          "caixa_inativa",
          "dominio_inativo",
          "dominio_nao_verificado",
          "dominio_somente_envio",
          "dominio_divergente"
        ]
      }
    }
  },
  "mail_CaixaElegivel": {
    "type": "object",
    "required": [
      "id",
      "endereco",
      "display_name",
      "tipo",
      "origem",
      "elegivel",
      "assinada"
    ],
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "endereco": {
        "type": "string",
        "example": "sac@empresa.test.asender.com.br"
      },
      "display_name": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "pessoal",
          "coletiva"
        ]
      },
      "origem": {
        "type": "string",
        "enum": [
          "manual",
          "automatica",
          "conta_iam",
          "legado"
        ]
      },
      "elegivel": {
        "type": "boolean"
      },
      "motivo": {
        "type": "string"
      },
      "assinada": {
        "type": "boolean"
      }
    }
  },
  "mail_AssinaturaDeCaixa": {
    "type": "object",
    "required": [
      "id",
      "mailbox_id",
      "endereco",
      "display_name",
      "assinante",
      "criada_por",
      "criada_em"
    ],
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "mailbox_id": {
        "type": "string",
        "format": "uuid"
      },
      "endereco": {
        "type": "string"
      },
      "display_name": {
        "type": "string"
      },
      "assinante": {
        "type": "string",
        "enum": [
          "atendimento"
        ]
      },
      "criada_por": {
        "type": "string",
        "description": "sub de quem ligou"
      },
      "criada_em": {
        "type": "string",
        "format": "date-time"
      },
      "revogada_em": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "revogada_por": {
        "type": "string"
      }
    }
  },
  "mail_MensagemAssinada": {
    "type": "object",
    "required": [
      "id",
      "mailbox_id",
      "direction",
      "message_id",
      "from_email",
      "subject",
      "received_at",
      "anexos"
    ],
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "mailbox_id": {
        "type": "string",
        "format": "uuid"
      },
      "direction": {
        "type": "string",
        "enum": [
          "inbound"
        ]
      },
      "message_id": {
        "type": "string",
        "description": "Message-ID RFC 5322"
      },
      "thread_id": {
        "type": "string"
      },
      "in_reply_to": {
        "type": "string"
      },
      "from_email": {
        "type": "string"
      },
      "from_name": {
        "type": "string"
      },
      "to_emails": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cc_emails": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "subject": {
        "type": "string"
      },
      "body_text": {
        "type": "string"
      },
      "body_html": {
        "type": "string",
        "description": "HTML já sanitizado pelo mail",
        "imagens inline embutidas": null
      },
      "received_at": {
        "type": "string",
        "format": "date-time"
      },
      "anexos": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "filename",
            "content_type",
            "size_bytes"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "filename": {
              "type": "string"
            },
            "content_type": {
              "type": "string"
            },
            "size_bytes": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "mail_EnvioDoAssinante": {
    "type": "object",
    "required": [
      "to"
    ],
    "additionalProperties": false,
    "properties": {
      "to": {
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "string"
        }
      },
      "cc": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "subject": {
        "type": "string"
      },
      "text": {
        "type": "string"
      },
      "html": {
        "type": "string"
      },
      "in_reply_to_id": {
        "type": "string",
        "format": "uuid",
        "description": "id NO MAIL da mensagem do cliente"
      },
      "attachments": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "filename",
            "content_type",
            "content_base64"
          ],
          "properties": {
            "filename": {
              "type": "string"
            },
            "content_type": {
              "type": "string"
            },
            "content_base64": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "mail_ResultadoEnvioAssinante": {
    "type": "object",
    "required": [
      "message_id",
      "status"
    ],
    "properties": {
      "message_id": {
        "type": "string"
      },
      "sent_id": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "sent"
        ]
      },
      "idempotent_replay": {
        "type": "boolean"
      }
    }
  },
  "mail_AcaoDNS": {
    "type": "object",
    "description": "O que a aplicação fez num registro. Nunca há \"apagado\": registro alheio que atrapalha vira `conflito` com a instrução em `detalhe`.",
    "properties": {
      "resultado": {
        "type": "string",
        "enum": [
          "mantido",
          "criado",
          "atualizado",
          "conflito",
          "falhou"
        ]
      },
      "tipo": {
        "type": "string",
        "example": "CNAME"
      },
      "nome": {
        "type": "string"
      },
      "valor": {
        "type": "string"
      },
      "papel": {
        "type": "string"
      },
      "anterior": {
        "type": "string",
        "description": "valor antes de um `atualizado` (para desfazer à mão)"
      },
      "detalhe": {
        "type": "string"
      }
    }
  },
  "mail_RelatorioCloudflare": {
    "type": "object",
    "properties": {
      "zona": {
        "type": "string"
      },
      "ok": {
        "type": "boolean",
        "description": "nenhum conflito nem falha"
      },
      "registros": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/mail_AcaoDNS"
        }
      }
    }
  },
  "mail_ResumoDeFerramenta": {
    "type": "object",
    "description": "Contrato comum de resumo de ferramenta (plano 2026-10-02) — o mesmo formato em toda ferramenta.",
    "required": [
      "ferramenta",
      "periodo",
      "indicadores",
      "series"
    ],
    "properties": {
      "ferramenta": {
        "type": "string",
        "description": "slug da ferramenta (crm, mail, pages, atendimento, …)"
      },
      "periodo": {
        "type": "object",
        "required": [
          "de",
          "ate",
          "chave"
        ],
        "properties": {
          "de": {
            "type": "string",
            "format": "date",
            "description": "primeiro dia da janela (inclusivo)"
          },
          "ate": {
            "type": "string",
            "format": "date",
            "description": "último dia da janela (inclusivo)"
          },
          "chave": {
            "type": "string",
            "enum": [
              "7d",
              "30d",
              "90d"
            ]
          }
        }
      },
      "indicadores": {
        "type": "array",
        "minItems": 1,
        "maxItems": 6,
        "items": {
          "$ref": "#/components/schemas/mail_ResumoIndicador"
        }
      },
      "series": {
        "type": "array",
        "maxItems": 2,
        "items": {
          "$ref": "#/components/schemas/mail_ResumoSerie"
        }
      }
    }
  },
  "mail_ResumoIndicador": {
    "type": "object",
    "required": [
      "chave",
      "rotulo",
      "valor",
      "anterior",
      "formato",
      "link"
    ],
    "properties": {
      "chave": {
        "type": "string",
        "description": "id estável do indicador"
      },
      "rotulo": {
        "type": "string",
        "description": "rótulo pt-BR (o front pode traduzir pela chave)"
      },
      "valor": {
        "type": "number"
      },
      "anterior": {
        "type": [
          "number",
          "null"
        ],
        "description": "mesmo indicador na janela anterior de mesmo tamanho; null = sem comparação"
      },
      "formato": {
        "type": "string",
        "enum": [
          "numero",
          "percentual",
          "moeda",
          "duracao"
        ],
        "description": "moeda em centavos BRL; duracao em segundos; percentual 0–100"
      },
      "link": {
        "type": "string",
        "description": "caminho relativo dentro da ferramenta, já com a conta"
      }
    }
  },
  "mail_ResumoSerie": {
    "type": "object",
    "required": [
      "chave",
      "rotulo",
      "tipo",
      "pontos"
    ],
    "properties": {
      "chave": {
        "type": "string"
      },
      "rotulo": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "linha",
          "barra"
        ]
      },
      "pontos": {
        "type": "array",
        "description": "um ponto por dia da janela (dia sem evento vem com 0)",
        "items": {
          "type": "object",
          "required": [
            "data",
            "valor"
          ],
          "properties": {
            "data": {
              "type": "string",
              "format": "date"
            },
            "valor": {
              "type": "number"
            }
          }
        }
      }
    }
  },
  "mail_Erro": {
    "type": "object",
    "description": "Envelope único de erro da Mail API.",
    "required": [
      "error",
      "message"
    ],
    "properties": {
      "error": {
        "type": "string",
        "description": "classe do erro (ex.: ValidationError, AuthorizationError, NotFound, QuotaExceeded, SendFailed)"
      },
      "message": {
        "type": "string",
        "description": "mensagem legível; nunca revela existência de recurso de outra conta"
      }
    }
  },
  "mail_Email": {
    "type": "object",
    "description": "Corpo de `POST /v1/emails`.",
    "required": [
      "from",
      "to"
    ],
    "properties": {
      "from": {
        "type": "string",
        "format": "email",
        "description": "endereço de uma CAIXA existente da conta (o domínio verificado não basta); o tenant tem de ser dono",
        "examples": [
          "joana@empresa.com.br"
        ]
      },
      "to": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        },
        "minItems": 1
      },
      "cc": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        }
      },
      "bcc": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        }
      },
      "subject": {
        "type": "string"
      },
      "text": {
        "type": "string",
        "description": "corpo em texto puro"
      },
      "html": {
        "type": "string",
        "description": "corpo HTML (sanitizado no servidor)"
      },
      "in_reply_to_id": {
        "type": "string",
        "description": "id interno da mensagem respondida (threading), opcional"
      },
      "identity_id": {
        "type": "string",
        "format": "uuid",
        "description": "identidade de envio (send-as) da caixa — o webmail (/mailboxes/{id}/send). O endereço dela precisa ser de um domínio da org com DKIM verificado; senão 422. Opcional."
      },
      "attachments": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/mail_Anexo"
        }
      }
    }
  },
  "mail_Anexo": {
    "type": "object",
    "required": [
      "filename",
      "content"
    ],
    "properties": {
      "filename": {
        "type": "string"
      },
      "content_type": {
        "type": "string",
        "description": "MIME; inferido do nome se ausente"
      },
      "content": {
        "type": "string",
        "format": "byte",
        "description": "conteúdo em base64"
      }
    }
  },
  "mail_Etiqueta": {
    "type": "object",
    "description": "Corpo de criação/edição de etiqueta (M-E).",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "1 a 60 caracteres, único na caixa"
      },
      "color": {
        "type": "string",
        "description": "rótulo simbólico da paleta (ex.: red, blue); vazio = sem cor"
      }
    }
  },
  "mail_EtiquetaComContagem": {
    "type": "object",
    "description": "Etiqueta da caixa com origem e contagens — a lateral do webmail (ADR-0087, frente C).",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "mailbox_id": {
        "type": "string",
        "format": "uuid"
      },
      "name": {
        "type": "string",
        "description": "nome com '/' é desenhado como grupo na tela (sem hierarquia no banco)"
      },
      "color": {
        "type": "string"
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "origem": {
        "type": "string",
        "enum": [
          "usuario",
          "sistema",
          "org"
        ]
      },
      "sistema": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "importante",
          "lista",
          null
        ],
        "description": "chave da etiqueta de sistema; não renomeia nem apaga"
      },
      "total": {
        "type": "integer",
        "description": "mensagens com a etiqueta (todas as pastas); ausente = 0"
      },
      "nao_lidas": {
        "type": "integer",
        "description": "dessas, as não lidas; ausente = 0"
      }
    }
  },
  "mail_LoteDeEtiquetas": {
    "type": "object",
    "description": "Etiquetas a aplicar/remover. Ids de mensagem ou etiqueta de OUTRA caixa são ignorados, nunca vinculados.",
    "properties": {
      "message_ids": {
        "type": "array",
        "maxItems": 500,
        "items": {
          "type": "string",
          "format": "uuid"
        }
      },
      "adicionar": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "string",
          "format": "uuid"
        }
      },
      "remover": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "string",
          "format": "uuid"
        }
      }
    }
  },
  "mail_ResultadoDeEtiquetas": {
    "type": "object",
    "description": "O que MUDOU (não o que foi pedido).",
    "properties": {
      "vinculadas": {
        "type": "integer"
      },
      "desvinculadas": {
        "type": "integer"
      }
    }
  },
  "mail_Identidade": {
    "type": "object",
    "description": "Corpo de criação/edição de identidade de envio (M-E).",
    "required": [
      "email"
    ],
    "properties": {
      "from_name": {
        "type": "string",
        "description": "nome de exibição do De"
      },
      "email": {
        "type": "string",
        "format": "email",
        "description": "endereço De; no envio precisa ser de um domínio da org com DKIM verificado"
      },
      "is_default": {
        "type": "boolean",
        "description": "pré-seleciona no compositor; no máximo uma padrão por caixa"
      }
    }
  },
  "mail_EmailAceito": {
    "type": "object",
    "required": [
      "message_id",
      "status"
    ],
    "properties": {
      "message_id": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "sent"
        ],
        "examples": [
          "sent"
        ]
      },
      "idempotent_replay": {
        "type": "boolean",
        "description": "true quando a Idempotency-Key já havia sido usada; nada foi reenviado"
      }
    }
  },
  "mail_Pasta": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "kind": {
        "type": "string",
        "enum": [
          "inbox",
          "sent",
          "drafts",
          "archive",
          "spam",
          "trash",
          "custom"
        ]
      },
      "name": {
        "type": "string"
      },
      "total": {
        "type": "integer",
        "format": "int64"
      },
      "unread": {
        "type": "integer",
        "format": "int64"
      }
    }
  },
  "mail_PatchDeMensagem": {
    "type": "object",
    "description": "Campo ausente não é alterado. Pelo menos um é obrigatório (corpo vazio = 400).",
    "properties": {
      "read": {
        "type": "boolean"
      },
      "starred": {
        "type": "boolean"
      },
      "folder": {
        "type": "string",
        "enum": [
          "inbox",
          "sent",
          "drafts",
          "archive",
          "spam",
          "trash"
        ],
        "description": "pasta de destino; criada sob demanda"
      }
    }
  },
  "mail_MensagemDaLista": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "direction": {
        "type": "string",
        "enum": [
          "inbound",
          "outbound"
        ]
      },
      "from_email": {
        "type": "string"
      },
      "from_name": {
        "type": "string"
      },
      "to_emails": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "subject": {
        "type": "string"
      },
      "snippet": {
        "type": "string",
        "description": "começo do corpo em texto puro (200 caracteres)"
      },
      "has_attachment": {
        "type": "boolean"
      },
      "attachment_count": {
        "type": "integer"
      },
      "starred": {
        "type": "boolean"
      },
      "folder_kind": {
        "type": "string"
      },
      "folder_name": {
        "type": "string",
        "description": "nome da pasta (o da pessoa, ou o padrão da de sistema) — o selo de \"Todos os e-mails\""
      },
      "read": {
        "type": "boolean"
      },
      "received_at": {
        "type": "string",
        "format": "date-time"
      },
      "status": {
        "type": "string"
      }
    }
  },
  "mail_PaginaDeMensagens": {
    "type": "object",
    "properties": {
      "messages": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/mail_MensagemDaLista"
        }
      },
      "next_cursor": {
        "type": "string",
        "description": "vazio quando acabou; opaco — devolva como veio"
      },
      "total": {
        "type": "integer",
        "description": "só com `q` e sem cursor: quantas mensagens a busca acha na caixa (até 10 000)"
      },
      "total_limitado": {
        "type": "boolean",
        "description": "true quando há mais que 10 000"
      }
    }
  },
  "mail_RegraDaBusca": {
    "type": "object",
    "description": "A busca convertida numa regra para o construtor (ações vazias — a pessoa escolhe).",
    "properties": {
      "filtro": {
        "$ref": "#/components/schemas/mail_FiltroV2"
      },
      "pronta": {
        "type": "boolean",
        "description": "há ao menos uma condição"
      },
      "pastas": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "escopo de \"aplicar às existentes\" (kinds ou ids)"
      },
      "nao_convertidos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "termo": {
              "type": "string"
            },
            "motivo": {
              "type": "string"
            }
          }
        }
      },
      "busca_convertivel": {
        "type": "string",
        "description": "a busca só com os termos que viraram regra"
      },
      "total_busca": {
        "type": "integer",
        "description": "resultados da busca convertível no escopo — a prévia da regra dá o mesmo número"
      },
      "total_limitado": {
        "type": "boolean"
      }
    }
  },
  "mail_Parecidos": {
    "type": "object",
    "properties": {
      "selecionadas": {
        "type": "integer",
        "description": "mensagens analisadas (as desta caixa)"
      },
      "busca_sugerida": {
        "type": "string"
      },
      "criterios": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "chave": {
              "type": "string",
              "enum": [
                "remetente",
                "remetentes",
                "local",
                "dominio",
                "dominios",
                "dominio_registravel",
                "lista",
                "listas",
                "assunto_prefixo",
                "assunto_palavras",
                "para",
                "para_dominio",
                "cc",
                "responder_para",
                "anexo"
              ]
            },
            "familia": {
              "type": "string",
              "enum": [
                "remetente",
                "lista",
                "assunto",
                "destinatario",
                "anexo",
                "outros"
              ]
            },
            "rotulo": {
              "type": "string"
            },
            "busca": {
              "type": "string",
              "description": "vazio = não vira busca (ver motivo)"
            },
            "motivo": {
              "type": "string"
            },
            "cobertura": {
              "type": "integer"
            },
            "especificidade": {
              "type": "integer"
            },
            "sugerido": {
              "type": "boolean"
            },
            "total": {
              "type": [
                "integer",
                "null"
              ]
            }
          }
        }
      }
    }
  },
  "mail_Rascunho": {
    "type": "object",
    "description": "Um rascunho é uma mensagem status='draft' na pasta drafts.",
    "properties": {
      "to": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        }
      },
      "cc": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        }
      },
      "bcc": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "email"
        }
      },
      "subject": {
        "type": "string"
      },
      "html": {
        "type": "string"
      },
      "in_reply_to_id": {
        "type": "string"
      }
    }
  },
  "mail_Contato": {
    "type": "object",
    "required": [
      "email"
    ],
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "email": {
        "type": "string",
        "format": "email"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "mail_Assinatura": {
    "type": "object",
    "properties": {
      "html": {
        "type": "string",
        "description": "HTML da assinatura; sanitizado no servidor (bluemonday) na gravação"
      },
      "enabled": {
        "type": "boolean"
      }
    }
  },
  "mail_PoliticaDaOrg": {
    "type": "object",
    "description": "Políticas de verificação da organização (ADR-0087). Ausência de configuração = os padrões abaixo. O PUT SUBSTITUI a política inteira: campo ausente volta ao padrão.",
    "properties": {
      "org_id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true,
        "description": "vem da rota; um valor no corpo é ignorado"
      },
      "spam_limiar": {
        "type": [
          "number",
          "null"
        ],
        "minimum": 2,
        "maximum": 30,
        "description": "pontuação a partir da qual vai para a Spam; null = o limiar do serviço (5)"
      },
      "spam_purga_dias": {
        "type": "integer",
        "minimum": 1,
        "maximum": 365,
        "default": 30,
        "description": "dias NA PASTA Spam antes de apagar (conta desde que a mensagem entrou nela)"
      },
      "quarentena_purga_dias": {
        "type": "integer",
        "minimum": 1,
        "maximum": 365,
        "default": 30
      },
      "av_heuristica": {
        "type": "string",
        "enum": [
          "quarentena",
          "marcar"
        ],
        "default": "quarentena",
        "description": "achado heurístico/PUA do antivírus: reter na Quarentena ou só marcar"
      },
      "encaminhamento_externo": {
        "type": "boolean",
        "default": false,
        "description": "regra de filtro pode encaminhar para fora da organização"
      }
    }
  },
  "mail_RemetenteDaOrg": {
    "type": "object",
    "description": "Remetente permitido (confia=true) ou bloqueado pela organização. Precedência na entrega: lista pessoal da caixa > lista da org > pontuação. Endereço exato vence domínio; domínio mais específico vence o pai (`@a.loja.com` antes de `@loja.com`).",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "padrao": {
        "type": "string",
        "examples": [
          "@fornecedor.com.br",
          "nf@fornecedor.com.br"
        ],
        "description": "endereço ou @domínio, normalizado em minúsculas"
      },
      "confia": {
        "type": "boolean"
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "mail_VereditoAV": {
    "type": "object",
    "description": "O veredito do antivírus (ADR-0087). Também volta em GET /mailboxes/{id}/messages/{msgId} como `av_status`/`av_assinatura`. `nao_verificado` = nenhum scanner olhou (não é \"limpo\").",
    "properties": {
      "av_status": {
        "type": "string",
        "enum": [
          "nao_verificado",
          "pendente",
          "limpo",
          "infectado"
        ]
      },
      "av_assinatura": {
        "type": [
          "string",
          "null"
        ]
      },
      "av_motor": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "mail_CondicaoDeRegra": {
    "type": "object",
    "required": [
      "campo",
      "operador",
      "valor"
    ],
    "description": "Uma condição do motor de regras v2 (ADR-0087). campo ∈ de, para, cc, qualquer_destinatario, assunto, corpo, tem_anexo, list_id, cabecalho:<Nome>, tamanho, anexo_nome, anexo_tipo, spam_score, av_status, recebida_em, dominio_de. operador ∈ contem, nao_contem, igual, comeca_com, termina_com, regex (RE2, ≤256), dominio (aceita lista \"a.com,b.com\"), um_de / contem_um_de (lista por vírgula, ≤20), maior_que, menor_que, existe, nao_existe — cada campo aceita só os seus. `valor` sem CR/LF (≤512). Nos campos de endereço (de, dominio_de, para, cc, qualquer_destinatario), `igual`/`um_de` com um item que é DOMÍNIO (\"x.com\" ou \"@x.com\") casam o domínio ou qualquer subdomínio dele — a mesma semântica da busca (`de:x.com`); item que é endereço continua igualdade exata.",
    "properties": {
      "campo": {
        "type": "string",
        "examples": [
          "list_id",
          "cabecalho:X-Mailer"
        ]
      },
      "operador": {
        "type": "string",
        "examples": [
          "regex"
        ]
      },
      "valor": {
        "type": "string",
        "maxLength": 512
      }
    }
  },
  "mail_AcaoDeRegra": {
    "type": "object",
    "required": [
      "tipo"
    ],
    "description": "tipo ∈ mover (Entrada, Arquivo ou uma pasta da pessoa — nunca Spam, Lixeira, Quarentena; com várias regras movendo, vence a PRIMEIRA na ordem, org antes das pessoais), arquivar (= mover para o Arquivo: pula a Entrada), apagar (= Lixeira), marcar_lida, estrelar, marcar_importante, nao_eh_spam, marcar_spam, etiquetar, desetiquetar, encaminhar (só destino verificado; nunca retroativo), responder (anti-loop; nunca retroativo). `valor`: pasta; id de etiqueta (pessoal) ou nome (org); destinos separados por vírgula (≤5); texto da resposta.",
    "properties": {
      "tipo": {
        "type": "string"
      },
      "valor": {
        "type": "string"
      }
    }
  },
  "mail_FiltroV2": {
    "type": "object",
    "required": [
      "nome",
      "condicoes",
      "acoes"
    ],
    "description": "Regra pessoal (por caixa e pessoa). Todas as condições precisam casar; o primeiro destino vence.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "nome": {
        "type": "string",
        "maxLength": 80
      },
      "posicao": {
        "type": "integer",
        "readOnly": true
      },
      "ativo": {
        "type": "boolean"
      },
      "parar_aqui": {
        "type": "boolean"
      },
      "condicoes": {
        "type": "array",
        "minItems": 1,
        "maxItems": 20,
        "items": {
          "$ref": "#/components/schemas/mail_CondicaoDeRegra"
        }
      },
      "acoes": {
        "type": "array",
        "minItems": 1,
        "maxItems": 10,
        "items": {
          "$ref": "#/components/schemas/mail_AcaoDeRegra"
        }
      },
      "execucoes": {
        "type": "integer",
        "readOnly": true,
        "description": "quantas vezes a regra agiu"
      },
      "ultima_execucao": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "readOnly": true
      }
    }
  },
  "mail_RegraDaOrg": {
    "description": "Regra da organização — roda antes das pessoais; etiqueta por NOME, pasta só de sistema, sem encaminhar/responder.",
    "allOf": [
      {
        "$ref": "#/components/schemas/mail_FiltroV2"
      },
      {
        "type": "object",
        "properties": {
          "domain_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "null = todas as caixas da org"
          },
          "final": {
            "type": "boolean",
            "description": "depois desta",
            "as regras pessoais não rodam": null
          }
        }
      }
    ]
  },
  "mail_PreviaDeRegras": {
    "type": "object",
    "properties": {
      "examinadas": {
        "type": "integer"
      },
      "afetadas": {
        "type": "integer"
      },
      "restam": {
        "type": "boolean",
        "description": "havia mais mensagens além do teto de 5 000"
      },
      "amostra": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "assunto": {
              "type": "string"
            },
            "de": {
              "type": "string"
            },
            "recebida_em": {
              "type": "string",
              "format": "date-time"
            },
            "acoes": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "tipos; os de efeito externo vêm como \"encaminhar:nao_retroativo\""
            },
            "destino": {
              "type": "string",
              "description": "a pasta onde a mensagem FICA (kind ou id da pasta da pessoa); vazio = não muda"
            }
          }
        }
      }
    }
  },
  "mail_JobDeRegras": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "status": {
        "type": "string",
        "enum": [
          "fila",
          "rodando",
          "feito",
          "falhou",
          "cancelado"
        ]
      },
      "examinadas": {
        "type": "integer"
      },
      "afetadas": {
        "type": "integer"
      },
      "erro": {
        "type": [
          "string",
          "null"
        ]
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "terminado_em": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      }
    }
  },
  "mail_SugestaoDeRegra": {
    "type": "object",
    "properties": {
      "motivo": {
        "type": "string",
        "examples": [
          "142 mensagens da lista novidades.loja.example nos últimos 90 dias, 3% lidas"
        ]
      },
      "filtro": {
        "$ref": "#/components/schemas/mail_FiltroV2"
      }
    }
  },
  "mail_EventoDeAuditoriaDeRegra": {
    "type": "object",
    "properties": {
      "regra_id": {
        "type": [
          "string",
          "null"
        ],
        "format": "uuid"
      },
      "user_id": {
        "type": "string"
      },
      "operacao": {
        "type": "string",
        "enum": [
          "criar",
          "editar",
          "apagar",
          "reordenar",
          "aplicar"
        ]
      },
      "antes": {
        "type": [
          "object",
          "null"
        ]
      },
      "depois": {
        "type": [
          "object",
          "null"
        ]
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "mail_ExecucaoDeRegra": {
    "type": "object",
    "properties": {
      "regra_id": {
        "type": "string",
        "format": "uuid"
      },
      "origem": {
        "type": "string",
        "enum": [
          "usuario",
          "org"
        ]
      },
      "nome": {
        "type": [
          "string",
          "null"
        ],
        "description": "null quando a regra foi apagada ou é regra pessoal de outra pessoa"
      },
      "momento": {
        "type": "string",
        "enum": [
          "entrega",
          "lote"
        ]
      },
      "acoes": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/mail_AcaoDeRegra"
        }
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "mail_DestinoDeEncaminhamento": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "email": {
        "type": "string"
      },
      "verificado_em": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "mesma_org": {
        "type": "boolean"
      }
    }
  },
  "mail_CaixaAtribuivel": {
    "type": "object",
    "description": "Linha da busca de atribuíveis — só metadado de gestão.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "address": {
        "type": "string",
        "example": "sac@empresa.test.asender.com.br"
      },
      "domain_id": {
        "type": "string",
        "format": "uuid"
      },
      "domain": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "pessoal",
          "coletiva"
        ]
      },
      "origem": {
        "type": "string",
        "enum": [
          "manual",
          "automatica",
          "conta_iam",
          "legado"
        ]
      },
      "titulares": {
        "type": "integer",
        "description": "pessoas com grant ativo"
      },
      "pessoal_de_outra_pessoa": {
        "type": "boolean",
        "description": "caixa pessoal (conta_iam) da qual quem busca não é dono"
      }
    }
  },
  "mail_LoteGrantsCorpo": {
    "type": "object",
    "required": [
      "operacao",
      "usuarios",
      "alvo"
    ],
    "properties": {
      "operacao": {
        "type": "string",
        "enum": [
          "conceder",
          "revogar"
        ]
      },
      "usuarios": {
        "type": "array",
        "minItems": 1,
        "maxItems": 20,
        "uniqueItems": true,
        "items": {
          "type": "string"
        },
        "description": "pessoas ATIVAS do tenant"
      },
      "papel": {
        "type": "string",
        "enum": [
          "owner",
          "delegate"
        ],
        "default": "delegate",
        "description": "só ao conceder"
      },
      "alvo": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "modo",
              "caixas"
            ],
            "properties": {
              "modo": {
                "type": "string",
                "enum": [
                  "caixas"
                ]
              },
              "caixas": {
                "type": "array",
                "minItems": 1,
                "maxItems": 500,
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              }
            }
          },
          {
            "type": "object",
            "required": [
              "modo"
            ],
            "properties": {
              "modo": {
                "type": "string",
                "enum": [
                  "todas"
                ]
              },
              "dominio_id": {
                "type": "string",
                "format": "uuid"
              },
              "tipo": {
                "type": "string",
                "enum": [
                  "pessoal",
                  "coletiva"
                ]
              },
              "incluir_pessoais": {
                "type": "boolean",
                "description": "inclui caixas conta_iam (exige confirmar_pessoais)"
              }
            }
          }
        ]
      },
      "confirmar_pessoais": {
        "type": "boolean"
      },
      "confirmar_acesso_proprio": {
        "type": "boolean",
        "description": "exigido ao conceder quando o próprio admin está entre as pessoas"
      }
    }
  },
  "mail_LotePrevia": {
    "type": "object",
    "properties": {
      "total_caixas": {
        "type": "integer"
      },
      "total_pares": {
        "type": "integer"
      },
      "a_alterar": {
        "type": "integer",
        "description": "pares que a execução mudaria"
      },
      "ja_tem": {
        "type": "integer",
        "description": "conceder: pares que já têm grant; revogar: pares sem grant (nada a fazer)"
      },
      "papel_diferente_mantido": {
        "type": "integer",
        "description": "pares que já têm grant com OUTRO papel — mantido, nunca alterado"
      },
      "pessoais_incluidas": {
        "type": "integer"
      },
      "lotes": {
        "type": "integer",
        "description": "nº de páginas da execução"
      },
      "confirmacao_esperada": {
        "type": "integer",
        "description": "valor de `confirmar_contagem` (== a_alterar)"
      },
      "amostra": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "object",
          "properties": {
            "address": {
              "type": "string"
            },
            "user_id": {
              "type": "string"
            },
            "acao": {
              "type": "string",
              "enum": [
                "conceder",
                "revogar",
                "pular"
              ]
            }
          }
        }
      }
    }
  },
  "mail_LoteResultado": {
    "type": "object",
    "properties": {
      "lote_id": {
        "type": "string",
        "format": "uuid"
      },
      "processadas": {
        "type": "integer",
        "description": "caixas da página"
      },
      "concedidos": {
        "type": "integer"
      },
      "revogados": {
        "type": "integer"
      },
      "ja_tinham": {
        "type": "integer",
        "description": "pares pulados (conceder: já tinham; revogar: não tinham)"
      },
      "proximo": {
        "type": "string",
        "nullable": true,
        "description": "cursor para o `apos` da próxima chamada; nulo ao concluir"
      },
      "concluido": {
        "type": "boolean"
      }
    }
  },
  "auth_MeSegurancaEmailExternoBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "email"
    ],
    "properties": {
      "email": {
        "type": "string",
        "maxLength": 254
      }
    }
  },
  "auth_MeSegurancaCodigoBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "codigo"
    ],
    "properties": {
      "codigo": {
        "type": "string",
        "pattern": "^[0-9]{6}$"
      }
    }
  },
  "auth_MeSegurancaAdiamentos": {
    "type": "object",
    "properties": {
      "quantidade": {
        "type": "integer",
        "description": "Total de adiamentos da conta."
      },
      "seguidos": {
        "type": "integer",
        "description": "Adiamentos desde a última ativação."
      },
      "ultimo_em": {
        "type": "string",
        "format": "date-time",
        "nullable": true
      },
      "vira_link": {
        "type": "boolean",
        "description": "Com 3 seguidos o passo vira link na faixa, sem modal (D15)."
      }
    }
  },
  "auth_MeSegurancaAdiamento": {
    "type": "object",
    "properties": {
      "adiado": {
        "type": "boolean"
      },
      "reaparece": {
        "type": "string",
        "enum": [
          "proxima_sessao"
        ]
      },
      "adiamentos": {
        "$ref": "#/components/schemas/auth_MeSegurancaAdiamentos"
      }
    }
  },
  "auth_MeSegurancaMetodos": {
    "type": "object",
    "properties": {
      "contagem": {
        "type": "integer"
      },
      "tipos": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "senha",
            "passkey",
            "totp",
            "email_externo"
          ]
        }
      },
      "minimo_admin": {
        "type": "integer",
        "example": 2
      },
      "emails_externos": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Mascarados."
      }
    }
  },
  "auth_MeSegurancaSituacao": {
    "type": "object",
    "description": "Situação de segurança da própria conta (ADR-0146 D8/D15/D17).",
    "properties": {
      "modo": {
        "type": "string",
        "enum": [
          false,
          "observar",
          "enforce"
        ]
      },
      "nivel_efetivo": {
        "type": "string",
        "enum": [
          "estrito",
          "reduzido"
        ]
      },
      "modo_reduzido": {
        "type": "boolean"
      },
      "limites": {
        "type": "object",
        "description": "Vazio no estrito; no reduzido: sessao_absoluta_horas, inatividade_horas, dispositivos_max, api_keys_permitidas, acoes_sensiveis_por_hora."
      },
      "segundo_fator_obrigatorio": {
        "type": "boolean"
      },
      "origem": {
        "type": "string"
      },
      "expira_em": {
        "type": "string",
        "format": "date-time",
        "nullable": true
      },
      "protegido": {
        "type": "boolean"
      },
      "admin_apto": {
        "type": "boolean"
      },
      "pode_adiar": {
        "type": "boolean"
      },
      "exige_cadastro": {
        "type": "boolean",
        "description": "Poder administrativo com < 2 métodos (D17): ativação obrigatória, sem 'depois'."
      },
      "ativacao_obrigatoria_admin": {
        "type": "boolean",
        "description": "Alias de exige_cadastro (compatibilidade com a U1)."
      },
      "metodos_verificados": {
        "type": "integer",
        "description": "Alias de metodos.contagem para protegido (compatibilidade com a U1)."
      },
      "metodos": {
        "$ref": "#/components/schemas/auth_MeSegurancaMetodos"
      },
      "adiamentos": {
        "$ref": "#/components/schemas/auth_MeSegurancaAdiamentos"
      },
      "somente_leitura_ate": {
        "type": "string",
        "format": "date-time",
        "nullable": true
      }
    }
  },
  "auth_SegurancaDecisao": {
    "type": "object",
    "description": "Decisão efetiva de 2FA da conta (ADR-0146).",
    "properties": {
      "modo": {
        "type": "string",
        "enum": [
          false,
          "observar",
          "enforce"
        ]
      },
      "nivel_efetivo": {
        "type": "string",
        "enum": [
          "estrito",
          "reduzido"
        ]
      },
      "segundo_fator_obrigatorio": {
        "type": "boolean"
      },
      "origem": {
        "type": "string"
      },
      "protegido": {
        "type": "boolean"
      },
      "pode_adiar": {
        "type": "boolean"
      },
      "expira_em": {
        "type": "string",
        "format": "date-time",
        "nullable": true
      },
      "admin_apto": {
        "type": "boolean"
      },
      "metodos_verificados": {
        "type": "integer"
      },
      "observado": {
        "type": "string",
        "description": "No modo observar, o nível que valeria em enforce."
      }
    }
  },
  "auth_SegurancaExcecao": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "escopo": {
        "type": "string",
        "enum": [
          "equipe",
          "usuario"
        ]
      },
      "user_id": {
        "type": "string"
      },
      "motivo": {
        "type": "string"
      },
      "criada_por": {
        "type": "string"
      },
      "criada_em": {
        "type": "string",
        "format": "date-time"
      },
      "expira_em": {
        "type": "string",
        "format": "date-time"
      },
      "revogada_em": {
        "type": "string",
        "format": "date-time"
      },
      "ativa": {
        "type": "boolean"
      }
    }
  },
  "auth_SegurancaVisao": {
    "type": "object",
    "properties": {
      "tenant_id": {
        "type": "string"
      },
      "modo": {
        "type": "string",
        "enum": [
          false,
          "observar",
          "enforce"
        ]
      },
      "efeito_ativo": {
        "type": "boolean"
      },
      "nivel_base": {
        "type": "string",
        "enum": [
          "estrito",
          "recomendado"
        ]
      },
      "configurada": {
        "type": "boolean"
      },
      "atualizado_por": {
        "type": "string"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      },
      "motivo": {
        "type": "string"
      },
      "excecoes": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/auth_SegurancaExcecao"
        }
      },
      "contas_sem_fator": {
        "type": "integer"
      },
      "parametros_modo_reduzido": {
        "type": "object"
      },
      "compensacoes_aplicadas": {
        "type": "boolean"
      }
    }
  },
  "auth_ErrorEnvelope": {
    "type": "object",
    "required": [
      "Error",
      "RequestId"
    ],
    "properties": {
      "Error": {
        "type": "object",
        "required": [
          "Type",
          "Code",
          "Message"
        ],
        "properties": {
          "Type": {
            "type": "string",
            "enum": [
              "Sender",
              "Receiver"
            ]
          },
          "Code": {
            "type": "string",
            "examples": [
              "InvalidRequest",
              "InvalidInput",
              "MissingToken",
              "InvalidCredentials",
              "InvalidToken",
              "ExpiredToken",
              "TwoFactorFailed",
              "TwoFactorSuperseded",
              "TwoFactorCodeExpired",
              "TwoFactorMissing",
              "NotFound",
              "Conflict",
              "NotReady",
              "InternalError"
            ]
          },
          "Message": {
            "type": "string"
          },
          "Details": {}
        }
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_User": {
    "type": "object",
    "description": "Nunca traz `password_hash` nem o segredo TOTP.",
    "properties": {
      "id": {
        "type": "string",
        "examples": [
          "usr_demo_owner"
        ]
      },
      "email": {
        "type": "string",
        "format": "email"
      },
      "name": {
        "type": "string"
      },
      "created_at": {
        "type": "string",
        "format": "date-time"
      },
      "deleted_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "Migration 012: não-nulo só pelo caminho de exclusão de plataforma."
      },
      "deleted_by": {
        "type": [
          "string",
          "null"
        ]
      },
      "delete_reason": {
        "type": [
          "string",
          "null"
        ]
      },
      "purge_at": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "Quando o purge automático apaga de verdade (deleted_at + 30 dias)."
      }
    }
  },
  "auth_LoginResult": {
    "type": "object",
    "properties": {
      "token": {
        "type": "string",
        "description": "JWT de sessão. VAZIO quando `two_factor_required`."
      },
      "expires_at": {
        "type": "string",
        "format": "date-time"
      },
      "user_id": {
        "type": "string"
      },
      "two_factor_required": {
        "type": "boolean"
      },
      "two_factor_token": {
        "type": "string",
        "description": "TICKET de desafio 2FA (JWT curto, ~5 min, assinado). Presente **só**\nquando `two_factor_required:true`. Prova, no passo do código, que a\nsenha já foi apresentada neste login. É o valor que `POST\n/v1/2fa/check` EXIGE — o cliente o repassa, não o inspeciona."
      },
      "two_factor_method": {
        "type": "string",
        "enum": [
          "email",
          "totp"
        ],
        "description": "CANAL do segundo fator. `email` (padrão de toda conta): o login já\nenviou um código de 6 dígitos ao e-mail do usuário — a tela mostra\n\"enviamos um código\" e oferece reenvio (`POST /v1/2fa/email/resend`).\n`totp`: o usuário digita o código do app. Presente só com\n`two_factor_required:true`. Conta GERENCIADA nunca recebe `email`."
      },
      "enrollment_required": {
        "type": "boolean",
        "description": "Conta GERENCIADA sem fator utilizável (TOTP confirmado): a senha bateu, mas\nNENHUMA sessão e NENHUM e-mail saíram (o e-mail do login é a própria caixa —\ncanal circular). O cliente abre a ativação com `enrollment_token`."
      },
      "enrollment_token": {
        "type": "string",
        "description": "Ticket de ativação (JWT ~15 min, aud própria). Não é sessão: só as rotas\n`/v1/auth/ativacao/*` o aceitam. Presente só com `enrollment_required:true`."
      },
      "must_reset": {
        "type": "boolean",
        "description": "Senha temporária: troca obrigatória (também na ativação)."
      }
    }
  },
  "auth_AtivacaoTicketBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "ticket"
    ],
    "properties": {
      "ticket": {
        "type": "string",
        "description": "O `enrollment_token` do login."
      }
    }
  },
  "auth_UserIdBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "user_id"
    ],
    "properties": {
      "user_id": {
        "type": "string"
      }
    }
  },
  "auth_UserSenhaBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "user_id",
      "senha"
    ],
    "description": "Corpo das operações que MEXEM num fator (ligar/trocar). A `senha` é o\nfator ≠ do que se altera (piso 17).",
    "properties": {
      "user_id": {
        "type": "string"
      },
      "senha": {
        "type": "string",
        "format": "password"
      }
    }
  },
  "auth_TwoFAResendBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "two_factor_token"
    ],
    "description": "Reenvio do código de e-mail. A identidade vem do ticket, não de um `user_id`.",
    "properties": {
      "two_factor_token": {
        "type": "string",
        "description": "O ticket de desafio devolvido por `POST /v1/auth/login`."
      }
    }
  },
  "auth_TwoFACodeBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "user_id",
      "code"
    ],
    "properties": {
      "user_id": {
        "type": "string"
      },
      "code": {
        "type": "string",
        "description": "TOTP de 6 dígitos."
      }
    }
  },
  "auth_TwoFACheckBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "two_factor_token",
      "code"
    ],
    "description": "Corpo do 2º passo do login. Sem `user_id`: a identidade e a escolha de\nsessão longa vêm do `two_factor_token` assinado, não de um campo cru.",
    "properties": {
      "two_factor_token": {
        "type": "string",
        "description": "O ticket de desafio devolvido por `POST /v1/auth/login`."
      },
      "code": {
        "type": "string",
        "description": "Código de 6 dígitos do canal da conta (app ou e-mail) OU um código de recuperação (XXXX-XXXX-XXXX, uso único; gasto grava `codigo_recuperacao_usado` e avisa)."
      }
    }
  },
  "auth_Discovery": {
    "type": "object",
    "description": "Metadados do provedor OIDC (OIDC Discovery + RFC 8414). Cacheável (`Cache-Control: public, max-age=300`); muda só em deploy/rotação.",
    "properties": {
      "issuer": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net"
        ]
      },
      "authorization_endpoint": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net/authorize"
        ]
      },
      "token_endpoint": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net/token"
        ]
      },
      "userinfo_endpoint": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net/userinfo"
        ]
      },
      "jwks_uri": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net/.well-known/jwks.json"
        ]
      },
      "end_session_endpoint": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net/logout"
        ]
      },
      "registration_endpoint": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net/register"
        ],
        "description": "RFC 7591; só quando OAUTH_DCR_ATIVO=true."
      },
      "client_id_metadata_document_supported": {
        "type": "boolean",
        "description": "CIMD; só quando OAUTH_CIMD_ATIVO=true."
      },
      "response_types_supported": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "code"
          ]
        ]
      },
      "grant_types_supported": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "authorization_code",
            "refresh_token"
          ]
        ]
      },
      "subject_types_supported": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "public"
          ]
        ]
      },
      "id_token_signing_alg_values_supported": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "RS256"
          ]
        ]
      },
      "token_endpoint_auth_methods_supported": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "client_secret_basic",
            "client_secret_post",
            "none"
          ]
        ]
      },
      "code_challenge_methods_supported": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "S256"
          ]
        ]
      },
      "scopes_supported": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          [
            "openid",
            "profile",
            "email",
            "offline_access"
          ]
        ]
      },
      "claims_supported": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "auth_JWKS": {
    "type": "object",
    "description": "Conjunto de chaves públicas RS256 (JWK Set) para validar a assinatura dos tokens.",
    "required": [
      "keys"
    ],
    "properties": {
      "keys": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/auth_JWK"
        }
      }
    }
  },
  "auth_JWK": {
    "type": "object",
    "description": "Uma chave pública RSA no formato JWK (RFC 7517).",
    "required": [
      "kty",
      "use",
      "alg",
      "kid",
      "n",
      "e"
    ],
    "properties": {
      "kty": {
        "type": "string",
        "enum": [
          "RSA"
        ]
      },
      "use": {
        "type": "string",
        "enum": [
          "sig"
        ]
      },
      "alg": {
        "type": "string",
        "enum": [
          "RS256"
        ]
      },
      "kid": {
        "type": "string",
        "description": "key id; casa com o header `kid` do JWT para escolher a chave certa numa rotação"
      },
      "n": {
        "type": "string",
        "description": "módulo RSA, base64url sem padding"
      },
      "e": {
        "type": "string",
        "description": "expoente RSA, base64url sem padding"
      }
    }
  },
  "auth_TokenResponse": {
    "type": "object",
    "description": "Resposta de sucesso do `POST /token` (RFC 6749 §5.1 + OIDC). `Cache-Control: no-store`.",
    "required": [
      "access_token",
      "token_type",
      "expires_in"
    ],
    "properties": {
      "access_token": {
        "type": "string",
        "description": "JWT RS256 (`tok_use:access`) para chamar as APIs; `aud` = client_id"
      },
      "token_type": {
        "type": "string",
        "enum": [
          "Bearer"
        ]
      },
      "expires_in": {
        "type": "integer",
        "description": "segundos até o access token expirar"
      },
      "id_token": {
        "type": "string",
        "description": "JWT RS256 (`tok_use:id`) que prova QUEM logou; validado no client contra o JWKS"
      },
      "refresh_token": {
        "type": "string",
        "description": "presente só quando o scope pediu `offline_access`; opaco, rotacionado a cada uso"
      },
      "scope": {
        "type": "string",
        "description": "os escopos efetivamente concedidos (inclui sempre `openid`)"
      }
    }
  },
  "auth_ErroOAuth": {
    "type": "object",
    "description": "Envelope de erro OAuth (RFC 6749 §5.2), usado por `/token` e `/userinfo`.",
    "required": [
      "error"
    ],
    "properties": {
      "error": {
        "type": "string",
        "description": "código do erro",
        "examples": [
          "invalid_grant",
          "invalid_client",
          "invalid_request",
          "unsupported_grant_type",
          "invalid_token",
          "server_error"
        ]
      },
      "error_description": {
        "type": "string",
        "description": "detalhe legível; nunca vaza segredo nem existência de recurso alheio"
      }
    }
  },
  "auth_Introspeccao": {
    "type": "object",
    "description": "Resposta da introspecção (RFC 7662). Inativo traz só `active:false`.",
    "required": [
      "active"
    ],
    "properties": {
      "active": {
        "type": "boolean"
      },
      "scope": {
        "type": "string"
      },
      "client_id": {
        "type": "string"
      },
      "sub": {
        "type": "string",
        "description": "ID interno imutável do usuário"
      },
      "tenant": {
        "type": "string",
        "description": "a conta (acc_…) do consentimento"
      },
      "exp": {
        "type": "integer"
      },
      "iat": {
        "type": "integer"
      },
      "iss": {
        "type": "string"
      },
      "aud": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "jti": {
        "type": "string"
      },
      "token_type": {
        "type": "string",
        "enum": [
          "Bearer",
          "refresh_token"
        ]
      }
    }
  },
  "auth_EscopoOAuth": {
    "type": "object",
    "required": [
      "id",
      "rotulo",
      "descricao",
      "leitura"
    ],
    "properties": {
      "id": {
        "type": "string",
        "examples": [
          "leads:read"
        ]
      },
      "rotulo": {
        "type": "string",
        "description": "pt-BR, para a tela de consentimento"
      },
      "descricao": {
        "type": "string"
      },
      "leitura": {
        "type": "boolean",
        "description": "true nos escopos `*:read`"
      }
    }
  },
  "auth_ConsentimentoView": {
    "type": "object",
    "required": [
      "client",
      "escopos",
      "contas"
    ],
    "properties": {
      "client": {
        "type": "object",
        "properties": {
          "nome": {
            "type": "string"
          },
          "site_url": {
            "type": "string"
          },
          "logo_url": {
            "type": "string"
          },
          "verificado": {
            "type": "boolean",
            "description": "selo Verificado pela Asender"
          },
          "estado": {
            "type": "string",
            "enum": [
              "desenvolvimento",
              "em_revisao",
              "publicado",
              "recusado",
              "suspenso"
            ]
          },
          "origem": {
            "type": "string",
            "enum": [
              "ops",
              "portal",
              "cimd",
              "dcr"
            ]
          },
          "dominios_redirect": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "hosts únicos (sem porta) dos redirect_uris"
          }
        }
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "rotulo": {
              "type": "string"
            },
            "descricao": {
              "type": "string"
            }
          }
        }
      },
      "contas": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "acc_…"
            },
            "nome": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "auth_AppPortal": {
    "type": "object",
    "properties": {
      "client_id": {
        "type": "string"
      },
      "nome": {
        "type": "string"
      },
      "type": {
        "type": "string",
        "enum": [
          "confidential",
          "public"
        ]
      },
      "site_url": {
        "type": "string"
      },
      "logo_url": {
        "type": "string"
      },
      "redirect_uris": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "declarados"
      },
      "escopos_aprovados": {
        "type": "array",
        "nullable": true,
        "items": {
          "type": "string"
        },
        "description": "null = ainda sem revisão"
      },
      "estado": {
        "type": "string",
        "enum": [
          "desenvolvimento",
          "em_revisao",
          "publicado",
          "recusado",
          "suspenso"
        ]
      },
      "origem": {
        "type": "string",
        "enum": [
          "ops",
          "portal",
          "cimd",
          "dcr"
        ]
      },
      "verificado": {
        "type": "boolean"
      },
      "motivo_estado": {
        "type": "string",
        "description": "motivo da última recusa ou suspensão"
      },
      "conta": {
        "type": "string",
        "description": "acc_… dona"
      },
      "revisao_pendente": {
        "type": "boolean"
      },
      "criado_por": {
        "type": "string"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "auth_AppPortalNovo": {
    "type": "object",
    "required": [
      "conta",
      "nome",
      "redirect_uris",
      "escopos"
    ],
    "properties": {
      "conta": {
        "type": "string",
        "description": "acc_… (owner/admin)"
      },
      "nome": {
        "type": "string",
        "maxLength": 100
      },
      "site_url": {
        "type": "string",
        "format": "uri"
      },
      "logo_url": {
        "type": "string",
        "format": "uri"
      },
      "redirect_uris": {
        "type": "array",
        "maxItems": 10,
        "items": {
          "type": "string"
        }
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "type": {
        "type": "string",
        "enum": [
          "confidential",
          "public"
        ],
        "default": "confidential"
      }
    }
  },
  "auth_AppPortalAjuste": {
    "type": "object",
    "properties": {
      "nome": {
        "type": "string"
      },
      "site_url": {
        "type": "string"
      },
      "logo_url": {
        "type": "string"
      },
      "redirect_uris": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "auth_TestadorApp": {
    "type": "object",
    "properties": {
      "user_id": {
        "type": "string",
        "description": "id público usr_…"
      },
      "nome": {
        "type": "string"
      },
      "email": {
        "type": "string"
      },
      "convidado_em": {
        "type": "string"
      }
    }
  },
  "auth_RevisaoApp": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "pedido_por": {
        "type": "string",
        "description": "só na visão da equipe"
      },
      "escopos_pedidos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "decisao": {
        "type": "string",
        "description": "vazio = pendente; aprovado, recusado, suspenso, reativado, verificado, nao_verificado, publicado_ops"
      },
      "revisor": {
        "type": "string",
        "description": "só na visão da equipe"
      },
      "motivo": {
        "type": "string"
      },
      "escopos_aprovados": {
        "type": "array",
        "nullable": true,
        "items": {
          "type": "string"
        }
      },
      "decidido_em": {
        "type": "string",
        "nullable": true
      },
      "criado_em": {
        "type": "string"
      }
    }
  },
  "auth_ItemFilaRevisao": {
    "type": "object",
    "properties": {
      "revisao_id": {
        "type": "string"
      },
      "app": {
        "$ref": "#/components/schemas/auth_AppPortal"
      },
      "pedido_por": {
        "type": "string"
      },
      "escopos_pedidos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "pedido_em": {
        "type": "string"
      }
    }
  },
  "auth_BloqueioDominio": {
    "type": "object",
    "required": [
      "dominio",
      "motivo",
      "bloqueado_por"
    ],
    "properties": {
      "dominio": {
        "type": "string"
      },
      "motivo": {
        "type": "string"
      },
      "bloqueado_por": {
        "type": "string"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "auth_RegistroClientePedido": {
    "type": "object",
    "required": [
      "redirect_uris"
    ],
    "description": "Metadados do RFC 7591 aceitos; os demais campos são ignorados.",
    "properties": {
      "client_name": {
        "type": "string",
        "maxLength": 100
      },
      "client_uri": {
        "type": "string",
        "format": "uri"
      },
      "logo_uri": {
        "type": "string",
        "format": "uri"
      },
      "redirect_uris": {
        "type": "array",
        "minItems": 1,
        "maxItems": 10,
        "items": {
          "type": "string",
          "format": "uri"
        }
      },
      "grant_types": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "authorization_code",
            "refresh_token"
          ]
        }
      },
      "response_types": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "code"
          ]
        }
      },
      "token_endpoint_auth_method": {
        "type": "string",
        "enum": [
          "none"
        ]
      },
      "scope": {
        "type": "string",
        "description": "Separado por espaço; só identidade e leitura são mantidos."
      }
    }
  },
  "auth_RegistroClienteResposta": {
    "type": "object",
    "required": [
      "client_id",
      "client_id_issued_at",
      "redirect_uris",
      "grant_types",
      "response_types",
      "token_endpoint_auth_method",
      "scope"
    ],
    "description": "Metadados EFETIVOS. Nunca traz `client_secret` nem `registration_access_token`.",
    "properties": {
      "client_id": {
        "type": "string",
        "examples": [
          "dcr_0123456789abcdef0123456789abcdef"
        ]
      },
      "client_id_issued_at": {
        "type": "integer",
        "description": "Unix, segundos."
      },
      "client_name": {
        "type": "string"
      },
      "client_uri": {
        "type": "string"
      },
      "logo_uri": {
        "type": "string"
      },
      "redirect_uris": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "grant_types": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "response_types": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "token_endpoint_auth_method": {
        "type": "string",
        "enum": [
          "none"
        ]
      },
      "scope": {
        "type": "string"
      }
    }
  },
  "auth_MotivoRevisao": {
    "type": "object",
    "required": [
      "motivo"
    ],
    "properties": {
      "motivo": {
        "type": "string",
        "minLength": 5,
        "maxLength": 500
      }
    }
  },
  "auth_ConsentimentoDecisao": {
    "type": "object",
    "required": [
      "decisao"
    ],
    "properties": {
      "conta": {
        "type": "string",
        "description": "acc_… escolhida; obrigatória em `aprovar`"
      },
      "decisao": {
        "type": "string",
        "enum": [
          "aprovar",
          "negar"
        ]
      }
    }
  },
  "auth_AppConectado": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "description": "id do grant (use em DELETE)"
      },
      "nome": {
        "type": "string"
      },
      "site_url": {
        "type": "string"
      },
      "logo_url": {
        "type": "string"
      },
      "conta": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "nome": {
            "type": "string"
          }
        }
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "rotulo": {
              "type": "string"
            },
            "descricao": {
              "type": "string"
            }
          }
        }
      },
      "conectado_em": {
        "type": "string",
        "format": "date-time"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "auth_OAuthClient": {
    "type": "object",
    "description": "Um app de terceiro. Nunca carrega o segredo nem o hash.",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "confidential",
          "public"
        ]
      },
      "client_id": {
        "type": "string",
        "examples": [
          "app_0123456789abcdef"
        ]
      },
      "nome": {
        "type": "string"
      },
      "site_url": {
        "type": "string"
      },
      "logo_url": {
        "type": "string"
      },
      "redirects": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "refresh_ttl_s": {
        "type": "integer",
        "description": "0 = padrão do AS"
      },
      "ativo": {
        "type": "boolean"
      },
      "dono_tenant": {
        "type": "string"
      },
      "criado_por": {
        "type": "string"
      },
      "criado_em": {
        "type": "string"
      }
    }
  },
  "auth_OAuthClientNovo": {
    "type": "object",
    "required": [
      "nome",
      "redirects",
      "escopos"
    ],
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "confidential",
          "public"
        ],
        "default": "confidential",
        "description": "público = sem segredo (apps nativos/CLI/MCP)"
      },
      "nome": {
        "type": "string",
        "maxLength": 100
      },
      "site_url": {
        "type": "string",
        "format": "uri"
      },
      "logo_url": {
        "type": "string",
        "format": "uri"
      },
      "redirects": {
        "type": "array",
        "minItems": 1,
        "maxItems": 10,
        "items": {
          "type": "string",
          "format": "uri"
        }
      },
      "escopos": {
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "string"
        }
      },
      "refresh_ttl_s": {
        "type": "integer",
        "minimum": 3600,
        "maximum": 31536000
      },
      "dono_tenant": {
        "type": "string"
      },
      "motivo": {
        "type": "string"
      }
    }
  },
  "auth_OAuthClientAjuste": {
    "type": "object",
    "properties": {
      "nome": {
        "type": "string"
      },
      "site_url": {
        "type": "string"
      },
      "logo_url": {
        "type": "string"
      },
      "redirects": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "refresh_ttl_s": {
        "type": "integer"
      },
      "ativo": {
        "type": "boolean"
      },
      "motivo": {
        "type": "string"
      }
    }
  },
  "auth_Ok": {
    "type": "object",
    "properties": {
      "ok": {
        "type": "boolean",
        "const": true
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeConta": {
    "type": "object",
    "required": [
      "user",
      "fatores"
    ],
    "properties": {
      "user": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "usr_demo_owner"
            ]
          },
          "name": {
            "type": "string"
          },
          "email_primario": {
            "type": "string",
            "format": "email"
          },
          "criado_em": {
            "type": "string",
            "format": "date-time"
          },
          "password_changed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "must_reset": {
            "type": "boolean"
          }
        }
      },
      "fatores": {
        "type": "object",
        "properties": {
          "senha": {
            "type": "boolean"
          },
          "email_otp": {
            "type": "boolean"
          },
          "totp": {
            "type": "boolean"
          },
          "codigos_restantes": {
            "type": "integer"
          },
          "passkeys": {
            "type": "integer"
          }
        }
      },
      "reauth": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/auth_MeReauthEstado"
          },
          {
            "type": "null"
          }
        ]
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MePerfilBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "minLength": 1
      }
    }
  },
  "auth_MeMetodo": {
    "type": "string",
    "enum": [
      "email_otp",
      "totp",
      "senha",
      "codigo_recuperacao",
      "passkey"
    ]
  },
  "auth_MeReauthStartBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "metodo"
    ],
    "properties": {
      "metodo": {
        "$ref": "#/components/schemas/auth_MeMetodo"
      },
      "email_id": {
        "type": "string",
        "format": "uuid",
        "description": "Só `email_otp`: o e-mail VERIFICADO que recebe o código (ausente = padrão)."
      },
      "origem": {
        "type": "string",
        "format": "uri",
        "description": "Só `passkey`: a origem do auth_front em que a cerimônia roda (allowlist).",
        "examples": [
          "https://auth.asender.net"
        ]
      }
    }
  },
  "auth_MeDestino": {
    "type": "object",
    "description": "Destino possível do e-mail OTP da reauth. O endereço em claro nunca sai.",
    "required": [
      "email_id",
      "mascarado",
      "primario"
    ],
    "properties": {
      "email_id": {
        "type": "string",
        "format": "uuid"
      },
      "mascarado": {
        "type": "string",
        "examples": [
          "m***@test.asender.com.br"
        ]
      },
      "primario": {
        "type": "boolean"
      }
    }
  },
  "auth_MeReauthStartResp": {
    "type": "object",
    "properties": {
      "metodo": {
        "$ref": "#/components/schemas/auth_MeMetodo"
      },
      "destinos": {
        "type": "array",
        "description": "Só `email_otp`. Primário primeiro; o 1º é o padrão.",
        "items": {
          "$ref": "#/components/schemas/auth_MeDestino"
        }
      },
      "enviado_para": {
        "type": "string",
        "description": "Só `email_otp`: o mascarado de quem recebeu."
      },
      "desafio_id": {
        "type": "string",
        "format": "uuid",
        "description": "Só `passkey`: volta no confirm (uso único, 5 min, preso a esta sessão)."
      },
      "opcoes": {
        "$ref": "#/components/schemas/auth_WebAuthnOpcoes"
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeReauthRequiredDetails": {
    "type": "object",
    "description": "`Error.Details` do 403 ReauthRequired.",
    "properties": {
      "metodos_aceitos": {
        "type": "array",
        "description": "Os métodos da política que a conta PODE usar agora (vazio = nenhum: a tela explica o que fazer).",
        "items": {
          "$ref": "#/components/schemas/auth_MeMetodo"
        }
      },
      "metodos": {
        "type": "object",
        "description": "P5: TODOS os métodos da política da rota, cada um com `disponivel` e, se não, o `motivo`.",
        "additionalProperties": {
          "$ref": "#/components/schemas/auth_MeMetodoEstado"
        },
        "examples": [
          {
            "senha": {
              "disponivel": true
            },
            "email_otp": {
              "disponivel": false,
              "motivo": "EmailNaoVerificado"
            }
          }
        ]
      },
      "destinos": {
        "type": "array",
        "description": "Só quando `email_otp` está entre os aceitos.",
        "items": {
          "$ref": "#/components/schemas/auth_MeDestino"
        }
      }
    }
  },
  "auth_MeMetodoEstado": {
    "type": "object",
    "required": [
      "disponivel"
    ],
    "properties": {
      "disponivel": {
        "type": "boolean"
      },
      "motivo": {
        "type": "string",
        "enum": [
          "EmailNaoVerificado",
          "TOTPNaoAtivado",
          "SemCodigos",
          "SemPasskey",
          "SemSenha",
          "NaoSuportado"
        ],
        "description": "Só quando indisponível. `EmailNaoVerificado`: nenhum e-mail verificado — a tela manda verificar (reenviar não pede reauth)."
      }
    }
  },
  "auth_WebAuthnOpcoes": {
    "type": "object",
    "description": "As opções da cerimônia WebAuthn como a go-webauthn as serializa: `{publicKey:{…}}`, campos binários (challenge, user.id, ids de credencial) em base64url.",
    "properties": {
      "publicKey": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "additionalProperties": true
  },
  "auth_WebAuthnCredencial": {
    "type": "object",
    "description": "A PublicKeyCredential em JSON (formato `toJSON` da especificação): id, rawId, type, response{clientDataJSON, attestationObject|authenticatorData+signature+userHandle}, clientExtensionResults.",
    "required": [
      "id",
      "rawId",
      "type",
      "response"
    ],
    "additionalProperties": true,
    "properties": {
      "id": {
        "type": "string"
      },
      "rawId": {
        "type": "string"
      },
      "type": {
        "type": "string",
        "enum": [
          "public-key"
        ]
      },
      "response": {
        "type": "object",
        "additionalProperties": true
      }
    }
  },
  "auth_MePasskey": {
    "type": "object",
    "description": "Uma chave de acesso. Nunca sai a chave pública nem o credential id.",
    "required": [
      "id",
      "nome",
      "criado_em",
      "sincronizada",
      "rp_id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "nome": {
        "type": "string",
        "maxLength": 64
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "usado_em": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "sincronizada": {
        "type": "boolean",
        "description": "Credencial de backup (iCloud/Google): BE=1."
      },
      "rp_id": {
        "type": "string",
        "examples": [
          "auth.asender.net"
        ]
      }
    }
  },
  "auth_MePasskeys": {
    "type": "object",
    "properties": {
      "passkeys": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/auth_MePasskey"
        }
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MePasskeyRegistroStartBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "origem"
    ],
    "properties": {
      "origem": {
        "type": "string",
        "format": "uri",
        "examples": [
          "https://auth.asender.net"
        ]
      }
    }
  },
  "auth_MePasskeyDesafio": {
    "type": "object",
    "properties": {
      "desafio_id": {
        "type": "string",
        "format": "uuid"
      },
      "opcoes": {
        "$ref": "#/components/schemas/auth_WebAuthnOpcoes"
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MePasskeyRegistroFinishBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "desafio_id",
      "credencial"
    ],
    "properties": {
      "desafio_id": {
        "type": "string",
        "format": "uuid"
      },
      "nome": {
        "type": "string",
        "maxLength": 64,
        "description": "Vazio = \"Chave de acesso\"."
      },
      "credencial": {
        "$ref": "#/components/schemas/auth_WebAuthnCredencial"
      }
    }
  },
  "auth_MePasskeyResp": {
    "type": "object",
    "properties": {
      "passkey": {
        "$ref": "#/components/schemas/auth_MePasskey"
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MePasskeyRenomearBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "nome"
    ],
    "properties": {
      "nome": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64
      }
    }
  },
  "auth_PasskeyLoginFinishBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "desafio_id",
      "credencial"
    ],
    "properties": {
      "desafio_id": {
        "type": "string",
        "format": "uuid"
      },
      "credencial": {
        "$ref": "#/components/schemas/auth_WebAuthnCredencial"
      },
      "lembrar": {
        "type": "boolean",
        "description": "Sessão longa (90d) em vez de 7d."
      }
    }
  },
  "auth_MeReauthConfirmBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "metodo"
    ],
    "properties": {
      "metodo": {
        "$ref": "#/components/schemas/auth_MeMetodo"
      },
      "codigo": {
        "type": "string",
        "description": "email_otp, totp ou codigo_recuperacao."
      },
      "senha": {
        "type": "string",
        "writeOnly": true,
        "description": "Só para metodo=senha."
      },
      "desafio_id": {
        "type": "string",
        "format": "uuid",
        "description": "Só para metodo=passkey: o do start."
      },
      "credencial": {
        "$ref": "#/components/schemas/auth_WebAuthnCredencial"
      }
    }
  },
  "auth_MeReauthEstado": {
    "type": "object",
    "properties": {
      "valida_ate": {
        "type": "string",
        "format": "date-time"
      },
      "metodo": {
        "$ref": "#/components/schemas/auth_MeMetodo"
      }
    }
  },
  "auth_MeSenhaBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "nova"
    ],
    "properties": {
      "nova": {
        "type": "string",
        "writeOnly": true
      },
      "encerrar_outras": {
        "type": "boolean",
        "default": true
      }
    }
  },
  "auth_MeSenhaResp": {
    "type": "object",
    "properties": {
      "ok": {
        "type": "boolean"
      },
      "sessoes_encerradas": {
        "type": "integer"
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeEmailBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "email"
    ],
    "properties": {
      "email": {
        "type": "string",
        "format": "email"
      }
    }
  },
  "auth_MeEmails": {
    "type": "object",
    "properties": {
      "emails": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "email": {
              "type": "string",
              "format": "email"
            },
            "verified": {
              "type": "boolean"
            },
            "primary": {
              "type": "boolean"
            },
            "pendente_expira_em": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "estado": {
              "type": "string",
              "enum": [
                "verificado",
                "pendente",
                "em_uso_por_outra_conta"
              ]
            }
          }
        }
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeTOTPSetup": {
    "type": "object",
    "properties": {
      "otpauth_url": {
        "type": "string"
      },
      "secret": {
        "type": "string"
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeCodigoBody": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "codigo"
    ],
    "properties": {
      "codigo": {
        "type": "string"
      }
    }
  },
  "auth_MeCodigoRecuperacao": {
    "type": "string",
    "description": "12 símbolos de um alfabeto sem ambíguos (sem 0/O, 1/I/L, U), em 3 grupos; CSPRNG, ~58,9 bits. Aceito também sem hífen/minúsculo.",
    "pattern": "^[2-9A-HJKMNP-TV-Z]{4}-[2-9A-HJKMNP-TV-Z]{4}-[2-9A-HJKMNP-TV-Z]{4}$",
    "examples": [
      "K7QF-2MZD-9RTA"
    ]
  },
  "auth_MeTOTPConfirmado": {
    "type": "object",
    "properties": {
      "ok": {
        "type": "boolean"
      },
      "codigos_recuperacao": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/auth_MeCodigoRecuperacao"
        },
        "maxItems": 10,
        "description": "10 na 1ª ativação (conta sem códigos vivos); vazio quando já havia. Mostrados UMA vez."
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeRemocaoAgendada": {
    "type": "object",
    "required": [
      "id",
      "fator",
      "agendado_para"
    ],
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "fator": {
        "type": "string",
        "enum": [
          "totp",
          "passkey"
        ]
      },
      "agendado_para": {
        "type": "string",
        "format": "date-time"
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeCodigos": {
    "type": "object",
    "properties": {
      "codigos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/auth_MeCodigoRecuperacao"
        },
        "minItems": 10,
        "maxItems": 10
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeFatores": {
    "type": "object",
    "required": [
      "fatores",
      "remocoes_pendentes"
    ],
    "properties": {
      "fatores": {
        "type": "object",
        "description": "Fatores de login (senha, e-mail OTP no primário verificado, app, passkeys). Códigos de recuperação não contam no mínimo de 2.",
        "properties": {
          "senha": {
            "type": "boolean"
          },
          "email_otp": {
            "type": "boolean"
          },
          "totp": {
            "type": "boolean"
          },
          "codigos_restantes": {
            "type": "integer",
            "minimum": 0
          },
          "passkeys": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "remocoes_pendentes": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "fator",
            "executar_em"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "fator": {
              "type": "string",
              "enum": [
                "totp",
                "passkey"
              ]
            },
            "executar_em": {
              "type": "string",
              "format": "date-time"
            },
            "alvo_id": {
              "type": "string",
              "format": "uuid",
              "description": "Só `passkey`: a chave que sai."
            }
          }
        }
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeSessoes": {
    "type": "object",
    "properties": {
      "sessoes": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "user_agent": {
              "type": "string"
            },
            "ip": {
              "type": "string"
            },
            "criada_em": {
              "type": "string",
              "format": "date-time"
            },
            "usada_em": {
              "type": "string",
              "format": "date-time"
            },
            "expira_em": {
              "type": "string",
              "format": "date-time"
            },
            "atual": {
              "type": "boolean"
            }
          }
        }
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeSenhasApp": {
    "type": "object",
    "properties": {
      "senhas": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/auth_MeSenhaApp"
        }
      },
      "por_caixa": {
        "type": "boolean",
        "description": "Capacidade: true quando a criação de senha presa a UMA caixa está ligada (APP_PASSWORD_POR_CAIXA). Falso: a tela esconde o seletor de alcance."
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeSenhaApp": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "pattern": "^[a-z2-7]{8}$",
        "description": "O id curto (parte da credencial); não é segredo."
      },
      "rotulo": {
        "type": "string",
        "maxLength": 60
      },
      "escopos": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "mail:imap",
            "mail:smtp"
          ]
        }
      },
      "criada_em": {
        "type": "string",
        "format": "date-time"
      },
      "expira_em": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "ultimo_uso_em": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "ultimo_ip": {
        "type": "string"
      },
      "caixa": {
        "type": [
          "string",
          "null"
        ],
        "description": "Endereço (minúsculo) a que a senha está presa; null = todas as caixas com grant."
      }
    }
  },
  "auth_MeSenhaAppBody": {
    "type": "object",
    "required": [
      "rotulo",
      "escopos"
    ],
    "additionalProperties": false,
    "properties": {
      "rotulo": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      },
      "escopos": {
        "type": "array",
        "minItems": 1,
        "items": {
          "type": "string",
          "enum": [
            "mail:imap",
            "mail:smtp"
          ]
        }
      },
      "caixa": {
        "type": "string",
        "maxLength": 254,
        "description": "Opcional. Prende a senha a UMA caixa (e-mail; normalizado para minúsculo). Formato inválido: 400 ValidationError. Recurso desligado (APP_PASSWORD_POR_CAIXA): 400 RecursoDesligado."
      }
    }
  },
  "auth_MeSenhaAppEmitida": {
    "allOf": [
      {
        "$ref": "#/components/schemas/auth_MeSenhaApp"
      },
      {
        "type": "object",
        "properties": {
          "segredo": {
            "type": "string",
            "pattern": "^asp_[a-z2-7]{8}_[a-z2-7]{32}$",
            "description": "A credencial inteira. Mostrada UMA vez."
          },
          "RequestId": {
            "type": "string"
          }
        }
      }
    ]
  },
  "auth_SenhaAppValidarBody": {
    "type": "object",
    "required": [
      "segredo",
      "escopo",
      "ip"
    ],
    "additionalProperties": false,
    "properties": {
      "segredo": {
        "type": "string",
        "description": "A credencial digitada no cliente de e-mail."
      },
      "escopo": {
        "type": "string",
        "enum": [
          "mail:imap",
          "mail:smtp"
        ]
      },
      "ip": {
        "type": "string",
        "description": "IP do cliente de e-mail (para o freio e a auditoria)."
      }
    }
  },
  "auth_SenhaAppValidada": {
    "type": "object",
    "properties": {
      "user_id": {
        "type": "string",
        "pattern": "^usr_[0-9a-f]{16}$"
      },
      "app_id": {
        "type": "string",
        "pattern": "^[a-z2-7]{8}$"
      },
      "rotulo": {
        "type": "string"
      },
      "caixa_endereco": {
        "type": "string",
        "description": "Presente SÓ quando a senha é presa a uma caixa: o gateway deve recusar o login se o username for outro endereço. Ausente = ampla."
      }
    }
  },
  "auth_MeEncerradas": {
    "type": "object",
    "properties": {
      "encerradas": {
        "type": "integer"
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_MeEventos": {
    "type": "object",
    "properties": {
      "eventos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "tipo": {
              "type": "string",
              "enum": [
                "senha_trocada",
                "email_adicionado",
                "email_verificado",
                "email_removido",
                "primario_trocado",
                "totp_ativado",
                "segundo_fator_ativado_primeiro_acesso",
                "totp_remocao_agendada",
                "totp_remocao_cancelada",
                "totp_desativado",
                "codigos_gerados",
                "codigo_recuperacao_usado",
                "sessao_revogada",
                "sessoes_encerradas",
                "reauth_ok",
                "reauth_falhou",
                "nome_alterado",
                "senha_app_criada",
                "senha_app_revogada",
                "senha_app_falha_agregada",
                "senha_app_primeiro_uso_por_ip"
              ]
            },
            "criado_em": {
              "type": "string",
              "format": "date-time"
            },
            "ip": {
              "type": "string"
            },
            "user_agent": {
              "type": "string"
            },
            "detalhe": {
              "type": "object"
            }
          }
        }
      },
      "proximo": {
        "type": [
          "string",
          "null"
        ]
      },
      "RequestId": {
        "type": "string"
      }
    }
  },
  "auth_LixeiraTipoRecurso": {
    "type": "string",
    "pattern": "^[a-z0-9_]{1,40}$",
    "description": "Tipo do registro de tipos do servico (ex. mensagem, caixa, pixeldominio)."
  },
  "auth_LixeiraEstagio": {
    "type": "string",
    "enum": [
      "usuario",
      "admin",
      "retido"
    ]
  },
  "auth_LixeiraInstanteUtc": {
    "type": "string",
    "format": "date-time",
    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$",
    "description": "UTC com exatamente 6 casas (a ordenacao lexical do BFF depende disso)."
  },
  "auth_LixeiraItemLixeira": {
    "type": "object",
    "required": [
      "id",
      "tipo",
      "nome",
      "estagio",
      "apagado_em"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "tipo": {
        "$ref": "#/components/schemas/auth_LixeiraTipoRecurso"
      },
      "nome": {
        "type": "string",
        "maxLength": 120,
        "description": "Rotulo SEGURO para reconhecer o item. Nunca corpo, conteudo, segredo ou PII alem do necessario."
      },
      "estagio": {
        "$ref": "#/components/schemas/auth_LixeiraEstagio"
      },
      "apagado_em": {
        "$ref": "#/components/schemas/auth_LixeiraInstanteUtc"
      },
      "apagado_por": {
        "type": "string",
        "description": "Id imutavel do usuario/servico; nunca e-mail"
      },
      "apagado_por_nome": {
        "type": "string",
        "maxLength": 120
      },
      "apagado_motivo": {
        "type": "string",
        "maxLength": 500
      },
      "motivo": {
        "type": "string",
        "deprecated": true,
        "description": "Alias legado de `apagado_motivo` (o BFF le `motivo`). Mesmo valor."
      },
      "expira_usuario_em": {
        "$ref": "#/components/schemas/auth_LixeiraInstanteUtc"
      },
      "dias_restantes": {
        "type": "integer",
        "minimum": 0,
        "description": "Dias ate o fim do estagio corrente"
      },
      "movido_admin_em": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/auth_LixeiraInstanteUtc"
          },
          {
            "type": "null"
          }
        ]
      },
      "expira_admin_em": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/auth_LixeiraInstanteUtc"
          },
          {
            "type": "null"
          }
        ]
      },
      "retido_ate": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/auth_LixeiraInstanteUtc"
          },
          {
            "type": "null"
          }
        ]
      },
      "pai_apagado": {
        "type": "boolean",
        "description": "true se o pai ainda esta apagado (restaurar exige restaurar o pai primeiro)."
      },
      "pai": {
        "type": "object",
        "properties": {
          "tipo": {
            "$ref": "#/components/schemas/auth_LixeiraTipoRecurso"
          },
          "id": {
            "type": "string"
          }
        }
      },
      "lote_id": {
        "type": "string",
        "description": "Itens apagados juntos (cascata logica) restauram em bloco"
      },
      "tamanho_bytes": {
        "type": "integer",
        "minimum": 0
      }
    }
  },
  "auth_LixeiraPaginaLixeira": {
    "type": "object",
    "required": [
      "itens",
      "cursor"
    ],
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 200,
        "items": {
          "$ref": "#/components/schemas/auth_LixeiraItemLixeira"
        }
      },
      "cursor": {
        "type": "string",
        "description": "Vazio = fim"
      },
      "proximo": {
        "type": "string",
        "deprecated": true,
        "description": "Alias legado de `cursor`"
      }
    }
  },
  "auth_LixeiraRestaurarInterno": {
    "type": "object",
    "required": [
      "por"
    ],
    "properties": {
      "por": {
        "type": "string",
        "maxLength": 128
      },
      "motivo": {
        "type": "string",
        "minLength": 10,
        "maxLength": 500,
        "description": "Obrigatorio em estagio admin/retido"
      }
    }
  },
  "auth_LixeiraAnteciparInterno": {
    "type": "object",
    "required": [
      "motivo",
      "confirmacao"
    ],
    "properties": {
      "motivo": {
        "type": "string",
        "minLength": 10,
        "maxLength": 500
      },
      "confirmacao": {
        "type": "string",
        "description": "Deve ser igual ao `id` do item"
      }
    }
  },
  "auth_LixeiraReterInterno": {
    "type": "object",
    "required": [
      "ate",
      "motivo"
    ],
    "properties": {
      "ate": {
        "$ref": "#/components/schemas/auth_LixeiraInstanteUtc"
      },
      "motivo": {
        "type": "string",
        "minLength": 10,
        "maxLength": 500
      }
    }
  },
  "auth_LixeiraLiberarInterno": {
    "type": "object",
    "required": [
      "motivo"
    ],
    "properties": {
      "motivo": {
        "type": "string",
        "minLength": 10,
        "maxLength": 500
      }
    }
  },
  "auth_LixeiraPurgaAgendada": {
    "type": "object",
    "required": [
      "estado",
      "trilha_id"
    ],
    "properties": {
      "estado": {
        "type": "string",
        "enum": [
          "agendada",
          "na_fila_do_purgador"
        ]
      },
      "trilha_id": {
        "type": "string"
      }
    }
  },
  "auth_LixeiraEstatisticas": {
    "type": "object",
    "required": [
      "por_estagio",
      "vencendo_7d",
      "retidos",
      "blob_pendente"
    ],
    "properties": {
      "por_estagio": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "estagio",
            "tipo",
            "total"
          ],
          "properties": {
            "estagio": {
              "$ref": "#/components/schemas/auth_LixeiraEstagio"
            },
            "tipo": {
              "$ref": "#/components/schemas/auth_LixeiraTipoRecurso"
            },
            "total": {
              "type": "integer",
              "minimum": 0
            },
            "bytes": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      },
      "vencendo_7d": {
        "type": "integer",
        "minimum": 0
      },
      "retidos": {
        "type": "integer",
        "minimum": 0
      },
      "blob_pendente": {
        "type": "integer",
        "minimum": 0
      }
    }
  },
  "auth_LixeiraProblem": {
    "type": "object",
    "description": "RFC 9457",
    "required": [
      "type",
      "title",
      "status"
    ],
    "properties": {
      "type": {
        "type": "string",
        "format": "uri"
      },
      "title": {
        "type": "string"
      },
      "status": {
        "type": "integer"
      },
      "detail": {
        "type": "string"
      },
      "instance": {
        "type": "string"
      },
      "trace_id": {
        "type": "string"
      },
      "motivo": {
        "type": "string",
        "description": "Slug (alias do `motivo` legado)"
      },
      "pai": {
        "type": "object",
        "properties": {
          "tipo": {
            "$ref": "#/components/schemas/auth_LixeiraTipoRecurso"
          },
          "id": {
            "type": "string"
          }
        }
      },
      "filhos": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "object",
          "properties": {
            "tipo": {
              "$ref": "#/components/schemas/auth_LixeiraTipoRecurso"
            },
            "id": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "crm_ResumoDeFerramenta": {
    "type": "object",
    "description": "Contrato comum de resumo de ferramenta (plano 2026-10-02) — o mesmo formato em toda ferramenta.",
    "required": [
      "ferramenta",
      "periodo",
      "indicadores",
      "series"
    ],
    "properties": {
      "ferramenta": {
        "type": "string",
        "description": "slug da ferramenta (crm, mail, pages, atendimento, …)"
      },
      "periodo": {
        "type": "object",
        "required": [
          "de",
          "ate",
          "chave"
        ],
        "properties": {
          "de": {
            "type": "string",
            "format": "date",
            "description": "primeiro dia da janela (inclusivo)"
          },
          "ate": {
            "type": "string",
            "format": "date",
            "description": "último dia da janela (inclusivo)"
          },
          "chave": {
            "type": "string",
            "enum": [
              "7d",
              "30d",
              "90d"
            ]
          }
        }
      },
      "indicadores": {
        "type": "array",
        "minItems": 1,
        "maxItems": 6,
        "items": {
          "$ref": "#/components/schemas/crm_ResumoIndicador"
        }
      },
      "series": {
        "type": "array",
        "maxItems": 2,
        "items": {
          "$ref": "#/components/schemas/crm_ResumoSerie"
        }
      }
    }
  },
  "crm_ResumoIndicador": {
    "type": "object",
    "required": [
      "chave",
      "rotulo",
      "valor",
      "anterior",
      "formato",
      "link"
    ],
    "properties": {
      "chave": {
        "type": "string",
        "description": "id estável do indicador"
      },
      "rotulo": {
        "type": "string",
        "description": "rótulo pt-BR (o front pode traduzir pela chave)"
      },
      "valor": {
        "type": "number"
      },
      "anterior": {
        "type": [
          "number",
          "null"
        ],
        "description": "mesmo indicador na janela anterior de mesmo tamanho; null = sem comparação"
      },
      "formato": {
        "type": "string",
        "enum": [
          "numero",
          "percentual",
          "moeda",
          "duracao"
        ],
        "description": "moeda em centavos BRL; duracao em segundos; percentual 0–100"
      },
      "link": {
        "type": "string",
        "description": "caminho relativo dentro da ferramenta, já com a conta"
      }
    }
  },
  "crm_ResumoSerie": {
    "type": "object",
    "required": [
      "chave",
      "rotulo",
      "tipo",
      "pontos"
    ],
    "properties": {
      "chave": {
        "type": "string"
      },
      "rotulo": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "linha",
          "barra"
        ]
      },
      "pontos": {
        "type": "array",
        "description": "um ponto por dia da janela (dia sem evento vem com 0)",
        "items": {
          "type": "object",
          "required": [
            "data",
            "valor"
          ],
          "properties": {
            "data": {
              "type": "string",
              "format": "date"
            },
            "valor": {
              "type": "number"
            }
          }
        }
      }
    }
  },
  "crm_ContagemPorChave": {
    "type": "object",
    "properties": {
      "chave": {
        "type": "string"
      },
      "contagem": {
        "type": "integer",
        "format": "int64"
      }
    }
  },
  "crm_Erro": {
    "type": "object",
    "description": "Envelope único de erro da CRM API — um campo só.",
    "required": [
      "erro"
    ],
    "properties": {
      "erro": {
        "type": "string",
        "description": "mensagem legível; nunca revela schema nem existência de recurso alheio"
      }
    }
  },
  "crm_TipoDaLixeira": {
    "type": "string",
    "description": "Allowlist de tipos restauráveis pelo usuário. `identidade` é o vínculo desvinculado de um contato (telefone, e-mail, Telegram, LID do WhatsApp): o `nome` é o valor MASCARADO; restaurar dá 409 `conflito_unicidade` se outra identidade ativa da conta já tem o valor e 409 `pai_apagado` (pai `contato`) se o contato dono está apagado.",
    "enum": [
      "contato",
      "cliente",
      "empresa",
      "projeto",
      "coluna",
      "tarefa",
      "segmento",
      "destino",
      "alerta",
      "identidade"
    ]
  },
  "crm_ItemDaLixeira": {
    "type": "object",
    "required": [
      "tipo",
      "id",
      "nome",
      "apagado_em"
    ],
    "properties": {
      "tipo": {
        "$ref": "#/components/schemas/crm_TipoDaLixeira"
      },
      "id": {
        "type": "string",
        "description": "id público do item"
      },
      "nome": {
        "type": "string",
        "description": "nome ou título para reconhecer o item"
      },
      "apagado_em": {
        "type": "string",
        "format": "date-time"
      },
      "apagado_por": {
        "type": "string",
        "description": "id do usuário que apagou (vazio se foi o sistema); o front resolve o nome"
      },
      "motivo": {
        "type": "string",
        "description": "motivo informado ao apagar (contato)"
      }
    }
  },
  "crm_LixeiraPagina": {
    "type": "object",
    "required": [
      "itens",
      "cursor"
    ],
    "properties": {
      "itens": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_ItemDaLixeira"
        }
      },
      "cursor": {
        "type": "string",
        "description": "cursor da próxima página; vazio = fim"
      }
    }
  },
  "crm_RestauroRecusado": {
    "type": "object",
    "required": [
      "erro",
      "motivo"
    ],
    "properties": {
      "erro": {
        "type": "string"
      },
      "motivo": {
        "type": "string",
        "enum": [
          "conflito_unicidade",
          "pai_apagado"
        ]
      },
      "pai": {
        "type": "string",
        "enum": [
          "projeto",
          "coluna",
          "cliente",
          "empresa",
          "contato"
        ],
        "description": "só em pai_apagado: o que precisa ser restaurado primeiro"
      }
    }
  },
  "crm_Passo": {
    "type": "object",
    "description": "Um degrau da jornada.",
    "required": [
      "numero",
      "tipo"
    ],
    "properties": {
      "numero": {
        "type": "integer",
        "description": "posição, começando em 1, sem buraco"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "esperar",
          "agir",
          "condicao"
        ]
      },
      "espera": {
        "type": "integer",
        "format": "int64",
        "description": "duração em nanossegundos (só em `esperar`); 1 dia = 86400000000000"
      },
      "acao": {
        "type": "string",
        "enum": [
          "email",
          "push",
          "webhook",
          "mudar_estagio",
          "entrar_lista",
          "enviar_conversao",
          "responder_conversa",
          "encaminhar_fila"
        ],
        "description": "só em `agir`; `enviar_conversao` (ADR-0120) pede parametros instalacao_id, evento, valor?, moeda?"
      },
      "parametros": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "argumentos da ação. `enviar_conversao` (ADR-0120): o operador envia `instalacao_id`, `evento`, `valor?`, `moeda?`; `instalacao_app` é INTERNO (gerido pelo servidor, opcional na entrada): o servidor o grava ao salvar, com o slug confirmado por Integrações, e sobrescreve o que o cliente mandar. Valor fora de `meta_capi|google_ads|tiktok_events` = 422.",
        "properties": {
          "instalacao_app": {
            "type": "string",
            "enum": [
              "meta_capi",
              "google_ads",
              "tiktok_events"
            ],
            "description": "server-managed: não é campo do construtor; o cliente pode omitir"
          }
        }
      },
      "condicao": {
        "type": "string",
        "description": "condição do passo `condicao`. Hoje o CRM só julga a família `email.*` (W3): `email.abriu`, `email.nao_abriu`, `email.clicou`, `email.nao_clicou`, com opções `;passo=N` (passo de e-mail alvo; padrão = o último e-mail ANTES da condição), `;automaticas=true` (conta abertura/clique de máquina; padrão só humano) e `;link=I` (só nas de clique). Texto fora da família é recusado na execução. Condição `email.*` malformada, ou sem e-mail anterior, é 422 ao salvar. Exemplo \"não abriu em 48 h\": e-mail, espera de 48 h, condição `email.nao_abriu`."
      },
      "se_pular_ir": {
        "type": "integer",
        "description": "passo para onde saltar quando a condição é falsa"
      }
    }
  },
  "crm_Gatilho": {
    "type": "object",
    "description": "O que faz um contato entrar na jornada.",
    "required": [
      "tipo"
    ],
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "lead_capturado",
          "campo_mudou",
          "inatividade",
          "evento_pixel",
          "etapa_alterada",
          "conversa_aberta",
          "email_aberto",
          "email_clicado"
        ]
      },
      "args": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "`etapa_alterada` (ADR-0120): `para` obrigatório (etapa de destino), `de` opcional; nenhum outro argumento. `email_aberto`/`email_clicado` (W3): `email_id` obrigatório (id público do e-mail; ausente nunca é curinga), `incluir_automaticas` (`true` conta abertura/clique de máquina; padrão só humano), e `link` (índice, só no clicado). O contato entra a partir de mensagem enviada por uma inscrição de jornada (a correlação vem do evento `events.interno.marketing.email.fato`)."
      }
    }
  },
  "crm_Jornada": {
    "type": "object",
    "description": "Automação completa.",
    "properties": {
      "id": {
        "type": "string"
      },
      "tenant_id": {
        "type": "string",
        "description": "resolvido da sessão; nunca aceito no corpo"
      },
      "nome": {
        "type": "string"
      },
      "gatilho": {
        "$ref": "#/components/schemas/crm_Gatilho"
      },
      "passos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Passo"
        }
      },
      "ativa": {
        "type": "boolean",
        "description": "criada sempre false; muda por PUT .../ativa"
      },
      "layout": {
        "$ref": "#/components/schemas/crm_Layout"
      }
    }
  },
  "crm_JornadaComAvisos": {
    "description": "A jornada salva/ligada, mais `avisos` quando algo não pôde ser conferido (ex.: o serviço de Integrações estava fora ao validar um passo `enviar_conversao` — piso 10: salva mesmo assim).",
    "allOf": [
      {
        "$ref": "#/components/schemas/crm_Jornada"
      },
      {
        "type": "object",
        "properties": {
          "avisos": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    ]
  },
  "crm_CampoCanvas": {
    "type": "object",
    "description": "Um campo de formulário de um nó do construtor.",
    "required": [
      "nome",
      "rotulo",
      "tipo",
      "obrigatorio"
    ],
    "properties": {
      "nome": {
        "type": "string"
      },
      "rotulo": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "texto",
          "decimal",
          "moeda",
          "instalacao"
        ]
      },
      "obrigatorio": {
        "type": "boolean"
      },
      "padrao": {
        "type": "string"
      },
      "dica": {
        "type": "string"
      },
      "apps": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "só em `instalacao`: apps de Integrações aceitos (meta_capi, google_ads, tiktok_events)"
      }
    }
  },
  "crm_AcaoCanvas": {
    "type": "object",
    "required": [
      "tipo",
      "rotulo",
      "grupo",
      "campos"
    ],
    "properties": {
      "tipo": {
        "type": "string"
      },
      "rotulo": {
        "type": "string"
      },
      "grupo": {
        "type": "string",
        "enum": [
          "marketing",
          "bot"
        ]
      },
      "campos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_CampoCanvas"
        }
      }
    }
  },
  "crm_GatilhoCanvas": {
    "type": "object",
    "required": [
      "tipo",
      "rotulo",
      "grupo"
    ],
    "properties": {
      "tipo": {
        "type": "string"
      },
      "rotulo": {
        "type": "string"
      },
      "grupo": {
        "type": "string",
        "enum": [
          "marketing",
          "bot"
        ]
      },
      "args": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_CampoCanvas"
        }
      }
    }
  },
  "crm_CondicaoCanvas": {
    "type": "object",
    "description": "Condição pronta do nó `condicao` (W3 — família `email.*`).",
    "required": [
      "expr",
      "rotulo",
      "grupo"
    ],
    "properties": {
      "expr": {
        "type": "string",
        "description": "texto que vai em `Passo.condicao`, ex.: `email.nao_abriu`"
      },
      "rotulo": {
        "type": "string"
      },
      "grupo": {
        "type": "string",
        "enum": [
          "email"
        ]
      }
    }
  },
  "crm_CatalogoCanvas": {
    "type": "object",
    "description": "Gatilhos, ações e condições prontas do construtor visual, com os campos tipados de cada nó.",
    "required": [
      "gatilhos",
      "acoes"
    ],
    "properties": {
      "gatilhos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_GatilhoCanvas"
        }
      },
      "acoes": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_AcaoCanvas"
        }
      },
      "condicoes": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_CondicaoCanvas"
        },
        "description": "aditivo (W3): cliente antigo ignora"
      }
    }
  },
  "crm_Posicao": {
    "type": "object",
    "description": "Coordenada de tela de um nó no construtor visual.",
    "properties": {
      "x": {
        "type": "number"
      },
      "y": {
        "type": "number"
      }
    }
  },
  "crm_Layout": {
    "type": "object",
    "description": "Posições dos nós do CONSTRUTOR VISUAL, por chave canônica (\"gatilho\", \"fim\" ou o número do passo). Presentação pura — o motor não a usa; vazio quando a jornada foi criada pelo diálogo.",
    "properties": {
      "posicoes": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/crm_Posicao"
        }
      }
    }
  },
  "crm_NoGrafo": {
    "type": "object",
    "description": "Um nó arrastável do construtor visual.",
    "required": [
      "id",
      "tipo"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "id do cliente, estável dentro do grafo"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "gatilho",
          "agir",
          "esperar",
          "condicao",
          "fim"
        ]
      },
      "x": {
        "type": "number"
      },
      "y": {
        "type": "number"
      },
      "gatilho": {
        "$ref": "#/components/schemas/crm_Gatilho"
      },
      "acao": {
        "type": "string",
        "enum": [
          "email",
          "push",
          "webhook",
          "mudar_estagio",
          "entrar_lista",
          "enviar_conversao",
          "responder_conversa",
          "encaminhar_fila"
        ]
      },
      "parametros": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        }
      },
      "espera": {
        "type": "integer",
        "format": "int64",
        "description": "duração em nanossegundos (só em `esperar`)"
      },
      "condicao": {
        "type": "string"
      }
    }
  },
  "crm_ArestaGrafo": {
    "type": "object",
    "description": "Liga dois nós pelo id. Ramo vazio segue a espinha; \"senao\" é o salto da condição.",
    "required": [
      "de",
      "para"
    ],
    "properties": {
      "de": {
        "type": "string"
      },
      "para": {
        "type": "string"
      },
      "ramo": {
        "type": "string",
        "enum": [
          "",
          "senao"
        ]
      }
    }
  },
  "crm_Grafo": {
    "type": "object",
    "description": "O fluxo desenhado no construtor visual. O servidor o converte em `gatilho`+`passos`+`layout` (fonte única da conversão) e recusa (422) um desenho que não lineariza.",
    "required": [
      "nos",
      "arestas"
    ],
    "properties": {
      "nome": {
        "type": "string"
      },
      "nos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_NoGrafo"
        }
      },
      "arestas": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_ArestaGrafo"
        }
      }
    }
  },
  "crm_PedidoJornada": {
    "type": "object",
    "description": "Corpo de `POST /v1/jornadas` e `PUT /v1/jornadas/{id}`. Sem `id`, `tenant_id` nem `ativa`. Envie `nome`+`gatilho`+`passos` (diálogo) OU `grafo` (construtor visual) — mutuamente exclusivos; mandar os dois é 422.",
    "properties": {
      "nome": {
        "type": "string"
      },
      "gatilho": {
        "$ref": "#/components/schemas/crm_Gatilho"
      },
      "passos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Passo"
        }
      },
      "grafo": {
        "$ref": "#/components/schemas/crm_Grafo"
      }
    }
  },
  "crm_PedidoAtivar": {
    "type": "object",
    "required": [
      "ativa"
    ],
    "properties": {
      "ativa": {
        "type": "boolean"
      }
    }
  },
  "crm_Origem": {
    "type": "object",
    "description": "Atribuição da captura.",
    "properties": {
      "utm_source": {
        "type": "string"
      },
      "utm_medium": {
        "type": "string"
      },
      "utm_campaign": {
        "type": "string"
      },
      "utm_term": {
        "type": "string"
      },
      "utm_content": {
        "type": "string"
      },
      "referrer": {
        "type": "string"
      },
      "dominio": {
        "type": "string"
      },
      "form_id": {
        "type": "string"
      },
      "modo": {
        "type": "string",
        "description": "ex.: manual, formulario"
      },
      "canal_origem": {
        "type": "string",
        "enum": [
          "",
          "organico",
          "pago",
          "email",
          "social",
          "direto",
          "referral",
          "afiliado",
          "offline",
          "outro"
        ],
        "description": "canal da primeira captura (catálogo v2); filtrável"
      },
      "landing_page": {
        "type": "string",
        "description": "landing page da primeira captura (catálogo v2); filtrável (igualdade sem caixa)"
      },
      "extra": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "demais campos de origem do catálogo v2 (utm_id, gbraid, wbraid, fbclid, msclkid, ttclid, fbp, fbc, ga_client_id, pagina_conversao...), first-touch, nunca filtráveis — só no detalhe (`GET /v1/contatos/{id}`): são identificadores de navegador."
      }
    }
  },
  "crm_Qualidade": {
    "type": "object",
    "description": "Sinal sobre o lead; presente só quando avaliado.",
    "properties": {
      "nota": {
        "type": "integer"
      },
      "faixa": {
        "type": "string"
      },
      "datacenter": {
        "type": "boolean"
      }
    }
  },
  "crm_ConsentimentoDoContato": {
    "type": "object",
    "description": "Estado de consentimento resumido, sem o texto integral do aviso.",
    "properties": {
      "base": {
        "type": "string",
        "enum": [
          "consentimento",
          "legitimo_interesse",
          "execucao_contrato"
        ]
      },
      "ativo": {
        "type": "boolean"
      },
      "concedido_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_Contato": {
    "type": "object",
    "description": "Representação pública do contato — a PII vem decifrada; os índices cegos nunca saem.",
    "properties": {
      "id": {
        "type": "string"
      },
      "email": {
        "type": "string",
        "description": "decifrado; ausente se não houver"
      },
      "telefone": {
        "type": "string",
        "description": "decifrado; ausente se não houver"
      },
      "nome": {
        "type": "string"
      },
      "sobrenome": {
        "type": "string"
      },
      "cargo": {
        "type": "string"
      },
      "departamento": {
        "type": "string"
      },
      "pais": {
        "type": "string",
        "description": "ISO 3166-1 alfa-2 (ex.: BR)"
      },
      "estado": {
        "type": "string"
      },
      "cidade": {
        "type": "string"
      },
      "idioma": {
        "type": "string"
      },
      "linkedin": {
        "type": "string"
      },
      "fonte": {
        "type": "string",
        "description": "fonte do lead"
      },
      "genero": {
        "type": "string",
        "enum": [
          "",
          "feminino",
          "masculino",
          "nao-binario",
          "outro",
          "prefiro-nao-informar"
        ],
        "description": "catálogo v2; em claro e filtrável; \"\" = não informado"
      },
      "nivel_hierarquico": {
        "type": "string",
        "enum": [
          "",
          "estagiario",
          "analista",
          "especialista",
          "coordenador",
          "gerente",
          "diretor",
          "vp",
          "c-level",
          "socio",
          "outro"
        ],
        "description": "catálogo v2; em claro e filtrável; \"\" = não informado"
      },
      "empresa": {
        "nullable": true,
        "allOf": [
          {
            "$ref": "#/components/schemas/crm_EmpresaRef"
          }
        ]
      },
      "dispositivo": {
        "type": "string",
        "enum": [
          "",
          "desktop",
          "mobile",
          "tablet",
          "bot",
          "desconhecido"
        ],
        "description": "do ÚLTIMO envio de formulário; filtrável"
      },
      "so": {
        "type": "string",
        "description": "sistema operacional do último envio (ex.: Android); filtrável"
      },
      "navegador": {
        "type": "string",
        "description": "navegador do último envio (ex.: Chrome); filtrável"
      },
      "ip_pais": {
        "type": "string",
        "description": "ISO-2 do país pelo IP do último envio (DB-IP Lite); filtrável"
      },
      "ip_cidade": {
        "type": "string",
        "description": "cidade pelo IP do último envio"
      },
      "email_status": {
        "type": "string",
        "enum": [
          "",
          "ok",
          "suspeito",
          "dominio_inexistente",
          "descartavel",
          "desconhecido"
        ],
        "description": "verificação do e-mail de identidade feita na captura (sintaxe, MX, descartável, sugestão de correção); \"\" = nunca verificado; filtrável. Trocar o e-mail no PATCH vira ok se o novo é a sugestão, senão desconhecido",
        "example": "suspeito"
      },
      "email_sugestao": {
        "type": "string",
        "description": "correção sugerida para o e-mail (ex. bianchi@gmail.com para bianchi@gmil.com), decifrada — só no detalhe; aplicá-la é um PATCH do e-mail",
        "example": "bianchi@gmail.com"
      },
      "contexto_primeiro": {
        "allOf": [
          {
            "$ref": "#/components/schemas/crm_ContextoDoEnvio"
          }
        ],
        "description": "contexto COMPLETO do PRIMEIRO envio (nunca sobrescrito), decifrado — só no detalhe."
      },
      "contexto_ultimo": {
        "allOf": [
          {
            "$ref": "#/components/schemas/crm_ContextoDoEnvio"
          }
        ],
        "description": "contexto COMPLETO do ÚLTIMO envio, decifrado — só no detalhe."
      },
      "estagio": {
        "type": "string",
        "enum": [
          "novo",
          "contatado",
          "qualificado",
          "cliente",
          "descartado"
        ]
      },
      "dono_id": {
        "type": "string"
      },
      "marcadores": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "atributos": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "campos personalizados, decifrados — só no detalhe (`GET /v1/contatos/{id}`)."
      },
      "dados_pessoais": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "PII forte decifrada — só no detalhe. Qualquer chave de entidade `contato_cifrado` do catálogo v2 (117: whatsapp, cpf, data_nascimento, endereço e prefixos comercial_/cobranca_/entrega_, redes sociais, comercial, marketing, relacionamento...). Campos de papel `consentimento` (aceita_*) são só EVIDÊNCIA do formulário (\"valor @ carimbo\"): nunca viram o consentimento estruturado do contato."
      },
      "origem": {
        "$ref": "#/components/schemas/crm_Origem"
      },
      "qualidade": {
        "$ref": "#/components/schemas/crm_Qualidade"
      },
      "consentimento": {
        "$ref": "#/components/schemas/crm_ConsentimentoDoContato"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_ContextoDoEnvio": {
    "type": "object",
    "description": "Contexto técnico de um envio de formulário (contrato C8). Os campos do servidor vêm do runtime (IP, user agent interpretado, geo por IP — \"IP Geolocation by DB-IP\", CC BY 4.0); os demais, do navegador. Ausente = não coletado. Contém PII (IP, user agent, id de dispositivo, coordenadas): guardado cifrado e zerado na anonimização.",
    "properties": {
      "ip": {
        "type": "string"
      },
      "ip_versao": {
        "type": "integer",
        "enum": [
          4,
          6
        ]
      },
      "user_agent": {
        "type": "string"
      },
      "navegador": {
        "type": "string"
      },
      "navegador_versao": {
        "type": "string"
      },
      "so": {
        "type": "string"
      },
      "so_versao": {
        "type": "string"
      },
      "dispositivo": {
        "type": "string",
        "enum": [
          "desktop",
          "mobile",
          "tablet",
          "bot",
          "desconhecido"
        ]
      },
      "idioma_http": {
        "type": "string",
        "description": "Accept-Language"
      },
      "geo": {
        "type": "object",
        "properties": {
          "pais": {
            "type": "string",
            "description": "ISO-2"
          },
          "regiao": {
            "type": "string"
          },
          "cidade": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          },
          "fuso": {
            "type": "string",
            "description": "IANA"
          }
        }
      },
      "rede": {
        "type": "object",
        "properties": {
          "asn": {
            "type": "string"
          },
          "org": {
            "type": "string"
          }
        }
      },
      "recebida_em": {
        "type": "string",
        "format": "date-time"
      },
      "pagina_url": {
        "type": "string"
      },
      "pagina_titulo": {
        "type": "string"
      },
      "referrer": {
        "type": "string"
      },
      "idiomas": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "fuso": {
        "type": "string",
        "description": "IANA, do navegador"
      },
      "tela": {
        "type": "string",
        "example": "1920x1080"
      },
      "janela": {
        "type": "string",
        "example": "1280x720"
      },
      "dpr": {
        "type": "number"
      },
      "cores": {
        "type": "integer"
      },
      "memoria_gb": {
        "type": "number"
      },
      "conexao": {
        "type": "string",
        "example": "4g"
      },
      "toque": {
        "type": "boolean"
      },
      "plataforma": {
        "type": "string"
      },
      "mobile": {
        "type": "boolean"
      },
      "marcas": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "cookies": {
        "type": "boolean"
      },
      "dnt": {
        "type": "string"
      },
      "tempo_no_form_s": {
        "type": "number"
      },
      "visitas": {
        "type": "integer"
      },
      "dispositivo_id": {
        "type": "string",
        "description": "UUID persistido no navegador (localStorage do site)"
      },
      "primeira_visita": {
        "type": "object",
        "properties": {
          "em": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string"
          },
          "referrer": {
            "type": "string"
          },
          "utm": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "click_ids": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "utm": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "source, medium, campaign, term, content"
      },
      "click_ids": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "gclid, gbraid, wbraid, fbclid, msclkid, ttclid, li_fat_id, twclid, yclid, dclid, epik, sccid, igshid"
      },
      "verificacao_email": {
        "type": "array",
        "description": "verificação de cada campo de e-mail do envio, feita pelo runtime",
        "items": {
          "type": "object",
          "properties": {
            "campo": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "ok",
                "suspeito",
                "dominio_inexistente",
                "descartavel",
                "desconhecido"
              ]
            },
            "sugestao": {
              "type": "string",
              "description": "correção sugerida (e-mail)"
            },
            "mx": {
              "type": "boolean"
            },
            "descartavel": {
              "type": "boolean"
            },
            "papel": {
              "type": "boolean",
              "description": "conta de função (contato@, vendas@…)"
            },
            "gratuito": {
              "type": "boolean",
              "description": "provedor gratuito (gmail, outlook…)"
            }
          }
        }
      }
    },
    "example": {
      "ip": "203.0.113.9",
      "navegador": "Chrome",
      "so": "Android",
      "dispositivo": "mobile",
      "geo": {
        "pais": "BR",
        "regiao": "Pernambuco",
        "cidade": "Recife",
        "fuso": "America/Recife"
      },
      "pagina_url": "https://loja.test/contato",
      "idiomas": [
        "pt-BR"
      ],
      "tempo_no_form_s": 42.5
    }
  },
  "crm_PedidoContato": {
    "type": "object",
    "description": "Corpo de `POST`/`PATCH` de contato. Sem `id`, `tenant_id` nem índices (mass assignment vira 400).",
    "properties": {
      "email": {
        "type": "string"
      },
      "telefone": {
        "type": "string"
      },
      "nome": {
        "type": "string"
      },
      "estagio": {
        "type": "string",
        "enum": [
          "novo",
          "contatado",
          "qualificado",
          "cliente",
          "descartado"
        ]
      },
      "dono_id": {
        "type": "string"
      },
      "marcadores": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "lista vazia remove todos"
      },
      "sobrenome": {
        "type": "string",
        "description": "ausente preserva; \"\" limpa (vale para todos os campos abaixo)"
      },
      "cargo": {
        "type": "string"
      },
      "departamento": {
        "type": "string"
      },
      "pais": {
        "type": "string",
        "description": "ISO 3166-1 alfa-2; outro formato → 422"
      },
      "estado": {
        "type": "string"
      },
      "cidade": {
        "type": "string"
      },
      "idioma": {
        "type": "string"
      },
      "linkedin": {
        "type": "string"
      },
      "genero": {
        "type": "string",
        "enum": [
          "",
          "feminino",
          "masculino",
          "nao-binario",
          "outro",
          "prefiro-nao-informar"
        ],
        "description": "catálogo v2; maiúsculas e acento são normalizados; fora das opções → 422"
      },
      "nivel_hierarquico": {
        "type": "string",
        "enum": [
          "",
          "estagiario",
          "analista",
          "especialista",
          "coordenador",
          "gerente",
          "diretor",
          "vp",
          "c-level",
          "socio",
          "outro"
        ],
        "description": "catálogo v2; fora das opções → 422"
      },
      "fonte": {
        "type": "string"
      },
      "empresa_id": {
        "type": "string",
        "description": "id de uma empresa DESTA conta (escolhida no seletor); \"\" solta; alheia/inexistente → 422"
      },
      "dados_pessoais": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "só as chaves do catálogo (entidade contato_cifrado); valor \"\" remove; chave desconhecida → 422."
      },
      "atributos": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "campos personalizados; valor \"\" remove; até 60 chaves."
      }
    },
    "example": {
      "email": "ana@test.asender.com.br",
      "telefone": "+55 11 91234-5678",
      "nome": "Ana",
      "sobrenome": "Souza",
      "cargo": "Diretora Comercial",
      "pais": "BR",
      "cidade": "São Paulo",
      "empresa_id": "emp_3f9a0c1d2e4b5a6c",
      "dados_pessoais": {
        "cpf": "12345678909"
      },
      "atributos": {
        "Interesse": "Plano Pro"
      }
    }
  },
  "crm_EmpresaRef": {
    "type": "object",
    "description": "a empresa do contato pelo NOME (a tela nunca mostra o id).",
    "properties": {
      "id": {
        "type": "string"
      },
      "nome": {
        "type": "string"
      }
    }
  },
  "crm_Empresa": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "example": "emp_3f9a0c1d2e4b5a6c"
      },
      "nome": {
        "type": "string",
        "example": "ACME Ltda"
      },
      "cnpj": {
        "type": "string",
        "description": "14 dígitos",
        "example": "11222333000181"
      },
      "site": {
        "type": "string",
        "example": "https://acme.com.br"
      },
      "dominio": {
        "type": "string",
        "example": "acme.com.br"
      },
      "setor": {
        "type": "string",
        "example": "Varejo"
      },
      "porte": {
        "type": "string",
        "enum": [
          "",
          "mei",
          "micro",
          "pequena",
          "media",
          "grande"
        ]
      },
      "funcionarios": {
        "type": "string",
        "enum": [
          "",
          "1-10",
          "11-50",
          "51-200",
          "201-500",
          "501-1000",
          "1001+"
        ]
      },
      "faturamento": {
        "type": "string",
        "enum": [
          "",
          "ate-360k",
          "360k-4.8m",
          "4.8m-30m",
          "30m-300m",
          "300m+"
        ]
      },
      "pais": {
        "type": "string",
        "example": "BR"
      },
      "estado": {
        "type": "string"
      },
      "cidade": {
        "type": "string"
      },
      "tipo_empresa": {
        "type": "string",
        "enum": [
          "",
          "prospect",
          "cliente",
          "parceiro",
          "revendedor",
          "fornecedor",
          "concorrente",
          "investidor",
          "outro"
        ],
        "description": "catálogo v2; filtrável"
      },
      "cnae": {
        "type": "string",
        "description": "catálogo v2; filtrável por prefixo"
      },
      "segmento": {
        "type": "string",
        "description": "catálogo v2; filtrável (igualdade sem caixa)"
      },
      "regime_tributario": {
        "type": "string",
        "enum": [
          "",
          "mei",
          "simples-nacional",
          "lucro-presumido",
          "lucro-real",
          "outro"
        ],
        "description": "catálogo v2; filtrável"
      },
      "ano_fundacao": {
        "type": "integer",
        "description": "0 = não informado; filtrável por faixa (ano_de/ano_ate)"
      },
      "qtd_funcionarios": {
        "type": "integer",
        "description": "0 = não informado; filtrável por faixa (qtd_min/qtd_max)"
      },
      "dados": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "campos descritivos do catálogo v2 (razao_social, nome_fantasia, inscricao_estadual, inscricao_municipal, natureza_juridica, telefone_empresa, email_empresa, redes *_empresa, descricao_empresa, logo_empresa); `{}` quando não há. Não filtráveis."
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_PedidoEmpresa": {
    "type": "object",
    "description": "Corpo de POST/PATCH de empresa. Ausente preserva, \"\" limpa. CNPJ aceita máscara e é validado (DV); nome vazio com CNPJ vira o CNPJ formatado. Campo desconhecido (ex.: tenant_id) → 400.",
    "properties": {
      "nome": {
        "type": "string"
      },
      "cnpj": {
        "type": "string"
      },
      "site": {
        "type": "string"
      },
      "setor": {
        "type": "string"
      },
      "porte": {
        "type": "string"
      },
      "funcionarios": {
        "type": "string"
      },
      "faturamento": {
        "type": "string"
      },
      "pais": {
        "type": "string"
      },
      "estado": {
        "type": "string"
      },
      "cidade": {
        "type": "string"
      },
      "tipo_empresa": {
        "type": "string"
      },
      "cnae": {
        "type": "string"
      },
      "segmento": {
        "type": "string"
      },
      "regime_tributario": {
        "type": "string"
      },
      "ano_fundacao": {
        "type": "integer",
        "description": "0 limpa; 1000..2200"
      },
      "qtd_funcionarios": {
        "type": "integer",
        "description": "0 limpa"
      },
      "dados": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "MESCLA por chave (valor \"\" remove); só chaves descritivas de empresa do catálogo — outra chave, ou valor do tipo errado (URL, e-mail, telefone), → 422."
      }
    },
    "example": {
      "nome": "ACME Ltda",
      "cnpj": "11.222.333/0001-81",
      "porte": "media",
      "site": "acme.com.br",
      "tipo_empresa": "cliente",
      "dados": {
        "razao_social": "ACME Comércio Ltda"
      }
    }
  },
  "crm_ListaEmpresas": {
    "type": "object",
    "required": [
      "empresas",
      "proximo"
    ],
    "properties": {
      "empresas": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Empresa"
        }
      },
      "proximo": {
        "type": "string"
      }
    }
  },
  "crm_CatalogoDeCampos": {
    "type": "object",
    "description": "o contrato asender_docs/contratos/campos-contato.json.",
    "properties": {
      "versao": {
        "type": "integer",
        "example": 2
      },
      "descricao": {
        "type": "string"
      },
      "papeis": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "significado de cada `papel` (dado, consentimento, derivado)."
      },
      "grupos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "chave": {
              "type": "string"
            },
            "rotulo": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      },
      "campos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "chave": {
              "type": "string",
              "example": "cidade"
            },
            "grupo": {
              "type": "string",
              "example": "endereco"
            },
            "tipo": {
              "type": "string",
              "example": "texto"
            },
            "entidade": {
              "type": "string",
              "enum": [
                "contato",
                "contato_cifrado",
                "identidade",
                "empresa",
                "origem"
              ]
            },
            "filtravel": {
              "type": "boolean"
            },
            "pii": {
              "type": "boolean"
            },
            "papel": {
              "type": "string",
              "enum": [
                "dado",
                "consentimento",
                "derivado"
              ],
              "description": "dado = a ingestão grava na entidade do campo; consentimento = aceite declarado no formulário, só EVIDÊNCIA (nunca levanta supressão nem libera envio); derivado = o sistema preenche — fora do construtor e do seletor de importação, e o valor vindo de formulário é ignorado."
            },
            "unico": {
              "type": "boolean",
              "description": "true = só UM campo do formulário pode ocupar a chave; false (mensagem, observacoes) = vários, concatenados na ingestão."
            },
            "mascara": {
              "type": "string",
              "nullable": true,
              "description": "tipo de campo que o construtor cria ao aceitar a sugestão; igual a `tipo`, exceto `texto` → null."
            },
            "promove_a": {
              "type": "string",
              "enum": [
                "email",
                "telefone"
              ],
              "description": "presente só em whatsapp, celular, telefone_comercial, telefone_residencial (→ telefone) e email_comercial, email_pessoal (→ email): com o slot de identidade livre no formulário, o PRIMEIRO campo desse tipo o ocupa."
            },
            "sinonimos": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "títulos que um humano usaria, normalizados (minúsculas, sem acento, só [a-z0-9] e espaço)."
            },
            "opcoes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "rotulo": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              },
              "description": "pt e en; os demais idiomas caem em en, depois pt."
            }
          }
        }
      }
    }
  },
  "crm_ListaContatos": {
    "type": "object",
    "required": [
      "contatos",
      "proximo"
    ],
    "properties": {
      "contatos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Contato"
        }
      },
      "proximo": {
        "type": "string",
        "description": "cursor opaco da próxima página; vazio = acabou"
      }
    }
  },
  "crm_PedidoApagamento": {
    "type": "object",
    "properties": {
      "motivo": {
        "type": "string",
        "description": "opcional; default \"apagado pelo usuário\""
      }
    }
  },
  "crm_PedidoExclusaoNovo": {
    "type": "object",
    "required": [
      "contato_id",
      "solicitante"
    ],
    "properties": {
      "contato_id": {
        "type": "string",
        "description": "id público do contato (con_…)"
      },
      "solicitante": {
        "type": "string",
        "maxLength": 200,
        "description": "como o titular se identificou (PII; redigido após a execução)"
      },
      "canal": {
        "type": "string",
        "enum": [
          "formulario",
          "email",
          "telefone",
          "chat",
          "presencial",
          "outro"
        ],
        "default": "outro"
      },
      "motivo": {
        "type": "string",
        "maxLength": 1000
      }
    }
  },
  "crm_PedidoExclusaoDecisao": {
    "type": "object",
    "properties": {
      "motivo": {
        "type": "string",
        "maxLength": 1000,
        "description": "obrigatório ao recusar; opcional ao aprovar"
      }
    }
  },
  "crm_PedidoExclusao": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "ped_…"
      },
      "contato_id": {
        "type": "string"
      },
      "solicitante": {
        "type": "string"
      },
      "canal": {
        "type": "string"
      },
      "motivo": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "pendente",
          "aprovado",
          "recusado",
          "executado"
        ]
      },
      "criado_por": {
        "type": "string"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "decidido_por": {
        "type": "string"
      },
      "decisao_motivo": {
        "type": "string"
      },
      "decidido_em": {
        "type": "string",
        "format": "date-time"
      },
      "executado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_PedidosExclusaoPagina": {
    "type": "object",
    "properties": {
      "itens": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_PedidoExclusao"
        }
      },
      "proximo": {
        "type": "string",
        "description": "cursor opaco; vazio = acabou"
      }
    }
  },
  "crm_Atividade": {
    "type": "object",
    "description": "Uma entrada da timeline.",
    "properties": {
      "id": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "description": "ex.: nota_adicionada, dados_exportados, contato_anonimizado"
      },
      "resumo": {
        "type": "string"
      },
      "autor_id": {
        "type": "string",
        "description": "ausente quando foi o sistema"
      },
      "por_sistema": {
        "type": "boolean"
      },
      "dados": {
        "type": "object",
        "additionalProperties": true,
        "description": "Chaves por tipo. `conversao_enviada` (ADR-0120): `app` (slug do app, ausente se nem Integrações nem o cache do passo o souberam), `instalacao_nome`, `evento`, `valor`, `moeda`. `conversao_resultado`: `app`, `instalacao_nome`, `desfecho`, `id_externo`, `motivo`."
      },
      "ocorreu_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_ListaAtividades": {
    "type": "object",
    "required": [
      "atividades",
      "proximo",
      "total"
    ],
    "properties": {
      "atividades": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Atividade"
        }
      },
      "proximo": {
        "type": "string",
        "description": "cursor opaco; vazio = acabou"
      },
      "total": {
        "type": "integer"
      }
    }
  },
  "crm_PedidoNota": {
    "type": "object",
    "required": [
      "texto"
    ],
    "properties": {
      "texto": {
        "type": "string",
        "description": "até 4000 caracteres"
      }
    }
  },
  "crm_ConversaDoContato": {
    "type": "object",
    "description": "Item RASO da projeção local — sem estado nem prévia de mensagem (ver a descrição da rota). O detalhe completo mora no asender_atendimento_api.",
    "properties": {
      "conversa_id": {
        "type": "string",
        "description": "id PÚBLICO e opaco, do asender_atendimento_api"
      },
      "canal": {
        "type": "string",
        "enum": [
          "form",
          "email",
          "whatsapp",
          "chat"
        ]
      },
      "vinculado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_ListaConversasDoContato": {
    "type": "object",
    "required": [
      "itens"
    ],
    "properties": {
      "itens": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_ConversaDoContato"
        }
      }
    }
  },
  "crm_IdentidadeDoContato": {
    "type": "object",
    "required": [
      "id",
      "tipo",
      "valor_mascarado",
      "verificada",
      "criada_em"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "id público opaco (idn_…)"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "email",
          "telefone",
          "whatsapp",
          "chat_visitante",
          "telegram",
          "whatsapp_lid"
        ]
      },
      "valor_mascarado": {
        "type": "string",
        "description": "ex.: a***@dominio.com, +55*********78, tg:******789, lid:***123 — o valor em claro nunca é devolvido"
      },
      "verificada": {
        "type": "boolean"
      },
      "fonte": {
        "type": "string",
        "description": "formulario, importacao, manual, conversa:…; ausente nas espelhadas das colunas escalares"
      },
      "criada_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_ListaIdentidadesDoContato": {
    "type": "object",
    "required": [
      "itens"
    ],
    "properties": {
      "itens": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_IdentidadeDoContato"
        }
      }
    }
  },
  "crm_PedidoIdentidadeManual": {
    "type": "object",
    "required": [
      "tipo",
      "valor"
    ],
    "additionalProperties": false,
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "telefone",
          "email",
          "telegram",
          "whatsapp_lid"
        ]
      },
      "valor": {
        "type": "string",
        "description": "telefone E.164 (+5511912345678), e-mail, tg:<dígitos> ou lid:<id>"
      }
    }
  },
  "crm_PedidoDesvinculo": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "motivo": {
        "type": "string",
        "maxLength": 500,
        "description": "texto livre; fica só na linha da identidade, não na timeline"
      }
    }
  },
  "crm_ConflitoDeIdentidade": {
    "type": "object",
    "required": [
      "erro",
      "contato_id",
      "sugestoes_url"
    ],
    "properties": {
      "erro": {
        "type": "string"
      },
      "contato_id": {
        "type": "string",
        "description": "id público do contato que já tem o endereço (a UI oferece a mesclagem)"
      },
      "sugestoes_url": {
        "type": "string",
        "description": "a fila onde a colisão foi enfileirada (/v1/identidades/sugestoes)"
      }
    }
  },
  "crm_IdentidadeResolvida": {
    "type": "object",
    "required": [
      "achou"
    ],
    "properties": {
      "achou": {
        "type": "boolean"
      },
      "contato_id": {
        "type": "string",
        "description": "ausente quando achou é false"
      }
    }
  },
  "crm_Consentimento": {
    "type": "object",
    "description": "Preferência da pessoa, canal a canal, no positivo (`recebe`).",
    "required": [
      "recebe"
    ],
    "properties": {
      "recebe": {
        "type": "object",
        "additionalProperties": {
          "type": "boolean"
        },
        "description": "uma entrada por canal, sempre as quatro; ex.: { email: true, sms: false, push: true, whatsapp: true }"
      },
      "fuso": {
        "type": "string",
        "description": "fuso da pessoa, quando conhecido"
      }
    }
  },
  "crm_PedidoConsentimento": {
    "type": "object",
    "description": "Um canal por vez; `recebe` ausente é 422.",
    "required": [
      "canal",
      "recebe"
    ],
    "properties": {
      "canal": {
        "type": "string",
        "enum": [
          "email",
          "sms",
          "push",
          "whatsapp"
        ],
        "description": "webhook NÃO entra: alcança um sistema do cliente, não uma pessoa"
      },
      "recebe": {
        "type": "boolean",
        "description": "true volta a receber, false sai"
      },
      "origem": {
        "type": "string",
        "description": "quem pediu; default \"painel\""
      }
    }
  },
  "crm_Criterio": {
    "type": "object",
    "description": "Uma condição sobre um campo da allowlist.",
    "required": [
      "campo",
      "operador"
    ],
    "properties": {
      "campo": {
        "type": "string",
        "enum": [
          "estagio",
          "dono",
          "nome",
          "origem_source",
          "origem_medium",
          "origem_campanha",
          "origem_dominio",
          "origem_form",
          "origem_modo",
          "criado_em",
          "atualizado_em",
          "marcador",
          "consentimento"
        ]
      },
      "operador": {
        "type": "string",
        "enum": [
          "igual",
          "diferente",
          "contem",
          "comeca_com",
          "existe",
          "nao_existe",
          "maior_que",
          "menor_que",
          "tem_marcador",
          "nao_tem_marcador"
        ]
      },
      "valor": {
        "type": "string",
        "description": "não exigido por existe/nao_existe"
      }
    }
  },
  "crm_Segmento": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "tenant_id": {
        "type": "string",
        "description": "resolvido da sessão"
      },
      "nome": {
        "type": "string"
      },
      "conjuncao": {
        "type": "string",
        "enum": [
          "e",
          "ou"
        ],
        "description": "padrão `e`"
      },
      "criterios": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Criterio"
        }
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_PedidoSegmento": {
    "type": "object",
    "description": "Corpo de criar/atualizar/prévia. Sem `id`, `tenant_id` nem `criado_em`.",
    "required": [
      "nome",
      "criterios"
    ],
    "properties": {
      "nome": {
        "type": "string"
      },
      "conjuncao": {
        "type": "string",
        "enum": [
          "e",
          "ou"
        ]
      },
      "criterios": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Criterio"
        }
      }
    }
  },
  "crm_SegmentoComAlcance": {
    "type": "object",
    "required": [
      "segmento",
      "alcance"
    ],
    "properties": {
      "segmento": {
        "$ref": "#/components/schemas/crm_Segmento"
      },
      "alcance": {
        "type": "integer",
        "description": "quantos contatos alcança agora; -1 = não consegui contar"
      }
    }
  },
  "crm_ListaSegmentos": {
    "type": "object",
    "required": [
      "segmentos"
    ],
    "properties": {
      "segmentos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Segmento"
        }
      }
    }
  },
  "crm_Alcance": {
    "type": "object",
    "required": [
      "alcance"
    ],
    "properties": {
      "alcance": {
        "type": "integer"
      }
    }
  },
  "crm_Alerta": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "nome": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "sem_leads",
          "queda_qualidade"
        ]
      },
      "limiar": {
        "type": "number"
      },
      "janela_minutos": {
        "type": "integer"
      },
      "estado": {
        "type": "string",
        "enum": [
          "calmo",
          "disparado"
        ]
      },
      "ativo": {
        "type": "boolean"
      },
      "destino_id": {
        "type": "string"
      },
      "disparado_em": {
        "type": "string",
        "format": "date-time"
      },
      "avaliado_em": {
        "type": "string",
        "format": "date-time"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_AlertaEvento": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "alerta_id": {
        "type": "string"
      },
      "tipo": {
        "type": "string"
      },
      "motivo": {
        "type": "string"
      },
      "valor": {
        "type": "number"
      },
      "ocorreu_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_PedidoAlerta": {
    "type": "object",
    "required": [
      "nome",
      "tipo"
    ],
    "properties": {
      "nome": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "sem_leads",
          "queda_qualidade"
        ]
      },
      "limiar": {
        "type": "number"
      },
      "janela_minutos": {
        "type": "integer"
      },
      "destino_id": {
        "type": "string"
      },
      "ativo": {
        "type": "boolean"
      }
    }
  },
  "crm_ListaAlertas": {
    "type": "object",
    "required": [
      "alertas"
    ],
    "properties": {
      "alertas": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Alerta"
        }
      }
    }
  },
  "crm_ListaEventosAlerta": {
    "type": "object",
    "required": [
      "eventos"
    ],
    "properties": {
      "eventos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_AlertaEvento"
        }
      }
    }
  },
  "crm_Destino": {
    "type": "object",
    "description": "Destino de lead. O segredo nunca volta — só `tem_segredo`.",
    "properties": {
      "id": {
        "type": "string"
      },
      "nome": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "webhook",
          "conversao"
        ]
      },
      "provedor": {
        "type": "string",
        "description": "só em conversao (ex.: meta)"
      },
      "config": {
        "type": "object",
        "additionalProperties": true,
        "description": "ex.: { pixel_id }; o token nunca aparece"
      },
      "url": {
        "type": "string"
      },
      "ativo": {
        "type": "boolean"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "tem_segredo": {
        "type": "boolean"
      }
    }
  },
  "crm_Entrega": {
    "type": "object",
    "description": "Tentativa de levar um evento a um destino. O payload não volta (carrega PII).",
    "properties": {
      "id": {
        "type": "string"
      },
      "evento": {
        "type": "string"
      },
      "estado": {
        "type": "string"
      },
      "tentativas": {
        "type": "integer"
      },
      "ultimo_codigo": {
        "type": "integer"
      },
      "ultimo_erro": {
        "type": "string"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "entregue_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_PedidoDestino": {
    "type": "object",
    "description": "Corpo de criar/atualizar. O `tipo` vem da ROTA, não do corpo.",
    "properties": {
      "nome": {
        "type": "string"
      },
      "url": {
        "type": "string",
        "description": "http/https; rede interna é recusada (422). Ignorado em conversao"
      },
      "segredo": {
        "type": "string",
        "description": "cifrado no servidor; ausente no PUT preserva o gravado"
      },
      "ativo": {
        "type": "boolean"
      },
      "provedor": {
        "type": "string",
        "description": "só conversao (hoje: meta)"
      },
      "config": {
        "type": "object",
        "additionalProperties": true,
        "description": "só conversao; exige pixel_id"
      }
    }
  },
  "crm_ListaDestinos": {
    "type": "object",
    "required": [
      "destinos"
    ],
    "properties": {
      "destinos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Destino"
        }
      }
    }
  },
  "crm_ListaIntegracoes": {
    "type": "object",
    "required": [
      "integracoes"
    ],
    "properties": {
      "integracoes": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Destino"
        }
      }
    }
  },
  "crm_ListaEntregas": {
    "type": "object",
    "required": [
      "entregas"
    ],
    "properties": {
      "entregas": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/crm_Entrega"
        }
      }
    }
  },
  "crm_TesteEnfileirado": {
    "type": "object",
    "required": [
      "enfileiradas"
    ],
    "properties": {
      "enfileiradas": {
        "type": "integer"
      },
      "aviso": {
        "type": "string"
      }
    }
  },
  "crm_Retencao": {
    "type": "object",
    "description": "Política de retenção. `dias: null` = guardar indefinidamente.",
    "properties": {
      "dias": {
        "type": [
          "integer",
          "null"
        ],
        "description": "30 a 3650, ou null"
      },
      "aplicada_em": {
        "type": "string",
        "format": "date-time"
      },
      "anonimizados_total": {
        "type": "integer",
        "format": "int64"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_RespostaRetencao": {
    "type": "object",
    "required": [
      "retencao"
    ],
    "properties": {
      "retencao": {
        "$ref": "#/components/schemas/crm_Retencao"
      }
    }
  },
  "crm_PedidoRetencao": {
    "type": "object",
    "description": "`dias` ausente é 400; `null` desliga a expiração.",
    "required": [
      "dias"
    ],
    "properties": {
      "dias": {
        "type": [
          "integer",
          "null"
        ]
      }
    }
  },
  "crm_Uso": {
    "type": "object",
    "description": "Consumo da conta. Os números locais sempre voltam; a quota depende do core.",
    "properties": {
      "periodo": {
        "type": "string",
        "description": "AAAA-MM"
      },
      "contatos": {
        "type": "integer",
        "format": "int64"
      },
      "contatos_no_periodo": {
        "type": "integer",
        "format": "int64"
      },
      "anonimizados": {
        "type": "integer",
        "format": "int64"
      },
      "quota_mensal": {
        "type": [
          "integer",
          "null"
        ]
      },
      "quota_conhecida": {
        "type": "boolean",
        "description": "false separa \"sem limite\" de \"core fora\""
      },
      "core_disponivel": {
        "type": "boolean"
      },
      "emails_enviados": {
        "type": "integer",
        "format": "int64"
      },
      "sms_enviados": {
        "type": "integer",
        "format": "int64"
      },
      "push_enviados": {
        "type": "integer",
        "format": "int64"
      },
      "chamadas_api": {
        "type": "integer",
        "format": "int64"
      }
    }
  },
  "crm_RespostaUso": {
    "type": "object",
    "required": [
      "uso"
    ],
    "properties": {
      "uso": {
        "$ref": "#/components/schemas/crm_Uso"
      }
    }
  },
  "crm_Projeto": {
    "type": "object",
    "description": "Um projeto do kanban. Só a logo está detalhada aqui; as demais rotas de /v1/projetos usam o mesmo objeto.",
    "required": [
      "id",
      "coluna_id",
      "titulo",
      "descricao",
      "ordem",
      "dono_id",
      "prazo",
      "valor",
      "tem_logo",
      "logo_versao",
      "criado_em",
      "atualizado_em"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "coluna_id": {
        "type": "string"
      },
      "cliente_id": {
        "type": "string"
      },
      "cliente_nome": {
        "type": "string"
      },
      "titulo": {
        "type": "string"
      },
      "descricao": {
        "type": "string"
      },
      "ordem": {
        "type": "integer"
      },
      "dono_id": {
        "type": "string"
      },
      "prazo": {
        "type": "string",
        "description": "AAAA-MM-DD ou vazio"
      },
      "valor": {
        "type": "string",
        "description": "decimal canônico ou vazio"
      },
      "tem_logo": {
        "type": "boolean",
        "description": "o projeto tem logo customizada (campo aditivo)"
      },
      "logo_versao": {
        "type": "string",
        "description": "primeiros 12 hex do sha256 da logo; vazio sem logo — use como cache-buster do GET /logo (campo aditivo)"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "crm_ErroLogo": {
    "type": "object",
    "description": "Erro do envio de logo — o envelope `erro` mais um `codigo` estável.",
    "required": [
      "erro",
      "codigo"
    ],
    "properties": {
      "erro": {
        "type": "string"
      },
      "codigo": {
        "type": "string",
        "enum": [
          "ArquivoGrande",
          "FormatoInvalido",
          "ArquivoInfectado",
          "AntivirusIndisponivel"
        ]
      }
    }
  },
  "crm_PedidoLogo": {
    "type": "object",
    "required": [
      "arquivo"
    ],
    "properties": {
      "arquivo": {
        "type": "string",
        "format": "binary",
        "description": "PNG ou JPEG, até 512 KiB, 32..2048 px por lado. O tipo é detectado pelos bytes (Content-Type e extensão do cliente são ignorados); a imagem é re-codificada (EXIF e metadados somem). SVG e outros tipos são recusados."
      }
    }
  },
  "pages_EstadoCloudflare": {
    "type": "object",
    "description": "O que a tela pode oferecer para o domínio na Cloudflare. O token NUNCA volta (nem cifrado). `domain_connect.motivo` explica por que o botão de 1 clique não aparece — consulta_falhou | fora_da_cloudflare | sem_domain_connect | sem_chave | template_pendente.",
    "properties": {
      "zona": {
        "type": "string",
        "example": "loja.com.br"
      },
      "na_cloudflare": {
        "type": "boolean"
      },
      "consulta_falhou": {
        "type": "boolean"
      },
      "domain_connect": {
        "type": "object",
        "properties": {
          "disponivel": {
            "type": "boolean"
          },
          "motivo": {
            "type": "string",
            "enum": [
              "consulta_falhou",
              "fora_da_cloudflare",
              "sem_domain_connect",
              "sem_chave",
              "template_pendente"
            ]
          }
        }
      },
      "token": {
        "type": "object",
        "properties": {
          "disponivel": {
            "type": "boolean",
            "description": "o ambiente tem a chave de cifra (ENCRYPTION_KEY)"
          },
          "configurado": {
            "type": "boolean"
          },
          "zona": {
            "type": "string"
          },
          "atualizado_em": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ultima_aplicacao": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/pages_AplicacaoDNS"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  },
  "pages_AplicacaoDNS": {
    "type": "object",
    "description": "Uma linha da trilha de auditoria (append-only) das ações no DNS.",
    "properties": {
      "ator": {
        "type": "string"
      },
      "metodo": {
        "type": "string",
        "enum": [
          "token",
          "domain_connect"
        ]
      },
      "evento": {
        "type": "string",
        "enum": [
          "token_salvo",
          "token_removido",
          "aplicacao",
          "url_gerada"
        ]
      },
      "zona": {
        "type": "string"
      },
      "resultado": {
        "type": "string",
        "enum": [
          "ok",
          "parcial",
          "erro"
        ]
      },
      "registros": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_AcaoDNS"
        }
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "pages_AcaoDNS": {
    "type": "object",
    "description": "O que a aplicação fez num registro. Nunca há \"apagado\": registro alheio que atrapalha vira `conflito` com a instrução em `detalhe`.",
    "properties": {
      "resultado": {
        "type": "string",
        "enum": [
          "mantido",
          "criado",
          "atualizado",
          "conflito",
          "falhou"
        ]
      },
      "tipo": {
        "type": "string",
        "example": "CNAME"
      },
      "nome": {
        "type": "string"
      },
      "valor": {
        "type": "string"
      },
      "papel": {
        "type": "string"
      },
      "anterior": {
        "type": "string",
        "description": "valor antes de um `atualizado` (para desfazer à mão)"
      },
      "detalhe": {
        "type": "string"
      }
    }
  },
  "pages_RelatorioCloudflare": {
    "type": "object",
    "properties": {
      "zona": {
        "type": "string"
      },
      "ok": {
        "type": "boolean",
        "description": "nenhum conflito nem falha"
      },
      "registros": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_AcaoDNS"
        }
      }
    }
  },
  "pages_UsoDeCota": {
    "type": "object",
    "required": [
      "limite",
      "usado"
    ],
    "properties": {
      "limite": {
        "type": [
          "integer",
          "null"
        ],
        "description": "null = ilimitado"
      },
      "usado": {
        "type": "integer"
      }
    }
  },
  "pages_CotaExcedida": {
    "type": "object",
    "required": [
      "recurso",
      "limite",
      "usado"
    ],
    "properties": {
      "erro": {
        "type": "string"
      },
      "recurso": {
        "type": "string",
        "enum": [
          "pages_subdominios",
          "pages_dominios_principais"
        ]
      },
      "limite": {
        "type": "integer"
      },
      "usado": {
        "type": "integer"
      }
    }
  },
  "pages_DominioGratis": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "host": {
        "type": "string",
        "example": "minhaloja.apages.xyz"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "gratis"
        ]
      },
      "classe": {
        "type": "string",
        "enum": [
          "subdominio"
        ]
      },
      "verificado": {
        "type": "boolean"
      },
      "pronto": {
        "type": "boolean"
      },
      "verificado_em": {
        "type": "string",
        "format": "date-time"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "posse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        }
      },
      "apontamento": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        }
      },
      "tls": {
        "type": "object",
        "properties": {
          "estado": {
            "type": "string"
          }
        }
      }
    }
  },
  "pages_ResumoDeFerramenta": {
    "type": "object",
    "description": "Contrato comum de resumo de ferramenta (plano 2026-10-02) — o mesmo formato em toda ferramenta.",
    "required": [
      "ferramenta",
      "periodo",
      "indicadores",
      "series"
    ],
    "properties": {
      "ferramenta": {
        "type": "string",
        "description": "slug da ferramenta (crm, mail, pages, atendimento, …)"
      },
      "periodo": {
        "type": "object",
        "required": [
          "de",
          "ate",
          "chave"
        ],
        "properties": {
          "de": {
            "type": "string",
            "format": "date",
            "description": "primeiro dia da janela (inclusivo)"
          },
          "ate": {
            "type": "string",
            "format": "date",
            "description": "último dia da janela (inclusivo)"
          },
          "chave": {
            "type": "string",
            "enum": [
              "7d",
              "30d",
              "90d"
            ]
          }
        }
      },
      "indicadores": {
        "type": "array",
        "minItems": 1,
        "maxItems": 6,
        "items": {
          "$ref": "#/components/schemas/pages_ResumoIndicador"
        }
      },
      "series": {
        "type": "array",
        "maxItems": 2,
        "items": {
          "$ref": "#/components/schemas/pages_ResumoSerie"
        }
      }
    }
  },
  "pages_ResumoIndicador": {
    "type": "object",
    "required": [
      "chave",
      "rotulo",
      "valor",
      "anterior",
      "formato",
      "link"
    ],
    "properties": {
      "chave": {
        "type": "string",
        "description": "id estável do indicador"
      },
      "rotulo": {
        "type": "string",
        "description": "rótulo pt-BR (o front pode traduzir pela chave)"
      },
      "valor": {
        "type": "number"
      },
      "anterior": {
        "type": [
          "number",
          "null"
        ],
        "description": "mesmo indicador na janela anterior de mesmo tamanho; null = sem comparação"
      },
      "formato": {
        "type": "string",
        "enum": [
          "numero",
          "percentual",
          "moeda",
          "duracao"
        ],
        "description": "moeda em centavos BRL; duracao em segundos; percentual 0–100"
      },
      "link": {
        "type": "string",
        "description": "caminho relativo dentro da ferramenta, já com a conta"
      }
    }
  },
  "pages_ResumoSerie": {
    "type": "object",
    "required": [
      "chave",
      "rotulo",
      "tipo",
      "pontos"
    ],
    "properties": {
      "chave": {
        "type": "string"
      },
      "rotulo": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "linha",
          "barra"
        ]
      },
      "pontos": {
        "type": "array",
        "description": "um ponto por dia da janela (dia sem evento vem com 0)",
        "items": {
          "type": "object",
          "required": [
            "data",
            "valor"
          ],
          "properties": {
            "data": {
              "type": "string",
              "format": "date"
            },
            "valor": {
              "type": "number"
            }
          }
        }
      }
    }
  },
  "pages_RecorteFunil": {
    "type": "object",
    "properties": {
      "chave": {
        "type": "string",
        "description": "utm_source, host do referrer ou (direto); dispositivo; ou host+caminho da página"
      },
      "visualizacoes": {
        "type": "integer"
      },
      "inicios": {
        "type": "integer"
      },
      "envios": {
        "type": "integer"
      },
      "taxa_conversao": {
        "type": "number"
      }
    }
  },
  "pages_ErroAutoria": {
    "type": "object",
    "description": "Envelope de erro da AUTORIA (asender_pages_api).",
    "required": [
      "erro"
    ],
    "properties": {
      "erro": {
        "type": "string",
        "description": "mensagem legível; nunca revela existência de recurso de outra conta"
      },
      "codigo": {
        "type": "string",
        "description": "código estável, quando a recusa tem um (ex.: destinos integracao)"
      },
      "local": {
        "type": "string",
        "description": "o campo culpado, quando há (ex.: destinos[1].config.status_id)"
      }
    }
  },
  "pages_ErroRuntime": {
    "type": "object",
    "description": "Envelope de erro do RUNTIME (asender_pages_runtime) — RFC 7807-compatível.",
    "required": [
      "error"
    ],
    "properties": {
      "error": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "pages_PaginaArquivada": {
    "type": "object",
    "description": "Uma página na lixeira do usuário.",
    "required": [
      "id",
      "titulo",
      "slug",
      "dominio",
      "arquivada_em",
      "arquivada_por",
      "arquivada_por_nome"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "titulo": {
        "type": "string"
      },
      "slug": {
        "type": "string"
      },
      "dominio": {
        "type": "string",
        "description": "Vazio = host da plataforma."
      },
      "arquivada_em": {
        "type": "string",
        "format": "date-time"
      },
      "arquivada_por": {
        "type": "string",
        "description": "Id do usuário que arquivou; vazio quando foi o sistema."
      },
      "arquivada_por_nome": {
        "type": "string",
        "description": "Nome (senão e-mail) de quem arquivou, resolvido no servidor pelo lote do auth; vazio quando foi o sistema ou o nome não pôde ser resolvido (auth fora). Telas mostram este campo, nunca o id."
      }
    }
  },
  "pages_FormularioArquivado": {
    "type": "object",
    "description": "Um formulário na lixeira do usuário.",
    "required": [
      "id",
      "nome",
      "arquivado_em",
      "arquivado_por"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "public_id do formulário."
      },
      "nome": {
        "type": "string"
      },
      "arquivado_em": {
        "type": "string",
        "format": "date-time"
      },
      "arquivado_por": {
        "type": "string",
        "description": "Id do usuário que apagou (lido da auditoria); vazio quando foi chave de API, o sistema ou o rastro não existe."
      },
      "arquivado_por_nome": {
        "type": "string",
        "description": "Nome (senão e-mail) de quem apagou, resolvido no servidor; opcional — vazio quando o nome não pôde ser resolvido. Telas mostram este campo, nunca o id."
      }
    }
  },
  "pages_Pagina": {
    "type": "object",
    "description": "Uma página do construtor.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "slug": {
        "type": "string",
        "description": "caminho da página no host (ex.: `promo`)"
      },
      "dominio": {
        "type": "string",
        "description": "host onde ela é servida; vazio usa o padrão `sites.asender.net`"
      },
      "titulo": {
        "type": "string"
      },
      "template": {
        "$ref": "#/components/schemas/pages_TemplatePagina"
      }
    }
  },
  "pages_PedidoLote": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "acao",
      "ids"
    ],
    "properties": {
      "acao": {
        "type": "string",
        "enum": [
          "publicar",
          "despublicar",
          "duplicar",
          "mudar_dominio",
          "arquivar"
        ]
      },
      "ids": {
        "type": "array",
        "minItems": 1,
        "maxItems": 100,
        "items": {
          "type": "string"
        }
      },
      "rascunho": {
        "type": "string",
        "enum": [
          "pular",
          "publicar_salva"
        ],
        "default": "pular",
        "description": "só vale em publicar"
      },
      "simular": {
        "type": "boolean",
        "default": false
      },
      "dominio_id": {
        "type": "string",
        "description": "mudar_dominio: domínio de destino (\"\" = host da plataforma)"
      },
      "caminho_por_pagina": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "mudar_dominio: id da página → caminho novo (ausente = mantém)"
      }
    }
  },
  "pages_ResultadoLote": {
    "type": "object",
    "required": [
      "id",
      "status"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "titulo": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "ok",
          "pulada",
          "erro"
        ]
      },
      "motivo": {
        "type": "string",
        "enum": [
          "nao_encontrada",
          "rascunho_mais_novo",
          "conteudo_invalido",
          "sem_versao",
          "ja_publicada",
          "ja_despublicada",
          "sem_privilegio",
          "slug_em_uso",
          "dominio_invalido",
          "caminho_em_uso",
          "indisponivel",
          "falha_interna"
        ]
      },
      "detalhe": {
        "type": "string"
      },
      "sem_mudanca": {
        "type": "boolean"
      },
      "versao": {
        "type": "integer"
      },
      "rascunho_mais_novo": {
        "type": "boolean"
      },
      "nova_pagina_id": {
        "type": "string"
      },
      "novo_slug": {
        "type": "string"
      },
      "url_destino": {
        "type": "string"
      }
    }
  },
  "pages_RespostaLote": {
    "type": "object",
    "required": [
      "lote_id",
      "acao",
      "simulado",
      "total",
      "ok",
      "puladas",
      "erros",
      "resultados"
    ],
    "properties": {
      "lote_id": {
        "type": "string"
      },
      "acao": {
        "type": "string"
      },
      "simulado": {
        "type": "boolean"
      },
      "total": {
        "type": "integer"
      },
      "ok": {
        "type": "integer"
      },
      "puladas": {
        "type": "integer"
      },
      "erros": {
        "type": "integer"
      },
      "resultados": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ResultadoLote"
        }
      }
    }
  },
  "pages_ImportarPagina": {
    "type": "object",
    "description": "Corpo de `POST /v1/paginas/importar` (a conta vem da sessão; `tenant_id` é recusado).",
    "required": [
      "slug",
      "titulo",
      "template"
    ],
    "properties": {
      "slug": {
        "type": "string"
      },
      "dominio": {
        "type": "string",
        "description": "domínio próprio; exige posse PROVADA do host"
      },
      "titulo": {
        "type": "string"
      },
      "template": {
        "$ref": "#/components/schemas/pages_TemplatePagina"
      },
      "seo": {
        "type": "object",
        "description": "SEO da página vindo do arquivo; `og_imagem_url` também é copiada para a conta.",
        "additionalProperties": true
      }
    }
  },
  "pages_ItemImportacaoMidia": {
    "type": "object",
    "required": [
      "original",
      "estado",
      "usos"
    ],
    "properties": {
      "original": {
        "type": "string"
      },
      "novo": {
        "type": "string",
        "description": "URL na biblioteca da conta (vazio se mantido)"
      },
      "estado": {
        "type": "string",
        "enum": [
          "copiado",
          "ja_na_conta",
          "mantido_original"
        ]
      },
      "motivo": {
        "type": "string",
        "description": "só em mantido_original: destino_bloqueado, redirecionamentos_demais, endereco_nao_resolvido, arquivo_grande, tipo_nao_permitido, svg_recusado, antivirus_recusou, antivirus_indisponivel, falha_ao_baixar, falha_ao_gravar, tempo_esgotado, limite_total_excedido, limite_de_arquivos, importacao_externa_desligada, midia_origem_inexistente, caminho_relativo"
      },
      "midia_id": {
        "type": "string"
      },
      "usos": {
        "type": "integer"
      },
      "caminhos": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "pages_AvisoImportacao": {
    "type": "object",
    "required": [
      "codigo"
    ],
    "properties": {
      "codigo": {
        "type": "string",
        "enum": [
          "formulario_removido",
          "rastreio_removido",
          "vinculo_removido",
          "seo_nao_salvo"
        ]
      },
      "caminho": {
        "type": "string"
      },
      "detalhe": {
        "type": "string"
      }
    }
  },
  "pages_RelatorioImportacao": {
    "type": "object",
    "required": [
      "itens",
      "avisos",
      "copiadas",
      "ja_na_conta",
      "mantidas",
      "copia_disponivel",
      "seo_aplicado"
    ],
    "properties": {
      "itens": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ItemImportacaoMidia"
        }
      },
      "avisos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_AvisoImportacao"
        }
      },
      "copiadas": {
        "type": "integer"
      },
      "ja_na_conta": {
        "type": "integer"
      },
      "mantidas": {
        "type": "integer"
      },
      "copia_disponivel": {
        "type": "boolean",
        "description": "false = o serviço subiu sem galeria; nada foi copiado"
      },
      "seo_aplicado": {
        "type": "boolean"
      }
    }
  },
  "pages_ResultadoImportacao": {
    "type": "object",
    "required": [
      "pagina",
      "importacao"
    ],
    "properties": {
      "pagina": {
        "$ref": "#/components/schemas/pages_Pagina"
      },
      "importacao": {
        "$ref": "#/components/schemas/pages_RelatorioImportacao"
      }
    }
  },
  "pages_ResultadoRecopia": {
    "type": "object",
    "required": [
      "importacao"
    ],
    "properties": {
      "importacao": {
        "$ref": "#/components/schemas/pages_RelatorioImportacao"
      },
      "versao": {
        "type": "integer",
        "description": "presente quando uma versão nova foi gravada"
      }
    }
  },
  "pages_CriarPagina": {
    "type": "object",
    "description": "Corpo de `POST /v1/paginas`.",
    "required": [
      "titulo"
    ],
    "properties": {
      "slug": {
        "type": "string"
      },
      "dominio": {
        "type": "string",
        "description": "domínio próprio; exige posse PROVADA do host (senão 422)"
      },
      "titulo": {
        "type": "string"
      },
      "template": {
        "allOf": [
          {
            "$ref": "#/components/schemas/pages_TemplatePagina"
          }
        ],
        "description": "conteúdo inicial (v1 ou v2); conteúdo privilegiado (bloco/item `html`, HTML cru) exige nível pelo PEP. Ausente: a página nasce v2 com UMA seção (preset `hero`) com o título digitado — sem cabeçalho forçado."
      }
    }
  },
  "pages_EditarPagina": {
    "type": "object",
    "description": "Corpo de `PATCH /v1/paginas/{id}`. Campo ausente não muda; ao menos um é obrigatório.",
    "properties": {
      "slug": {
        "type": "string"
      },
      "dominio": {
        "type": "string"
      },
      "titulo": {
        "type": "string"
      }
    }
  },
  "pages_TemplatePagina": {
    "description": "O conteúdo de uma versão da página. A escrita aceita os DOIS formatos durante a transição (ADR-0086): o número `versao` escolhe o contrato. `1` (ou ausente) é a lista plana de blocos; `2` é o documento seção > colunas > itens, de estrutura, estilo e props FECHADOS (campo desconhecido = 422). A leitura devolve o que foi gravado (versões v1 antigas seguem v1).",
    "oneOf": [
      {
        "$ref": "#/components/schemas/pages_TemplateV1"
      },
      {
        "$ref": "#/components/schemas/pages_DocumentoV2"
      }
    ]
  },
  "pages_TemplateV1": {
    "type": "object",
    "description": "Template v1: blocos `{tipo, ...campos}` (passthrough por campo; tipo da allowlist).",
    "required": [
      "secoes"
    ],
    "properties": {
      "versao": {
        "type": "integer",
        "enum": [
          1
        ]
      },
      "configuracoes": {
        "type": "object"
      },
      "secoes": {
        "type": "array",
        "minItems": 1,
        "maxItems": 200,
        "items": {
          "type": "object",
          "required": [
            "tipo"
          ],
          "properties": {
            "tipo": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "pages_ErroConteudo": {
    "type": "object",
    "description": "Recusa (422) de um documento v2. `codigo` é o nome da sentinela do validador (o mesmo do validador TS do editor) e `caminho` aponta o nó culpado — o editor seleciona o nó por ele. Sem nó, `caminho` é `versao`, `secoes` ou `documento`. Recusa de template v1 continua só com `erro`.",
    "required": [
      "erro",
      "codigo",
      "caminho"
    ],
    "properties": {
      "erro": {
        "type": "string",
        "description": "mensagem legível (já cita o caminho)"
      },
      "codigo": {
        "type": "string",
        "enum": [
          "ErrMalformado",
          "ErrVersao",
          "ErrSemSecoes",
          "ErrLimite",
          "ErrSemColunas",
          "ErrID",
          "ErrAncora",
          "ErrTipoDesconhecido",
          "ErrPropInvalida",
          "ErrEstiloInvalido",
          "ErrEstruturaInvalida"
        ]
      },
      "caminho": {
        "type": "string",
        "examples": [
          "secoes[1].colunas[0].itens[2].props.cor"
        ]
      }
    }
  },
  "pages_DocumentoV2": {
    "title": "Documento de página v2 (seção > colunas > itens)",
    "description": "Contrato do template de página v2 do Asender Pages. Fonte Go: asender_pages_api/internal/domain/documento (cópia idêntica no asender_pages_runtime); gêmeo TS: asender_pages_front/lib/documento-v2. TestEsquemaJSONBateComGo e o teste esquema-v2 do front provam que os três concordam. Plano: asender_archive/plan/2026-10-03-pages-secoes-colunas-itens.md.",
    "x-limites": {
      "MaxSecoes": 200,
      "MaxColunas": 12,
      "MaxPesoColuna": 12,
      "MaxItensPorColuna": 100,
      "MaxItensTotal": 1000,
      "MaxItensLista": 50,
      "MaxEspaco": 400,
      "MaxRaio": 200,
      "MaxBorda": 20,
      "MinLarguraMax": 320,
      "MaxLarguraMax": 2400,
      "MaxAlturaPx": 2000,
      "MaxAlturaVh": 100,
      "MaxAtrasoPopup": 120,
      "GapPadraoItens": 16,
      "GapPadraoColunas": 24,
      "LarguraMaxPadrao": 1080,
      "MaxTamanhoID": 64,
      "MaxTamanhoNome": 80,
      "MaxTamanhoURL": 2048,
      "MaxTextoCurto": 300,
      "MaxTextoLongo": 20000,
      "MaxTamanhoHTML": 200000,
      "MaxTamanhoPrazo": 64,
      "MaxTextoTag": 60,
      "MaxPaineis": 20,
      "MaxItensPorPainel": 20,
      "MaxTituloPainel": 200,
      "MaxIconeTag": 48,
      "MaxFAQResposta": 4000,
      "MaxFAQPagina": 50,
      "MaxSubir": 200,
      "MaxPaddingImagem": 40,
      "MinIconeFundo": 24,
      "MaxIconeFundo": 72,
      "MaxColunasCartoes": 4,
      "MinLarguraCartao": 96,
      "MaxLarguraCartao": 400,
      "MinMiniatura": 56,
      "MaxMiniatura": 96,
      "MaxInclinar": 12,
      "MaxRotacaoCartao": 15
    },
    "x-privilegiados": [
      "html"
    ],
    "x-observacoes": [
      "Unicidade de id (seção, coluna e item no MESMO espaço) e de âncora, o teto de 1000 itens por página e as regras de fundo por tipo são conferidos pelo validador (Go/TS), não por este schema.",
      "Toda prop urlLink aceita a irmã <prop>_rastreio (objeto do encurtador, link.TrocarPorCurtos).",
      "ADR-0109 — abas/acordeao: os painéis moram em props.itens; cada painel tem titulo e itens aninhados (um nível só: nunca abas, acordeao, html nem formulario dentro). Ids dos itens aninhados dividem o espaço de ids do documento; o teto de 1000 itens os conta. aberta < nº de abas; acordeao com um_por_vez aceita no máximo um painel aberto; faq exige texto de resposta (até MaxFAQResposta) em cada painel e até MaxFAQPagina perguntas na página. Abas não geram schema.org; acordeao com faq=true gera FAQPage no JSON-LD da página publicada.",
      "L3 — estilo.subir (0..MaxSubir px) vira margin-top negativa e SUBSTITUI a margem de topo do item.",
      "L4 — fundo.cor_base é a cor sólida sob as demais camadas; fundo.sobreposicao exige `cor` OU `gradiente` (um só), com opacidade 0..100 na camada inteira; desenha-se sobre imagem, gradiente ou cor.",
      "L5 — imagem: `raio` PRESENTE vence `forma`; ausente = a forma de sempre.",
      "L6 — icone_fundo*/icone_dir_fundo*: contêiner (círculo/quadrado) atrás do ícone do início/fim; `redes` só no item. links.efeito_icone=girar gira o ícone do fim no hover.",
      "L2 — cartoes: até MaxItensLista cartões; permitido dentro de painel; `rotacao` do cartão vence `inclinar` do conjunto; `cor_fim` liga o degradê do fundo do cartão.",
      "Texto vale em code points (runas), não em bytes nem em unidades UTF-16."
    ],
    "type": "object",
    "additionalProperties": false,
    "required": [
      "versao",
      "secoes"
    ],
    "properties": {
      "versao": {
        "const": 2
      },
      "configuracoes": {},
      "estilo": {
        "$ref": "#/components/schemas/pages_DocV2_estiloPagina"
      },
      "secoes": {
        "type": "array",
        "minItems": 1,
        "maxItems": 200,
        "items": {
          "$ref": "#/components/schemas/pages_DocV2_secao"
        }
      }
    }
  },
  "pages_DocV2_id": {
    "type": "string",
    "pattern": "^[A-Za-z0-9_-]{1,64}$"
  },
  "pages_DocV2_ancora": {
    "type": "string",
    "pattern": "^[a-z][a-z0-9-]{0,63}$"
  },
  "pages_DocV2_cor": {
    "type": "string",
    "anyOf": [
      {
        "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$"
      },
      {
        "enum": [
          "transparente",
          "acento",
          "texto",
          "suave",
          "fundo",
          "superficie",
          "borda"
        ]
      }
    ]
  },
  "pages_DocV2_corOuVazia": {
    "anyOf": [
      {
        "const": ""
      },
      {
        "$ref": "#/components/schemas/pages_DocV2_cor"
      }
    ]
  },
  "pages_DocV2_urlLink": {
    "type": "string",
    "maxLength": 2048,
    "description": "Vazia, #ancora, /caminho (não //) ou esquema http/https/mailto/tel; sem caractere de controle."
  },
  "pages_DocV2_urlMidia": {
    "type": "string",
    "maxLength": 2048,
    "pattern": "^[^\"'()\\\\ <>\\u0000-\\u001f\\u007f]*$",
    "description": "Vazia, /caminho (não //) ou http(s) com host; sem aspas, parênteses, barra invertida, espaço, < > nem controle."
  },
  "pages_DocV2_identOuVazio": {
    "type": "string",
    "pattern": "^([a-z0-9_-]{1,40})?$"
  },
  "pages_DocV2_idRefOuVazio": {
    "type": "string",
    "pattern": "^([A-Za-z0-9_-]{1,64})?$"
  },
  "pages_DocV2_rastreio": {
    "type": [
      "object",
      "null"
    ],
    "description": "Objeto do encurtador (link_id, codigo, destino, desligado…); passthrough."
  },
  "pages_DocV2_lados": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "topo": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "direita": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "base": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "esquerda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      }
    }
  },
  "pages_DocV2_fundo": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "nenhum",
          "cor",
          "gradiente",
          "imagem"
        ]
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_base": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "gradiente": {
        "$ref": "#/components/schemas/pages_DocV2_gradiente"
      },
      "imagem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "$ref": "#/components/schemas/pages_DocV2_urlMidia"
          },
          "posicao": {
            "type": "string",
            "enum": [
              "centro",
              "topo",
              "base",
              "esquerda",
              "direita",
              "topo-esquerda",
              "topo-direita",
              "base-esquerda",
              "base-direita"
            ]
          },
          "tamanho": {
            "type": "string",
            "enum": [
              "cobrir",
              "conter",
              "auto"
            ]
          },
          "repetir": {
            "type": "boolean"
          },
          "fixo": {
            "type": "boolean"
          }
        }
      },
      "sobreposicao": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "opacidade"
        ],
        "oneOf": [
          {
            "required": [
              "cor"
            ]
          },
          {
            "required": [
              "gradiente"
            ]
          }
        ],
        "properties": {
          "cor": {
            "$ref": "#/components/schemas/pages_DocV2_cor"
          },
          "gradiente": {
            "$ref": "#/components/schemas/pages_DocV2_gradiente"
          },
          "opacidade": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      }
    }
  },
  "pages_DocV2_gradiente": {
    "description": "Degradê de duas cores (e uma do meio, opcional): o do fundo e o da sobreposição. As cores aceitam o token `transparente` (fade).",
    "type": "object",
    "additionalProperties": false,
    "required": [
      "de",
      "para"
    ],
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "linear",
          "radial"
        ]
      },
      "de": {
        "$ref": "#/components/schemas/pages_DocV2_cor"
      },
      "meio": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "para": {
        "$ref": "#/components/schemas/pages_DocV2_cor"
      },
      "angulo": {
        "type": "integer",
        "minimum": 0,
        "maximum": 360
      }
    }
  },
  "pages_DocV2_borda": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "largura": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "estilo": {
        "type": "string",
        "enum": [
          "solida",
          "tracejada",
          "pontilhada"
        ]
      },
      "lados": {
        "type": "array",
        "uniqueItems": true,
        "items": {
          "enum": [
            "topo",
            "direita",
            "base",
            "esquerda"
          ]
        }
      }
    }
  },
  "pages_DocV2_estiloPagina": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "tema": {
        "type": "string",
        "enum": [
          "claro",
          "escuro",
          "auto"
        ]
      },
      "fundo": {
        "$ref": "#/components/schemas/pages_DocV2_fundo"
      },
      "padrao": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tipo"
        ],
        "properties": {
          "tipo": {
            "type": "string",
            "enum": [
              "nenhum",
              "pontos",
              "grade",
              "diagonal"
            ]
          },
          "cor": {
            "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
          },
          "opacidade": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "tamanho": {
            "anyOf": [
              {
                "const": 0
              },
              {
                "type": "integer",
                "minimum": 8,
                "maximum": 96
              }
            ]
          }
        }
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "fonte_titulos": {
        "description": "Família (títulos h1..h6): vazio/ausente herda do kit de marca; senão um id da allowlist (auto-hospedada em /_f/). Qualquer outro valor é recusado (ErrEstiloInvalido).",
        "anyOf": [
          {
            "const": ""
          },
          {
            "type": "string",
            "enum": [
              "comfortaa",
              "urbanist",
              "montserrat",
              "inter",
              "poppins",
              "open-sans",
              "nunito",
              "playfair-display",
              "merriweather",
              "dm-sans",
              "manrope",
              "raleway"
            ]
          }
        ]
      },
      "fonte_texto": {
        "description": "Família (texto corrido): vazio/ausente herda do kit de marca; senão um id da allowlist (auto-hospedada em /_f/). Qualquer outro valor é recusado (ErrEstiloInvalido).",
        "anyOf": [
          {
            "const": ""
          },
          {
            "type": "string",
            "enum": [
              "comfortaa",
              "urbanist",
              "montserrat",
              "inter",
              "poppins",
              "open-sans",
              "nunito",
              "playfair-display",
              "merriweather",
              "dm-sans",
              "manrope",
              "raleway"
            ]
          }
        ]
      },
      "preloader": {
        "description": "Tela de carregamento com a logo do kit de marca efetivo. `logo` é uma variante do kit, nunca uma URL.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "ativo": {
            "type": "boolean"
          },
          "logo": {
            "type": "string",
            "enum": [
              "principal",
              "horizontal",
              "icone",
              "escuro"
            ]
          },
          "animacao": {
            "type": "string",
            "enum": [
              "pulso",
              "fade",
              "giro",
              "barra"
            ]
          },
          "cor_fundo": {
            "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
          },
          "tamanho": {
            "anyOf": [
              {
                "const": 0
              },
              {
                "type": "integer",
                "minimum": 32,
                "maximum": 240
              }
            ]
          },
          "duracao_min_ms": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3000
          }
        }
      },
      "conteudo": {
        "$ref": "#/components/schemas/pages_DocV2_estiloCaixa"
      }
    }
  },
  "pages_DocV2_estiloCaixa": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "padding": {
        "$ref": "#/components/schemas/pages_DocV2_lados"
      },
      "padding_celular": {
        "$ref": "#/components/schemas/pages_DocV2_lados"
      },
      "fundo": {
        "$ref": "#/components/schemas/pages_DocV2_fundo"
      },
      "borda": {
        "$ref": "#/components/schemas/pages_DocV2_borda"
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "sombra": {
        "type": "string",
        "enum": [
          "nenhuma",
          "suave",
          "media",
          "forte"
        ]
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      }
    }
  },
  "pages_DocV2_estiloSecao": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "padding": {
        "$ref": "#/components/schemas/pages_DocV2_lados"
      },
      "padding_celular": {
        "$ref": "#/components/schemas/pages_DocV2_lados"
      },
      "fundo": {
        "$ref": "#/components/schemas/pages_DocV2_fundo"
      },
      "borda": {
        "$ref": "#/components/schemas/pages_DocV2_borda"
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "sombra": {
        "type": "string",
        "enum": [
          "nenhuma",
          "suave",
          "media",
          "forte"
        ]
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "largura": {
        "type": "string",
        "enum": [
          "contida",
          "total"
        ]
      },
      "largura_max": {
        "type": "integer",
        "anyOf": [
          {
            "const": 0
          },
          {
            "minimum": 320,
            "maximum": 2400
          }
        ]
      },
      "altura_minima": {
        "type": "integer",
        "minimum": 0,
        "maximum": 2000
      },
      "altura_unidade": {
        "type": "string",
        "enum": [
          "px",
          "vh"
        ]
      },
      "alinhamento_vertical": {
        "type": "string",
        "enum": [
          "topo",
          "centro",
          "base",
          "esticar"
        ]
      },
      "gap_colunas": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      }
    }
  },
  "pages_DocV2_secao": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "id",
      "colunas"
    ],
    "properties": {
      "id": {
        "$ref": "#/components/schemas/pages_DocV2_id"
      },
      "preset": {
        "type": "string",
        "pattern": "^[a-z0-9_-]{1,40}$"
      },
      "nome": {
        "type": "string",
        "maxLength": 80
      },
      "ancora": {
        "$ref": "#/components/schemas/pages_DocV2_ancora"
      },
      "comportamento": {
        "type": "string",
        "enum": [
          "normal",
          "fixa_topo",
          "popup"
        ]
      },
      "atraso_popup": {
        "type": "integer",
        "minimum": 0,
        "maximum": 120
      },
      "ocultar_em": {
        "type": "array",
        "uniqueItems": true,
        "items": {
          "enum": [
            "computador",
            "tablet",
            "celular"
          ]
        }
      },
      "ocultar_se_vazia": {
        "type": "boolean"
      },
      "layout_celular": {
        "type": "string",
        "enum": [
          "empilhar",
          "manter"
        ]
      },
      "inverter_celular": {
        "type": "boolean"
      },
      "estilo": {
        "$ref": "#/components/schemas/pages_DocV2_estiloSecao"
      },
      "colunas": {
        "type": "array",
        "minItems": 1,
        "maxItems": 12,
        "items": {
          "$ref": "#/components/schemas/pages_DocV2_coluna"
        }
      }
    }
  },
  "pages_DocV2_coluna": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "id",
      "itens"
    ],
    "properties": {
      "id": {
        "$ref": "#/components/schemas/pages_DocV2_id"
      },
      "largura": {
        "type": "integer",
        "minimum": 0,
        "maximum": 12
      },
      "alinhamento_vertical": {
        "type": "string",
        "enum": [
          "topo",
          "centro",
          "base",
          "esticar"
        ]
      },
      "alinhamento_horizontal": {
        "type": "string",
        "enum": [
          "inicio",
          "centro",
          "fim",
          "esticar"
        ]
      },
      "gap": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "estilo": {
        "$ref": "#/components/schemas/pages_DocV2_estiloCaixa"
      },
      "itens": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/pages_DocV2_item"
        }
      }
    }
  },
  "pages_DocV2_item": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "id",
      "tipo",
      "props"
    ],
    "properties": {
      "id": {
        "$ref": "#/components/schemas/pages_DocV2_id"
      },
      "tipo": {
        "enum": [
          "titulo",
          "texto",
          "imagem",
          "botao",
          "tags",
          "links",
          "cartoes",
          "abas",
          "acordeao",
          "redes",
          "menu",
          "formulario",
          "video",
          "divisor",
          "espacador",
          "icone",
          "selo",
          "contador",
          "marca",
          "html"
        ]
      },
      "props": {
        "type": "object"
      },
      "estilo": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "margem": {
            "$ref": "#/components/schemas/pages_DocV2_lados"
          },
          "alinhamento": {
            "type": "string",
            "enum": [
              "herdar",
              "inicio",
              "centro",
              "fim"
            ]
          },
          "largura_max": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2400
          },
          "cor_texto": {
            "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
          },
          "subir": {
            "type": "integer",
            "minimum": 0,
            "maximum": 200
          }
        }
      },
      "ocultar_em": {
        "type": "array",
        "uniqueItems": true,
        "items": {
          "enum": [
            "computador",
            "tablet",
            "celular"
          ]
        }
      }
    },
    "allOf": [
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "titulo"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_titulo"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "texto"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_texto"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "imagem"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_imagem"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "botao"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_botao"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "tags"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_tags"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "links"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_links"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "cartoes"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_cartoes"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "abas"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_abas"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "acordeao"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_acordeao"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "redes"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_redes"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "menu"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_menu"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "formulario"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_formulario"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "video"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_video"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "divisor"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_divisor"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "espacador"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_espacador"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "icone"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_icone"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "selo"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_selo"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "contador"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_contador"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "marca"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_marca"
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "tipo": {
              "const": "html"
            }
          }
        },
        "then": {
          "properties": {
            "props": {
              "$ref": "#/components/schemas/pages_DocV2_props_html"
            }
          }
        }
      }
    ]
  },
  "pages_DocV2_props_titulo": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "texto": {
        "type": "string",
        "maxLength": 300
      },
      "nivel": {
        "type": "integer",
        "minimum": 1,
        "maximum": 6
      },
      "tamanho": {
        "type": "string",
        "enum": [
          "auto",
          "p",
          "m",
          "g",
          "gg"
        ]
      },
      "transformar": {
        "type": "string",
        "enum": [
          "nenhum",
          "caixa_alta",
          "caixa_baixa",
          "capitalizar"
        ]
      },
      "espacamento": {
        "type": "integer",
        "minimum": 0,
        "maximum": 6
      },
      "destaque_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      }
    }
  },
  "pages_DocV2_props_texto": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "texto": {
        "type": "string",
        "maxLength": 20000
      },
      "variante": {
        "type": "string",
        "enum": [
          "normal",
          "suave",
          "destaque",
          "citacao"
        ]
      },
      "tamanho": {
        "type": "string",
        "enum": [
          "auto",
          "p",
          "m",
          "g",
          "gg"
        ]
      },
      "transformar": {
        "type": "string",
        "enum": [
          "nenhum",
          "caixa_alta",
          "caixa_baixa",
          "capitalizar"
        ]
      },
      "espacamento": {
        "type": "integer",
        "minimum": 0,
        "maximum": 6
      },
      "destaque_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      }
    }
  },
  "pages_DocV2_props_imagem": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "url": {
        "$ref": "#/components/schemas/pages_DocV2_urlMidia"
      },
      "alt": {
        "type": "string",
        "maxLength": 300
      },
      "link": {
        "$ref": "#/components/schemas/pages_DocV2_urlLink"
      },
      "forma": {
        "type": "string",
        "enum": [
          "normal",
          "arredondada",
          "circulo"
        ]
      },
      "largura": {
        "type": "integer",
        "minimum": 16,
        "maximum": 2400
      },
      "proporcao": {
        "type": "string",
        "enum": [
          "auto",
          "1:1",
          "4:3",
          "3:4",
          "16:9",
          "9:16"
        ]
      },
      "ajuste": {
        "type": "string",
        "enum": [
          "cobrir",
          "conter"
        ]
      },
      "borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "sombra": {
        "type": "string",
        "enum": [
          "nenhuma",
          "leve",
          "forte"
        ]
      },
      "cor_fundo": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "padding": {
        "type": "integer",
        "minimum": 0,
        "maximum": 40
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "link_rastreio": {
        "$ref": "#/components/schemas/pages_DocV2_rastreio"
      }
    }
  },
  "pages_DocV2_props_botao": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "rotulo": {
        "type": "string",
        "maxLength": 300
      },
      "transformar": {
        "type": "string",
        "enum": [
          "nenhum",
          "caixa_alta",
          "caixa_baixa",
          "capitalizar"
        ]
      },
      "espacamento": {
        "type": "integer",
        "minimum": 0,
        "maximum": 6
      },
      "url": {
        "$ref": "#/components/schemas/pages_DocV2_urlLink"
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "variante": {
        "type": "string",
        "enum": [
          "solido",
          "contorno",
          "texto"
        ]
      },
      "tamanho": {
        "type": "string",
        "enum": [
          "p",
          "m",
          "g"
        ]
      },
      "largura_total": {
        "type": "boolean"
      },
      "nova_aba": {
        "type": "boolean"
      },
      "cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "padding_v": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "padding_h": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "fonte_peso": {
        "type": "string",
        "enum": [
          "400",
          "500",
          "600",
          "700",
          "800"
        ]
      },
      "fonte_tamanho": {
        "type": "integer",
        "minimum": 10,
        "maximum": 72
      },
      "sombra": {
        "type": "string",
        "enum": [
          "nenhuma",
          "leve",
          "forte"
        ]
      },
      "icone": {
        "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
      },
      "icone_dir": {
        "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
      },
      "hover_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "vidro": {
        "type": "boolean"
      },
      "vidro_opacidade": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      },
      "vidro_desfoque": {
        "type": "integer",
        "minimum": 0,
        "maximum": 40
      },
      "vidro_saturacao": {
        "type": "integer",
        "minimum": 100,
        "maximum": 200
      },
      "icone_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "icone_dir_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_dir_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_dir_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_icone_inicio": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_icone_fim": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "imagem": {
        "$ref": "#/components/schemas/pages_DocV2_urlMidia"
      },
      "imagem_alt": {
        "type": "string",
        "maxLength": 300
      },
      "imagem_posicao": {
        "type": "string",
        "enum": [
          "inicio",
          "fim",
          "topo"
        ]
      },
      "imagem_tamanho": {
        "type": "string",
        "enum": [
          "p",
          "m",
          "g"
        ]
      },
      "imagem_forma": {
        "type": "string",
        "enum": [
          "quadrada",
          "arredondada",
          "circulo"
        ]
      },
      "icone_img": {
        "$ref": "#/components/schemas/pages_DocV2_urlMidia"
      },
      "icone_dir_img": {
        "$ref": "#/components/schemas/pages_DocV2_urlMidia"
      },
      "url_rastreio": {
        "$ref": "#/components/schemas/pages_DocV2_rastreio"
      }
    }
  },
  "pages_DocV2_props_links": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "titulo": {
              "type": "string",
              "maxLength": 300
            },
            "texto": {
              "type": "string",
              "maxLength": 300
            },
            "url": {
              "$ref": "#/components/schemas/pages_DocV2_urlLink"
            },
            "icone": {
              "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
            },
            "icone_img": {
              "$ref": "#/components/schemas/pages_DocV2_urlMidia"
            },
            "icone_dir": {
              "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
            },
            "icone_dir_img": {
              "$ref": "#/components/schemas/pages_DocV2_urlMidia"
            },
            "destaque": {
              "type": "boolean"
            },
            "nova_aba": {
              "type": "boolean"
            },
            "cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_texto": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_borda": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_texto": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_borda": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "raio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200
            },
            "borda": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            },
            "padding_v": {
              "type": "integer",
              "minimum": 0,
              "maximum": 400
            },
            "padding_h": {
              "type": "integer",
              "minimum": 0,
              "maximum": 400
            },
            "fonte_peso": {
              "type": "string",
              "enum": [
                "400",
                "500",
                "600",
                "700",
                "800"
              ]
            },
            "fonte_tamanho": {
              "type": "integer",
              "minimum": 10,
              "maximum": 72
            },
            "sombra": {
              "type": "string",
              "enum": [
                "nenhuma",
                "leve",
                "forte"
              ]
            },
            "vidro": {
              "type": "boolean"
            },
            "vidro_opacidade": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            },
            "vidro_desfoque": {
              "type": "integer",
              "minimum": 0,
              "maximum": 40
            },
            "vidro_saturacao": {
              "type": "integer",
              "minimum": 100,
              "maximum": 200
            },
            "icone_fundo": {
              "type": "string",
              "enum": [
                "nenhum",
                "circulo",
                "quadrado"
              ]
            },
            "icone_fundo_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "icone_fundo_tamanho": {
              "type": "integer",
              "minimum": 24,
              "maximum": 72
            },
            "icone_dir_fundo": {
              "type": "string",
              "enum": [
                "nenhum",
                "circulo",
                "quadrado"
              ]
            },
            "icone_dir_fundo_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "icone_dir_fundo_tamanho": {
              "type": "integer",
              "minimum": 24,
              "maximum": 72
            },
            "cor_icone": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_icone_inicio": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_icone_fim": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_icone": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "imagem": {
              "$ref": "#/components/schemas/pages_DocV2_urlMidia"
            },
            "imagem_alt": {
              "type": "string",
              "maxLength": 300
            },
            "imagem_posicao": {
              "type": "string",
              "enum": [
                "inicio",
                "fim",
                "topo"
              ]
            },
            "imagem_tamanho": {
              "type": "string",
              "enum": [
                "p",
                "m",
                "g"
              ]
            },
            "imagem_forma": {
              "type": "string",
              "enum": [
                "quadrada",
                "arredondada",
                "circulo"
              ]
            },
            "url_rastreio": {
              "$ref": "#/components/schemas/pages_DocV2_rastreio"
            }
          }
        }
      },
      "estilo": {
        "type": "string",
        "enum": [
          "cartao",
          "preenchido",
          "contorno",
          "fantasma",
          "suave",
          "sombra"
        ]
      },
      "tamanho": {
        "type": "string",
        "enum": [
          "p",
          "m",
          "g"
        ]
      },
      "largura": {
        "type": "string",
        "enum": [
          "total",
          "conteudo"
        ]
      },
      "alinhamento_texto": {
        "type": "string",
        "enum": [
          "centro",
          "inicio"
        ]
      },
      "efeito": {
        "type": "string",
        "enum": [
          "elevar",
          "escala",
          "brilho",
          "fundo",
          "sublinhado",
          "nenhum"
        ]
      },
      "efeito_icone": {
        "type": "string",
        "enum": [
          "nenhum",
          "deslizar",
          "destacar",
          "girar"
        ]
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "espaco": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "vidro": {
        "type": "boolean"
      },
      "vidro_opacidade": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      },
      "vidro_desfoque": {
        "type": "integer",
        "minimum": 0,
        "maximum": 40
      },
      "vidro_saturacao": {
        "type": "integer",
        "minimum": 100,
        "maximum": 200
      },
      "icone_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "icone_dir_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_dir_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_dir_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "cor_icone_inicio": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_icone_fim": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "tamanho_icone": {
        "type": "integer",
        "minimum": 12,
        "maximum": 64
      }
    }
  },
  "pages_DocV2_props_tags": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "texto": {
              "type": "string",
              "maxLength": 60
            },
            "icone": {
              "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
            },
            "url": {
              "$ref": "#/components/schemas/pages_DocV2_urlLink"
            },
            "nova_aba": {
              "type": "boolean"
            },
            "cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_texto": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_borda": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_texto": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_borda": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "raio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200
            },
            "borda": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            },
            "padding_v": {
              "type": "integer",
              "minimum": 0,
              "maximum": 400
            },
            "padding_h": {
              "type": "integer",
              "minimum": 0,
              "maximum": 400
            },
            "fonte_peso": {
              "type": "string",
              "enum": [
                "400",
                "500",
                "600",
                "700",
                "800"
              ]
            },
            "fonte_tamanho": {
              "type": "integer",
              "minimum": 10,
              "maximum": 72
            },
            "sombra": {
              "type": "string",
              "enum": [
                "nenhuma",
                "leve",
                "forte"
              ]
            },
            "vidro": {
              "type": "boolean"
            },
            "vidro_opacidade": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            },
            "vidro_desfoque": {
              "type": "integer",
              "minimum": 0,
              "maximum": 40
            },
            "vidro_saturacao": {
              "type": "integer",
              "minimum": 100,
              "maximum": 200
            },
            "icone_fundo": {
              "type": "string",
              "enum": [
                "nenhum",
                "circulo",
                "quadrado"
              ]
            },
            "icone_fundo_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "icone_fundo_tamanho": {
              "type": "integer",
              "minimum": 24,
              "maximum": 72
            },
            "icone_dir_fundo": {
              "type": "string",
              "enum": [
                "nenhum",
                "circulo",
                "quadrado"
              ]
            },
            "icone_dir_fundo_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "icone_dir_fundo_tamanho": {
              "type": "integer",
              "minimum": 24,
              "maximum": 72
            },
            "cor_icone": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_icone": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "imagem": {
              "$ref": "#/components/schemas/pages_DocV2_urlMidia"
            },
            "imagem_alt": {
              "type": "string",
              "maxLength": 300
            },
            "imagem_posicao": {
              "type": "string",
              "enum": [
                "inicio",
                "fim",
                "topo"
              ]
            },
            "imagem_tamanho": {
              "type": "string",
              "enum": [
                "p",
                "m",
                "g"
              ]
            },
            "imagem_forma": {
              "type": "string",
              "enum": [
                "quadrada",
                "arredondada",
                "circulo"
              ]
            },
            "icone_img": {
              "$ref": "#/components/schemas/pages_DocV2_urlMidia"
            },
            "icone_dir_img": {
              "$ref": "#/components/schemas/pages_DocV2_urlMidia"
            },
            "cor_icone_inicio": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "url_rastreio": {
              "$ref": "#/components/schemas/pages_DocV2_rastreio"
            }
          }
        }
      },
      "preset": {
        "type": "string",
        "enum": [
          "translucido",
          "solido",
          "contorno"
        ]
      },
      "icone": {
        "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
      },
      "cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "vidro": {
        "type": "boolean"
      },
      "vidro_opacidade": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      },
      "vidro_desfoque": {
        "type": "integer",
        "minimum": 0,
        "maximum": 40
      },
      "vidro_saturacao": {
        "type": "integer",
        "minimum": 100,
        "maximum": 200
      },
      "icone_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "icone_dir_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_dir_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_dir_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "hover_cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "tamanho_icone": {
        "type": "integer",
        "minimum": 10,
        "maximum": 48
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "padding_v": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "padding_h": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "fonte_peso": {
        "type": "string",
        "enum": [
          "400",
          "500",
          "600",
          "700",
          "800"
        ]
      },
      "fonte_tamanho": {
        "type": "integer",
        "minimum": 10,
        "maximum": 72
      },
      "gap": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "alinhamento": {
        "type": "string",
        "enum": [
          "inicio",
          "centro",
          "fim"
        ]
      },
      "quebra": {
        "type": "string",
        "enum": [
          "quebrar",
          "linha"
        ]
      }
    }
  },
  "pages_DocV2_props_cartoes": {
    "description": "Galeria de cartões (L2): foto + título/texto/tag/ícone + link, em grade, carrossel ou lista. Tudo opcional; ausente = o desenho padrão.",
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "img": {
              "$ref": "#/components/schemas/pages_DocV2_urlMidia"
            },
            "alt": {
              "type": "string",
              "maxLength": 300
            },
            "titulo": {
              "type": "string",
              "maxLength": 300
            },
            "texto": {
              "type": "string",
              "maxLength": 300
            },
            "tag": {
              "type": "string",
              "maxLength": 60
            },
            "icone": {
              "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
            },
            "url": {
              "$ref": "#/components/schemas/pages_DocV2_urlLink"
            },
            "nova_aba": {
              "type": "boolean"
            },
            "rotacao": {
              "type": "integer",
              "minimum": -15,
              "maximum": 15
            },
            "cor_fim": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "angulo": {
              "type": "integer",
              "minimum": 0,
              "maximum": 360
            },
            "cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_texto": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "cor_borda": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_texto": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_borda": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "raio": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200
            },
            "borda": {
              "type": "integer",
              "minimum": 0,
              "maximum": 20
            },
            "padding_v": {
              "type": "integer",
              "minimum": 0,
              "maximum": 400
            },
            "padding_h": {
              "type": "integer",
              "minimum": 0,
              "maximum": 400
            },
            "fonte_peso": {
              "type": "string",
              "enum": [
                "400",
                "500",
                "600",
                "700",
                "800"
              ]
            },
            "fonte_tamanho": {
              "type": "integer",
              "minimum": 10,
              "maximum": 72
            },
            "sombra": {
              "type": "string",
              "enum": [
                "nenhuma",
                "leve",
                "forte"
              ]
            },
            "cor_icone": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "hover_cor_icone": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "vidro": {
              "type": "boolean"
            },
            "vidro_opacidade": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            },
            "vidro_desfoque": {
              "type": "integer",
              "minimum": 0,
              "maximum": 40
            },
            "vidro_saturacao": {
              "type": "integer",
              "minimum": 100,
              "maximum": 200
            },
            "icone_fundo": {
              "type": "string",
              "enum": [
                "nenhum",
                "circulo",
                "quadrado"
              ]
            },
            "icone_fundo_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "icone_fundo_tamanho": {
              "type": "integer",
              "minimum": 24,
              "maximum": 72
            },
            "icone_dir_fundo": {
              "type": "string",
              "enum": [
                "nenhum",
                "circulo",
                "quadrado"
              ]
            },
            "icone_dir_fundo_cor": {
              "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
            },
            "icone_dir_fundo_tamanho": {
              "type": "integer",
              "minimum": 24,
              "maximum": 72
            },
            "url_rastreio": {
              "$ref": "#/components/schemas/pages_DocV2_rastreio"
            }
          }
        }
      },
      "layout": {
        "type": "string",
        "enum": [
          "grade",
          "carrossel",
          "lista"
        ]
      },
      "colunas": {
        "type": "integer",
        "minimum": 1,
        "maximum": 4
      },
      "largura_cartao": {
        "type": "integer",
        "minimum": 96,
        "maximum": 400
      },
      "proporcao": {
        "type": "string",
        "enum": [
          "auto",
          "1:1",
          "4:3",
          "3:4",
          "16:9",
          "9:16",
          "4:5"
        ]
      },
      "ajuste": {
        "type": "string",
        "enum": [
          "cobrir",
          "conter"
        ]
      },
      "legenda": {
        "type": "string",
        "enum": [
          "abaixo",
          "sobre",
          "nenhuma"
        ]
      },
      "miniatura": {
        "type": "integer",
        "minimum": 56,
        "maximum": 96
      },
      "forma_miniatura": {
        "type": "string",
        "enum": [
          "quadrada",
          "arredondada",
          "circulo"
        ]
      },
      "moldura": {
        "type": "string",
        "enum": [
          "nenhuma",
          "polaroid"
        ]
      },
      "inclinar": {
        "type": "integer",
        "minimum": 0,
        "maximum": 12
      },
      "rotulo": {
        "type": "string",
        "maxLength": 300
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_sup_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_dir": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "raio_inf_esq": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "sombra": {
        "type": "string",
        "enum": [
          "nenhuma",
          "leve",
          "forte"
        ]
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "gap": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "efeito": {
        "type": "string",
        "enum": [
          "elevar",
          "escala",
          "brilho",
          "nenhum"
        ]
      },
      "alinhamento_texto": {
        "type": "string",
        "enum": [
          "centro",
          "inicio"
        ]
      },
      "tamanho_icone": {
        "type": "integer",
        "minimum": 12,
        "maximum": 64
      },
      "cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "vidro": {
        "type": "boolean"
      },
      "vidro_opacidade": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100
      },
      "vidro_desfoque": {
        "type": "integer",
        "minimum": 0,
        "maximum": 40
      },
      "vidro_saturacao": {
        "type": "integer",
        "minimum": 100,
        "maximum": 200
      },
      "icone_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "icone_dir_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_dir_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_dir_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      }
    }
  },
  "pages_DocV2_props_abas": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "titulo": {
              "type": "string",
              "maxLength": 200
            },
            "itens": {
              "$ref": "#/components/schemas/pages_DocV2_itensDePainel"
            }
          }
        }
      },
      "aberta": {
        "type": "integer",
        "minimum": 0,
        "maximum": 19
      },
      "rotulo": {
        "type": "string",
        "maxLength": 300
      },
      "estilo": {
        "type": "string",
        "enum": [
          "linha",
          "pilula",
          "cartao"
        ]
      },
      "alinhamento": {
        "type": "string",
        "enum": [
          "inicio",
          "centro",
          "fim",
          "esticar"
        ]
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_ativa": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto_ativa": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_borda_ativa": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "padding_v": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "padding_h": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "fonte_peso": {
        "type": "string",
        "enum": [
          "400",
          "500",
          "600",
          "700",
          "800"
        ]
      },
      "fonte_tamanho": {
        "type": "integer",
        "minimum": 10,
        "maximum": 72
      },
      "gap": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "painel_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "painel_cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "painel_cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "painel_borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "painel_raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "painel_padding": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      }
    }
  },
  "pages_DocV2_props_acordeao": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "titulo": {
              "type": "string",
              "maxLength": 200
            },
            "aberto": {
              "type": "boolean"
            },
            "itens": {
              "$ref": "#/components/schemas/pages_DocV2_itensDePainel"
            }
          }
        }
      },
      "um_por_vez": {
        "type": "boolean"
      },
      "faq": {
        "type": "boolean"
      },
      "nivel": {
        "type": "integer",
        "minimum": 2,
        "maximum": 6
      },
      "estilo": {
        "type": "string",
        "enum": [
          "cartao",
          "linha",
          "simples"
        ]
      },
      "indicador": {
        "type": "string",
        "enum": [
          "seta",
          "mais",
          "nenhum"
        ]
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_borda": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_aberto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "cor_texto_aberto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "hover_cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 200
      },
      "borda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 20
      },
      "padding_v": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "padding_h": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "fonte_peso": {
        "type": "string",
        "enum": [
          "400",
          "500",
          "600",
          "700",
          "800"
        ]
      },
      "fonte_tamanho": {
        "type": "integer",
        "minimum": 10,
        "maximum": 72
      },
      "gap": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "painel_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "painel_cor_texto": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "painel_padding": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      }
    }
  },
  "pages_DocV2_itensDePainel": {
    "description": "Itens aninhados de um painel de abas/acordeão (ADR-0109): objetos `item` dos tipos permitidos em painel (nunca abas, acordeao, html nem formulario); `props` obrigatório. A conferência de id único e de props de cada item é a do `item`.",
    "type": "array",
    "maxItems": 20,
    "items": {
      "$ref": "#/components/schemas/pages_DocV2_item",
      "required": [
        "id",
        "tipo",
        "props"
      ],
      "properties": {
        "tipo": {
          "enum": [
            "titulo",
            "texto",
            "imagem",
            "botao",
            "tags",
            "links",
            "cartoes",
            "redes",
            "menu",
            "video",
            "divisor",
            "espacador",
            "icone",
            "selo",
            "contador",
            "marca"
          ]
        }
      }
    }
  },
  "pages_DocV2_props_redes": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "rede": {
              "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
            },
            "url": {
              "$ref": "#/components/schemas/pages_DocV2_urlLink"
            },
            "url_rastreio": {
              "$ref": "#/components/schemas/pages_DocV2_rastreio"
            }
          }
        }
      },
      "tamanho": {
        "type": "string",
        "enum": [
          "p",
          "m",
          "g"
        ]
      },
      "cor_icone": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      },
      "icone_dir_fundo": {
        "type": "string",
        "enum": [
          "nenhum",
          "circulo",
          "quadrado"
        ]
      },
      "icone_dir_fundo_cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "icone_dir_fundo_tamanho": {
        "type": "integer",
        "minimum": 24,
        "maximum": 72
      }
    }
  },
  "pages_DocV2_props_menu": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "itens": {
        "type": "array",
        "maxItems": 50,
        "items": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "rotulo": {
              "type": "string",
              "maxLength": 300
            },
            "url": {
              "$ref": "#/components/schemas/pages_DocV2_urlLink"
            },
            "url_rastreio": {
              "$ref": "#/components/schemas/pages_DocV2_rastreio"
            }
          }
        }
      },
      "orientacao": {
        "type": "string",
        "enum": [
          "horizontal",
          "vertical"
        ]
      },
      "colapsar_celular": {
        "type": "boolean"
      }
    }
  },
  "pages_DocV2_props_formulario": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "form_id": {
        "$ref": "#/components/schemas/pages_DocV2_idRefOuVazio"
      },
      "rotulo": {
        "type": "string",
        "maxLength": 300
      }
    }
  },
  "pages_DocV2_props_video": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "url": {
        "$ref": "#/components/schemas/pages_DocV2_urlLink",
        "description": "Embed: sem irmã url_rastreio (o encurtador trocaria o src por um 302)."
      },
      "titulo": {
        "type": "string",
        "maxLength": 300
      }
    }
  },
  "pages_DocV2_props_divisor": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      },
      "espessura": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20
      },
      "estilo": {
        "type": "string",
        "enum": [
          "solida",
          "tracejada",
          "pontilhada"
        ]
      },
      "largura": {
        "type": "integer",
        "minimum": 10,
        "maximum": 100
      }
    }
  },
  "pages_DocV2_props_espacador": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "altura": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      },
      "altura_celular": {
        "type": "integer",
        "minimum": 0,
        "maximum": 400
      }
    }
  },
  "pages_DocV2_props_icone": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "nome": {
        "$ref": "#/components/schemas/pages_DocV2_identOuVazio"
      },
      "tamanho": {
        "type": "integer",
        "minimum": 12,
        "maximum": 256
      },
      "cor": {
        "$ref": "#/components/schemas/pages_DocV2_corOuVazia"
      }
    }
  },
  "pages_DocV2_props_selo": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "texto": {
        "type": "string",
        "maxLength": 300
      }
    }
  },
  "pages_DocV2_props_contador": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "prazo": {
        "type": "string",
        "maxLength": 64
      },
      "rotulo": {
        "type": "string",
        "maxLength": 300
      }
    }
  },
  "pages_DocV2_props_marca": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "mostrar_logo": {
        "type": "boolean"
      },
      "mostrar_nome": {
        "type": "boolean"
      },
      "altura_logo": {
        "type": "integer",
        "minimum": 16,
        "maximum": 200
      }
    }
  },
  "pages_DocV2_props_html": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "html": {
        "type": "string",
        "maxLength": 200000
      }
    }
  },
  "pages_Form": {
    "type": "object",
    "description": "Definição de um formulário — o contrato de campos que a captura valida.",
    "required": [
      "nome",
      "campos"
    ],
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "external_id": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$",
        "description": "Id do formulário no SEU sistema (ex.: o id do formulário do blog). Único por conta entre formulários não apagados (colisão → 409). Na resposta vem sempre que existir. No `PUT /v1/formularios/{id}`, ausente = mantém o atual; presente e diferente = troca, se livre.",
        "example": "blog-contato"
      },
      "nome": {
        "type": "string"
      },
      "campos": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_Campo"
        }
      },
      "exige_consentimento": {
        "type": "boolean"
      },
      "texto_consentimento": {
        "type": "string",
        "maxLength": 500,
        "description": "rótulo da caixa de aceite mostrado ao titular; vazio assume o padrão (\"Concordo em receber comunicações\")"
      },
      "base_legal": {
        "type": "string",
        "default": "consentimento",
        "enum": [
          "consentimento",
          "legitimo_interesse",
          "execucao_contrato",
          "obrigacao_legal"
        ],
        "description": "base legal de tratamento (LGPD, Art. 7); default `consentimento`"
      },
      "origens": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "allowlist de origens do modo snippet (CORS por FORMULÁRIO)"
      },
      "destino_pos_envio": {
        "type": "string",
        "description": "URL para onde levar o visitante depois de enviar"
      },
      "mensagem_pos_envio": {
        "type": "string",
        "description": "texto da tela de agradecimento padrão"
      },
      "restringir_origens": {
        "type": "boolean",
        "description": "liga a trava de sites autorizados (exige ao menos uma origem)"
      },
      "texto_botao": {
        "type": "string",
        "maxLength": 60,
        "description": "texto do botão de envio; vazio = \"Enviar\""
      },
      "layout": {
        "$ref": "#/components/schemas/pages_LayoutFormulario"
      },
      "estilo_botao": {
        "$ref": "#/components/schemas/pages_EstiloBotaoFormulario"
      },
      "janela": {
        "$ref": "#/components/schemas/pages_JanelaFormulario"
      },
      "acoes_agendadas": {
        "type": "array",
        "maxItems": 10,
        "items": {
          "$ref": "#/components/schemas/pages_AcaoAgendada"
        },
        "description": "Ações pós-envio AGENDADAS (até 10): depois do envio, cada ação cuja condição passou sai com atraso ou numa data fixa. O `PUT` substitui o recurso — omitir remove as anteriores. Ação sem `id` ganha um `aag_*` gerado; violações respondem 422 com o campo `acoes_agendadas`. A fila e a execução são do runtime (ADR-0150);"
      }
    }
  },
  "pages_AcaoAgendada": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "canal",
      "quando"
    ],
    "description": "Uma ação pós-envio agendada. Canais (conjunto FECHADO):\n- `email`, `whatsapp`, `sms`: exigem `para` (nome de um campo do formulário,\n do tipo `email` no e-mail e `telefone` no WhatsApp/SMS) e `template`;\n `variaveis` mapeia variável do template para nome de campo.\n- `webhook`, `integracao`: exigem `destino_id` de um destino já declarado do\n MESMO tipo no formulário (webhook: `wh_` + 12 hex do SHA-256 da URL;\n integração: id da instalação `itg_*`); não aceitam `para`, `template` nem `variaveis`.\n`exige_consentimento` assume `true` nos canais de mensagem quando omitido e\nnão pode ser `false` enquanto a `base_legal` do formulário for `consentimento`.\nA condição usa o mesmo formato da dos destinos.",
    "properties": {
      "id": {
        "type": "string",
        "pattern": "^aag_[a-z0-9]{8,32}$",
        "description": "identificador da ação, único no formulário; omitido na entrada, o servidor gera"
      },
      "canal": {
        "type": "string",
        "enum": [
          "email",
          "whatsapp",
          "sms",
          "webhook",
          "integracao"
        ]
      },
      "quando": {
        "$ref": "#/components/schemas/pages_QuandoAcao"
      },
      "condicao": {
        "allOf": [
          {
            "$ref": "#/components/schemas/pages_CondicaoDestino"
          }
        ],
        "description": "QUANDO a ação é enfileirada, julgada no envio; ausente = sempre. Mesmo formato e validação da condição dos destinos"
      },
      "para": {
        "type": "string",
        "description": "nome do campo do formulário com o destinatário (email ou telefone); só nos canais de mensagem"
      },
      "template": {
        "type": "string",
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9_.:-]+$",
        "description": "id do template no canal; obrigatório nos canais de mensagem"
      },
      "variaveis": {
        "type": "object",
        "maxProperties": 20,
        "additionalProperties": {
          "type": "string"
        },
        "description": "variável do template (chave [A-Za-z0-9_]) para nome de campo declarado do formulário"
      },
      "destino_id": {
        "type": "string",
        "description": "webhook/integracao: id de um destino já declarado do mesmo tipo (ver descrição do schema)"
      },
      "exige_consentimento": {
        "type": "boolean",
        "description": "exige o consentimento do titular antes de enviar; omitido vale true em email/whatsapp/sms e false nos demais. A resposta sempre traz o valor"
      }
    }
  },
  "pages_QuandoAcao": {
    "type": "object",
    "description": "Quando a ação sai: informe EXATAMENTE um entre `atraso_min` (relativo ao envio)\ne `em` (data fixa). `em` deve ser futuro no momento do salvamento (a ação\nidêntica já gravada é tolerada) e é normalizado para UTC ao segundo. Ação que\npassa da tolerância de execução (2h) é pulada, nunca disparada atrasada.",
    "oneOf": [
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "atraso_min"
        ],
        "properties": {
          "atraso_min": {
            "type": "integer",
            "minimum": 1,
            "maximum": 525600,
            "description": "minutos depois do envio (1 a 525600, um ano)"
          }
        }
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "em"
        ],
        "properties": {
          "em": {
            "type": "string",
            "format": "date-time",
            "description": "data fixa (RFC 3339, UTC); deve ser futura"
          }
        }
      }
    ]
  },
  "pages_JanelaFormulario": {
    "type": "object",
    "additionalProperties": false,
    "description": "Janela de funcionamento DESTE formulário: quando abre, quando fecha e quantas\nrespostas aceita. Todo campo é opcional; formulário sem `janela` (ou com `{}`)\nfica sempre aberto, como antes. O `PUT` substitui o recurso — omitir o objeto\nremove uma janela anterior. Horários em UTC (RFC 3339), normalizados ao segundo.\nAbertura inclusiva (no instante `abre_em` já está aberto) e fechamento exclusivo\n(no instante `fecha_em` já está encerrado). Fora da janela o runtime responde\n410 Gone (RFC 9457) e mostra a mensagem correspondente. `fecha_em` deve ser\nposterior a `abre_em`; violações respondem 422 com o campo `janela`.",
    "properties": {
      "abre_em": {
        "type": "string",
        "format": "date-time",
        "description": "instante em que o formulário passa a aceitar respostas; ausente = já aberto"
      },
      "fecha_em": {
        "type": "string",
        "format": "date-time",
        "description": "instante em que o formulário deixa de aceitar respostas; ausente = sem fim. Deve ser posterior a abre_em"
      },
      "max_respostas": {
        "type": "integer",
        "minimum": 1,
        "maximum": 1000000,
        "description": "teto de respostas; atingido, o formulário encerra por limite. Ausente = sem teto"
      },
      "mensagem_fechado": {
        "type": "string",
        "maxLength": 500,
        "description": "texto mostrado ao visitante quando o formulário está encerrado (data ou limite); texto simples, escapado na renderização"
      },
      "mensagem_antes": {
        "type": "string",
        "maxLength": 500,
        "description": "texto mostrado ao visitante antes da abertura; texto simples, escapado na renderização"
      }
    }
  },
  "pages_EstiloBotaoFormulario": {
    "type": "object",
    "additionalProperties": false,
    "description": "Personalização do botão de envio DESTE formulário, por cima do kit de marca (`--asf-cor`, `--asf-raio`). Todo campo é opcional e ausente HERDA o kit/padrão: formulário sem `estilo_botao` (ou com `{}`) renderiza exatamente como antes. O `PUT` substitui o recurso — omitir o objeto limpa uma personalização anterior. Cores só `#rrggbb` (`#rgb` é aceito e normalizado para 6 dígitos minúsculos); qualquer valor fora do domínio responde 422 com o campo culpado, sem ecoar o valor. O servidor valida só o DOMÍNIO — o contraste texto x fundo (< 4.5:1) é aviso do editor e não bloqueia o salvar. `gradienteAte` só vale com `estilo: gradiente` e `alinhamento` só com `largura: auto`; fora disso são aceitos e ignorados. No snippet publicado vira um bloco `<style>` escopado ao formulário (sem `style=\"\"` inline).",
    "properties": {
      "estilo": {
        "type": "string",
        "enum": [
          "solido",
          "contorno",
          "fantasma",
          "gradiente"
        ]
      },
      "cor": {
        "type": "string",
        "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
        "description": "fundo/cor principal"
      },
      "corTexto": {
        "type": "string",
        "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
      },
      "corBorda": {
        "type": "string",
        "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"
      },
      "larguraBorda": {
        "type": "integer",
        "minimum": 0,
        "maximum": 8,
        "description": "px"
      },
      "gradienteAte": {
        "type": "string",
        "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$",
        "description": "2ª cor; só estilo gradiente (ausente deriva da principal)"
      },
      "raio": {
        "type": "integer",
        "minimum": 0,
        "maximum": 40,
        "description": "px; 0 = quadrado"
      },
      "altura": {
        "type": "string",
        "enum": [
          "p",
          "m",
          "g"
        ],
        "description": "36 / 44 / 52 px"
      },
      "largura": {
        "type": "string",
        "enum": [
          "total",
          "auto"
        ]
      },
      "alinhamento": {
        "type": "string",
        "enum": [
          "esquerda",
          "centro",
          "direita"
        ],
        "description": "só vale com largura auto (padrão esquerda)"
      },
      "peso": {
        "type": "string",
        "enum": [
          "normal",
          "semibold",
          "bold"
        ]
      },
      "sombra": {
        "type": "boolean"
      },
      "textoMaiusculo": {
        "type": "boolean"
      }
    }
  },
  "pages_LayoutFormulario": {
    "type": "object",
    "description": "Disposição dos campos em linhas de 1 a 4 colunas iguais (schema v2). Só POSICIONA — a validação continua sendo a de `campos`. Ausente = legado: uma coluna por linha na ordem de `campos`. Na escrita, todo campo aparece exatamente uma vez e nenhum nome desconhecido é aceito (422). Linha sem campo é descartada; coluna vazia é permitida (espaço reservado). O PUT substitui o recurso: omitir o layout volta ao legado.",
    "required": [
      "versao",
      "linhas"
    ],
    "properties": {
      "versao": {
        "type": "integer",
        "enum": [
          2
        ]
      },
      "linhas": {
        "type": "array",
        "maxItems": 60,
        "items": {
          "type": "object",
          "required": [
            "colunas"
          ],
          "properties": {
            "colunas": {
              "type": "array",
              "minItems": 1,
              "maxItems": 4,
              "items": {
                "type": "object",
                "required": [
                  "campos"
                ],
                "properties": {
                  "campos": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "nomes dos campos, empilhados"
                  }
                }
              }
            }
          }
        }
      }
    },
    "example": {
      "versao": 2,
      "linhas": [
        {
          "colunas": [
            {
              "campos": [
                "nome"
              ]
            },
            {
              "campos": [
                "sobrenome"
              ]
            }
          ]
        },
        {
          "colunas": [
            {
              "campos": [
                "email"
              ]
            }
          ]
        }
      ]
    }
  },
  "pages_FormDetalhe": {
    "type": "object",
    "description": "O formulário publicado, os embeds prontos e o rascunho pendente do editor.",
    "properties": {
      "formulario": {
        "$ref": "#/components/schemas/pages_Form"
      },
      "snippet": {
        "type": "string",
        "description": "HTML completo do embed"
      },
      "snippet_js": {
        "type": "string",
        "description": "linha de <script> que carrega o embed atual"
      },
      "endpoint": {
        "type": "string"
      },
      "endpoint_api": {
        "type": "string"
      },
      "rascunho": {
        "type": "object",
        "nullable": true,
        "description": "corpo do PUT salvo sem publicar (`null` = nada pendente)"
      },
      "rascunho_em": {
        "type": "string",
        "format": "date-time",
        "nullable": true
      }
    }
  },
  "pages_Campo": {
    "type": "object",
    "description": "Um campo declarado do formulário. Submissão de campo não declarado é RECUSADA.",
    "required": [
      "nome",
      "tipo"
    ],
    "properties": {
      "nome": {
        "type": "string",
        "description": "nome técnico (chave da submissão)"
      },
      "chave": {
        "type": "string",
        "description": "chave do catálogo de campos nativos (ex.: `empresa`, `cargo`) — liga o campo ao atributo correspondente do contato no CRM"
      },
      "rotulo": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "texto",
          "texto_longo",
          "email",
          "telefone",
          "numero",
          "booleano",
          "opcao",
          "data",
          "cpf",
          "cnpj",
          "cep",
          "url",
          "pais",
          "oculto",
          "endereco",
          "agendamento"
        ]
      },
      "obrigatorio": {
        "type": "boolean"
      },
      "opcoes": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "valores aceitos quando `tipo=opcao`"
      },
      "marcado_padrao": {
        "type": "boolean",
        "description": "caixa de seleção (`booleano`) já marcada; padrão false; recusado na caixa de consentimento (LGPD)"
      },
      "valor_marcado": {
        "type": "string",
        "maxLength": 100,
        "description": "caixa de seleção: valor enviado quando marcada (vazio = \"true\"); não pode ser uma forma de \"não\""
      },
      "consentimento": {
        "type": "boolean",
        "description": "Esta caixa de seleção É o consentimento de comunicações (opt-in do contato): não vira atributo do lead, vira o `consentimento` do evento com o texto da caixa e a `base_legal` do formulário. No máximo uma por formulário. O rótulo de uma caixa aceita link no formato `[texto](https://…)`. Formulário antigo com `exige_consentimento` é LIDO com esta caixa (nome `consentimento`) no fim dos campos."
      },
      "endereco": {
        "$ref": "#/components/schemas/pages_ConfigEndereco"
      },
      "agendamento": {
        "$ref": "#/components/schemas/pages_ConfigAgendamento"
      }
    }
  },
  "pages_ConfigAgendamento": {
    "type": "object",
    "description": "Configuração do campo de AGENDAMENTO (só no `tipo=agendamento`; obrigatória nele, recusada nos outros tipos). O visitante escolhe um horário livre da agenda; o valor submetido é o INÍCIO do horário, instante RFC 3339 normalizado para UTC com precisão de segundo (`2026-12-01T13:00:00Z`) — o runtime reserva o horário na submissão. No máximo UM campo de agendamento por formulário; não alimenta chave do catálogo nativo; aceita `condicao`. Ao salvar, a agenda é conferida no serviço Agenda (deve existir na conta e estar ativa: 422 `agenda-inexistente`/`agenda-inativa`; serviço fora do ar: 503 `agenda-indisponivel`, só para formulário COM o campo).",
    "required": [
      "agenda_id"
    ],
    "properties": {
      "agenda_id": {
        "type": "string",
        "pattern": "^agd_[0-9a-f]{16}$",
        "example": "agd_0123456789abcdef"
      }
    }
  },
  "pages_AgendaResumo": {
    "type": "object",
    "required": [
      "id",
      "nome",
      "fuso",
      "duracao_min",
      "ativa"
    ],
    "properties": {
      "id": {
        "type": "string",
        "example": "agd_0123456789abcdef"
      },
      "nome": {
        "type": "string"
      },
      "fuso": {
        "type": "string",
        "description": "fuso IANA da agenda",
        "example": "America/Sao_Paulo"
      },
      "duracao_min": {
        "type": "integer"
      },
      "ativa": {
        "type": "boolean"
      }
    }
  },
  "pages_ConfigEndereco": {
    "type": "object",
    "description": "Configuração do widget de ENDEREÇO (só no `tipo=endereco`; mesma forma do `CampoEndereco` do @asender/ui). O campo se abre nas partes, sempre do mais abrangente ao mais específico: país > CEP > estado > cidade > bairro > rua > número + complemento. A submissão manda cada parte como `<nome>.<parte>` (`endereco.cep`…) e o lead grava as mesmas chaves, normalizadas: CEP no formato do país (BR `99999-999`), estado BR como UF (+ `<nome>.estado_nome`). Ausente = os padrões: BR editável, todos os países, CEP/cidade/rua/número obrigatórios. Uma parte do endereço vale como campo de condição do direcional (`endereco.estado = SP`).",
    "properties": {
      "pais": {
        "type": "object",
        "properties": {
          "oculto": {
            "type": "boolean",
            "description": "vai sempre o `padrao` (exige `padrao`)"
          },
          "padrao": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO-2; ausente = BR, ou o primeiro permitido",
            "example": "BR"
          },
          "editavel": {
            "type": "boolean",
            "description": "false = o país aparece mas não se troca (ausente = true)"
          },
          "permitidos": {
            "type": "array",
            "maxItems": 300,
            "items": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            },
            "description": "países aceitos; vazio = todos"
          },
          "rotulo": {
            "type": "string",
            "maxLength": 100
          }
        }
      },
      "cep": {
        "$ref": "#/components/schemas/pages_ConfigParteEndereco"
      },
      "estado": {
        "$ref": "#/components/schemas/pages_ConfigParteEndereco"
      },
      "cidade": {
        "$ref": "#/components/schemas/pages_ConfigParteEndereco"
      },
      "bairro": {
        "$ref": "#/components/schemas/pages_ConfigParteEndereco"
      },
      "rua": {
        "$ref": "#/components/schemas/pages_ConfigParteEndereco"
      },
      "numero": {
        "$ref": "#/components/schemas/pages_ConfigParteEndereco"
      },
      "complemento": {
        "$ref": "#/components/schemas/pages_ConfigParteEndereco"
      }
    }
  },
  "pages_ConfigParteEndereco": {
    "type": "object",
    "properties": {
      "oculto": {
        "type": "boolean",
        "description": "a parte não aparece e não é coletada"
      },
      "obrigatorio": {
        "type": "boolean",
        "description": "ausente = o padrão da parte; oculta nunca é obrigatória"
      },
      "rotulo": {
        "type": "string",
        "maxLength": 100
      }
    }
  },
  "pages_Destino": {
    "type": "object",
    "description": "Um destino de um formulário — para onde a submissão é copiada e como cada campo é mapeado. crm/marketing viajam no evento NATS v2; webhook é despachado localmente pelo runtime (com SSRF-guard, retry e HMAC); integracao vira o comando `integracoes.entrega.solicitada` (ADR-0099) para uma instalação do serviço de Integrações (API própria, Kommo) — a credencial mora lá, nunca aqui. Até 10 integrações por formulário, sem repetir instalação.",
    "required": [
      "tipo"
    ],
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "crm",
          "marketing",
          "webhook",
          "integracao"
        ]
      },
      "ativo": {
        "type": "boolean",
        "description": "destino desligado não dispara, mas guarda o mapa"
      },
      "config": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "webhook: { url, secret? }. marketing: { lista_id?, lista_nome? } (lista lst_…). crm: vazio. integracao: { instalacao_id (itg_…, obrigatório), + as opções por destino do catálogo (Kommo: pipeline_id, status_id, responsavel_id, tags separadas por vírgula) } — até 20 opções, valor ≤ 1024; opção vazia = a da instalação."
      },
      "mapa": {
        "type": "object",
        "additionalProperties": {
          "type": "string",
          "enum": [
            "email",
            "telefone",
            "nome",
            ""
          ]
        },
        "description": "nome_do_campo → alvo canônico ou '' (custom, nunca descartado)"
      },
      "condicao": {
        "$ref": "#/components/schemas/pages_CondicaoDestino"
      },
      "condicao_erro": {
        "type": "string",
        "readOnly": true,
        "description": "Só na leitura: por que a condição gravada não vale mais (campo apagado do formulário, opção removida) ou \"Marketing sem a condição de aceite\". O runtime PULA o destino com esse motivo no trilho do lead — nunca o deixa passar."
      },
      "integracao": {
        "readOnly": true,
        "description": "Só na leitura, destino integracao: o resumo da instalação (do serviço de Integrações).",
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "app": {
            "type": "string",
            "enum": [
              "http",
              "kommo"
            ]
          },
          "app_nome": {
            "type": "string"
          },
          "nome": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "rascunho",
              "ativa",
              "pausada",
              "reautorizar"
            ]
          }
        }
      },
      "integracao_erro": {
        "type": "string",
        "readOnly": true,
        "description": "Só na leitura, destino integracao: por que a instalação não recebe (removida / de outra conta, ou precisa ser reconectada). Ignorado na entrada."
      }
    }
  },
  "pages_CondicaoDestino": {
    "type": "object",
    "nullable": true,
    "description": "QUANDO o destino recebe a submissão (ausente/null = sempre). Avaliada no runtime, a cada submissão. O destino `marketing` só é aceito com uma condição que GARANTA a caixa de aceite marcada (modo `todas`, ou cláusula única) — é o que registra o opt-in; sem ela, 422.",
    "required": [
      "modo",
      "clausulas"
    ],
    "properties": {
      "modo": {
        "type": "string",
        "enum": [
          "todas",
          "qualquer"
        ]
      },
      "clausulas": {
        "type": "array",
        "minItems": 1,
        "maxItems": 20,
        "items": {
          "type": "object",
          "required": [
            "campo",
            "operador"
          ],
          "properties": {
            "campo": {
              "type": "string",
              "description": "nome de um campo do formulário, ou especial: @utm_source, @utm_medium, @utm_campaign, @utm_term, @utm_content, @pagina_url, @referrer"
            },
            "operador": {
              "type": "string",
              "description": "pelo tipo do campo — booleano: marcado|desmarcado; numero: maior|menor|igual; opcao: igual|um_de (valores entre as opções do campo); demais: igual|diferente| contem|vazio|preenchido|um_de",
              "enum": [
                "marcado",
                "desmarcado",
                "igual",
                "diferente",
                "contem",
                "vazio",
                "preenchido",
                "um_de",
                "maior",
                "menor"
              ]
            },
            "valor": {
              "type": "string",
              "maxLength": 500
            },
            "valores": {
              "type": "array",
              "maxItems": 50,
              "items": {
                "type": "string",
                "maxLength": 500
              }
            }
          }
        }
      }
    },
    "example": {
      "modo": "todas",
      "clausulas": [
        {
          "campo": "aceite",
          "operador": "marcado"
        }
      ]
    }
  },
  "pages_PushConvite": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "modo": {
        "type": "string",
        "enum": [
          "barra",
          "botao_flutuante"
        ],
        "default": "barra"
      },
      "texto": {
        "type": "string",
        "minLength": 1,
        "maxLength": 140
      },
      "texto_botao": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40
      },
      "atraso_s": {
        "type": "integer",
        "minimum": 0,
        "maximum": 600,
        "default": 5
      }
    }
  },
  "pages_PushDoDominioEntrada": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "ligado",
      "vapid_public_key",
      "site_key",
      "api_base"
    ],
    "properties": {
      "ligado": {
        "type": "boolean"
      },
      "vapid_public_key": {
        "type": "string",
        "description": "base64url",
        "minLength": 80,
        "maxLength": 100
      },
      "site_key": {
        "type": "string",
        "pattern": "^pk_push_[A-Za-z0-9._~-]{10,500}$"
      },
      "api_base": {
        "type": "string",
        "format": "uri",
        "description": "https",
        "sem caminho": null
      },
      "convite": {
        "$ref": "#/components/schemas/pages_PushConvite"
      }
    }
  },
  "pages_PushDoDominio": {
    "type": "object",
    "required": [
      "ligado"
    ],
    "properties": {
      "ligado": {
        "type": "boolean"
      },
      "vapid_public_key": {
        "type": "string"
      },
      "site_key": {
        "type": "string"
      },
      "api_base": {
        "type": "string"
      },
      "convite": {
        "$ref": "#/components/schemas/pages_PushConvite"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "pages_MoverDominioPedido": {
    "type": "object",
    "required": [
      "dominio_id"
    ],
    "properties": {
      "dominio_id": {
        "type": "string",
        "description": "id do domínio de destino (`GET /v1/dominios`); `\"\"` = host da plataforma",
        "examples": [
          "dom_01J9XYZ"
        ]
      },
      "caminho": {
        "type": "string",
        "pattern": "^([a-z0-9]+(-[a-z0-9]+)*)?$",
        "description": "slug de um segmento; vazio mantém o slug atual",
        "examples": [
          "meu-slug"
        ]
      }
    }
  },
  "pages_MoverDominioResposta": {
    "type": "object",
    "properties": {
      "pagina_id": {
        "type": "string"
      },
      "dominio_id": {
        "type": "string"
      },
      "dominio": {
        "type": "string",
        "description": "host de destino; vazio = host da plataforma"
      },
      "caminho": {
        "type": "string"
      },
      "url_publica": {
        "type": "string"
      },
      "alterado": {
        "type": "boolean",
        "description": "false quando a página já estava nesse endereço"
      },
      "publicada": {
        "type": "boolean"
      },
      "redirecionamento": {
        "type": [
          "object",
          "null"
        ],
        "description": "criado quando a página já foi publicada alguma vez e o endereço mudou; o endereço antigo passa a responder 301",
        "properties": {
          "criado": {
            "type": "boolean"
          },
          "de": {
            "type": "string",
            "examples": [
              "https://antigo.exemplo.com/slug-antigo"
            ]
          }
        }
      }
    }
  },
  "pages_MoverDominioErro": {
    "type": "object",
    "properties": {
      "erro": {
        "type": "string"
      },
      "motivo": {
        "type": "string",
        "enum": [
          "caminho_em_uso",
          "pagina_inicial",
          "dominio_nao_verificado",
          "caminho_invalido"
        ]
      }
    }
  },
  "pages_Dominio": {
    "type": "object",
    "description": "Um domínio da conta, com os 3 passos da tela (plano 2026-10-02 §4.1): posse (TXT), apontamento (CNAME → nome-alvo no subdomínio; ALIAS/ flattening → nome-alvo no principal, com `www` e A/AAAA como caminhos B e C — migration 038) e certificado. `pronto` = os três ok. Os campos planos `registro_txt` e `verificado` seguem por compatibilidade.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "host": {
        "type": "string"
      },
      "tipo": {
        "type": "string",
        "enum": [
          "proprio",
          "gratis"
        ]
      },
      "classe": {
        "type": "string",
        "enum": [
          "principal",
          "subdominio"
        ],
        "description": "pela Public Suffix List"
      },
      "registro_txt": {
        "type": "string",
        "description": "o TXT de posse a publicar no DNS"
      },
      "verificado": {
        "type": "boolean"
      },
      "padrao": {
        "type": "boolean",
        "description": "true no domínio padrão da conta (`apages.xyz`, criado automaticamente); vem primeiro em `GET /v1/dominios`"
      },
      "posse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "registro_txt": {
            "type": "string"
          },
          "token": {
            "type": "string"
          },
          "verificado_em": {
            "type": "string",
            "format": "date-time"
          },
          "erro": {
            "type": "string"
          }
        }
      },
      "apontamento": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "configurado": {
            "type": "boolean",
            "description": "false = o ambiente não tem alvo de apontamento"
          },
          "alvo_cname": {
            "type": "string",
            "examples": [
              "cname.apages.xyz"
            ]
          },
          "esperado": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/pages_RegistroDNS"
            },
            "description": "o caminho recomendado, sempre por NOME: CNAME (subdomínio) ou ALIAS (principal) para `alvo_cname`; A/AAAA só sem nome-alvo configurado"
          },
          "alternativos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/pages_RegistroDNS"
            },
            "description": "ÚLTIMO recurso do principal: A/AAAA da borda (os IPs podem mudar); vazio no subdomínio"
          },
          "www": {
            "type": "object",
            "description": "principal com nome-alvo: publicar em `www.<host>` por CNAME e redirecionar o principal para ele",
            "properties": {
              "host": {
                "type": "string",
                "examples": [
                  "www.loja.com.br"
                ]
              },
              "registros": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pages_RegistroDNS"
                }
              }
            }
          },
          "encontrado": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/pages_RegistroDNS"
            },
            "description": "o que o DNS respondeu na última checagem"
          },
          "metodo": {
            "type": "string",
            "enum": [
              "cname",
              "enderecos"
            ],
            "description": "como o domínio chegou na última checagem; `enderecos` = mesmos IPs do nome-alvo (ALIAS/flattening ou A/AAAA)"
          },
          "diagnosticos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/pages_DiagnosticoDNS"
            }
          },
          "recomenda_cname": {
            "type": "boolean",
            "description": "apontado por IP com nome-alvo disponível: recomendação NÃO bloqueante de migrar para CNAME/ALIAS"
          },
          "deriva_em": {
            "type": "string",
            "format": "date-time",
            "description": "quando o vigia viu o domínio apontado por IP deixar de casar com o nome-alvo (ausente = sem deriva); o domínio segue no ar"
          },
          "deriva": {
            "type": "string"
          },
          "checado_em": {
            "type": "string",
            "format": "date-time"
          },
          "erro": {
            "type": "string"
          }
        }
      },
      "tls": {
        "type": "object",
        "properties": {
          "estado": {
            "type": "string",
            "enum": [
              "pendente",
              "ativo",
              "erro"
            ]
          },
          "expira_em": {
            "type": "string",
            "format": "date-time"
          },
          "erro": {
            "type": "string"
          }
        }
      },
      "pronto": {
        "type": "boolean"
      },
      "pagina_inicial": {
        "description": "A HOME (apex) do domínio — migration 029: qual página responde `GET https://host/`. `null` quando não há home marcada, ou quando a página marcada foi apagada ou saiu deste domínio.",
        "nullable": true,
        "allOf": [
          {
            "$ref": "#/components/schemas/pages_PaginaInicial"
          }
        ]
      }
    }
  },
  "pages_PaginaInicial": {
    "type": "object",
    "description": "Resumo da página marcada como home de um domínio.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "titulo": {
        "type": "string"
      },
      "slug": {
        "type": "string"
      },
      "publicada": {
        "type": "boolean",
        "description": "false = marcada como home mas ainda sem versão publicada"
      }
    }
  },
  "pages_DefinirPaginaInicial": {
    "type": "object",
    "required": [
      "pagina_id"
    ],
    "properties": {
      "pagina_id": {
        "type": "string",
        "format": "uuid",
        "description": "o id público da página da conta; se estiver em outro endereço, é movida para este domínio (mesmo slug)"
      }
    }
  },
  "pages_DiagnosticoDNS": {
    "type": "object",
    "description": "Uma observação precisa do passo 2 (a tela traduz pelo código).",
    "required": [
      "codigo"
    ],
    "properties": {
      "codigo": {
        "type": "string",
        "enum": [
          "cname_outro_alvo",
          "enderecos_outros",
          "enderecos_mistos",
          "proxy_cloudflare",
          "sem_registro",
          "ips_podem_mudar",
          "ttl",
          "deriva"
        ]
      },
      "encontrado": {
        "type": "string",
        "description": "o valor achado (nome ou IPs separados por vírgula)"
      },
      "esperado": {
        "type": "string",
        "description": "o valor esperado (nome-alvo ou IPs atuais dele)"
      },
      "segundos": {
        "type": "integer",
        "description": "o TTL, no código `ttl` (dica de propagação)"
      }
    }
  },
  "pages_RegistroDNS": {
    "type": "object",
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "TXT",
          "CNAME",
          "A",
          "AAAA",
          "ALIAS"
        ]
      },
      "nome": {
        "type": "string"
      },
      "valor": {
        "type": "string"
      }
    }
  },
  "pages_CriarDominio": {
    "type": "object",
    "required": [
      "host"
    ],
    "properties": {
      "host": {
        "type": "string",
        "examples": [
          "lp.empresa.com.br"
        ]
      }
    }
  },
  "pages_Redirect": {
    "type": "object",
    "description": "Um link curto.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "slug": {
        "type": "string"
      },
      "dominio": {
        "type": "string"
      },
      "destino": {
        "type": "string",
        "format": "uri"
      },
      "ativo": {
        "type": "boolean"
      },
      "cliques": {
        "type": "integer",
        "format": "int64",
        "readOnly": true
      }
    }
  },
  "pages_LinkConfigUTM": {
    "type": "object",
    "description": "Etiqueta de campanha que o link põe no destino. `modo` acrescentar = só se ausente; forcar = sobrescreve (e apaga repetições).",
    "properties": {
      "modo": {
        "type": "string",
        "enum": [
          "acrescentar",
          "forcar"
        ],
        "default": "acrescentar"
      },
      "source": {
        "type": "string",
        "maxLength": 200
      },
      "medium": {
        "type": "string",
        "maxLength": 200
      },
      "campaign": {
        "type": "string",
        "maxLength": 200
      },
      "term": {
        "type": "string",
        "maxLength": 200
      },
      "content": {
        "type": "string",
        "maxLength": 200
      }
    }
  },
  "pages_LinkParametros": {
    "type": "object",
    "description": "Pares fixos (até 20) que o link sempre leva ao destino.",
    "properties": {
      "fixos": {
        "type": "object",
        "additionalProperties": {
          "type": "string",
          "maxLength": 500
        }
      },
      "modo_fixos": {
        "type": "string",
        "enum": [
          "acrescentar",
          "forcar"
        ],
        "default": "acrescentar"
      }
    }
  },
  "pages_LinkRepasse": {
    "type": "object",
    "description": "O \"dispatcher\": o que fazer com os parâmetros que CHEGAM no link curto. Ordem: bloquear → lista/todos → renomear; o repassado nunca sobrescreve o destino. Nomes comparados sem caixa.",
    "properties": {
      "modo": {
        "type": "string",
        "enum": [
          "nenhum",
          "todos",
          "lista"
        ],
        "default": "nenhum"
      },
      "lista": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 50
      },
      "renomear": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        }
      },
      "bloquear": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 50
      }
    }
  },
  "pages_LinkEntrada": {
    "type": "object",
    "description": "Corpo de criar/editar link (e da prévia). Campos desconhecidos → 400.",
    "required": [
      "destino"
    ],
    "properties": {
      "destino": {
        "type": "string",
        "format": "uri",
        "maxLength": 2048,
        "description": "http(s) absoluto; sem usuário na URL; não pode ser o próprio encurtador nem endereço interno."
      },
      "titulo": {
        "type": "string",
        "maxLength": 200
      },
      "slug": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9-]{0,63}$",
        "description": "Opcional: <host>/r/<slug>."
      },
      "dominio": {
        "type": "string",
        "description": "Domínio VERIFICADO desta conta (exige slug); vazio = host padrão."
      },
      "ativo": {
        "type": "boolean",
        "default": true
      },
      "status_http": {
        "type": "integer",
        "enum": [
          302,
          307
        ],
        "default": 302
      },
      "utm": {
        "$ref": "#/components/schemas/pages_LinkConfigUTM"
      },
      "parametros": {
        "$ref": "#/components/schemas/pages_LinkParametros"
      },
      "repasse": {
        "$ref": "#/components/schemas/pages_LinkRepasse"
      },
      "origem": {
        "type": "object",
        "description": "Só na criação. `pagina` torna o POST idempotente por (pagina_id, bloco_id, destino).",
        "properties": {
          "tipo": {
            "type": "string",
            "enum": [
              "manual",
              "pagina"
            ]
          },
          "pagina_id": {
            "type": "string"
          },
          "bloco_id": {
            "type": "string"
          }
        }
      }
    }
  },
  "pages_Link": {
    "allOf": [
      {
        "$ref": "#/components/schemas/pages_LinkEntrada"
      },
      {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true
          },
          "codigo": {
            "type": "string",
            "readOnly": true,
            "pattern": "^[0-9abcdefghjkmnpqrstvwxyz]{8}$",
            "description": "Código global (Crockford, CSPRNG); nunca reaproveitado."
          },
          "cliques": {
            "type": "integer",
            "format": "int64",
            "readOnly": true,
            "description": "Cliques de gente (robôs de pré-visualização fora)."
          },
          "url_curta": {
            "type": "string",
            "format": "uri",
            "readOnly": true
          },
          "url_slug": {
            "type": "string",
            "format": "uri",
            "readOnly": true
          },
          "criado_em": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "atualizado_em": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      }
    ]
  },
  "pages_ContagemValorLink": {
    "type": "object",
    "properties": {
      "valor": {
        "type": "string",
        "description": "\"\" = direto / sem etiqueta / não identificado"
      },
      "cliques": {
        "type": "integer",
        "format": "int64"
      }
    }
  },
  "pages_RelatorioLink": {
    "type": "object",
    "description": "Cliques do período, dias em America/Sao_Paulo. Sem IP nem dado pessoal; únicos = visitantes distintos por dia (hash com sal diário).",
    "properties": {
      "de": {
        "type": "string",
        "format": "date"
      },
      "ate": {
        "type": "string",
        "format": "date"
      },
      "total": {
        "type": "integer",
        "format": "int64"
      },
      "unicos": {
        "type": "integer",
        "format": "int64"
      },
      "robos": {
        "type": "integer",
        "format": "int64"
      },
      "por_dia": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "dia": {
              "type": "string",
              "format": "date"
            },
            "cliques": {
              "type": "integer"
            },
            "unicos": {
              "type": "integer"
            }
          }
        }
      },
      "por_origem": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ContagemValorLink"
        }
      },
      "por_dispositivo": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ContagemValorLink"
        }
      },
      "por_pais": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ContagemValorLink"
        }
      },
      "por_utm_source": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ContagemValorLink"
        }
      },
      "por_utm_medium": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ContagemValorLink"
        }
      },
      "por_utm_campaign": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/pages_ContagemValorLink"
        }
      }
    }
  },
  "pages_Marca": {
    "type": "object",
    "description": "Cabeçalho de marca da conta.",
    "properties": {
      "nome_exibicao": {
        "type": "string"
      },
      "logo_url": {
        "type": "string",
        "format": "uri"
      },
      "favicon_url": {
        "type": "string",
        "format": "uri"
      },
      "cor_primaria": {
        "type": "string",
        "description": "cor em hex (ex.: `#b4531f`)"
      }
    }
  },
  "pages_KitMarcaDados": {
    "type": "object",
    "description": "Seções do kit (todas opcionais). Ver `internal/domain/marca`. Imagens só https; cores #rrggbb.",
    "properties": {
      "identidade": {
        "type": "object",
        "properties": {
          "nome_marca": {
            "type": "string",
            "maxLength": 80
          },
          "nome_fantasia": {
            "type": "string",
            "maxLength": 120
          },
          "razao_social": {
            "type": "string",
            "maxLength": 200
          },
          "slogan": {
            "type": "string",
            "maxLength": 120
          },
          "descricao_curta": {
            "type": "string",
            "maxLength": 300
          },
          "descricao_longa": {
            "type": "string",
            "maxLength": 2000
          },
          "logos": {
            "type": "object",
            "properties": {
              "principal": {
                "type": "string",
                "format": "uri"
              },
              "horizontal": {
                "type": "string",
                "format": "uri"
              },
              "icone": {
                "type": "string",
                "format": "uri"
              },
              "escuro": {
                "type": "string",
                "format": "uri"
              },
              "usar_logo_da_empresa": {
                "type": "boolean",
                "description": "referencia o logo da empresa do admin (core), sem copiar"
              }
            }
          },
          "favicon_url": {
            "type": "string",
            "format": "uri"
          },
          "cores": {
            "type": "object",
            "properties": {
              "primaria": {
                "type": "string"
              },
              "secundaria": {
                "type": "string"
              },
              "acento": {
                "type": "string"
              },
              "acento2": {
                "type": "string"
              },
              "fundo": {
                "type": "string"
              },
              "texto": {
                "type": "string"
              }
            }
          },
          "fontes": {
            "type": "object",
            "properties": {
              "titulos": {
                "type": "string"
              },
              "texto": {
                "type": "string"
              }
            }
          }
        }
      },
      "compartilhamento": {
        "type": "object",
        "properties": {
          "imagem_url": {
            "type": "string",
            "format": "uri",
            "description": "recomendado 1200×630"
          },
          "imagem_largura": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "imagem_altura": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "imagem_alt": {
            "type": "string",
            "maxLength": 300
          },
          "site_name": {
            "type": "string",
            "maxLength": 80
          },
          "x_handle": {
            "type": "string",
            "description": "normalizado para @usuario"
          },
          "facebook_app_id": {
            "type": "string",
            "description": "só dígitos"
          },
          "facebook_pagina_url": {
            "type": "string",
            "format": "uri"
          },
          "locale": {
            "type": "string",
            "description": "pt_BR"
          }
        }
      },
      "redes": {
        "type": "object",
        "description": "rede → URL canônica https. Chaves: instagram, x, facebook, linkedin, youtube, tiktok, pinterest, threads, whatsapp (→ wa.me), telegram, github, behance, dribbble, spotify, site. Aceita handle ou URL na entrada.",
        "additionalProperties": {
          "type": "string"
        }
      },
      "contato": {
        "type": "object",
        "properties": {
          "telefones": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "object",
              "properties": {
                "rotulo": {
                  "type": "string"
                },
                "e164": {
                  "type": "string"
                }
              }
            }
          },
          "whatsapp": {
            "type": "string",
            "description": "E.164"
          },
          "emails": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "object",
              "properties": {
                "rotulo": {
                  "type": "string"
                },
                "email": {
                  "type": "string",
                  "format": "email"
                }
              }
            }
          },
          "horario": {
            "type": "string",
            "maxLength": 300
          }
        }
      },
      "enderecos": {
        "type": "object",
        "properties": {
          "comercial": {
            "$ref": "#/components/schemas/pages_KitMarcaEndereco"
          },
          "fiscal": {
            "$ref": "#/components/schemas/pages_KitMarcaEndereco"
          }
        }
      },
      "legal": {
        "type": "object",
        "properties": {
          "documento": {
            "type": "string",
            "description": "CNPJ (inclusive alfanumérico) ou CPF, validado"
          },
          "tipo_documento": {
            "type": "string",
            "enum": [
              "cnpj",
              "cpf",
              ""
            ],
            "readOnly": true
          },
          "inscricao_estadual": {
            "type": "string"
          },
          "inscricao_municipal": {
            "type": "string"
          },
          "privacidade_url": {
            "type": "string",
            "format": "uri"
          },
          "termos_url": {
            "type": "string",
            "format": "uri"
          },
          "dpo_email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "voz": {
        "type": "object",
        "description": "contexto da IA; nunca sai para a página pública",
        "properties": {
          "tom_de_voz": {
            "type": "string",
            "maxLength": 300
          },
          "publico": {
            "type": "string",
            "maxLength": 300
          },
          "palavras_chave": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "type": "string",
              "maxLength": 40
            }
          }
        }
      }
    }
  },
  "pages_KitMarcaEndereco": {
    "type": "object",
    "properties": {
      "logradouro": {
        "type": "string"
      },
      "numero": {
        "type": "string"
      },
      "complemento": {
        "type": "string"
      },
      "bairro": {
        "type": "string"
      },
      "cidade": {
        "type": "string"
      },
      "uf": {
        "type": "string"
      },
      "cep": {
        "type": "string",
        "description": "BR: 00000-000"
      },
      "pais": {
        "type": "string",
        "description": "ISO-3166 alfa-2"
      },
      "latitude": {
        "type": "string"
      },
      "longitude": {
        "type": "string"
      },
      "maps_url": {
        "type": "string",
        "format": "uri"
      }
    }
  },
  "pages_KitMarca": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "nome": {
        "type": "string",
        "maxLength": 60
      },
      "padrao": {
        "type": "boolean"
      },
      "dados": {
        "$ref": "#/components/schemas/pages_KitMarcaDados"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "pages_KitMarcaResumo": {
    "allOf": [
      {
        "$ref": "#/components/schemas/pages_KitMarca"
      },
      {
        "type": "object",
        "properties": {
          "dominios": {
            "type": "integer"
          },
          "paginas": {
            "type": "integer"
          }
        }
      }
    ]
  },
  "pages_KitMarcaPedido": {
    "type": "object",
    "required": [
      "nome"
    ],
    "properties": {
      "nome": {
        "type": "string",
        "maxLength": 60
      },
      "dados": {
        "$ref": "#/components/schemas/pages_KitMarcaDados"
      },
      "duplicar_de": {
        "type": "string",
        "description": "só na criação"
      }
    }
  },
  "pages_KitMarcaVinculoPedido": {
    "type": "object",
    "properties": {
      "kit_id": {
        "type": "string",
        "description": "vazio = volta ao fallback"
      }
    }
  },
  "pages_KitMarcaVinculos": {
    "type": "object",
    "properties": {
      "dominios": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "dominio_id": {
              "type": "string"
            },
            "host": {
              "type": "string"
            },
            "kit_id": {
              "type": "string"
            },
            "kit_nome": {
              "type": "string"
            }
          }
        }
      },
      "paginas": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "pagina_id": {
              "type": "string"
            },
            "titulo": {
              "type": "string"
            },
            "dominio": {
              "type": "string"
            },
            "slug": {
              "type": "string"
            },
            "kit_id": {
              "type": "string"
            },
            "kit_nome": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "pages_KitMarcaEfetivo": {
    "type": "object",
    "properties": {
      "origem": {
        "type": "string",
        "enum": [
          "pagina",
          "dominio",
          "padrao",
          "vazio"
        ]
      },
      "kit": {
        "allOf": [
          {
            "$ref": "#/components/schemas/pages_KitMarca"
          }
        ],
        "nullable": true
      },
      "publico": {
        "type": "object",
        "nullable": true,
        "description": "projeção pública (sem voz) + same_as — a mesma do campo `kit` da página publicada"
      },
      "contexto_ia": {
        "type": "object",
        "description": "o kit como DADO para a geração por IA"
      }
    }
  },
  "pages_RascunhoPagina": {
    "type": "object",
    "properties": {
      "template": {
        "type": "object",
        "description": "o documento como foi gravado (v1 ou v2), sem validação de publicação"
      },
      "rascunho_em": {
        "type": "string",
        "format": "date-time",
        "description": "etiqueta de concorrência; devolva em `?base=`"
      },
      "rascunho_por": {
        "type": "string",
        "description": "`apikey:<key_id>` quando foi uma chave; ausente para pessoa"
      }
    }
  },
  "pages_ConflitoDeRascunho": {
    "type": "object",
    "properties": {
      "erro": {
        "type": "string"
      },
      "codigo": {
        "type": "string",
        "enum": [
          "RascunhoConflito"
        ]
      },
      "rascunho": {
        "$ref": "#/components/schemas/pages_RascunhoPagina"
      }
    }
  },
  "pages_SEOPagina": {
    "type": "object",
    "description": "SEO e compartilhamento de UMA página. Vazio = padrão do runtime.",
    "properties": {
      "titulo": {
        "type": "string",
        "maxLength": 120,
        "description": "<title>; o Google corta em ~60"
      },
      "descricao": {
        "type": "string",
        "maxLength": 320,
        "description": "meta description; o Google corta em ~155"
      },
      "canonical_url": {
        "type": "string",
        "format": "uri",
        "description": "URL absoluta http/https; vazio = a URL da própria página"
      },
      "noindex": {
        "type": "boolean",
        "description": "meta robots noindex + fora do sitemap"
      },
      "og_titulo": {
        "type": "string",
        "maxLength": 120
      },
      "og_descricao": {
        "type": "string",
        "maxLength": 320
      },
      "og_imagem_url": {
        "type": "string",
        "format": "uri",
        "description": "só https"
      },
      "og_imagem_alt": {
        "type": "string",
        "maxLength": 300
      },
      "og_imagem_largura": {
        "type": "integer",
        "minimum": 0,
        "maximum": 10000,
        "description": "0 = desconhecida; vai junto com a altura"
      },
      "og_imagem_altura": {
        "type": "integer",
        "minimum": 0,
        "maximum": 10000
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time",
        "readOnly": true
      }
    }
  },
  "pages_SEOSite": {
    "type": "object",
    "description": "SEO do host de uma conta (domínio verificado, ou o host da plataforma). Só `noindex` é gravável; o resto espelha o kit de marca efetivo do host (041).",
    "properties": {
      "nome_site": {
        "type": "string",
        "maxLength": 80,
        "description": "og:site_name, sufixo do título padrão, WebSite do JSON-LD"
      },
      "og_imagem_url": {
        "type": "string",
        "format": "uri",
        "description": "imagem padrão de compartilhamento; só https"
      },
      "og_imagem_alt": {
        "type": "string",
        "maxLength": 300
      },
      "og_imagem_largura": {
        "type": "integer",
        "minimum": 0,
        "maximum": 10000
      },
      "og_imagem_altura": {
        "type": "integer",
        "minimum": 0,
        "maximum": 10000
      },
      "favicon_url": {
        "type": "string",
        "format": "uri",
        "description": "só https; vazio cai no favicon da marca e depois no padrão"
      },
      "org_nome": {
        "type": "string",
        "maxLength": 120,
        "description": "Organization do JSON-LD"
      },
      "org_logo_url": {
        "type": "string",
        "format": "uri",
        "description": "só https"
      },
      "org_url": {
        "type": "string",
        "format": "uri",
        "description": "http/https"
      },
      "noindex": {
        "type": "boolean",
        "description": "robots.txt Disallow: / e noindex em toda página do host"
      },
      "kit": {
        "type": "object",
        "readOnly": true,
        "description": "kit de marca efetivo do host, de onde vêm os demais campos",
        "properties": {
          "id": {
            "type": "string"
          },
          "nome": {
            "type": "string"
          },
          "origem": {
            "type": "string",
            "enum": [
              "pagina",
              "dominio",
              "padrao",
              "vazio"
            ]
          }
        }
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time",
        "readOnly": true
      }
    }
  },
  "pages_NumerosDoRelatorio": {
    "type": "object",
    "description": "Visitas = sessões distintas; visualizações = eventos page_view; conversões = sessões com form_submit. As `form_*` contam o funil do formulário (taxa de envio = form_envios ÷ form_visualizacoes, conta de quem lê).",
    "properties": {
      "visitas": {
        "type": "integer"
      },
      "visualizacoes": {
        "type": "integer"
      },
      "conversoes": {
        "type": "integer"
      },
      "form_visualizacoes": {
        "type": "integer",
        "description": "eventos form_view (o formulário ficou visível); `extras.form` = id público do formulário"
      },
      "form_inicios": {
        "type": "integer",
        "description": "eventos form_start"
      },
      "form_envios": {
        "type": "integer",
        "description": "eventos form_submit"
      }
    }
  },
  "pages_RelatorioAnalytics": {
    "type": "object",
    "description": "Totais, série diária (dia civil de America/Sao_Paulo) e linhas da dimensão — da MESMA varredura, então a série soma o total.",
    "properties": {
      "de": {
        "type": "string",
        "format": "date-time"
      },
      "ate": {
        "type": "string",
        "format": "date-time"
      },
      "dimensao": {
        "type": "string"
      },
      "totais": {
        "$ref": "#/components/schemas/pages_NumerosDoRelatorio"
      },
      "serie": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/pages_NumerosDoRelatorio"
            },
            {
              "type": "object",
              "properties": {
                "dia": {
                  "type": "string",
                  "format": "date"
                }
              }
            }
          ]
        }
      },
      "linhas": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/pages_NumerosDoRelatorio"
            },
            {
              "type": "object",
              "properties": {
                "valor": {
                  "type": "string",
                  "description": "valor da dimensão; `(vazio)` = não preenchido"
                }
              }
            }
          ]
        }
      }
    }
  },
  "pages_RecorteDeVisao": {
    "type": "object",
    "required": [
      "periodo",
      "dimensao",
      "metrica"
    ],
    "properties": {
      "periodo": {
        "type": "string",
        "enum": [
          "7d",
          "30d",
          "90d",
          "personalizado"
        ]
      },
      "de": {
        "type": "string",
        "format": "date",
        "description": "só no personalizado (AAAA-MM-DD)"
      },
      "ate": {
        "type": "string",
        "format": "date",
        "description": "só no personalizado; até 92 dias"
      },
      "comparar": {
        "type": "boolean",
        "description": "comparar com o período anterior de mesma duração"
      },
      "dimensao": {
        "type": "string",
        "enum": [
          "pagina",
          "utm_source",
          "utm_medium",
          "utm_campaign",
          "pais",
          "dispositivo",
          "formulario"
        ]
      },
      "metrica": {
        "type": "string",
        "enum": [
          "visitas",
          "visualizacoes",
          "conversoes",
          "taxa"
        ]
      },
      "filtros": {
        "type": "object",
        "description": "chave = dimensão; valor até 200 caracteres; `(vazio)` filtra os não preenchidos",
        "additionalProperties": {
          "type": "string",
          "maxLength": 200
        }
      }
    }
  },
  "pages_VisaoDeRelatorio": {
    "type": "object",
    "description": "Um recorte nomeado da Analytics, compartilhado pela conta.",
    "properties": {
      "id": {
        "type": "string"
      },
      "nome": {
        "type": "string",
        "maxLength": 80
      },
      "recorte": {
        "$ref": "#/components/schemas/pages_RecorteDeVisao"
      },
      "criado_em": {
        "type": "string",
        "format": "date-time"
      },
      "atualizado_em": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "pages_PedidoDeVisao": {
    "type": "object",
    "required": [
      "nome",
      "recorte"
    ],
    "additionalProperties": false,
    "properties": {
      "nome": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80
      },
      "recorte": {
        "$ref": "#/components/schemas/pages_RecorteDeVisao"
      }
    }
  },
  "pages_Variante": {
    "type": "object",
    "description": "Uma variante de um teste A/B da página.",
    "required": [
      "id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,64}$",
        "description": "id textual da variante (único no experimento; vai em cookie e na credencial do pixel)"
      },
      "nome": {
        "type": "string"
      },
      "peso": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100,
        "description": "distribuição de tráfego (0–100)"
      }
    }
  },
  "pages_Roteamento": {
    "type": "object",
    "description": "Regra de desvio de uma página.",
    "required": [
      "estrategia",
      "destinos"
    ],
    "properties": {
      "estrategia": {
        "type": "string",
        "description": "dimensão da regra (ex.: geo, device, idioma)"
      },
      "destinos": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "object",
          "required": [
            "id"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "peso": {
              "type": "integer",
              "minimum": 0
            }
          }
        }
      }
    }
  },
  "pages_LeadAPI": {
    "type": "object",
    "description": "Corpo do modo API da captura (`POST /v1/leads` e `.../submissions`). Campos EXPLÍCITOS — sem bind do corpo inteiro (anti mass assignment). Corpo máximo: 64 KB.",
    "required": [
      "campos"
    ],
    "properties": {
      "form_id": {
        "type": "string",
        "description": "id do formulário; no path tem precedência sobre este campo"
      },
      "campos": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "os valores, por nome de campo declarado",
        "example": {
          "email": "fulana@exemplo.test",
          "nome": "Fulana"
        }
      },
      "id_externo": {
        "type": "string",
        "maxLength": 255,
        "description": "Id desta submissão no SEU sistema. É a chave de deduplicação (escopada por formulário): reenviar o mesmo `id_externo` devolve 200 com `duplicada: true` e o MESMO `lead_id`. O header `Idempotency-Key`, se enviado, vale no lugar.",
        "example": "blog-sub-48213"
      },
      "consentimento": {
        "type": "boolean",
        "description": "true equivale a `campos.consentimento=on` quando o campo não veio. Formulário com `exige_consentimento` recusa (400) sem ele."
      },
      "ocorrido_em": {
        "type": "string",
        "format": "date-time",
        "description": "quando o visitante enviou no seu sistema (RFC 3339). Vira o instante de recebimento do lead. Recusado (400) se estiver mais de 5 min no futuro ou mais de 365 dias no passado.",
        "example": "2026-10-08T14:03:00Z"
      },
      "origem": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 2048,
            "description": "URL da página onde o formulário foi enviado (http/https)",
            "example": "https://blog.exemplo.test/post/lancamento"
          },
          "utm_source": {
            "type": "string"
          },
          "utm_medium": {
            "type": "string"
          },
          "utm_campaign": {
            "type": "string"
          },
          "utm_term": {
            "type": "string"
          },
          "utm_content": {
            "type": "string"
          },
          "referrer": {
            "type": "string"
          }
        }
      }
    }
  },
  "pages_LeadAceito": {
    "type": "object",
    "description": "Resposta da captura. O status separa criado (201) de deduplicado (200) SÓ no modo API.",
    "required": [
      "ok"
    ],
    "properties": {
      "ok": {
        "type": "boolean"
      },
      "lead_id": {
        "type": "string",
        "format": "uuid"
      },
      "duplicada": {
        "type": "boolean",
        "description": "true quando a submissão foi deduplicada (nada de novo gravado); `lead_id` é o do envio original"
      },
      "id_externo": {
        "type": "string",
        "description": "eco do `id_externo` enviado, quando houve"
      }
    }
  },
  "pages_Pixel": {
    "type": "object",
    "description": "Um ponto de coleta.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "nome": {
        "type": "string"
      },
      "ativo": {
        "type": "boolean"
      },
      "snippet": {
        "type": "string",
        "readOnly": true,
        "description": "a tag pronta com a credencial assinada, para colar no site"
      }
    }
  },
  "pages_PixelUpsert": {
    "type": "object",
    "description": "Corpo de criar/editar pixel. No PATCH, informe `nome` e/ou `ativo`.",
    "properties": {
      "nome": {
        "type": "string",
        "maxLength": 120
      },
      "ativo": {
        "type": "boolean"
      }
    }
  },
  "pages_ItemLixeira": {
    "type": "object",
    "description": "Um item removido que a conta pode restaurar (ADR-0121). Os tipos `link`, `dominio`, `gratis` (subdomínio grátis), `midia`, `kit`, `visao`, `roteamento` e `rascunho` vêm do asender_pages_api; os tipos `pixeldominio` e `pixelconversao` vêm do asender_pages_runtime. Credencial (token Cloudflare) e histórico de destinos de formulário NUNCA entram: só o master.",
    "required": [
      "tipo",
      "id",
      "nome",
      "apagado_em",
      "apagado_por"
    ],
    "properties": {
      "tipo": {
        "type": "string",
        "enum": [
          "link",
          "dominio",
          "gratis",
          "midia",
          "kit",
          "visao",
          "roteamento",
          "rascunho",
          "pixeldominio",
          "pixelconversao"
        ],
        "description": "Tipo do item."
      },
      "id": {
        "type": "string",
        "description": "Id para o restaurar (público do recurso; `pxd_…`/`pxc_…` nos tipos de pixel)."
      },
      "nome": {
        "type": "string",
        "description": "Nome legível: título e endereço do link, host do domínio, nome da mídia/kit/visão, página do roteamento, `Rascunho da página X`, host ou nome da conversão do pixel."
      },
      "apagado_em": {
        "type": "string",
        "format": "date-time"
      },
      "apagado_por": {
        "type": "string",
        "description": "Id do ator que removeu (pode vir vazio)."
      },
      "apagado_por_nome": {
        "type": "string",
        "description": "Nome de quem removeu, quando o auth o resolve (nome, senão e-mail); omitido se não resolvido."
      }
    }
  },
  "pages_DominioDePixel": {
    "type": "object",
    "required": [
      "host"
    ],
    "properties": {
      "host": {
        "type": "string",
        "description": "origem autorizada a coletar com este pixel (allowlist do pixel)"
      }
    }
  },
  "pages_Conversao": {
    "type": "object",
    "description": "Uma conversão rastreada pelo pixel.",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid",
        "readOnly": true
      },
      "nome": {
        "type": "string",
        "maxLength": 120
      },
      "tipo": {
        "type": "string",
        "description": "como a conversão é detectada (ex.: clique, envio)"
      },
      "seletor": {
        "type": "string",
        "description": "seletor CSS do elemento observado, quando aplicável"
      }
    }
  },
  "pages_LoteDeColeta": {
    "type": "object",
    "description": "Corpo de `POST /collect` — um lote de eventos de comportamento.",
    "required": [
      "credencial",
      "eventos"
    ],
    "properties": {
      "credencial": {
        "type": "string",
        "description": "o token assinado do pixel, embutido na página servida"
      },
      "eventos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "tipo": {
              "type": "string",
              "description": "tipo do evento (ex.: pageview, click, scroll)"
            },
            "sessao_id": {
              "type": "string"
            },
            "ocorreu_em": {
              "type": "string",
              "format": "date-time"
            },
            "variante_id": {
              "type": "string",
              "description": "a variante de A/B ativa, quando houver"
            },
            "extras": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "pages_LoteDeReplay": {
    "type": "object",
    "description": "Corpo de `POST /replay` — um lote de uma jornada gravada.",
    "required": [
      "credencial",
      "sessao_id",
      "eventos"
    ],
    "properties": {
      "credencial": {
        "type": "string",
        "description": "o token assinado do pixel"
      },
      "sessao_id": {
        "type": "string"
      },
      "pagina": {
        "type": "string"
      },
      "viewport_w": {
        "type": "integer"
      },
      "viewport_h": {
        "type": "integer"
      },
      "eventos": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "t": {
              "type": "integer",
              "description": "offset em ms desde o início da sessão (o relógio é do SERVIDOR)"
            },
            "tipo": {
              "type": "string"
            },
            "payload": {
              "type": "object",
              "description": "carga do evento (JSON livre)"
            }
          }
        }
      }
    }
  }
}