Automations API Routes

Rotas de CRUD de automações, steps, execuções, blueprints, triggers webhook e resume.

GET /api/automations

Descrição: Lista automações do account com paginação offset-based ou cursor-based. Suporta filtro por folder, ordenação e direção.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Query params:
- page (number, default: 1) - página (offset mode)
- limit (number) - itens por página
- cursor (string) - cursor para paginação cursor-based
- folder_id (string, uuid, opcional) - filtro por pasta
- sort (string, default: “created_at”) - campo de ordenação
- order (string, default: “desc”) - “asc” | “desc”

Response:

200 (offset mode):

{
  "data": {
    "data": ["Automation"],
    "total": 50,
    "page": 1,
    "totalPages": 3
  }
}

200 (cursor mode):

{
  "data": {
    "data": ["Automation"],
    "nextCursor": "uuid | null"
  }
}

Notas: Modo cursor ativado automaticamente quando cursor está presente e page não esta. Usa páginationSchema e cursorPáginationSchema do Zod.

POST /api/automations

Descrição: Cria uma nova automação. Verifica plano ativo e limite de automações.

Auth: Required (getAuthContext()) Rate Limit: api preset (30/min) Audit: create em automation

Request:

Body (Zod automationSchema):

{
  "name": "string",
  "...outros campos do schema"
}

Response:

201: { "data": Automation }
401: Auth error
422: Validation error
429: Rate limit excedido

Notas: Verifica requireActivePlan() e requirePlanLimit() antes de criar. Usa getResourceCount() para contar automações existentes.

GET /api/automations/[id]

Descrição: Retorna uma automação por ID, scoped pelo account.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação

Response:

200: { "data": Automation }
404: Automação não encontrada

PUT /api/automations/[id]

Descrição: Atualiza uma automação existente. Aceita campos parciais.

Auth: Required (getAuthContext()) Rate Limit: api preset (30/min) Audit: update em automation

Request:

Path params: id (uuid) - ID da automação
Body: campos parciais do automationSchema (.partial())

Response:

200: { "data": Automation }
404: Automação não encontrada
429: Rate limit excedido

DELETE /api/automations/[id]

Descrição: Soft-delete de uma automação (seta deleted_at).

Auth: Required (getAuthContext()) Rate Limit: api preset (30/min) Audit: delete em automation

Request:

Path params: id (uuid) - ID da automação

Response:

204: No content
404: Automação não encontrada
429: Rate limit excedido

GET /api/automations/[id]/steps

Descrição: Lista todos os steps de uma automação, ordenados por created_at.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação

Response:

200: { "data": [AutomationStep] }
404: Automação não encontrada

PUT /api/automations/[id]/steps

Descrição: Substitui todos os steps de uma automação (replace atomico). Usa RPC replace_automation_steps.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação
Body (Zod stepsPayloadSchema):

{
  "steps": [
    {
      "id": "uuid",
      "type": "action | condition | wait | ...",
      "config": {},
      "position": { "x": 0, "y": 0 },
      "next_step_id": "uuid | null",
      "condition_false_step_id": "uuid | null",
      "step_filters": []
    }
  ]
}

Validado com automationStepFullSchema (schema completo com id e automation_id)

Response:

200: { "data": [AutomationStep] }
404: Automação não encontrada
422: Validation error

Notas: Operação atomica via RPC PostgreSQL. Remove steps antigos e insere novos em uma transação.

POST /api/automations/[id]/trigger

Descrição: Endpoint webhook para trigger externo de automação. Valida webhook secret via timing-safe comparison. Não exige autenticação de usuário — usa header X-Webhook-Secret.

Auth: Public (autenticado via X-Webhook-Secret header) Rate Limit: Custom: 30 req/min por automation ID Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação
Headers: X-Webhook-Secret: string (obrigatório)
Body: JSON livre (trigger data, opcional)

Response:

200:

{
  "data": {
    "execution_id": "uuid",
    "status": "completed | running | failed",
    "steps_total": 5,
    "steps_completed": 5
  }
}

400: Automação inativa ou não é webhook trigger
401: Secret ausente ou inválido
404: Automação não encontrada
500: Erro na execução

Notas:

Usa createAdminClient() para bypass RLS (não há user autenticado)
Se o webhook secret não existe na config, gera um novo (crypto.randomBytes) e salva
Secret comparado com timingSafeEqual para prevenir timing attacks
NAO usa withErrorHandling wrapper — error handling manual
Body vazio é aceito (trigger data = {})

POST /api/automations/[id]/toggle

Descrição: Alterna o status is_active de uma automação via RPC toggle_automation_active.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação

Response:

200: { "data": { is_active: boolean, ... } }
404: Automação não encontrada

POST /api/automations/[id]/execute

Descrição: Executa manualmente uma automação. A automação deve estar ativa.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: create em automation_execution

Request:

Path params: id (uuid) - ID da automação
Body (Zod executeSchema, opcional):

{
  "trigger_data": { "key": "value" }
}

trigger_data: default {} se não enviado ou body vazio

Response:

200:

{
  "data": {
    "execution_id": "uuid",
    "status": "completed | running | failed",
    "steps_total": 5,
    "steps_completed": 5,
    "error_message": "string | null"
  }
}

400: Automação desativada
404: Automação não encontrada

GET /api/automations/[id]/trigger-data

Descrição: Retorna sample data do último evento que matchou o trigger type da automação. Util para preview/teste no editor.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação

Response:

200: { "data": { ...properties } | null }

Notas:

Mapeia trigger_type para metric names (ex: order_created -> "Order Placed", tracking_updated -> array de métricas de shipment)
Se trigger_type = “event”, usa o campo trigger_metric da automação
Busca o último evento com esse metric_name e retorna suas properties
Retorna null se nenhum evento encontrado ou trigger type não mapeado

GET /api/automations/[id]/executions

Descrição: Lista execuções de uma automação, ordenadas por started_at desc.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação
Query params:
- limit (number, default: 50, min: 1, max: 100) - quantidade de execuções

Response:

200: { "data": [AutomationExecution] }
404: Automação não encontrada

GET /api/automations/[id]/executions/latest

Descrição: Retorna a execução mais recente de uma automação, incluindo os steps individuais.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params: id (uuid) - ID da automação

Response:

200:

{
  "data": {
    "...execution_fields",
    "steps": ["AutomationExecutionStep"]
  }
}

200: { "data": null } se nenhuma execução encontrada
404: Automação não encontrada

Notas: Steps ordenados por started_at asc (nulls first = false).

GET /api/automations/[id]/executions/[execId]

Descrição: Retorna detalhes de uma execução específica, incluindo steps individuais.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Path params:
- id (uuid) - ID da automação
- execId (uuid) - ID da execução

Response:

200:

{
  "data": {
    "...execution_fields",
    "steps": ["AutomationExecutionStep"]
  }
}

404: Automação ou execução não encontrada

GET /api/automations/blueprint

Descrição: Lista todos os blueprints (templates) de automação disponíveis.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request: N/A

Response:

200:

{
  "data": [
    {
      "id": "string",
      "name": "Recuperação de Carrinho",
      "description": "string",
      "icon": "string",
      "category": "ecommerce",
      "triggerType": "cart_abandoned"
    }
  ]
}

Notas: Blueprints carregados do módulo src/lib/automations/blueprints.ts (constante BLUEPRINTS).

POST /api/automations/blueprint

Descrição: Cria uma nova automação a partir de um blueprint. Insere automação + steps com conexões resolvidas.

Auth: Required (getAuthContext()) Rate Limit: Nenhum Audit: Nenhum

Request:

Body (Zod blueprintSchema):

{
  "blueprint_id": "string"
}

Response:

201: { "data": { "automation_id": "uuid" } }
404: Blueprint não encontrado

Notas:

Verifica requireActivePlan() e requirePlanLimit() antes de criar
Gera UUIDs para steps com crypto.randomUUID()
Resolve conexões entre steps usando índices do blueprint
Para steps de tipo condition, resolve condition_false_step_id (branch “no”) em update separado
Automação criada com is_active: false

POST /api/automations/resume

Descrição: Retoma uma execução de automação que estava suspensa (ex: após wait step). Chamada internamente pelo cron/scheduler.

Auth: Cron-only (via Authorization: Bearer {CRON_SECRET}) Rate Limit: Nenhum Audit: Nenhum

Request:

Headers: Authorization: Bearer {CRON_SECRET} (obrigatório)
Body:

{
  "suspension_id": "string (obrigatório)"
}

Response:

200:

{
  "data": {
    "execution_id": "uuid",
    "status": "completed | running | failed",
    "steps_completed": 5
  }
}

400: JSON inválido ou suspension_id ausente
401: Token inválido ou ausente
404: Suspension não encontrada ou já processada
500: Erro interno

Notas:

Rota com dynamic = "force-dynamic" e maxDuration = 60 (Vercel)
NAO usa withErrorHandling ou getAuthContext — auth via CRON_SECRET
Usa resumeAutomation() de src/lib/automations/executor