Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

# Criar (sessão do usuário; devolve a chave em claro UMA vez)
curl -X POST 'https://api.asender.net/api/tenants/TENANT_ID/api-keys' \
  -H 'Content-Type: application/json' \
  --cookie 'asender_session=...' \
  -d '{ "name": "integração-2fa", "scopes": ["email:send"] }'

# `scopes` é obrigatório (veja a tabela de escopos); sem ele a emissão responde 400.

# Listar / revogar
curl 'https://api.asender.net/api/tenants/TENANT_ID/api-keys' --cookie '...'
curl -X DELETE 'https://api.asender.net/api/tenants/TENANT_ID/api-keys/KEY_ID' --cookie '...'

{ "Error": { "Type": "Sender", "Code": "Throttling", "Message": "Rate limit exceeded." }, "RequestId": "req_…" }

{
  "Error": {
    "Type": "Sender",
    "Code": "ValidationError",
    "Message": "One or more fields failed validation.",
    "Details": { "Destination.ToAddresses": "must contain at least one address" }
  },
  "RequestId": "req_a1b2c3"
}

curl -X POST 'https://api.asender.net/v1/emails/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f7c1e2a-…' \
  -d '{
    "Source": "campanhas@empresa.com.br",
    "Destination": { "ToAddresses": ["cliente@exemplo.test"] },
    "Message": {
      "Subject": { "Data": "Novidades de setembro" },
      "Body": { "Html": { "Data": "<h1>Olá</h1>" } }
    }
  }'

{ "MessageId": "…", "MessageIds": ["…"], "Status": "queued", "ReusedIdempotency": false, "RequestId": "req_…" }

{
  "Error": {
    "Type": "Sender",
    "Code": "RemetenteNaoVerificado",
    "Message": "O domínio empresa.com.br não está verificado nesta conta (SPF e DKIM). Verifique o domínio em Admin → Domínios (https://admin.asender.net/t/acc_123/dominios), ou use um remetente de um domínio já verificado. Nada foi enviado."
  },
  "RequestId": "req_…"
}

curl 'https://api.asender.net/v1/senders' -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx'

{
  "Domains": [
    { "Name": "empresa.com.br", "Verified": true, "UsableFor": ["emails/send"], "DnsStatus": "ok" },
    { "Name": "novo.com.br", "Verified": false, "UsableFor": [], "DnsStatus": "pending" }
  ],
  "Mailboxes": [
    { "Address": "no-reply@empresa.com.br", "UsableFor": ["emails/send", "mail:/v1/emails"] },
    { "Address": "oi@novo.com.br", "UsableFor": ["mail:/v1/emails"] }
  ],
  "RequestId": "req_…"
}

# Falhas de envio das últimas 24 h
curl 'https://api.asender.net/v1/logs?status_class=4xx,5xx&path=/v1/emails/send&limit=20' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'

# Próxima página
curl 'https://api.asender.net/v1/logs?status_class=4xx,5xx&after=cur_eyJ0Ijoi…' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'

{
  "object": "list",
  "has_more": true,
  "next": "cur_eyJ0Ijoi…",
  "data": [
    {
      "id": "log_3f9a1c0b2d4e5f60", "object": "log",
      "created_at": "2026-10-07T12:00:01Z",
      "method": "POST", "path": "/v1/emails/send", "route": "/v1/emails/send",
      "status": 422, "duration_ms": 38, "mode": "test",
      "api_key": { "id": "key_9", "name": "producao" },
      "idempotency_key": "pedido-1042", "error_code": "RemetenteNaoVerificado",
      "message_ids": [], "request_id": "req_abc123"
    }
  ]
}

curl 'https://api.asender.net/v1/logs?message_id=msg_01HXYZ' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'

curl 'https://api.asender.net/v1/logs/log_3f9a1c0b2d4e5f60' \
  -H 'Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx'

# Abrir conversa: template aprovado
curl -X POST 'https://api.asender.net/v1/whatsapp/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1042-aviso' \
  -d '{ "To": ["+5511999990000"], "Template": "promo_outubro", "Variables": { "1": "Ana", "2": "10%" } }'

curl -X POST 'https://api.asender.net/v1/push/send' \
  -H 'Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: aviso-1042' \
  -d '{ "DeviceTokens": ["<token do aparelho registrado>"], "Notification": { "Title": "Pedido enviado", "Body": "Chega amanhã." } }'

{
  "Error": {
    "Type": "Sender",
    "Code": "IdempotencyConflict",
    "Message": "The Idempotency-Key was already used with a different request body. Send a new key for a new message, or resend the original payload to replay it."
  },
  "RequestId": "req_…"
}

Estado do segundo fator do usuário da sessão.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/auth/2fa' \
  -H 'Authorization: Bearer SEU_TOKEN'

Segunda etapa do login — confirma o código do segundo fator.

Respostas

Exemplo

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

Troca o app pelo e-mail (não desliga o 2º fator).

Respostas

Exemplo

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

Reenvia o código de e-mail do 2º fator (método `email`).

Público como o /api/auth/2fa: a identidade vem do TICKET de desafio (corpo {TwoFactorToken}). 401 sem ticket; 429 no cap de emissões.

Respostas

Exemplo

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

Inicia a ativação do segundo fator.

Respostas

Exemplo

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

Confirma a ativação do segundo fator.

Respostas

Exemplo

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

Autentica e devolve o token de sessão.

Corpo aceito em snake_case ({"email","password"}) porque é o que o asender_auth_api define e o proxy repassa; a RESPOSTA é PascalCase.

Com 2FA habilitado a resposta é 200 com Token:"" e TwoFactorRequired:true — explícito, para o chamador não confundir com upstream quebrado.

Respostas

Exemplo

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

Revoga a sessão do Bearer apresentado. IDEMPOTENTE.

Revoga no asender_auth_api; a validação de sessão passou a consultar o estado, então o token deixa de valer (401 no /api/auth/me seguinte).

Esta rota fica FORA do grupo SessionAuth, de propósito — é o único caso em /api/*. Dentro do grupo, o segundo logout (retry, aba duplicada, refresh) morria em 401 no middleware, quebrando a idempotência de uma operação que descreve um ESTADO desejado ("estar fora"), não uma transição.

Consequência observável, e é por isso que a classe declarada é bearer-unverified e não session: o handler exige o header Authorization (sem ele, 401) mas não valida a sessão. Qualquer string não vazia como Bearer — inclusive uma API key ou lixo — recebe 200. Não abre nada (revogar um token que não existe é no-op no asender_auth_api), mas o 401 desta rota vem do HANDLER, não do middleware: quem for auditar a superfície não pode contá-la como autenticada.

Respostas

Exemplo

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

Principal da sessão.

TenantId vem do asender_auth_api e costuma vir vazio — a resolução real do tenant é feita por rota (resolveSessionTenant), a partir dos vínculos no core. Não use este campo como escopo.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/auth/me' \
  -H 'Authorization: Bearer SEU_TOKEN'

Altera o NOME do usuário da sessão.

Só Name. Email no corpo → 400 UseEmailsEndpoint (achado F1 da "Minha conta"): o e-mail só muda por /api/me/emails*, com reautenticação e verificação. Campo desconhecido → 400.

Respostas

Exemplo

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

E-mails de recuperação do usuário logado.

O sub vem SEMPRE da sessão (anti-IDOR): não há como listar os e-mails de outro usuário. Repassa ao asender_auth_api /v1/users/{sub}/emails.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/auth/me/emails' \
  -H 'Authorization: Bearer SEU_TOKEN'

Acrescenta um e-mail de recuperação ao usuário logado.

O sub vem da sessão. Corpo repassado ao asender_auth_api; JSON malformado é recusado AQUI com 400 (não vira 502).

Respostas

Exemplo

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

Remove um e-mail de recuperação do usuário logado.

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/auth/me/emails/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Promove um e-mail do usuário logado a primário.

Parâmetros

Respostas

Exemplo

curl -X POST 'https://api.asender.net/api/auth/me/emails/id_AQUI/primary' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Reenvia a verificação de um e-mail do usuário logado.

Parâmetros

Respostas

Exemplo

curl -X POST 'https://api.asender.net/api/auth/me/emails/id_AQUI/verify/resend' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Reenvia o e-mail de verificação do usuário da sessão.

Respostas

Exemplo

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

Termina o login com chave de acesso e devolve a sessão (formato do /api/auth/2fa).

Respostas

Exemplo

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

Começa o login SEM senha com chave de acesso (público, teto por IP do auth).

Corpo {origem} (o authfront põe a origem do browser, conferida contra o host). Sem e-mail: o autenticador escolhe a conta. Resposta do auth repassada: {desafio_id, opcoes}.

Respostas

Exemplo

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

Inicia a recuperação de senha (resposta neutra, não vaza se a conta existe).

Respostas

Exemplo

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

Redefine a senha pelo token do link (+ código 2FA quando a conta tem segundo fator).

Respostas

Exemplo

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

Dispara o código do 2º fator (canal e-mail) do reset em curso.

Pública como o resto do fluxo de reset: quem esqueceu a senha não tem sessão. Recebe o Token do reset em andamento e envia o OTP ao e-mail primário do dono do token. Resposta neutra — não confirma se o token vale. Disparo de e-mail (piso 18) e alvo de spam/amplificação, então no MESMO teto de rate-limit por IP das outras rotas de auth públicas.

Respostas

Exemplo

curl -X POST 'https://api.asender.net/api/auth/password-reset/send-otp' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Cria o usuário e, quando pode, o tenant raiz dele.

O status distingue os dois desfechos, e isso é contrato.

201 = usuário E conta criados. 202 = usuário criado, conta não — com um Reason do conjunto fechado DomainClaimed | TenantNameTaken | ProvisioningFailed | Invited (cadastro por convite, sem equipe de propósito: o próximo passo é o aceite). O cliente ramifica pelo Reason e leva a pessoa ao onboarding; tratar 202 como sucesso liso produz conta ÓRFÃ (relato do dono, 2026-09-17): usuário autenticado que não pertence a conta nenhuma, invisível para qualquer admin.

DomainClaimed significa que o domínio do e-mail pertence a uma conta que já o verificou. Não nasce workspace paralelo: nasce um pedido de entrada, e AccessRequestId o identifica.

O campo Note em prosa saiu: texto serve para mostrar, não para ramificar.

Respostas

Exemplo

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

Dispositivos e sessões ativas do usuário.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/auth/sessions' \
  -H 'Authorization: Bearer SEU_TOKEN'

Revoga uma sessão específica.

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/auth/sessions/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Confirma o e-mail a partir do token do link.

Respostas

Exemplo

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

Prévia do convite pelo token do link — PÚBLICA, teto por IP.

Pública por desenho: quem abre o link do convite ainda não tem sessão. O token (CSPRNG) é a credencial — só o portador vê o e-mail do PRÓPRIO convite. Não devolve token, id da conta nem quem convidou. Está na allowlist publicRoutes do routes_test.go.

HasAccount diz se o e-mail do convite já tem conta (a tela oferece "Entrar" ou "Criar conta com este e-mail"). Só é consultado com Status: pending; nos outros estados, e quando o asender_auth_api não responde (degradação graciosa), vem null.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/invitations/token_AQUI/preview' \
  -H 'Authorization: Bearer SEU_TOKEN'

As feature flags avaliadas para a conta da sessão.

A conta vem do token verificado. Core fora = {Flags: null, Degradado: true}: a tela usa o padrão dela (piso 10).

Respostas

Exemplo

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

Minha conta: usuário, fatores e reauth vigente (repasse de GET /v1/me).

Respostas

Exemplo

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

Troca o nome (repasse de PATCH /v1/me).

Respostas

Exemplo

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

Gera 10 códigos de recuperação (reauth totp|email_otp).

Respostas

Exemplo

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

Convites pendentes/expirados para os e-mails VERIFICADOS do usuário.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/me/convites' \
  -H 'Authorization: Bearer SEU_TOKEN'

Aceita convite por public_id (idempotente; herda acessos).

Parâmetros

Respostas

Exemplo

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

Recusa convite (idempotente).

Parâmetros

Respostas

Exemplo

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

Quantos convites pendentes (badge). Falha → `{pendentes:null}` 200.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/me/convites/contagem' \
  -H 'Authorization: Bearer SEU_TOKEN'

E-mails da conta.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/me/emails' \
  -H 'Authorization: Bearer SEU_TOKEN'

Adiciona e-mail — 202 neutro sempre (reauth totp se tiver, senão email_otp).

Respostas

Exemplo

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

Remove e-mail (reauth totp se tiver, senão email_otp).

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/me/emails/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Torna o e-mail primário (mesma reauth).

Parâmetros

Respostas

Exemplo

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

Reenvia a verificação.

Parâmetros

Respostas

Exemplo

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

Trilha de segurança paginada (só `antes` e `limite` atravessam).

Parâmetros

Respostas

Exemplo

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

Inventário de fatores + remoções pendentes (leitura).

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/me/fatores' \
  -H 'Authorization: Bearer SEU_TOKEN'

Chaves de acesso (passkeys) da conta (leitura; sem chave pública nem credential id).

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/me/passkeys' \
  -H 'Authorization: Bearer SEU_TOKEN'

Remove uma chave de acesso (reauth email_otp|totp|codigo_recuperacao; último forte agenda 24h).

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/me/passkeys/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Renomeia uma chave de acesso (sem reauth).

Respostas

Exemplo

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

Grava a chave de acesso (resposta do autenticador).

Respostas

Exemplo

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

Começa o cadastro de uma chave de acesso (reauth email_otp|senha|totp|passkey).

Respostas

Exemplo

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

Confirma a reautenticação na sessão (repasse; 429 com Retry-After).

Respostas

Exemplo

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

Inicia a reautenticação (repasse).

Corpo {"metodo": "...", "email_id": "<uuid opcional>"} — email_id só para email_otp: o e-mail VERIFICADO que recebe o código (conferido no auth: dono + verificado; outro → 400 MetodoIndisponivel). Resposta 202 (repassada): {metodo, destinos?: [{email_id, mascarado, primario}], enviado_para?} — destinos/enviado_para só para email_otp; primário primeiro, o 1º é o padrão.

Respostas

Exemplo

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

Cancela a remoção agendada.

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/me/remocoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Troca a senha (reauth senha atual|email_otp|totp|passkey|codigo_recuperacao — P4).

Respostas

Exemplo

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

Sessões vivas do usuário.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/me/sessoes' \
  -H 'Authorization: Bearer SEU_TOKEN'

Revoga uma sessão própria.

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/me/sessoes/id_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Encerra as outras sessões (qualquer reauth).

Respostas

Exemplo

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

Agenda a remoção do TOTP em 24h (reauth email_otp|codigo_recuperacao).

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/me/totp' \
  -H 'Authorization: Bearer SEU_TOKEN'

Liga o TOTP (reauth email_otp|senha).

Respostas

Exemplo

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

Gera TOTP pendente (reauth email_otp|senha).

Respostas

Exemplo

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

Campanhas do tenant, com status e progresso.

Produto marketing (exige entitlement). Tenant resolvido da sessão. A query aceita SÓ limit (allowlist) — parâmetro fora da lista é 422 nomeando-o, nunca listagem sem filtro em silêncio.

Parâmetros

Respostas

Exemplo

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

Cria uma campanha em rascunho (draft).

NÃO dispara nada — a campanha nasce em draft. O envio real é do worker (piso 18), no horário do schedule.

Remetente obrigatório (2026-10-02): FromAddress vazio numa campanha de e-mail é 422 RemetenteObrigatorio (antes virava o remetente padrão e a campanha saía com todos os lotes recusados). O seletor GET /api/campaigns/remetentes lista os domínios aceitos.

Remetente: FromAddress de e-mail só de domínio VERIFICADO da conta (SPF+DKIM, no e-mail corporativo). Recusa repassada INTACTA do asender_mkt_api: 422 RemetenteNaoVerificado (mensagem para o usuário, com o domínio) e 503 VerificacaoIndisponivel — o front mostra aviso com o atalho para Admin → Domínios.

Respostas

Exemplo

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

Detalhe de uma campanha, com contadores.

Campanha de outro tenant também é 404 — não confirma existência alheia. Pausada pelo scheduler, traz PauseReason: remetente_nao_verificado (o domínio do From perdeu a verificação antes do disparo; nada saiu com outro remetente) ou a frase de dependência ausente.

Parâmetros

Respostas

Exemplo

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

Edita uma campanha (só enquanto em draft ou paused).

A garantia "só em draft/paused" é do repo do asender_mkt_api, atômica no WHERE. A pausada é editável para o dono resolver o motivo (ex.: trocar o remetente cujo domínio perdeu a verificação) antes de reagendar.

Parâmetros

Respostas

Exemplo

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

Cancela a campanha (draft/scheduled/paused→cancelled). Sem corpo.

Parâmetros

Respostas

Exemplo

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

Agenda a campanha (draft/paused→scheduled). NÃO envia.

Piso 18: só marca a intenção — quem entrega no horário é o worker, com o guard de efeito externo. A borda valida a FORMA de ScheduledAt (RFC 3339) aqui, sem hop; o asender_mkt_api valida a REGRA (data futura, lista/ template presentes).

Parâmetros

Respostas

Exemplo

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

Domínios verificados que podem assinar o remetente da campanha (seletor do wizard).

Desde 2026-10-02 o remetente da campanha de e-mail é OBRIGATÓRIO e só de domínio verificado (SPF e DKIM). Esta rota alimenta o seletor: os domínios verificados da conta da SESSÃO (nunca de outra conta), lidos no e-mail corporativo. Lista vazia é válida — a tela mostra LinkDominios para verificar um domínio.

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/campaigns/remetentes' \
  -H 'Authorization: Bearer SEU_TOKEN'

Audiência do tenant.

Parâmetros

Respostas

Exemplo

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

Cria um contato.

Subscribed ausente vira true — opt-in é o default do cadastro manual.

Parâmetros

Respostas

Exemplo

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

A ficha de UM contato da audiência, com o consentimento por canal.

Repassa GET /v1/contacts/{id} do mkt_api (produto marketing). Contato de outro tenant → o mesmo 404 de inexistente.

Parâmetros

Respostas

Exemplo

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

Importa até 5000 contatos, com upsert pela identidade natural.

Import parcial é resultado legítimo: itens ruins voltam em Errors com o índice de origem, e o lote não é invalidado por causa deles. Lote vazio ou acima do teto é 422.

Parâmetros

Respostas

Exemplo

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

Listas de contatos com contagem de membros.

Quem pode ler (S128): quem acessa o produto marketing OU qualquer uma das ferramentas de despacho — emailmarketing, sns, zapify, push —, decidido pelo PDP do asender_auth_api (/v1/authz/decide), produto a produto nesta ordem; a primeira permissão basta. É a fonte do seletor de público das telas de e-mail, SMS, WhatsApp e push. Nenhum permitido, conta suspensa ou PDP fora sem decisão em cache ⇒ 404 (deny-default; 404 e não 403 para não virar oráculo). Só a LEITURA: POST /api/lists, POST /api/lists/{id}/members e GET /api/lists/{id}/contacts seguem exigindo marketing.

Parâmetros

Respostas

Exemplo

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

Cria uma lista de contatos.

O upstream faz upsert por slug; este BFF responde sempre 201. Exige o produto marketing (a LEITURA em GET /api/lists aceita também as ferramentas de despacho; a escrita, não).

Parâmetros

Respostas

Exemplo

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

Membros de uma lista, paginados por cursor.

Repassa a paginação do serviço de mensageria sem cortar nada: enquanto HasMore for true, chame de novo com cursor=NextCursor até a última página. limit fora de 1..100 é 422 (nunca reduzido em silêncio). Substitui o uso de GET /api/contacts?list_id= com limit=500, que perdia os membros além do 500º. Lista de outro tenant responde 404.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/lists/id_AQUI/contacts' \
  -H 'Authorization: Bearer SEU_TOKEN'

Anexa contatos a uma lista.

NotFound traz os ids que não existem no tenant — o servidor diz o que NÃO pôde fazer, em vez de descartar em silêncio. Idempotente.

Parâmetros

Respostas

Exemplo

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

Histórico de envios do tenant corrente.

Parâmetros

Respostas

Exemplo

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

Detalhe do envio com timeline.

Parâmetros

Respostas

Exemplo

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

Composer do dashboard — envia em qualquer canal.

Corpo em PascalCase, campo a campo espelhando o contrato interno. Campo desconhecido é 400 (DisallowUnknownFields), não silêncio.

Parâmetros

Respostas

Exemplo

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

Devices de push do tenant, para o seletor da tela de disparo.

Fonte do seletor de dispositivos em /t/{conta}/send/push. Antes de existir, o caminho respondia 404 e o seletor ficava vazio mesmo com devices no banco — a tela levava o usuário a concluir que a conta não tinha dispositivo nenhum.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/push/devices' \
  -H 'Authorization: Bearer SEU_TOKEN'

Pacote de integração de Web Push para o site do cliente.

Devolve, num JSON só, tudo que o site precisa para receber Web Push: chave pública VAPID do tenant, manifest.json, o service worker e o snippet de inscrição — os três já preenchidos com os valores desta instalação. Gerar no servidor evita o chamado clássico do integrador que esqueceu de substituir um <SUA_CHAVE_AQUI>.

O snippet leva só credencial PÚBLICA (M15, ADR-0057). A chave de site SiteKey (pk_push_…) é assinada para (tenant da sessão, origems pedidas) e só é aceita em POST /v1/push/site/devices, a partir dessas origens. A API key de servidor nunca entra no snippet. Mesmo (tenant, origens) gera sempre a mesma chave; trocar de domínio = gerar de novo.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/push/site-config' \
  -H 'Authorization: Bearer SEU_TOKEN'

Templates do tenant.

Parâmetros

Respostas

Exemplo

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

Cria ou atualiza um template pelo par (tenant, slug).

Parâmetros

Respostas

Exemplo

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

A conta consulta se um e-mail está em supressão global (só leitura).

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/supressao-global/consulta' \
  -H 'Authorization: Bearer SEU_TOKEN'

Catálogo único de planos — vitrine pública (ADR-0075).

Anônima por desenho: é o que a LP (www.asender.net) e o hub (/contratar) mostram — nome, descrição, preço, CTA e limites de cada plano publicado. Sem tenant, sem sessão, sem segredo. Está na allowlist publicRoutes do routes_test.go.

Fonte única: core.planos + core.plano_limites, lidas do core em GET /v1/planos. Corpo em snake_case (contrato ADR-0075), não o PascalCase do resto do /api — a mesma forma do core, tipada (campo inesperado do core não vaza).

• preco_centavos: null = sob consulta (nunca 0).
• limites traz todo domínio de core.plano_limites do plano; dia/mes

null = sem limite naquela escala.

Cache: memória do BFF por PLANOS_CACHE_TTL (60 s) e Cache-Control: public, max-age=60. Stale-on-error: com o core fora, serve a última cópia boa (warn no log com RequestId); só a primeira leitura sem cópia responde 503 (Cache-Control: no-store).

Teto por IP próprio: PUBLIC_RATE_LIMIT_PER_IP (120) por PUBLIC_RATE_LIMIT_WINDOW (1 min).

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/public/planos' \
  -H 'Authorization: Bearer SEU_TOKEN'

Funil do período com quebra por canal.

Os três canais SEMPRE aparecem em ByChannel, zerados quando não houve tráfego. As chaves de ByChannel (email/sms/push) ficam em minúsculas porque são DADO, não nome de campo.

Taxas em [0,1], arredondadas a 4 casas, grampeadas no teto (a base pode ter bounced > sent, porque bounce não exige sent_at).

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/reports/overview' \
  -H 'Authorization: Bearer SEU_TOKEN'

Série temporal por bucket e canal.

Um ponto por (bucket, canal), buckets vazios inclusos. O campo continua se chamando Day mesmo com interval=hour — é o início do bucket; a granularidade vem em Period.Interval.

Este BFF aceita hour|day|week|month, mas o asender_mkt_api só implementa day|hour: week/month passam a validação daqui e são recusados com 422 pelo upstream.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/reports/timeseries' \
  -H 'Authorization: Bearer SEU_TOKEN'

Ranking de templates por volume, com taxas.

limit aceito de 1 a 100 nesta borda; o teto REAL aplicado pelo repositório do asender_mkt_api é 50.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/reports/top-templates' \
  -H 'Authorization: Bearer SEU_TOKEN'

Busca federada do hub: um termo procurado em todas as ferramentas da pessoa na conta.

O BFF pergunta ao PDP (/v1/authz/eu) quais ferramentas a pessoa acessa na conta (resolvida por pertinência; conta alheia → 404) e chama, em PARALELO e com prazo curto por ferramenta (BUSCA_PRAZO, default 1,5 s), as buscas que cada uma já faz — sempre com a credencial da PRÓPRIA pessoa: o Bearer da sessão (crm: /v1/contatos?q=, /v1/empresas?q=; pages: /v1/paginas filtrada, /v1/links?busca=; sns, zapify, push e emailmarketing: GET /v1/busca?q=&limit= → {templates, campaigns}; ferramentas novas: o endpoint comum GET /v1/busca?q=&limite= → {itens:[…]}) ou o caminho de serviço com o usuário verificado (mail: /mailboxes/minhas + /mailboxes/{id}/messages?todas=1&q=, até 3 caixas, com o PEP e as concessões do usuário no mail_api; marketing: /v1/contacts?q= e /v1/campaigns filtradas, o mesmo caminho de /api/contacts). Ferramenta lenta ou fora vem como {indisponivel: true} e o resto responde (piso 10); ferramenta que RECUSA (403/404) some; ferramenta sem resultado não aparece. Até 5 itens por fonte e 10 por ferramenta. caminho é sempre relativo à ferramenta, com o marcador {tenant} (o BFF descarta o resto).

Parâmetros

Respostas

Exemplo

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

Home do hub: o resumo de cada ferramenta que a pessoa acessa na conta.

O BFF pergunta ao PDP (/v1/authz/eu) quais ferramentas a pessoa acessa na conta (resolvida por pertinência; Ferramenta que falha, expira ou responde fora do contrato vem como {ferramenta, nome, subdominio, indisponivel: true} — o resto responde normalmente. Se a ferramenta RECUSA o acesso (403 membro sem o produto, 404), o bloco fica ausente. atendimento não vira bloco: quem tem CRM e o produto atendimento no PDP recebe até 3 indicadores do chat DENTRO do bloco do CRM (modulo: "chat", link para as conversas do CRM; falha do atendimento só tira o chat, ADR-0080). Links de indicador são sempre caminhos relativos à ferramenta (o BFF descarta os demais).

Parâmetros

Respostas

Exemplo

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

Home do marketing: o `/v1/resumo` do asender_mkt_api, repassado sem reinterpretação.

Rota do produto marketing (PEP: sem acesso à ferramenta → recusa do PEP). O corpo segue o contrato comum de resumo em snake/minúsculo, sem PascalMap: {ferramenta, periodo{de,ate,chave}, indicadores[{chave,rotulo,valor,anterior,formato,link}], series[{chave,rotulo,tipo,pontos[{data,valor}]}]}.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/resumo/marketing' \
  -H 'Authorization: Bearer SEU_TOKEN'

Categorias, produtos, impactos e limites do formulário de chamado.

Repassa o catálogo do atendimento. Sessão impersonada recebe o catálogo (estático, sem conta).

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/suporte/catalogo' \
  -H 'Authorization: Bearer SEU_TOKEN'

Chamados do usuário (`escopo=usuario`) ou da conta (`escopo=conta`, exige governança).

A conta vem da pertinência (X-Asender-Tenant, slug ou id, só vale se o usuário pertence a ela; alheia → 404). Cada chamado sai com solicitante {id, nome} e conta {id, nome, slug}. Parâmetros fora da allowlist são descartados. Sessão impersonada: escopo usuario → lista vazia; escopo conta → 403 SemGovernanca.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/suporte/chamados' \
  -H 'Authorization: Bearer SEU_TOKEN'

Abre um chamado.

Corpo estrito: campo desconhecido (tenant_id, solicitante_*, autor, estado, prioridade…) → 400 no BFF, sem tocar no atendimento. Qualquer membro da conta pode abrir (inclusive viewer). Idempotency-Key opcional ([A-Za-z0-9._:-]{1,128}); replay do mesmo usuário volta 200. Sessão impersonada → 403 ImpersonationReadOnly.

Parâmetros

Respostas

Exemplo

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

Um chamado do usuário (ou da conta, para quem governa).

Chamado inexistente, de outro usuário ou de outra conta → 404 indistinguível. Protocolo fora do formato CH-AAAA-NNNNNN → 404 sem chamar o atendimento.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Avalia o atendimento (nota 1..5), idempotente por ciclo.

Parâmetros

Respostas

Exemplo

curl -X PUT 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/avaliacao' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Fecha o chamado.

Corpo {} (ou ausente). Já fechado → 409.

Parâmetros

Respostas

Exemplo

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

Linha do tempo pública do chamado (mensagens e eventos).

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/itens' \
  -H 'Authorization: Bearer SEU_TOKEN'

Marca as respostas da equipe como lidas.

Parâmetros

Respostas

Exemplo

curl -X PUT 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/leitura' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Responde ao chamado (JSON ou multipart com até 3 anexos).

application/json ({corpo}) ou multipart/form-data (campo corpo + até 3 anexo, cada um ≤ 5 MiB). O multipart é reescrito em streaming só com esses campos; outro campo → 400. A resposta do cliente reabre pendente/resolvido. Chamado fechado → 409 ChamadoFechado (use /reabrir).

Parâmetros

Respostas

Exemplo

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

Baixa um anexo (streaming).

Sempre Content-Disposition: attachment, X-Content-Type-Options: nosniff e Cache-Control: private, no-store. Anexo de protocolo alheio → 404. Em verificação de antivírus → 409 AnexoEmVerificacao (+ Retry-After); bloqueado → 403 AnexoBloqueado.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/suporte/chamados/protocolo_AQUI/mensagens/msgId_AQUI/anexos/anexoId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Reabre o chamado dentro da janela.

Fora da janela → 409 JanelaDeReaberturaExpirada com Details.relacionado_a_sugerido (abra um novo chamado com relacionado_a).

Parâmetros

Respostas

Exemplo

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

Indicadores do menu (aguardando você, respostas não lidas, abertos).

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/suporte/chamados/contagem' \
  -H 'Authorization: Bearer SEU_TOKEN'

Auto-contratação de plano (self-service); registra pagamento pendente.

TRANSVERSAL (fora do grupo marketing): é a rota que tira o usuário do dead-end do hub. Concede a governança admin:owner da conta na hora (é grátis) e registra a INTENÇÃO de pagar — o acesso PAGO só é liberado quando o pagamento é aprovado no fluxo de billing manual (MVP).

Corpo NÃO-estrito: campos extras (um user_id malicioso, por ex.) são IGNORADOS — o dono vem sempre da sessão verificada (anti-IDOR). O tenant é resolvido pela sessão (header X-Asender-Tenant quando o usuário pertence à conta), nunca do corpo. Conta com OUTRO dono é recusada antes de qualquer escrita.

Respostas

Exemplo

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

Endereço de um CEP/zipcode (widget CampoEndereco dos fronts).

Sem conta no caminho: o endereço de um CEP é dado público — a guarda é a sessão + o rate limit por principal. País/CEP fora do formato voltam 422 sem hop. 200/404/422/503 do core passam como vieram; qualquer outra resposta (ou core fora) vira 502. Falha nunca bloqueia o formulário: o widget segue com os campos manuais.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/enderecos/consulta' \
  -H 'Authorization: Bearer SEU_TOKEN'

Aceita um convite e vincula o usuário à conta.

O usuário vem da sessão; quem autoriza é o token do convite (validado no core). A rota não exige pertinência à conta — quem aceita ainda não é membro. O status e o corpo do core são repassados.

Herança de acessos: com o aceite em 200, o BFF pede ao asender_auth_api (POST /v1/tenants/{id}/acessos/herdar) que dono e admin da conta herdem o maior papel de cada ferramenta assinada; developer/viewer não herdam. Falha na herança não desfaz o aceite (continua 200): vai para o log com o request id, e o acesso pode ser concedido na tela Equipe ou religando a ferramenta na Assinatura.

Respostas

Exemplo

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

Vínculos de tenant do usuário logado.

Respostas

Exemplo

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

Cria um tenant RAIZ pertencente ao usuário logado.

Allowlist tipada de dois campos. parent_id, monthly_quota, status, plan, owner_user_id e id são IGNORADOS e registrados — em nível ERROR, como tentativa de escalonamento de privilégio. O owner_user_id vem sempre do principal verificado.

Ignorar (em vez de 422) preserva chamadores antigos que mandam owner_user_id; ignorar aqui não é engolir: fica no log com o usuário que enviou.

Para pendurar um tenant sob outro use POST /api/tenants/{id}/children (autoriza o pai) ou PATCH /api/tenants/{id}/parent (autoriza os dois lados). É o único caminho autorizado para mexer na árvore.

Respostas

Exemplo

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

Lista as API keys da conta.

O {id} vem do cliente e é autorizado contra a pertinência do usuário (authorizeTenantParam) antes de qualquer hop; conta alheia responde 404, nunca 403. Espelha /v1/tenants/{id}/api-keys do core — o dashboard não fala /v1 direto porque o segredo de serviço não vive no front.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/api-keys' \
  -H 'Authorization: Bearer SEU_TOKEN'

Emite uma API key na conta (o texto puro volta UMA vez).

O user_id vem SEMPRE da sessão, nunca do corpo. A chave em texto puro é devolvida uma única vez, no corpo do core; não é persistida nem logada.

Parâmetros

Respostas

Exemplo

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

Revoga uma API key da conta.

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/api-keys/keyId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Credencial de WhatsApp da conta, MASCARADA.

O {id} vem do cliente e é autorizado por pertinência antes de qualquer hop (authorizeTenantParam); conta alheia responde 404, nunca 403.

O access_token NUNCA volta em claro: o core devolve mascarado.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/credentials' \
  -H 'Authorization: Bearer SEU_TOKEN'

Cadastra/substitui a credencial de WhatsApp da conta.

Exige papel de ESCRITA na conta (authorizeTenantParam recusa viewer com 403 ReadOnlyRole); conta alheia continua respondendo 404.

Corpo ESTRITO: campo desconhecido ou JSON malformado é recusado aqui com

1. O core cifra o access_token; o eco da resposta vem mascarado.

Parâmetros

Respostas

Exemplo

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

Números de WhatsApp da conta (vários por conta; o padrão primeiro).

Espelho de sessão de /v1/tenants/{id}/channels/whatsapp/numbers do core. O {id} é autorizado por pertinência antes de qualquer hop; conta alheia responde 404. O token só aparece mascarado.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers' \
  -H 'Authorization: Bearer SEU_TOKEN'

Adiciona um número de WhatsApp à conta.

Papel de ESCRITA. Corpo ESTRITO. Sem access_token, o core reaproveita o token de outro número da mesma WABA na conta. 409 NumeroEmUso quando o número já está em alguma conta (nunca diz qual).

Parâmetros

Respostas

Exemplo

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Remove um número — pede confirmação se houver conversas abertas.

Sem confirm=true, o BFF pergunta ao atendimento (com o Bearer da sessão) quantas conversas abertas entraram pelo número. Havendo alguma — ou não dando para saber — responde 409 ConversasAbertas com open_conversations (null = desconhecido) e NÃO remove. O histórico das conversas nunca é apagado; só as respostas por este número param.

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Edita um número (nome, WABA, token, ativo).

Parcial (campo ausente não muda). apply_token_to_waba leva o token novo aos irmãos da WABA. Pausar o padrão com outro ativo é 409 PadraoComOutros.

Respostas

Exemplo

curl -X PATCH 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Define o número como remetente padrão.

Parâmetros

Respostas

Exemplo

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI/default' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Testar conexão do número com a Meta (simulado fora de produção).

Parâmetros

Respostas

Exemplo

curl -X POST 'https://api.asender.net/api/tenants/id_AQUI/channels/whatsapp/numbers/numero_AQUI/test' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <uuid-v4>' \
  -d '{ }'

Cria uma sub-conta sob um tenant administrado pelo usuário.

Autoriza {id} por vínculo direto ou herdado (ser membro de um ancestral manda na subárvore). MonthlyQuota ausente/nulo = herda do ancestral mais próximo com valor. O usuário da SESSÃO vira o owner da sub-conta (nunca um campo do corpo): ela nasce com governança e as ferramentas padrão, e aparece no lançador e no admin.

Parâmetros

Respostas

Exemplo

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

As outras contas que o usuário governa e pode importar para a árvore de {id}.

Contas de que o usuário é membro DIRETO com papel owner/admin, fora da árvore de {id} (ela, a descendência e os ancestrais — já estão nela ou seria ciclo). Cada uma com o pai atual (PaiId/PaiNome) e, quando o usuário não governa esse pai, Bloqueio: ParentNotGoverned (a tela mostra desabilitada e explica). Exige governar {id}.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/importaveis' \
  -H 'Authorization: Bearer SEU_TOKEN'

Convites pendentes da conta.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/invitations' \
  -H 'Authorization: Bearer SEU_TOKEN'

Convida alguém para a conta.

Parâmetros

Respostas

Exemplo

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

Cancela um convite pendente.

Parâmetros

Respostas

Exemplo

curl -X DELETE 'https://api.asender.net/api/tenants/id_AQUI/invitations/token_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Imagem do logo da empresa (lançador e cabeçalho dos fronts).

O {id} é autorizado contra a pertinência do usuário (authorizeTenantParam) antes de o core ser perguntado; conta alheia responde 404. Os bytes são o PNG que o core recodificou (migration 031); a resposta leva Content-Type: image/png FIXO, nosniff, CSP sandbox e Cache-Control: private — imutável por um ano quando ?v= é a versão atual (a lista GET /api/tenants traz LogoQuadrado/LogoHorizontal). Só leitura: enviar/remover é governança no admin.asender.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logo/variante_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Log de requisições da API da conta (painel, sem corpos).

Painel (sessão). O {id} vem do cliente e é autorizado por pertinência (authorizeTenantParam; conta alheia responde 404) e por papel: só owner e admin leem o log da conta (deny-default; developer, viewer e papel indeterminado levam 403). O tenant enviado ao serviço de logs é o {id} já validado. Mesmos filtros e corpo de GET /v1/logs.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logs' \
  -H 'Authorization: Bearer SEU_TOKEN'

Detalhe de uma requisição (corpos redigidos).

Painel (sessão). O {id} vem do cliente e é autorizado por pertinência (authorizeTenantParam; conta alheia responde 404) e por papel: só owner e admin leem o log da conta (deny-default; developer, viewer e papel indeterminado levam 403). O tenant enviado ao serviço de logs é o {id} já validado. Mesmo corpo de GET /v1/logs/{id}; id de outra conta = 404 idêntico ao inexistente.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logs/logId_AQUI' \
  -H 'Authorization: Bearer SEU_TOKEN'

Resumo agregado da conta: total, taxa de erro, p50/p95, por rota e por código.

Painel (sessão). O {id} vem do cliente e é autorizado por pertinência (authorizeTenantParam; conta alheia responde 404) e por papel: só owner e admin leem o log da conta (deny-default; developer, viewer e papel indeterminado levam 403). O tenant enviado ao serviço de logs é o {id} já validado. p95_ms é estimado pelos buckets fixos do histograma.

Parâmetros

Respostas

Exemplo

curl -X GET 'https://api.asender.net/api/tenants/id_AQUI/logs/resumo' \
  -H 'Authorization: Bearer SEU_TOKEN'