# API Asender — documentação completa Este arquivo é a documentação INTEIRA da API aberta, em texto puro: convenções, guias e todas as 262 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://docs.asender.net. Especificação OpenAPI: https://docs.asender.net/openapi.json Cada ferramenta é um sistema à parte, com endereço próprio. Elas compartilham a identidade (o mesmo token vale em todas) e se integram entre si, mas falham separadamente: uma fora do ar não derruba as outras. APIs: https://api.asender.net Plataforma https://auth.asender.net Identidade (OIDC / OAuth 2.1) https://api.crm.asender.net CRM https://api.pages.asender.net Páginas https://api.sites.asender.net Publicação e analytics ============================================================================== # GUIA: Convenções da API ============================================================================== # API Design - Convencoes do Ecossistema Padroes de API consistentes entre o Relay PHP e o Asender Core. --- ## 1. Principios 1. **REST-ish, pragmatico** - nao precisa ser RESTfully puro, mas previsivel 2. **JSON-first** - request e response sempre JSON 3. **SES-compatible shape** - maioria das respostas segue o formato AWS SES (ja era assim no relay) 4. **Idempotencia** - endpoints POST de envio aceitam `IdempotencyKey` 5. **Versionada** - `/v1/` no Core; no relay, versionamento via action 6. **Self-documenting** - cada resposta inclui `RequestId` pra suporte --- ## 2. Autenticacao ### Header padrao ``` Authorization: Bearer ``` ### Alternativas (pra webhooks/crons) ``` ?api_key= (query param) X-Api-Key: (custom header - suportado pelo Core, nao pelo relay) ``` ### Formato de keys | Prefixo | Uso | |---------------|-----------------------------------------------| | `sk_master_` | Master key do relay (admin) | | `sk_live_` | Tenant key do relay OU API key do Core (prod) | | `sk_test_` | API key do Core em modo teste | | `pk_live_` | Publishable key (client-side, read-only) | Todas com 48 chars hex depois do prefixo. Hash SHA-256 armazenado. --- ## 3. Request Format ### Headers obrigatorios em POST/PUT ``` Content-Type: application/json; charset=utf-8 ``` ### Body JSON com chaves em **PascalCase** (alinhado com SES). Excecao: paths internos/admin podem usar snake_case se for mais conveniente. Documentado por endpoint. ### Exemplo ```json { "Source": "noreply@example.com", "Destination": { "ToAddresses": ["user@example.com"] }, "Message": { "Subject": {"Data": "Hello", "Charset": "UTF-8"}, "Body": {"Text": {"Data": "Hi there"}} } } ``` ### Idempotencia POST de envio aceita: ``` X-Idempotency-Key: uuid-or-any-string ``` ou no body: ```json {"IdempotencyKey": "..."} ``` Se a mesma key eh reutilizada dentro de 24h, retorna o mesmo MessageId sem re-enfileirar. --- ## 4. Response Format ### Sucesso ```json { "MessageId": "msg_xxx", "Status": "queued", "RequestId": "req_xxx" } ``` Sempre contem `RequestId`. ### HTTP Status Codes | Code | Uso | |------|---------------------------------------------| | 200 | Sucesso em GET/PUT/DELETE | | 201 | Recurso criado (POST) | | 204 | Sucesso sem body (OPTIONS, DELETE simples) | | 400 | Validacao falhou | | 401 | API key ausente/invalida | | 402 | Limite de plano excedido (Core) | | 403 | Sem permissao / tenant suspenso | | 404 | Recurso nao encontrado | | 405 | Metodo HTTP errado | | 409 | Conflito (ex: email ja existe na lista) | | 422 | Validacao semantica (dominio nao verificado, etc) | | 429 | Rate limit excedido | | 500 | Erro interno | | 503 | Servico indisponivel (SMTP down, etc) | ### Paginacao Listagens usam cursor-based OU offset-based. **Offset (simples, usado no relay):** ``` GET /v1/emails?limit=50&offset=100 { "Messages": [...], "Count": 50, "Total": 342, "RequestId": "..." } ``` **Cursor (recomendado no Core pra grandes volumes):** ``` GET /v1/emails?limit=50&cursor=eyJpZCI6MTAwfQ { "Messages": [...], "NextCursor": "eyJpZCI6MTUwfQ", "HasMore": true, "RequestId": "..." } ``` Cursor eh base64 de um JSON opaco com o estado (`{id: N}` ou similar). ### Headers de Response Sempre presentes: ``` X-Request-Id: req_xxx X-Content-Type-Options: nosniff X-Frame-Options: DENY ``` Quando relevante: ``` X-RateLimit-Limit: 100 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1681234567 Retry-After: 60 (em 429 ou 503) Location: /v1/emails/msg_xxx (em 201) ``` --- ## 5. Erro Format (SES-like) ### Estrutura ```json { "Error": { "Type": "Sender", "Code": "ValidationError", "Message": "Destination.ToAddresses must contain at least one address.", "Details": { "field": "Destination.ToAddresses", "constraint": "min_length", "value": 0 } }, "RequestId": "req_xxx" } ``` Campos: - `Type`: `Sender` (4xx - erro do cliente) ou `Receiver` (5xx - erro do servidor) - `Code`: enum estavel (nunca mude semantica, so adicione novos) - `Message`: descricao humana, localizavel - `Details` (opcional): contexto adicional maquina-legivel ### Codigos padronizados **Auth & Access:** - `AuthorizationError` - key ausente/invalida - `PermissionDenied` - key valida mas sem permissao - `TenantSuspended` - tenant suspenso - `PlanLimitExceeded` - limite do plano atingido (Core) **Validation:** - `ValidationError` - body invalido - `MissingParameter` - `InvalidParameter` - `InvalidJson` **Resources:** - `NotFound` - recurso nao existe - `Conflict` - duplicata - `Gone` - recurso foi deletado - `AlreadyExists` **Rate limits:** - `Throttling` - rate limit excedido - `QuotaExceeded` - quota mensal/diaria **Service:** - `InternalError` - 500 - `ServiceUnavailable` - 503 - `SmtpError` - problema com SMTP - `ProviderError` - erro do provedor externo (SES, Twilio, etc) **Specifics:** - `DomainNotVerified` - `SuppressedAddress` - destinatario na lista de supressao - `InvalidRecipient` - `NotInstalled` - relay nao instalado ainda --- ## 6. Webhooks ### Signature Outgoing webhooks assinam com HMAC-SHA256: ``` X-Asender-Signature: t=1681234567,v1=abc123def... X-Asender-Event: email.sent X-Asender-Event-Id: evt_xxx ``` Para verificar: ``` signed_payload = t + "." + body expected = hmac_sha256(webhook_secret, signed_payload) constant_time_compare(expected, v1) ``` Evita replay: rejeitar se `t` for mais antigo que 5min. ### Payload ```json { "EventId": "evt_xxx", "EventType": "email.delivered", "CreatedAt": "2026-04-12T15:30:00Z", "TenantId": "acc_xxx", "Data": { "MessageId": "msg_xxx", ... } } ``` ### Retry Se endpoint retorna nao-2xx, retry com backoff: - 1min, 5min, 15min, 1h, 6h, 24h (6 tentativas) - Apos 24h, marca delivery como `failed` --- ## 7. CORS ### Default Bloqueia cross-origin (API eh server-to-server). ### Allowlist Customer pode configurar origins permitidos (pra frontend JS usando publishable keys): ``` Access-Control-Allow-Origin: https://app.customer.com Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS Access-Control-Allow-Headers: Authorization, Content-Type Access-Control-Max-Age: 3600 ``` Preflight OPTIONS sempre responde 204. --- ## 8. Rate Limits ### Camadas 1. **Global per IP:** 1000 req/min em auth endpoints (brute force protection) 2. **Per API key:** configurado por plano 3. **Per tenant send limit:** hourly/daily de envios 4. **Per resource:** ex: max 100 templates por tenant ### Resposta ao atingir ```http HTTP/1.1 429 Too Many Requests Retry-After: 45 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1681234612 { "Error": { "Type": "Sender", "Code": "Throttling", "Message": "Rate limit exceeded. Retry after 45 seconds." } } ``` --- ## 9. Versionamento ### Core URL path: `/v1/`, `/v2/`. Mudancas breaking criam nova major version. Mudancas non-breaking (campos novos opcionais, enums adicionais) nao bumpam versao. ### Relay Via `action` name. Ex: `action=send` continua sendo v1. Se precisar breaking, criar `action=v2.send`. ### Deprecacao - Aviso no header: `Sunset: Wed, 01 Jan 2027 00:00:00 GMT` - Docs marcam como deprecated - Prazo minimo: 6 meses antes de remover --- ## 10. Batch Operations Convencao pra operacoes em lote: ```json POST /v1/emails/send-batch { "Entries": [ {"Id": "client-entry-1", ...payload}, {"Id": "client-entry-2", ...payload} ] } ``` Response: ```json { "Entries": [ {"Id": "client-entry-1", "MessageId": "msg_xxx", "Status": "queued"}, {"Id": "client-entry-2", "Error": "..."} ], "SuccessCount": 1, "FailCount": 1, "RequestId": "req_xxx" } ``` Sempre retorna 200, mesmo com falhas parciais. Cliente deve inspecionar `Entries[].Error`. Limite: max 500 entries por request. --- ## 11. Filtros e Queries Listagens aceitam filtros via query params: ``` GET /v1/emails?status=sent&from=2026-04-01&to=2026-04-30&tag=campaign:welcome ``` Formato: - Igualdade simples: `status=sent` - Datas: ISO 8601 `from=2026-04-12T10:00:00Z` - Multiplos valores: `status=sent,delivered` ou `status[]=sent&status[]=delivered` - Busca: `q=welcome` (full-text nos campos relevantes) - Sort: `sort=-created_at` (prefixo `-` = desc) --- ## 12. Seguranca - **HTTPS obrigatorio** em producao (relay + core) - **HSTS header** em respostas - **Sem CORS* default** em endpoints sensitivos - **Content-Security-Policy** no dashboard - **Rate limit agressivo** em auth - **Audit log** de acoes admin - **PII masking** em logs (emails, phones aparecem como `u***@e***.com`) - **Encryption at rest** de credenciais - **Keys nunca em logs** --- ## 13. SDK Philosophy SDKs sao thin wrappers. Devem: - Setar auth automaticamente via env var - Retry em 5xx com backoff exponencial (3 tentativas) - NAO fazer retry em 4xx - Expor typed response models - Honrar `Retry-After` - Oferecer sync + async (onde aplicavel) **PHP exemplo:** ```php $asender = new Asender\Client([ 'api_key' => getenv('ASENDER_API_KEY'), 'base_url' => 'https://api.asender.io', ]); $result = $asender->emails()->send([ 'Source' => 'noreply@example.com', 'Destination' => ['ToAddresses' => ['user@example.com']], 'Message' => [...], ]); echo $result->MessageId; ``` ============================================================================== # Plataforma (https://api.asender.net) ============================================================================== ### GET / Identidade do serviço. Respostas: 200 OK curl -X GET 'https://api.asender.net/' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /api/admin/blacklist Lista os bloqueios da plataforma. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/blacklist' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /api/admin/blacklist Acrescenta uma entrada à lista de bloqueio. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/blacklist' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /api/admin/blacklist/{id} Remove uma entrada da lista de bloqueio. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X DELETE 'https://api.asender.net/api/admin/blacklist/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /api/admin/blacklist/suggestions Sugestões de bloqueio ainda não decididas. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/blacklist/suggestions' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /api/admin/blacklist/suggestions Registra uma sugestão de bloqueio. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/blacklist/suggestions' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /api/admin/blacklist/suggestions/{id}/apply Aceita a sugestão e a promove a bloqueio. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/blacklist/suggestions/id_AQUI/apply' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /api/admin/blacklist/suggestions/{id}/dismiss Descarta a sugestão. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/blacklist/suggestions/id_AQUI/dismiss' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /api/admin/datacenter-asn ASNs classificados como datacenter. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/datacenter-asn' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /api/admin/datacenter-asn Classifica um ASN como datacenter. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/datacenter-asn' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /api/admin/datacenter-asn/{asn} Remove a classificação de um ASN. Parâmetros: asn (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X DELETE 'https://api.asender.net/api/admin/datacenter-asn/asn_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /api/admin/impersonation/end Encerra a sessão de suporte em andamento. Onde é usada: botão "sair da conta". Efeitos: a sessão de suporte para NA HORA. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/impersonation/end' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /api/admin/me Diz se o usuário da sessão é da plataforma. Onde é usada: o console, ao abrir — é o que decide entre mostrar o console e mostrar "não disponível". Efeitos: uma leitura na allowlist. Existe em vez de o console deduzir de outra rota: sem ela, o front descobriria que não é plataforma pelo 404 da PRIMEIRA rota que chamasse — e mostraria um erro de carregamento onde a resposta certa é "esta área não é sua". Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/me' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /api/admin/metrics Métricas agregadas da plataforma. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/metrics' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /api/admin/platform-alerts Regras de alerta da plataforma. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/platform-alerts' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /api/admin/platform-alerts Cria uma regra de alerta de plataforma. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/platform-alerts' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### PUT /api/admin/platform-alerts/{id} Substitui uma regra de alerta. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X PUT 'https://api.asender.net/api/admin/platform-alerts/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /api/admin/platform-alerts/{id} Remove uma regra de alerta. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X DELETE 'https://api.asender.net/api/admin/platform-alerts/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /api/admin/platform-alerts/events Disparos de alerta da plataforma. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/platform-alerts/events' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /api/admin/tenants Lista as contas, na visão da plataforma. Onde é usada: tela `/impersonate`. Efeitos: uma leitura no core. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/tenants' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /api/admin/tenants/{id} Detalhe de uma conta, na visão da plataforma. Onde é usada: console, ao abrir um cliente. Efeitos: uma leitura no core. # Por que não reusar `GET /api/tenants/{id}` Aquela rota exige PERTINÊNCIA: o usuário tem de ser membro da conta. Quem opera a plataforma não é membro de nenhuma conta de cliente — e não deve virar, porque virar membro para poder ver é exatamente o atalho que o ADR-0017 existe para impedir. A autorização aqui é a allowlist de plataforma, e a rota é outra. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X GET 'https://api.asender.net/api/admin/tenants/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### PATCH /api/admin/tenants/{id} Altera uma conta, na visão da plataforma. Onde é usada: console. Efeitos: uma escrita no core. # Isto NÃO é a sessão de suporte A impersonação é somente leitura (ADR-0017) porque entrar na conta é ver o que o cliente vê. Isto é outra coisa: é a plataforma agindo COMO plataforma — suspender uma conta abusiva, por exemplo — e a ação fica no log com o ator. A distinção importa: se a sessão de suporte pudesse escrever, "entrar para ajudar" viraria "entrar para consertar", e o limite que o ADR desenhou desapareceria na prática. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X PATCH 'https://api.asender.net/api/admin/tenants/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /api/admin/tenants/{id}/enter Abre sessão de suporte na conta (somente leitura, ADR-0017). Onde é usada: tela `/impersonate`. Efeitos: uma escrita no core — e, a partir dela, LEITURA da conta alheia. O motivo é obrigatório: uma trilha sem motivo responde "alguém entrou", que é a metade inútil da pergunta que ela existe para responder. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://api.asender.net/api/admin/tenants/id_AQUI/enter' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### 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 (user_id, código): o `user_id` sozinho não abre nada, 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 curl -X POST 'https://api.asender.net/api/auth/2fa' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -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 Desliga o segundo 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: ' \ -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: ' \ -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: ' \ -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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -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 `. Saídas: 200 `{Status:"ok"}` com a sessão revogada; 401 sem Bearer; 502 `LogoutFailed` quando o asender-auth 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, é 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR). curl -X POST 'https://api.asender.net/api/auth/logout' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /api/auth/me Principal da sessão. Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR). curl -X GET 'https://api.asender.net/api/auth/me' \ -H 'Authorization: Bearer SEU_TOKEN' ### PATCH /api/auth/me Altera o perfil do usuário da sessão. Onde é usada: tela de perfil do painel. Efeitos: escreve no asender-auth; e-mail novo desverifica a conta e dispara a verificação do endereço novo (lá). Respostas: 200 OK; 401 credencial ausente ou inválida curl -X PATCH 'https://api.asender.net/api/auth/me' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /api/auth/me/emails histórico paginado dos emails do tenant. Era 501; agora lê do asender_messages com o canal fixado em `email`. Onde é usada: API pública do cliente. Fluxo do dado: API key → Principal.TenantID → GET /v1/messages?channel=email. 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. curl -X GET 'https://api.asender.net/api/auth/me/emails' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /api/auth/me/emails Add: POST /api/auth/me/emails. curl -X POST 'https://api.asender.net/api/auth/me/emails' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /api/auth/me/emails/{id} Remove: DELETE /api/auth/me/emails/{id}. 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 Primary: POST /api/auth/me/emails/{id}/primary. 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: ' \ -d '{ }' ### POST /api/auth/me/emails/{id}/verify/resend Resend: POST /api/auth/me/emails/{id}/verify/resend. 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: ' \ -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: ' \ -d '{ }' ### POST /api/auth/register Cria usuário e (best-effort) o tenant raiz dele. Respostas: 201 Usuário criado.; 400 `400 ValidationError` — JSON inválido, campo desconhecido ou tipo errado.; 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: ' \ -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 impersonação NÃO passa por aqui A sessão de suporte é somente leitura (ADR-0017), e o middleware de impersonação 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 curl -X POST 'https://api.asender.net/api/auth/verify' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /api/contacts Audiência do tenant. Onde é usada: tela de audiência do dashboard. Entradas: `q`, `list_id`, `cursor`, `limit` (allowlist). Saídas: 200 com `{Contacts, NextCursor, HasMore}`. Parâmetros: X-Asender-Tenant (header); q (query); list_id (query); cursor (query); limit (query) Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -d '{ }' ### 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}`; 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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -d '{ }' ### 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: ' \ -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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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' ### 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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -d '{ }' ### 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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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. Fluxo do dado: cookie de sessão → SessionAuth → Principal → tenant resolvido no core → POST /v1/messages no asender_messages → outbox → NATS → worker. Saídas: 202 com `{Messages, ReusedIdempotency}`; 422 quando o asender_messages 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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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 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/messages/send' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /api/push/devices Devices de push do tenant, para o seletor da tela de disparo. Onde é usada: dashboard, tela `/send/push`. Fluxo do dado: `messages.push_devices` → asender_messages → aqui → seletor. 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 422 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). Fluxo do dado: core.vapid_keys → aqui → tela → arquivos no site do cliente → browser → `POST /v1/push/devices` → messages.push_devices. Saídas: 200 com `{PublicKey, ApiBase, Manifest, ServiceWorker, Snippet}`. Efeitos: pode criar o par VAPID do tenant na primeira chamada (no core). ## 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 `` 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) Respostas: 200 Artefatos prontos para o site.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR). 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). Fluxo do dado: sessão → tenant resolvido → asender_messages GET /v1/reports/overview → PascalCase. Entradas: `from`/`to` em ISO-8601 UTC; ausentes = últimos 30 dias (default resolvido pelo asender_messages, 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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/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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -d '{ }' ### GET /api/tenants Vínculos de tenant do usuário logado. Onde é usada: API pública do cliente. Fluxo do dado: API key → Principal.TenantID → GET /v1/messages?channel=email. 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 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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-core` 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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -d '{ }' ### GET /api/tenants/{id}/api-keys ListKeys lista as chaves da conta. Onde é usada: GET /api/tenants/{id}/api-keys. curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/api-keys' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /api/tenants/{id}/api-keys CreateKey emite uma chave. O texto puro volta UMA vez, no corpo do core. Onde é usada: POST /api/tenants/{id}/api-keys. 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: ' \ -d '{ }' ### DELETE /api/tenants/{id}/api-keys/{keyId} RevokeKey revoga uma chave. Onde é usada: DELETE /api/tenants/{id}/api-keys/{keyId}. curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/api-keys/keyId_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### 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. Parâmetros: id (path, obrigatório) Respostas: 201 Sub-conta criada.; 400 `400 ValidationError` — JSON inválido, campo desconhecido ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -d '{ }' ### GET /api/tenants/{id}/impersonations Trilha de sessões de suporte na conta. Onde é usada: tela de segurança da conta — do CLIENTE. Efeitos: uma leitura no core. # Esta rota NÃO exige plataforma Ela exige PERTINÊNCIA, como qualquer leitura de conta. Uma trilha que só a plataforma consegue ler serve para a plataforma se defender, não para o cliente se proteger (ADR-0017). 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/impersonations' \ -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: ' \ -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}/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: ' \ -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' ### PATCH /api/tenants/{id}/parent Move o tenant para outro pai (ou para a raiz). Onde é usada: tela de hierarquia de tenants. Segurança: autoriza os DOIS lados. Autorizar só `{id}` deixaria um usuário pendurar o tenant dele sob a árvore de outro cliente, o que é escalada de escopo — o novo pai passaria a "ver" a subárvore em rollup. Saídas: 200 com `{Tenant}`; 404 se qualquer um dos lados não é acessível; 422 quando o movimento cria ciclo (o trigger do core rejeita com check_violation). Efeitos: reescreve a closure de tenants no core. Parâmetros: id (path, obrigatório) Respostas: 200 Movido; a closure foi reescrita.; 400 `400 ValidationError` — JSON inválido, campo desconhecido ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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/parent' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -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 ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -d '{ }' ### GET /api/tenants/tree Subárvore do tenant corrente, em pré-ordem. Onde é usada: dashboard (settings/tenants) e backoffice. Fluxo do dado: sessão → tenant resolvido → asender-core GET /v1/tenants/{id}/tree → PascalCase. 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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 /healthz Liveness. Não toca dependência. Respostas: 200 Processo vivo. curl -X GET 'https://api.asender.net/healthz' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /metrics Métricas Prometheus. Respostas: 200 Texto no formato de exposição do Prometheus. curl -X GET 'https://api.asender.net/metrics' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /readyz Readiness. Respostas: 200 Pronto (possivelmente degradado). curl -X GET 'https://api.asender.net/readyz' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /v1/account Conta da API key usada, mais o contexto da própria chave. Respostas: 200 OK; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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. Fluxo do dado: API key verificada → Principal.TenantID → asender-core GET /v1/tenants/{id}/usage (snake_case) → PascalMap → resposta pública. 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-core/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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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/emails Histórico de emails do tenant da API key. Onde é usada: API pública do cliente. Fluxo do dado: API key → Principal.TenantID → GET /v1/messages?channel=email. 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) Respostas: 200 Página de mensagens.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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. Parâmetros: id (path, obrigatório) Respostas: 200 Detalhe.; 400 `400 ValidationError` — JSON inválido, campo desconhecido ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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. Fluxo do dado: igual ao Send, uma chamada ao asender_messages por item. Saídas: 202 com `{Results, Count}`; cada item traz MessageId ou Error. Efeitos: escrita no serviço de mensageria por item aceito. Respostas: 202 Lote processado (com ou sem itens rejeitados).; 400 `400 ValidationError` — JSON inválido, campo desconhecido ou tipo errado.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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: ' \ -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). Fluxo do dado: API key → APIKeyAuth → Principal.TenantID → POST /v1/messages (header X-Asender-Tenant) → messages + outbox no mesmo commit → NATS → worker. Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency}`; 400 em validação local; 422 quando o asender_messages 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.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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 POST 'https://api.asender.net/v1/emails/send' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### 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. Fluxo do dado: API key → Principal.TenantID → POST /v1/push/devices no asender_messages → messages.push_devices. 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. 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. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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`. curl -X POST 'https://api.asender.net/v1/push/devices' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/push/devices Lista os devices de push da conta da API key. Onde é usada: dashboard, tela `/send/push`. Fluxo do dado: `messages.push_devices` → asender_messages → aqui → seletor. 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: cursor (query); limit (query) Respostas: 200 Página de devices, em PascalCase.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 422 curl -X GET 'https://api.asender.net/v1/push/devices' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /v1/push/send Enfileira um push para tokens ou para um tópico. Onde é usada: API pública do cliente (autenticada por API key). Fluxo do dado: API key → APIKeyAuth → Principal.TenantID → POST /v1/messages (header X-Asender-Tenant) → messages + outbox no mesmo commit → NATS → worker. Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency}`; 400 em validação local; 422 quando o asender_messages 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.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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 POST 'https://api.asender.net/v1/push/send' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/sms/send Enfileira um SMS. Onde é usada: API pública do cliente (autenticada por API key). Fluxo do dado: API key → APIKeyAuth → Principal.TenantID → POST /v1/messages (header X-Asender-Tenant) → messages + outbox no mesmo commit → NATS → worker. Saídas: 202 com `{MessageId, MessageIds, Status, ReusedIdempotency}`; 400 em validação local; 422 quando o asender_messages 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.; 400 `400 ValidationError` com `Error.Details` mapeando campo → motivo.; 401 `401 AuthorizationError` — credencial ausente, malformada, inválida ou expirada. **Também** quando o upstream recusa o SERVICE_SECRET (erro de configuração, logado em ERROR).; 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 POST 'https://api.asender.net/v1/sms/send' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -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' ============================================================================== # Identidade (OIDC / OAuth 2.1) (https://auth.asender.net) ============================================================================== ### 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 JWKS serve /.well-known/jwks.json — a(s) chave(s) pública(s) RS256. Os clients Onde é usada: verificação no client. curl -X GET 'https://auth.asender.net/.well-known/jwks.json' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /.well-known/openid-configuration anuncia os endpoints e as capacidades (só `code`, só S256, só RS256 — o perfil OAuth2.1 da casa). Onde é usada: os clients leem isto no bootstrap para se autoconfigurar. Cacheável (muda só em deploy). curl -X GET 'https://auth.asender.net/.well-known/openid-configuration' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /authorize Authorize implementa GET /authorize (OAuth2.1 authorization code + PKCE). Onde é usada: o browser é redirecionado para cá pelo client (app) que quer logar. curl -X GET 'https://auth.asender.net/authorize' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /healthz Liveness. Onde é usada: liveness probe. Efeitos: escreve a resposta. Não consulta o banco de propósito: liveness que falha por causa do Postgres faz o orquestrador REINICIAR um serviço saudável durante uma instabilidade do banco — e reiniciar o serviço de login em massa transforma degradação em queda de autenticação para todo mundo. Respostas: 200 OK curl -X GET 'https://auth.asender.net/healthz' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /logout Expects Authorization: Bearer . curl -X GET 'https://auth.asender.net/logout' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /metrics Métricas Prometheus. Respostas: 200 Texto. curl -X GET 'https://auth.asender.net/metrics' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /readyz Readiness — ping no Postgres. Onde é usada: readiness probe. Efeitos: uma consulta trivial ao Postgres. É aqui que a dependência entra — o oposto do `/healthz`. O prazo curto é deliberado: uma sonda que espera indefinidamente nunca reporta "não pronto", e a instância continua recebendo login que vai falhar. Respostas: 200 Banco respondeu.; 503 `NotReady` — o erro do ping vai no `Message`. curl -X GET 'https://auth.asender.net/readyz' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /token Token implementa POST /token. Despacha por grant_type. Onde é usada: o client troca aqui, servidor-a-servidor (ou pelo BFF), o code/refresh por tokens. curl -X POST 'https://auth.asender.net/token' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /userinfo valida o Bearer (RS256, iss, exp) e devolve sub/email/name. Onde é usada: o client chama para hidratar o perfil. Sem token válido -> 401 invalid_token. curl -X GET 'https://auth.asender.net/userinfo' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /v1/2fa/check Segunda etapa do login — valida o código e EMITE a sessão. Respostas: 200 Código válido; sessão emitida.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401 TwoFactorFailed` — código TOTP inválido.; 404 `404 NotFound`. curl -X POST 'https://auth.asender.net/v1/2fa/check' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/2fa/disable Desliga o TOTP do usuário. Respostas: 200 Desligado.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401` — token de serviço ausente ou inválido. **Não ocorre com `ENV=development`.**; 404 `404 NotFound`. curl -X POST 'https://auth.asender.net/v1/2fa/disable' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/2fa/setup Gera o segredo TOTP e a `otpauth://` URL. Respostas: 200 Segredo gerado.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401` — token de serviço ausente ou inválido. **Não ocorre com `ENV=development`.**; 404 `404 NotFound`. curl -X POST 'https://auth.asender.net/v1/2fa/setup' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/2fa/verify Confirma o setup do TOTP. Respostas: 200 Confirmado.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401 TwoFactorFailed` — código TOTP inválido.; 404 `404 NotFound`. curl -X POST 'https://auth.asender.net/v1/2fa/verify' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/auth/login Autentica e emite sessão. Respostas: 200 Sessão emitida, ou 2FA pendente.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401 InvalidCredentials` — credenciais inválidas.; 500 `500 InternalError`. **DIVERGÊNCIA:** o `Message` recebe `err.Error()` CRU, como no `asender-core`. Pode vazar estrutura interna. curl -X POST 'https://auth.asender.net/v1/auth/login' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/auth/logout Revoga a sessão do Bearer apresentado. Respostas: 200 Revogada.; 401 `401` — `MissingToken` (sem `Authorization: Bearer`), `InvalidToken` (assinatura/formato) ou `ExpiredToken` (expirada **ou revogada por logout**). curl -X POST 'https://auth.asender.net/v1/auth/logout' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/auth/password-reset Solicita o token de redefinição de senha. Respostas: 200 Sempre `ok:true`; `reset_token` presente quando um token foi gerado.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401` — token de serviço ausente ou inválido. **Não ocorre com `ENV=development`.**; 500 `500 InternalError`. **DIVERGÊNCIA:** o `Message` recebe `err.Error()` CRU, como no `asender-core`. Pode vazar estrutura interna. curl -X POST 'https://auth.asender.net/v1/auth/password-reset' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/auth/password-reset/confirm Redefine a senha com o token emitido. Respostas: 200 Senha alterada.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `InvalidToken` ou `ExpiredToken`. curl -X POST 'https://auth.asender.net/v1/auth/password-reset/confirm' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/auth/sessions Sessões ativas do usuário. Onde é usada: tela de segurança do painel, através do BFF. Efeitos: uma leitura. Não recebe usuário por parâmetro: a lista é sempre a do dono do token. 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://auth.asender.net/v1/auth/sessions' \ -H 'Authorization: Bearer SEU_TOKEN' ### DELETE /v1/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. 404 tanto para sessão inexistente quanto para sessão de OUTRA pessoa: a distinção transformaria a rota num oráculo de id de sessão alheia. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X DELETE 'https://auth.asender.net/v1/auth/sessions/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /v1/auth/validate Resolve um token de sessão no usuário dono. Respostas: 200 Sessão válida.; 401 `401` — `MissingToken` (sem `Authorization: Bearer`), `InvalidToken` (assinatura/formato) ou `ExpiredToken` (expirada **ou revogada por logout**). curl -X GET 'https://auth.asender.net/v1/auth/validate' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /v1/auth/verify Confirma o e-mail a partir do token do link. Onde é usada: tela `/verify` do front, com o token da URL. Efeitos: duas escritas. Token inválido, expirado e já usado respondem IGUAL: distingui-los diria a quem tem um link velho se ele já foi usado por outra pessoa. Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://auth.asender.net/v1/auth/verify' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/authz/decide `{permitido, motivo, papel, nivel}`. Onde é usada: POST /v1/authz/decide. Efeitos: grava a trilha (dentro do PDP). Erro de banco vira 503, e não `{permitido:false}`: o PEP precisa distinguir "a política diz não" de "não consegui perguntar" — o primeiro ele mostra ao usuário, o segundo ele resolve com o cache que já tem (piso 10). curl -X POST 'https://auth.asender.net/v1/authz/decide' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/authz/eu `{produtos:[{slug,nome,subdominio,papel,nivel}]}`. Onde é usada: GET /v1/authz/eu?sub=&tenant= — alimenta o switcher e a home do hub. curl -X GET 'https://auth.asender.net/v1/authz/eu' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /v1/authz/produtos Catalogo devolve as ferramentas que existem. Onde é usada: GET /v1/authz/produtos. curl -X GET 'https://auth.asender.net/v1/authz/produtos' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /v1/tenants/{id}/acessos ListarAcessos devolve quem acessa o quê na conta. Onde é usada: GET /v1/tenants/{id}/acessos. curl -X GET 'https://auth.asender.net/v1/tenants/id_AQUI/acessos' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /v1/tenants/{id}/acessos Conceder dá acesso de uma pessoa a uma ferramenta da conta. Onde é usada: POST /v1/tenants/{id}/acessos {user_id, produto, papel}. Papel que o produto não declara é recusado pela FK — 422 com a mensagem, e não 500: "papel inventado" é erro de quem chamou, não do servidor. curl -X POST 'https://auth.asender.net/v1/tenants/id_AQUI/acessos' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/tenants/{id}/acessos/{userId}/{produto} Revogar tira o acesso. Onde é usada: DELETE /v1/tenants/{id}/acessos/{userId}/{produto}. Idempotente: revogar duas vezes responde ok nas duas. O efeito chega às ferramentas em até 60s (TTL do cache do PEP) — contrato escrito no ADR-0025. curl -X DELETE 'https://auth.asender.net/v1/tenants/id_AQUI/acessos/userId_AQUI/produto_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /v1/tenants/{id}/authz/decisoes Trilha devolve as decisões recentes da conta. Onde é usada: GET /v1/tenants/{id}/authz/decisoes?negadas=1&limite=50. curl -X GET 'https://auth.asender.net/v1/tenants/id_AQUI/authz/decisoes' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /v1/tenants/{id}/produtos ListarAssinatura devolve o que a conta assina. Onde é usada: GET /v1/tenants/{id}/produtos. curl -X GET 'https://auth.asender.net/v1/tenants/id_AQUI/produtos' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /v1/tenants/{id}/produtos Assinar liga ou suspende um produto na conta. Onde é usada: POST /v1/tenants/{id}/produtos {produto, status}. `status` é validado aqui E no CHECK da tabela: a borda dá a mensagem, o banco dá a garantia — a borda pode ser contornada por outro caminho de escrita. curl -X POST 'https://auth.asender.net/v1/tenants/id_AQUI/produtos' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/users Cria um usuário. Respostas: 201 Criado.; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401` — token de serviço ausente ou inválido. **Não ocorre com `ENV=development`.**; 409 `409 Conflict` — email já cadastrado.; 500 `500 InternalError`. **DIVERGÊNCIA:** o `Message` recebe `err.Error()` CRU, como no `asender-core`. Pode vazar estrutura interna. curl -X POST 'https://auth.asender.net/v1/users' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/users/{id} Um usuário pelo public id. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 `401` — token de serviço ausente ou inválido. **Não ocorre com `ENV=development`.**; 404 `404 NotFound`. curl -X GET 'https://auth.asender.net/v1/users/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### PATCH /v1/users/{id} Altera nome e/ou email. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 400 `400` — `InvalidRequest` (JSON inválido, **campo desconhecido**, corpo vazio, corpo acima de 1 MiB), `InvalidInput` (validação de domínio) ou `TwoFactorMissing` (2FA não configurado).; 401 `401` — token de serviço ausente ou inválido. **Não ocorre com `ENV=development`.**; 404 `404 NotFound`.; 409 `409 Conflict` — email já cadastrado. curl -X PATCH 'https://auth.asender.net/v1/users/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/users/{id} Remove o usuário. Parâmetros: id (path, obrigatório) Respostas: 204 Removido.; 401 `401` — token de serviço ausente ou inválido. **Não ocorre com `ENV=development`.**; 404 `404 NotFound`. curl -X DELETE 'https://auth.asender.net/v1/users/id_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### GET /v1/users/{id}/emails Listar devolve os e-mails do usuário. Onde é usada: GET /v1/users/{id}/emails. curl -X GET 'https://auth.asender.net/v1/users/id_AQUI/emails' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /v1/users/{id}/emails Adicionar cria um e-mail secundário (não-verificado) e dispara a verificação. Onde é usada: POST /v1/users/{id}/emails {email}. curl -X POST 'https://auth.asender.net/v1/users/id_AQUI/emails' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/users/{id}/emails/{emailId} Remover apaga um e-mail secundário. Onde é usada: DELETE /v1/users/{id}/emails/{emailId}. curl -X DELETE 'https://auth.asender.net/v1/users/id_AQUI/emails/emailId_AQUI' \ -H 'Authorization: Bearer SEU_TOKEN' ### POST /v1/users/{id}/emails/{emailId}/primary DefinirPrimario promove um e-mail verificado a primário. Onde é usada: POST /v1/users/{id}/emails/{emailId}/primary. curl -X POST 'https://auth.asender.net/v1/users/id_AQUI/emails/emailId_AQUI/primary' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/users/{id}/emails/{emailId}/verify/resend Reenviar redispara a verificação de um e-mail. Onde é usada: POST /v1/users/{id}/emails/{emailId}/verify/resend. curl -X POST 'https://auth.asender.net/v1/users/id_AQUI/emails/emailId_AQUI/verify/resend' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/users/{id}/verify/resend Reenvia o e-mail de verificação de um usuário. Onde é usada: POST /v1/users/{id}/emails/{emailId}/verify/resend. Parâmetros: id (path, obrigatório) Respostas: 200 OK; 401 credencial ausente ou inválida curl -X POST 'https://auth.asender.net/v1/users/id_AQUI/verify/resend' \ -H 'Authorization: Bearer SEU_TOKEN' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -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. Respostas: 200 OK curl -X GET 'https://auth.asender.net/version' \ -H 'Authorization: Bearer SEU_TOKEN' ============================================================================== # CRM (https://api.crm.asender.net) ============================================================================== ### GET /healthz responde 200 enquanto o processo está vivo. Não toca dependência: um liveness que consulta o banco derruba o pod quando o banco oscila. Onde é usada: rota pública /healthz. Efeitos: escreve JSON na resposta. curl -X GET 'https://api.crm.asender.net/healthz' ### GET /readyz 503 `starting` antes do fim do boot; depois disso, CONSULTA as sondas e responde 200 `ready` ou 503 `degraded` com o nome de cada dependência. Onde é usada: rota pública /readyz. Efeitos: escreve JSON na resposta; pode tocar a dependência (com cache de 1s). # Por que ele não é mais um trinco de boot A readiness era `MarkReady()` uma vez e pronto — memória do boot, não estado atual. Num incidente real de 2026-08-27 o serviço voltou com a credencial errada do Postgres, falhou ~30 vezes por minuto ao drenar o outbox, e /healthz e /readyz responderam 200 o tempo todo: o gate de saúde do deploy passou e quem descobriu foi o pentest, depois. Readiness que só lembra do boot não enxerga a dependência que caiu DEPOIS dele. /healthz continua sem tocar em nada, e isso é de propósito: liveness que consulta o banco derruba o processo quando o banco oscila. Quem tem de dizer "não me mande tráfego" é o readiness. O que sai na resposta é o NOME da dependência e "indisponível" — nunca a mensagem do driver, que carrega usuário, host e base. Rota pública não conta topologia; o erro inteiro vai para o log. curl -X GET 'https://api.crm.asender.net/readyz' ### GET /v1/alertas GET /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma leitura. curl -X GET 'https://api.crm.asender.net/v1/alertas' ### POST /v1/alertas POST /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X POST 'https://api.crm.asender.net/v1/alertas' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### PUT /v1/alertas/{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 PUT 'https://api.crm.asender.net/v1/alertas/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/alertas/{id} DELETE /v1/alertas/{id}. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X DELETE 'https://api.crm.asender.net/v1/alertas/id_AQUI' ### GET /v1/alertas/eventos GET /v1/alertas/eventos?limite=N. 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. curl -X GET 'https://api.crm.asender.net/v1/alertas/eventos' ### GET /v1/configuracoes/retencao GET /v1/configuracoes/retencao. 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. curl -X GET 'https://api.crm.asender.net/v1/configuracoes/retencao' ### PUT /v1/configuracoes/retencao PUT /v1/configuracoes/retencao com `{"dias": 90}` ou `{"dias": null}`. 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. curl -X PUT 'https://api.crm.asender.net/v1/configuracoes/retencao' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/contatos GET /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma leitura. curl -X GET 'https://api.crm.asender.net/v1/contatos' ### POST /v1/contatos POST /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X POST 'https://api.crm.asender.net/v1/contatos' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/contatos/{id} GET /v1/contatos/{id}/consentimento. Onde é usada: tela de contato, seção de preferências. Efeitos: uma leitura. Responde TODOS os canais conhecidos, inclusive os sem opt-out. Devolver só os que saíram faria a tela ter de saber a lista completa para desenhar as caixas — e a primeira que ficasse desatualizada esconderia um canal do operador. curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI' ### PATCH /v1/contatos/{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/contatos/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/contatos/{id} DELETE /v1/alertas/{id}. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X DELETE 'https://api.crm.asender.net/v1/contatos/id_AQUI' ### GET /v1/contatos/{id}/atividades GET /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma leitura. curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI/atividades' ### POST /v1/contatos/{id}/atividades POST /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X POST 'https://api.crm.asender.net/v1/contatos/id_AQUI/atividades' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/contatos/{id}/consentimento GET /v1/contatos/{id}/consentimento. Onde é usada: tela de contato, seção de preferências. Efeitos: uma leitura. Responde TODOS os canais conhecidos, inclusive os sem opt-out. Devolver só os que saíram faria a tela ter de saber a lista completa para desenhar as caixas — e a primeira que ficasse desatualizada esconderia um canal do operador. curl -X GET 'https://api.crm.asender.net/v1/contatos/id_AQUI/consentimento' ### PUT /v1/contatos/{id}/consentimento PUT /v1/contatos/{id}/consentimento. 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. curl -X PUT 'https://api.crm.asender.net/v1/contatos/id_AQUI/consentimento' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/contatos/exportar.csv GET /v1/contatos/exportar.csv?limite=N. 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. curl -X GET 'https://api.crm.asender.net/v1/contatos/exportar.csv' ### GET /v1/destinos GET /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma leitura. curl -X GET 'https://api.crm.asender.net/v1/destinos' ### POST /v1/destinos POST /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X POST 'https://api.crm.asender.net/v1/destinos' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### PUT /v1/destinos/{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 PUT 'https://api.crm.asender.net/v1/destinos/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/destinos/{id} DELETE /v1/alertas/{id}. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X DELETE 'https://api.crm.asender.net/v1/destinos/id_AQUI' ### GET /v1/destinos/{id}/entregas GET /v1/destinos/{id}/entregas?limite=N. 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. curl -X GET 'https://api.crm.asender.net/v1/destinos/id_AQUI/entregas' ### POST /v1/destinos/{id}/testar POST /v1/destinos/{id}/testar. 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. curl -X POST 'https://api.crm.asender.net/v1/destinos/id_AQUI/testar' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/integracoes-de-conversao GET /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma leitura. curl -X GET 'https://api.crm.asender.net/v1/integracoes-de-conversao' ### POST /v1/integracoes-de-conversao POST /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X POST 'https://api.crm.asender.net/v1/integracoes-de-conversao' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### PUT /v1/integracoes-de-conversao/{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 PUT 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/integracoes-de-conversao/{id} DELETE /v1/alertas/{id}. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X DELETE 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI' ### GET /v1/integracoes-de-conversao/{id}/entregas GET /v1/destinos/{id}/entregas?limite=N. 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. curl -X GET 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI/entregas' ### POST /v1/integracoes-de-conversao/{id}/testar POST /v1/destinos/{id}/testar. 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. curl -X POST 'https://api.crm.asender.net/v1/integracoes-de-conversao/id_AQUI/testar' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/jornadas GET /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma leitura. curl -X GET 'https://api.crm.asender.net/v1/jornadas' ### POST /v1/jornadas POST /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X POST 'https://api.crm.asender.net/v1/jornadas' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/jornadas/{id} GET /v1/contatos/{id}/consentimento. Onde é usada: tela de contato, seção de preferências. Efeitos: uma leitura. Responde TODOS os canais conhecidos, inclusive os sem opt-out. Devolver só os que saíram faria a tela ter de saber a lista completa para desenhar as caixas — e a primeira que ficasse desatualizada esconderia um canal do operador. curl -X GET 'https://api.crm.asender.net/v1/jornadas/id_AQUI' ### PUT /v1/jornadas/{id}/ativa PUT /v1/jornadas/{id}/ativa. 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. curl -X PUT 'https://api.crm.asender.net/v1/jornadas/id_AQUI/ativa' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/segmentos GET /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma leitura. curl -X GET 'https://api.crm.asender.net/v1/segmentos' ### POST /v1/segmentos POST /v1/alertas. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X POST 'https://api.crm.asender.net/v1/segmentos' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/segmentos/{id} GET /v1/contatos/{id}/consentimento. Onde é usada: tela de contato, seção de preferências. Efeitos: uma leitura. Responde TODOS os canais conhecidos, inclusive os sem opt-out. Devolver só os que saíram faria a tela ter de saber a lista completa para desenhar as caixas — e a primeira que ficasse desatualizada esconderia um canal do operador. curl -X GET 'https://api.crm.asender.net/v1/segmentos/id_AQUI' ### PUT /v1/segmentos/{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 PUT 'https://api.crm.asender.net/v1/segmentos/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/segmentos/{id} DELETE /v1/alertas/{id}. Onde é usada: tela de alertas. Efeitos: uma escrita. curl -X DELETE 'https://api.crm.asender.net/v1/segmentos/id_AQUI' ### POST /v1/segmentos/previa POST /v1/segmentos/previa. 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". curl -X POST 'https://api.crm.asender.net/v1/segmentos/previa' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/uso GET /v1/uso?periodo=YYYY-MM — números locais do CRM mais a quota e os contadores 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). curl -X GET 'https://api.crm.asender.net/v1/uso' ============================================================================== # Páginas (https://api.pages.asender.net) ============================================================================== ### GET /healthz responde 200 enquanto o processo está vivo. Não toca dependência: um liveness que consulta o banco derruba o pod quando o banco oscila. Onde é usada: rota pública /healthz. Efeitos: escreve JSON na resposta. curl -X GET 'https://api.pages.asender.net/healthz' ### GET /internal/v1/formularios/{id} GET /internal/v1/formularios/{id}. Onde é usada: chamado pelo `asender_runtime` para validar uma submissão. Efeitos: uma leitura. # Sem o tenant na rota, de propósito No modo SNIPPET o formulário está embutido no site de um terceiro e quem posta é o navegador de um visitante anônimo. O runtime não sabe de qual conta é o formulário — a conta é a RESPOSTA, tirada dele. Exigir o tenant na rota tornaria esta chamada impossível de fazer. Isto não afrouxa nada: o `public_id` é opaco e já está no HTML de quem visita o site. Quem o conhece já podia postar nele. O que protege esta rota é a credencial de serviço — sem ela, ela não responde nada. curl -X GET 'https://api.pages.asender.net/internal/v1/formularios/id_AQUI' ### GET /internal/v1/paginas GET /internal/v1/paginas?dominio=&slug=. Onde é usada: chamado pelo `asender_runtime` a cada requisição de página pública. Efeitos: uma leitura. # Query string e não caminho O domínio contém pontos e o slug pode conter hífen; os dois em segmentos de rota exigiriam escape que o roteador desfaz de formas diferentes conforme a versão. Query string é literal, e o que trafega aqui é rede interna. curl -X GET 'https://api.pages.asender.net/internal/v1/paginas' ### POST /internal/v1/paginas/{id}/cliques POST /internal/v1/paginas/{id}/cliques. Onde é usada: descarga periódica do contador em memória do `asender_runtime`. Efeitos: uma escrita por destino, somando ao que já existe. # Soma, e não atribui O corpo traz o DELTA do lote, nunca um total. Dois processos do runtime descarregando ao mesmo tempo somam certo; com atribuição, o último a escrever apagaria a contagem do outro — e o relatório mostraria menos visitas do que houve, sem nada indicar a perda. # Teto de destinos no corpo O mapa vem da rede. Sem teto, um lote com um milhão de chaves viraria um milhão de `INSERT` numa transação só. O teto é o mesmo do roteamento (20 destinos), porque é o máximo que uma página pode ter. curl -X POST 'https://api.pages.asender.net/internal/v1/paginas/id_AQUI/cliques' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /internal/v1/paginas/publicadas GET /internal/v1/paginas/publicadas?dominio=. Onde é usada: chamado pelo `asender_runtime` para montar `/sitemap.xml`. Efeitos: uma leitura. Devolve só slug e data: o sitemap não precisa de título nem template, e cada campo a mais seria dado do cliente saindo por uma rota que qualquer visitante alcança pelo runtime. Domínio sem página responde lista VAZIA, e não 404: "este host não tem página publicada" é uma resposta sobre o mundo, e o runtime precisa dela para devolver um sitemap vazio em vez de um erro. curl -X GET 'https://api.pages.asender.net/internal/v1/paginas/publicadas' ### GET /internal/v1/redirects GET /internal/v1/redirects?dominio=&slug=. Onde é usada: chamado pelo `asender_runtime` a cada clique. Efeitos: uma leitura. Não devolve o `tenant_id`: quem serve o redirect não precisa saber de quem ele é, e devolvê-lo daria a um visitante um mapa de qual conta encurta o quê. curl -X GET 'https://api.pages.asender.net/internal/v1/redirects' ### POST /internal/v1/redirects/cliques POST /internal/v1/redirects/cliques. Onde é usada: descarga periódica do contador em memória do runtime. Efeitos: uma escrita por link. SOMA, e não atribui: dois processos do runtime descarregando ao mesmo tempo somam certo; com atribuição, o último a escrever apagaria a contagem do outro. curl -X POST 'https://api.pages.asender.net/internal/v1/redirects/cliques' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /internal/v1/tls/authorize GET /internal/v1/tls/authorize?host=. Onde é usada: o servidor de borda, no meio do handshake TLS. Efeitos: uma consulta. # Fail-closed, e a resposta é um booleano Host desconhecido é `false` — negar é a resposta correta. Falha nossa é 503, e NÃO `false`: o servidor de borda tem de distinguir "não autorizado" de "não consegui decidir", senão um soluço de banco viraria recusa de certificado para domínio legítimo. A resposta não carrega tenant nem token. Quem monta o handshake não precisa disso, e devolvê-lo daria a quem sonda um mapa de quais domínios pertencem à plataforma. curl -X GET 'https://api.pages.asender.net/internal/v1/tls/authorize' ### GET /readyz 503 `starting` antes do fim do boot; depois disso, CONSULTA as sondas e responde 200 `ready` ou 503 `degraded` com o nome de cada dependência. Onde é usada: rota pública /readyz. Efeitos: escreve JSON na resposta; pode tocar a dependência (com cache de 1s). # Por que ele não é mais um trinco de boot A readiness era `MarkReady()` uma vez e pronto — memória do boot, não estado atual. Num incidente real de 2026-08-27 o serviço voltou com a credencial errada do Postgres, falhou ~30 vezes por minuto ao drenar o outbox, e /healthz e /readyz responderam 200 o tempo todo: o gate de saúde do deploy passou e quem descobriu foi o pentest, depois. Readiness que só lembra do boot não enxerga a dependência que caiu DEPOIS dele. /healthz continua sem tocar em nada, e isso é de propósito: liveness que consulta o banco derruba o processo quando o banco oscila. Quem tem de dizer "não me mande tráfego" é o readiness. O que sai na resposta é o NOME da dependência e "indisponível" — nunca a mensagem do driver, que carrega usuário, host e base. Rota pública não conta topologia; o erro inteiro vai para o log. curl -X GET 'https://api.pages.asender.net/readyz' ### GET /v1/configuracoes/marca GET /v1/paginas/{id}/experimento. 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. curl -X GET 'https://api.pages.asender.net/v1/configuracoes/marca' ### PUT /v1/configuracoes/marca PUT /v1/configuracoes/marca — os quatro campos de uma vez. Onde é usada: tela de marca do painel. Efeitos: uma escrita; muda o que o visitante vê na próxima visita. PUT e não PATCH: são quatro campos que a tela mostra e salva juntos, e campo vazio APAGA aquele elemento. Um PATCH criaria a pergunta "como apago o logo?", cuja resposta seria um campo especial que ninguém acerta na primeira leitura. curl -X PUT 'https://api.pages.asender.net/v1/configuracoes/marca' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/dominios GET /v1/dominios. Onde é usada: tela de domínios. Efeitos: uma leitura. curl -X GET 'https://api.pages.asender.net/v1/dominios' ### POST /v1/dominios POST /v1/dominios. 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. curl -X POST 'https://api.pages.asender.net/v1/dominios' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/dominios/{id} DELETE /v1/dominios/{id}. 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ê. curl -X DELETE 'https://api.pages.asender.net/v1/dominios/id_AQUI' ### POST /v1/dominios/{id}/verificar POST /v1/dominios/{id}/verificar. Onde é usada: botão "verificar" da tela de domínios. Efeitos: uma consulta DNS e uma escrita. # As duas falhas têm respostas DIFERENTES "Não consegui perguntar ao DNS" é 503 com "tente de novo"; "perguntei e o registro não está lá" é 422 com "publique o registro". Colapsar as duas faria o cliente ficar publicando um registro que já está lá. # E o resultado é GRAVADO nos dois casos Sem isso, quem tenta e falha vê a tela exatamente igual à de antes de tentar — e não tem como saber se o sistema chegou a olhar. curl -X POST 'https://api.pages.asender.net/v1/dominios/id_AQUI/verificar' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/formularios GET /v1/dominios. Onde é usada: tela de domínios. Efeitos: uma leitura. curl -X GET 'https://api.pages.asender.net/v1/formularios' ### POST /v1/formularios POST /v1/dominios. 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. curl -X POST 'https://api.pages.asender.net/v1/formularios' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/formularios/{id} GET /v1/paginas/{id}/experimento. 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. curl -X GET 'https://api.pages.asender.net/v1/formularios/id_AQUI' ### PUT /v1/formularios/{id} PUT /v1/formularios/{id}. Onde é usada: edição. Efeitos: escreve a linha. curl -X PUT 'https://api.pages.asender.net/v1/formularios/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/formularios/{id} DELETE /v1/dominios/{id}. 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ê. curl -X DELETE 'https://api.pages.asender.net/v1/formularios/id_AQUI' ### POST /v1/ia/gerar-pagina POST /v1/paginas/gerar — manda o pedido ao provedor, saneia a saída e devolve o template. 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). curl -X POST 'https://api.pages.asender.net/v1/ia/gerar-pagina' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/midias GET /v1/dominios. Onde é usada: tela de domínios. Efeitos: uma leitura. curl -X GET 'https://api.pages.asender.net/v1/midias' ### POST /v1/midias POST /v1/midias (multipart, campo `arquivo`). 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. curl -X POST 'https://api.pages.asender.net/v1/midias' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/midias/{id} DELETE /v1/dominios/{id}. 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ê. curl -X DELETE 'https://api.pages.asender.net/v1/midias/id_AQUI' ### POST /v1/midias/de-url POST /v1/midias/de-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. curl -X POST 'https://api.pages.asender.net/v1/midias/de-url' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/paginas GET /v1/dominios. Onde é usada: tela de domínios. Efeitos: uma leitura. curl -X GET 'https://api.pages.asender.net/v1/paginas' ### POST /v1/paginas POST /v1/dominios. 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. curl -X POST 'https://api.pages.asender.net/v1/paginas' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/paginas/{id} GET /v1/paginas/{id}/experimento. 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. curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI' ### PATCH /v1/paginas/{id} PATCH /v1/paginas/{id} — renomear, mudar o endereço público ou o domínio. 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. curl -X PATCH 'https://api.pages.asender.net/v1/paginas/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/paginas/{id}/ab/promover POST /v1/paginas/{id}/ab/promover. Onde é usada: botão "promover vencedora" e botão "iniciar teste" da tela de A/B. Efeitos: uma escrita. # 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. curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/ab/promover' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/paginas/{id}/cliques GET /v1/redirects/{id}/cliques. 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. curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/cliques' ### GET /v1/paginas/{id}/experimento GET /v1/paginas/{id}/experimento. 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. curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/experimento' ### PUT /v1/paginas/{id}/experimento/auto-stop PUT /v1/paginas/{id}/experimento/auto-stop. Onde é usada: tela de A/B. Efeitos: uma escrita. Aceito com o teste RODANDO, ao contrário das variantes: apertar o critério não reatribui visitante nem invalida amostra — só muda quando o job pode concluir. curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/experimento/auto-stop' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/paginas/{id}/publicar POST /v1/paginas/{id}/publicar. Onde é usada: botão publicar. Efeitos: move o ponteiro da página; o visitante passa a ver esta versão. curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/publicar' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/paginas/{id}/roteamento GET /v1/paginas/{id}/experimento. 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. curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/roteamento' ### PUT /v1/paginas/{id}/roteamento POST /v1/paginas/{id}/versoes. Onde é usada: botão salvar do editor. Efeitos: cria uma versão. curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/roteamento' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/paginas/{id}/roteamento DELETE /v1/dominios/{id}. 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ê. curl -X DELETE 'https://api.pages.asender.net/v1/paginas/id_AQUI/roteamento' ### GET /v1/paginas/{id}/variantes GET /v1/paginas/{id}/variantes. Onde é usada: tela de A/B. Efeitos: uma leitura. curl -X GET 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes' ### POST /v1/paginas/{id}/variantes POST /v1/paginas/{id}/variantes. Onde é usada: botão "nova variante" da tela de A/B. Efeitos: uma ou duas escritas. # O experimento nasce aqui, e em rascunho Exigir uma chamada de "criar experimento" antes da primeira variante daria ao operador um objeto vazio que não mede nada e que ele teria de lembrar de apagar. A primeira variante cria o teste. curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### PUT /v1/paginas/{id}/variantes/{varianteID} PUT /v1/paginas/{id}/variantes/{varianteID}. Onde é usada: ajustar peso ou versão na tela de A/B. Efeitos: uma escrita. curl -X PUT 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes/varianteID_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/paginas/{id}/variantes/{varianteID} DELETE /v1/paginas/{id}/variantes/{varianteID}. Onde é usada: tela de A/B. Efeitos: uma escrita. curl -X DELETE 'https://api.pages.asender.net/v1/paginas/id_AQUI/variantes/varianteID_AQUI' ### POST /v1/paginas/{id}/versoes POST /v1/paginas/{id}/versoes. Onde é usada: botão salvar do editor. Efeitos: cria uma versão. curl -X POST 'https://api.pages.asender.net/v1/paginas/id_AQUI/versoes' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/public/midias/{id} GET e HEAD /v1/public/midias/{id}. Onde é usada: a tag `` 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. curl -X GET 'https://api.pages.asender.net/v1/public/midias/id_AQUI' ### GET /v1/redirects GET /v1/dominios. Onde é usada: tela de domínios. Efeitos: uma leitura. curl -X GET 'https://api.pages.asender.net/v1/redirects' ### POST /v1/redirects POST /v1/dominios. 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. curl -X POST 'https://api.pages.asender.net/v1/redirects' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/redirects/{id} GET /v1/paginas/{id}/experimento. 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. curl -X GET 'https://api.pages.asender.net/v1/redirects/id_AQUI' ### PUT /v1/redirects/{id} PUT /v1/formularios/{id}. Onde é usada: edição. Efeitos: escreve a linha. curl -X PUT 'https://api.pages.asender.net/v1/redirects/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/redirects/{id} DELETE /v1/dominios/{id}. 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ê. curl -X DELETE 'https://api.pages.asender.net/v1/redirects/id_AQUI' ### GET /v1/redirects/{id}/cliques GET /v1/redirects/{id}/cliques. 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. curl -X GET 'https://api.pages.asender.net/v1/redirects/id_AQUI/cliques' ============================================================================== # Publicação e analytics (https://api.sites.asender.net) ============================================================================== ### GET / resolve host+caminho na página publicada e devolve o HTML renderizado. Onde é usada: rota curinga do runtime, a de maior tráfego do sistema. Efeitos: consulta a fonte; escreve a resposta. 404 quando não há página: o host pode apontar para nós sem ter página naquele caminho, e devolver erro de servidor nesse caso confundiria monitoramento com tráfego normal de quem digitou a URL errada. curl -X GET 'https://api.sites.asender.net/' ### 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.sites.asender.net/' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /{slug} resolve host+caminho na página publicada e devolve o HTML renderizado. Onde é usada: rota curinga do runtime, a de maior tráfego do sistema. Efeitos: consulta a fonte; escreve a resposta. 404 quando não há página: o host pode apontar para nós sem ter página naquele caminho, e devolver erro de servidor nesse caso confundiria monitoramento com tráfego normal de quem digitou a URL errada. curl -X GET 'https://api.sites.asender.net/slug_AQUI' ### 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.sites.asender.net/slug_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /collect POST /collect — abre a credencial, normaliza cada evento e publica. 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. curl -X POST 'https://api.sites.asender.net/collect' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /f/{formID} valida a ORIGEM contra os domínios verificados do tenant, ecoa os cabeçalhos de CORS e chama o mesmo pipeline. 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. curl -X POST 'https://api.sites.asender.net/f/formID_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /healthz responde 200 enquanto o processo está vivo. Não toca dependência: um liveness que consulta o banco derruba o pod quando o banco oscila. Onde é usada: rota pública /healthz. Efeitos: escreve JSON na resposta. curl -X GET 'https://api.sites.asender.net/healthz' ### GET /pixel.js GET /pixel.js. Onde é usada: toda página publicada, uma vez por visita (depois é cache). 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. curl -X GET 'https://api.sites.asender.net/pixel.js' ### GET /r/{slug} resolve host+caminho na página publicada e devolve o HTML renderizado. Onde é usada: rota curinga do runtime, a de maior tráfego do sistema. Efeitos: consulta a fonte; escreve a resposta. 404 quando não há página: o host pode apontar para nós sem ter página naquele caminho, e devolver erro de servidor nesse caso confundiria monitoramento com tráfego normal de quem digitou a URL errada. curl -X GET 'https://api.sites.asender.net/r/slug_AQUI' ### GET /readyz 503 `starting` antes do fim do boot; depois disso, CONSULTA as sondas e responde 200 `ready` ou 503 `degraded` com o nome de cada dependência. Onde é usada: rota pública /readyz. Efeitos: escreve JSON na resposta; pode tocar a dependência (com cache de 1s). # Por que ele não é mais um trinco de boot A readiness era `MarkReady()` uma vez e pronto — memória do boot, não estado atual. Num incidente real de 2026-08-27 o serviço voltou com a credencial errada do Postgres, falhou ~30 vezes por minuto ao drenar o outbox, e /healthz e /readyz responderam 200 o tempo todo: o gate de saúde do deploy passou e quem descobriu foi o pentest, depois. Readiness que só lembra do boot não enxerga a dependência que caiu DEPOIS dele. /healthz continua sem tocar em nada, e isso é de propósito: liveness que consulta o banco derruba o processo quando o banco oscila. Quem tem de dizer "não me mande tráfego" é o readiness. O que sai na resposta é o NOME da dependência e "indisponível" — nunca a mensagem do driver, que carrega usuário, host e base. Rota pública não conta topologia; o erro inteiro vai para o log. curl -X GET 'https://api.sites.asender.net/readyz' ### POST /replay POST /replay — abre a credencial, saneia e publica. 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. curl -X POST 'https://api.sites.asender.net/replay' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /robots.txt libera a indexação e aponta o sitemap do MESMO host. Onde é usada: rota pública. Efeitos: nenhum. # Por que liberar, e não bloquear A página existe para ser achada: é landing page de campanha, e quem a publica quer tráfego. Um `Disallow: /` como padrão transformaria uma decisão de produto ("esta página não deve ser indexada") em comportamento da plataforma — e o cliente descobriria meses depois, sem entender por que o anúncio orgânico nunca apareceu. 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.sites.asender.net/robots.txt' ### GET /sitemap.xml lista as páginas PUBLICADAS daquele host. Onde é usada: rota pública. Efeitos: uma leitura no `asender_pages`. # 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` 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.sites.asender.net/sitemap.xml' ### GET /v1/analytics/ab GET /v1/analytics/ab?pagina=. Onde é usada: tela do experimento. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/analytics/ab' ### GET /v1/analytics/breakdown GET /v1/analytics/breakdown?dimensao=utm_source&… Onde é usada: tela de origens. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/analytics/breakdown' ### GET /v1/analytics/events GET /v1/analytics/events?pagina=&limite=. Onde é usada: tela de depuração da instrumentação. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/analytics/events' ### GET /v1/analytics/heatmap GET /v1/analytics/heatmap?pagina=&lado=. 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. curl -X GET 'https://api.sites.asender.net/v1/analytics/heatmap' ### GET /v1/analytics/live GET /v1/analytics/live — sessões e eventos da janela curta. 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. curl -X GET 'https://api.sites.asender.net/v1/analytics/live' ### GET /v1/analytics/live/stream GET /v1/analytics/live/stream — Server-Sent Events. 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. curl -X GET 'https://api.sites.asender.net/v1/analytics/live/stream' ### GET /v1/analytics/overview GET /v1/analytics/overview?pagina=&de=&ate=. 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. curl -X GET 'https://api.sites.asender.net/v1/analytics/overview' ### GET /v1/analytics/session/{id} GET /v1/analytics/session/{id}. 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. curl -X GET 'https://api.sites.asender.net/v1/analytics/session/id_AQUI' ### GET /v1/analytics/traffic-quality GET /v1/analytics/traffic-quality. Onde é usada: tela de qualidade — "esse tráfego pago é gente?". Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/analytics/traffic-quality' ### POST /v1/forms/{formID}/submissions autentica por API key (resolvida pelo middleware), lê o JSON e chama o pipeline. 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. curl -X POST 'https://api.sites.asender.net/v1/forms/formID_AQUI/submissions' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### POST /v1/leads autentica por API key (resolvida pelo middleware), lê o JSON e chama o pipeline. 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. curl -X POST 'https://api.sites.asender.net/v1/leads' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/pixels GET /v1/pixels. Onde é usada: tela de pixels. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/pixels' ### POST /v1/pixels POST /v1/pixels. Onde é usada: tela de pixels. Efeitos: uma escrita. curl -X POST 'https://api.sites.asender.net/v1/pixels' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### GET /v1/pixels/{id} GET /v1/pixels/{id}. Onde é usada: tela de detalhe do pixel. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/pixels/id_AQUI' ### PATCH /v1/pixels/{id} PATCH /v1/pixels/{id}. 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. curl -X PATCH 'https://api.sites.asender.net/v1/pixels/id_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/pixels/{id} DELETE /v1/pixels/{id}. Onde é usada: tela de detalhe. Efeitos: uma escrita; a coleta daquele pixel para. curl -X DELETE 'https://api.sites.asender.net/v1/pixels/id_AQUI' ### GET /v1/pixels/{id}/conversions GET /v1/pixels/{id}/conversions. Onde é usada: tela de detalhe. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/pixels/id_AQUI/conversions' ### POST /v1/pixels/{id}/conversions POST /v1/pixels/{id}/conversions. Onde é usada: tela de detalhe. Efeitos: uma escrita. curl -X POST 'https://api.sites.asender.net/v1/pixels/id_AQUI/conversions' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### PATCH /v1/pixels/{id}/conversions/{cid} PATCH /v1/pixels/{id}/conversions/{cid}. Onde é usada: tela de detalhe. Efeitos: uma escrita. curl -X PATCH 'https://api.sites.asender.net/v1/pixels/id_AQUI/conversions/cid_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/pixels/{id}/conversions/{cid} DELETE /v1/pixels/{id}/conversions/{cid}. Onde é usada: tela de detalhe. Efeitos: uma escrita. curl -X DELETE 'https://api.sites.asender.net/v1/pixels/id_AQUI/conversions/cid_AQUI' ### GET /v1/pixels/{id}/domains GET /v1/pixels/{id}/domains. Onde é usada: tela de detalhe. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/pixels/id_AQUI/domains' ### POST /v1/pixels/{id}/domains POST /v1/pixels/{id}/domains. Onde é usada: tela de detalhe. Efeitos: uma escrita — e, a partir dela, o `/collect` ecoa CORS para aquele host. curl -X POST 'https://api.sites.asender.net/v1/pixels/id_AQUI/domains' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### PATCH /v1/pixels/{id}/domains/{domainId} PATCH /v1/pixels/{id}/domains/{domainId}. Onde é usada: tela de detalhe. Efeitos: uma escrita. curl -X PATCH 'https://api.sites.asender.net/v1/pixels/id_AQUI/domains/domainId_AQUI' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ }' ### DELETE /v1/pixels/{id}/domains/{domainId} DELETE /v1/pixels/{id}/domains/{domainId}. Onde é usada: tela de detalhe. Efeitos: uma escrita — a origem para de coletar na hora. curl -X DELETE 'https://api.sites.asender.net/v1/pixels/id_AQUI/domains/domainId_AQUI' ### GET /v1/replay/sessions GET /v1/replay/sessions?limite=N. Onde é usada: tela de replay. Efeitos: uma leitura. curl -X GET 'https://api.sites.asender.net/v1/replay/sessions' ### GET /v1/replay/sessions/{id}/events GET /v1/replay/sessions/{id}/events. 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. curl -X GET 'https://api.sites.asender.net/v1/replay/sessions/id_AQUI/events' ### 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.sites.asender.net/version' ============================================================================== # SCHEMAS (OpenAPI) ============================================================================== { "api_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" } } }, "api_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).\n" } } }, "api_CursorPage": { "type": "object", "properties": { "NextCursor": { "type": "integer", "description": "Cursor da próxima página; 0 quando acabou." }, "HasMore": { "type": "boolean" } } }, "api_Channel": { "type": "string", "enum": [ "email", "sms", "push" ] }, "api_MessageStatus": { "type": "string", "enum": [ "queued", "sending", "sent", "delivered", "bounced", "failed", "opened", "clicked" ] }, "api_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/Channel" }, "Status": { "$ref": "#/components/schemas/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" ] }, "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" } } }, "api_MessagePage": { "allOf": [ { "$ref": "#/components/schemas/RequestIdEnvelope" }, { "$ref": "#/components/schemas/CursorPage" }, { "type": "object", "properties": { "Messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } ] }, "api_MessageDetail": { "allOf": [ { "$ref": "#/components/schemas/RequestIdEnvelope" }, { "type": "object", "properties": { "Message": { "allOf": [ { "$ref": "#/components/schemas/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." } } } } } } ] }, "api_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" } } } }, "api_BatchResult": { "type": "object", "properties": { "Index": { "type": "integer" }, "Status": { "type": "string", "enum": [ "queued", "rejected", "failed" ] }, "MessageId": { "type": "string" }, "MessageIds": { "type": "array", "items": { "type": "string" } }, "Error": { "type": "object", "properties": { "Code": { "type": "string" }, "Message": { "type": "string" }, "Details": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "api_Template": { "type": "object", "properties": { "Id": { "type": "string" }, "TenantId": { "type": "string" }, "Slug": { "type": "string" }, "Name": { "type": "string" }, "Channel": { "$ref": "#/components/schemas/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" } } }, "api_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 } } }, "api_Contact": { "type": "object", "properties": { "Id": { "type": "string" }, "TenantId": { "type": "string" }, "Email": { "type": "string" }, "Phone": { "type": "string" }, "Name": { "type": "string" }, "Attributes": { "type": "object", "additionalProperties": true }, "Subscribed": { "type": "boolean" }, "UnsubscribedAt": { "type": [ "string", "null" ], "format": "date-time" }, "CreatedAt": { "type": "string", "format": "date-time" }, "UpdatedAt": { "type": "string", "format": "date-time" } } }, "api_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" } } }, "api_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" } } }, "api_Tenant": { "type": "object", "description": "Projeção do asender-core (`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" } } }, "api_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" } } }, "api_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" } } }, "api_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" } } }, "api_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`).\n", "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 } } }, "api_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" } } }, "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", "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" } } }, "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" } } }, "auth_UserIdBody": { "type": "object", "additionalProperties": false, "required": [ "user_id" ], "properties": { "user_id": { "type": "string" } } }, "auth_TwoFACodeBody": { "type": "object", "additionalProperties": false, "required": [ "user_id", "code" ], "properties": { "user_id": { "type": "string" }, "code": { "type": "string", "description": "TOTP de 6 dígitos." } } } }