Admin API Routes

Rotas exclusivas do painel administrativo da plataforma. Todas exigem getAdminContext() — usuário deve estar na lista PLATFORM_ADMIN_EMAILS.

---

GET /api/admin/accounts

Descrição: Lista todas as contas da plataforma com dados agregados via RPC admin_accounts_overview. Suporta busca por nome/email, filtro por plano e status.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

• Query params:
  • page (number, default: 1) - página
  • limit (number, default: 20) - itens por página
  • search (string) - busca case-insensitive por company_name ou owner_email
  • plan (string) - filtro por plano
  • status (string) - filtro por status

Response:

• 200:

{
  "data": {
    "data": ["AdminAccountRow"],
    "total": 100,
    "page": 1,
    "totalPages": 5
  }
}

• 401: Auth error

Notas: Páginação feita em memória (client-side) após filtragem. RPC retorna todos os dados, filtros aplicados em JS.

---

POST /api/admin/accounts

Descrição: Cria uma nova conta na plataforma.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

• Body:

{
  "name": "string (obrigatório)",
  "slug": "string (opcional, gerado automaticamente do name)",
  "plan": "string (opcional, default: 'free')"
}

Response:

• 201: { "data": Account }
• 401: Auth error

---

GET /api/admin/accounts/[id]

Descrição: Retorna detalhes completos de uma conta: dados da conta, usuários vinculados, e métricas (contatos, conversas).

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

• Path params: id (uuid) - ID da conta

Response:

• 200:

{
  "data": {
    "...account_fields",
    "users": ["AccountUser"],
    "metrics": {
      "contacts": 150,
      "conversations": 42
    }
  }
}

• 401: Auth error

---

PUT /api/admin/accounts/[id]

Descrição: Atualiza campos de uma conta. Aceita qualquer campo da tabela accounts.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

• Path params: id (uuid) - ID da conta
• Body: campos parciais da tabela accounts

Response:

• 200: { "data": Account }
• 401: Auth error

---

DELETE /api/admin/accounts/[id]

Descrição: Remove permanentemente uma conta (hard delete).

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

• Path params: id (uuid) - ID da conta

Response:

• 204: No content
• 401: Auth error

---

POST /api/admin/accounts/[id]/action

Descrição: Executa ações administrativas em uma conta: suspender, reativar, ou alterar plano.

Auth: Admin-only (getAdminContext()) Rate Limit: api preset (30/min) Audit: update em admin_account_action

Request:

• Path params: id (uuid) - ID da conta
• Body:

{
  "action": "suspend | reactivate | change_plan",
  "plan": "string (obrigatório apenas para change_plan)"
}

Response:

• 200: { "data": { "message": "Conta suspensa com sucesso" } }
• 401: Auth error
• 404: Conta não encontrada
• 422: Ação inválida

Notas:

• suspend: atualiza accounts.status para “suspended”
• reactivate: atualiza accounts.status para “active”
• change_plan: atualiza billing_subscriptions.plan para contas com status “active” ou “past_due”

---

POST /api/admin/accounts/[id]/impersonate

Descrição: Inicia modo suporte (impersonation). O admin acessa a plataforma como se fosse o cliente. Cria vínculo account_users temporário e seta cookies de suporte.

Auth: Admin-only (getAdminContext()) Rate Limit: api preset (30/min) Audit: login em admin_impersonation

Request:

• Path params: id (uuid) - ID da conta alvo

Response:

• 200:

{
  "data": {
    "account_id": "uuid",
    "account_name": "Empresa X"
  }
}

• 401: Auth error

Notas:

• Seta cookie x17-support-mode (httpOnly, 4h TTL) com dados do modo suporte
• Seta cookie x17-active-account-id para a conta alvo
• Se o admin já está vinculado a conta, não duplica o vínculo

---

POST /api/admin/accounts/exit-support

Descrição: Encerra o modo suporte. Remove o vínculo temporário do admin com a conta do cliente e restaura o cookie para a conta original.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request: N/A

Response:

• 200: { "data": { "account_id": "uuid-original" } }
• 401: Auth error
• 500: “Não está em modo suporte” (cookie ausente)

Notas:

• Remove o admin de account_users da conta do cliente (exceto se role = “owner”)
• Deleta cookie x17-support-mode
• Restaura cookie x17-active-account-id para a conta original do admin

---

GET /api/admin/stats

Descrição: Retorna estatísticas agregadas da plataforma: total de contas, usuários, contatos, conversas, MRR, ARR, contas pagantes e churn rate.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request: N/A

Response:

• 200:

{
  "data": {
    "totalAccounts": 50,
    "totalUsers": 120,
    "totalContacts": 15000,
    "totalConversations": 3200,
    "mrr": 4500.00,
    "arr": 54000.00,
    "payingAccounts": 30,
    "churnRate": 2.5
  }
}

• 401: Auth error

Notas: Usa Promise.all com 5 queries paralelas. Revenue data vem da RPC admin_revenue_overview.

---

GET /api/admin/revenue

Descrição: Retorna dados de revenue overview via RPC admin_revenue_overview.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request: N/A

Response:

• 200: { "data": { total_mrr, total_arr, paying_accounts, churn_rate_30d } }
• 401: Auth error

---

GET /api/admin/revenue/chart

Descrição: Retorna dados de revenue por dia para exibição em gráfico.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

• Query params:
  • days (number, default: 30, min: 1, max: 365) - período em dias

Response:

• 200: { "data": [{ date, revenue, ... }] }
• 401: Auth error

Notas: Usa RPC admin_revenue_by_day com parametro p_days.

---

GET /api/admin/churn

Descrição: Retorna análise de churn por período.

Auth: Admin-only (getAdminContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

• Query params:
  • days (number, default: 30, min: 1, max: 365) - período em dias

Response:

• 200: { "data": [churn_analysis_rows] }
• 401: Auth error

Notas: Usa RPC admin_churn_analysis com parametro p_days.