API Reference

Overview

A API do x17 segue o padrão REST usando Next.js App Router API Routes. Todas as rotas estão em src/app/api/.

Base URL: /api/*

Autenticação

A maioria das rotas exige autenticação via Supabase session cookie. O helper getAuthContext() (em src/lib/api/auth.ts) extrai userId, accountId e role do request.

interface AuthContext {
  userId: string
  accountId: string
  role: string // "owner" | "admin" | "member" | "viewer"
}

Rotas administrativas usam getAdminContext() (em src/lib/api/admin-auth.ts), que valida se o email do usuário está na lista PLATFORM_ADMIN_EMAILS (env var).

Roles disponíveis: owner, admin, member, viewer. O helper requireRole(ctx, ["owner", "admin"]) lança AuthError se o role não for permitido.

Error Handling

Todas as rotas usam o wrapper withErrorHandling() (em src/lib/api/response.ts) que captura exceções e retorna respostas padronizadas via formatApiError().

Formato padrão de erro

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "details": {}
  }
}

Códigos de erro

Código	HTTP Status	Descrição
`AUTH_ERROR`	401	Não autenticado ou sem permissão
`NOT_FOUND`	404	Recurso não encontrado
`VALIDATION_ERROR`	422	Dados inválidos (inclui erros Zod)
`WHATSAPP_ERROR`	502	Erro na API do WhatsApp/Meta
`VPS_ERROR`	502	Erro na VPS (AI proxy)
`RATE_LIMIT`	429	Limite de requisições excedido
`INTERNAL_ERROR`	500	Erro não mapeado

Classes de erro (`src/lib/errors.ts`)

AppError(message, code, statusCode, details) — erro base
AuthError(message?) — 401
NotFoundError(resource) — 404
ValidationError(message, details?) — 422
WhatsAppError(message, details?) — 502
VPSError(message, details?) — 502

Rate Limiting

Implementado com Upstash Redis sliding window (src/lib/api/rate-limit.ts). Fail-open: se Redis estiver indisponível, o request e permitido.

Presets

Preset	Limite	Janela
`webhook`	100	1 minuto
`api`	30	1 minuto
`auth`	5	1 minuto
`callback`	20	1 minuto
`ai`	20	1 hora
`send`	60	1 minuto

Headers de resposta (429)

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708000000000
Retry-After: 60

Audit Logging

Fire-and-forget via logAudit() (em src/lib/api/audit.ts). Usa createAdminClient() para bypass RLS. Nunca bloqueia a resposta.

logAudit({
  accountId: string,
  userId?: string,
  action: "create" | "update" | "delete" | "restore" | "login" | "export",
  entityType: string,
  entityId?: string,
  changes?: Record<string, unknown>,
  ip?: string,
})

Tabela: audit_logs.

Response Helpers (`src/lib/api/response.ts`)

success(data, status=200) — { data: T } com status 200
created(data) — { data: T } com status 201
noContent() — status 204, sem body
error(err) — formata erro via formatApiError()

Páginação

Offset-based (padrão)

GET /api/resource?page=1&limit=20

Resposta:

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

Cursor-based (onde disponível)

GET /api/resource?cursor=uuid&limit=20