Campaigns API Routes

GET /api/campaigns

Descrição: Lista todas as campanhas da conta autenticada com suporte a paginação e filtros. Auth: Required Rate Limit: Nenhum Audit: Nenhum

Request:

• Query params:
  • page (number, default: 1) - Página atual
  • limit (number, default: 20, max: 100) - Itens por página
  • sort (string, default: “created_at”) - Campo de ordenação
  • order (“asc” | “desc”, default: “desc”) - Direção da ordenação
  • folder_id (string, optional) - Filtrar por pasta

Response:

• 200: { data: Campaign[], total: number, page: number, totalPages: number }

Notas: Páginação offset-based via páginationSchema. Filtra por folder_id se fornecido.

---

POST /api/campaigns

Descrição: Cria uma nova campanha em status “draft”. Auth: Required Rate Limit: api preset (30 req/window) - chave: camp-create:{accountId} Audit: create / campaign

Request:

• Body (campaignSchema):

  {
    "name": "string (1-200 chars, obrigatório)",
    "template_id": "uuid (opcional)",
    "segment_id": "uuid (opcional)",
    "segment_config": {
      "tag_ids": ["uuid[]", "opcional"],
      "filters": {}
    },
    "scheduled_at": "datetime ISO (opcional)"
  }

Response:

• 201: Campaign (objeto criado com status “draft”)
• 422: Erro de validação Zod

Notas: Input sanitizado nos campos name. Sempre cria com status: "draft".

---

GET /api/campaigns/[id]

Descrição: Retorna uma campanha específica pelo ID, scoped pela conta autenticada. Auth: Required

Request:

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

Response:

• 200: Campaign
• 404: Campanha não encontrada

---

PUT /api/campaigns/[id]

Descrição: Atualiza uma campanha existente. Aceita campos parciais. Auth: Required Rate Limit: api preset (30 req/window) - chave: camp-mut:{accountId}

Request:

• Path params: id (uuid) - ID da campanha
• Body (campaignSchema.partial()): Qualquer campo do campaignSchema, todos opcionais

Response:

• 200: Campaign (atualizada)
• 404: Campanha não encontrada
• 422: Erro de validação

---

DELETE /api/campaigns/[id]

Descrição: Soft-delete de uma campanha. Não permite exclusão se a campanha esta em status “sending”. Auth: Required Rate Limit: api preset (30 req/window) - chave: camp-mut:{accountId} Audit: delete / campaign

Request:

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

Response:

• 204: No content (sucesso)
• 400: “Não e possível excluir uma campanha em envio” (ValidationError)
• 404: Campanha não encontrada

---

POST /api/campaigns/[id]/execute

Descrição: Executa uma campanha completa: resolve contatos do segmento, envia mensagens via WhatsApp (ou simula se não há perfil conectado), atualiza status de cada envio, e retorna estatísticas. Auth: Required Audit: update / campaign (com detalhes de execução)

Request:

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

Response:

• 200:

  {
    "total": 150,
    "sent": 148,
    "failed": 2,
    "simulated": false,
    "status": "completed | partial | sent"
  }

• 400: Validação (campanha não está em “draft”/“scheduled”, sem template, template não aprovado, nenhum contato encontrado)

Notas:

• Resolução de contatos: via segment_id (segment_members), tag_ids (contact_tags), rfm_segments (contact_rfm_scores), ou todos os contatos da conta
• Para segmentos com muitos contatos, busca em batches de 500
• Envio em batches de 10 com delay de 200ms entre mensagens
• Verifica plano ativo e limite mensal de mensagens (requireActivePlan, requirePlanLimit)
• A cada 50 envios, verifica se a campanha foi cancelada (status “cancelled”)
• Modo simulado: se não há perfil WhatsApp conectado, registra envios sem chamar a Meta API
• Cria notificação ao final (sucesso ou warning se houve falhas)

---

POST /api/campaigns/[id]/send

Descrição: Marca uma campanha como “sending” (inicia o processo de envio). Funciona como gatilho de envio. Auth: Required Rate Limit: Custom - 5 req/60s - chave: campaign-send:{accountId} Audit: create / campaign_send

Request:

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

Response:

• 200: Campaign (atualizada com status “sending”)
• 400: “Campanha só pode ser enviada quando está em rascunho ou agendada” (ValidationError)

---

POST /api/campaigns/[id]/cancel

Descrição: Cancela uma campanha em envio ou agendada. Atualiza o status para “cancelled” e cria notificação. Auth: Required Audit: update / campaign (com previousStatus)

Request:

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

Response:

• 200: { "status": "cancelled" }
• 400: “Campanha só pode ser cancelada quando está enviando ou agendada” (ValidationError)

Notas: Cria notificação de tipo “info” com mensagem contextualizada (envio interrompido vs agendamento cancelado).

---

GET /api/campaigns/[id]/stats

Descrição: Retorna estatísticas detalhadas de envio de uma campanha, agregando os registros de campaign_sends. Auth: Required

Request:

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

Response:

• 200:

  {
    "total": 150,
    "pending": 0,
    "sent": 140,
    "delivered": 130,
    "read": 100,
    "failed": 10
  }

Notas: Verifica ownership da campanha antes de buscar stats. Contagem feita em memória iterando sobre todos os campaign_sends.

---

GET /api/campaigns/[id]/sends

Descrição: Lista os envios individuais de uma campanha com dados do contato, páginados por offset. Auth: Required

Request:

• Path params: id (uuid) - ID da campanha
• Query params:
  • page (number, default: 1) - Página atual
  • limit (number, default: 20, max: 100) - Itens por página

Response:

• 200:

  {
    "data": [
      {
        "id": "uuid",
        "contact_id": "uuid",
        "status": "sent | failed | pending | delivered | read",
        "sent_at": "datetime",
        "error_message": "string | null",
        "wa_message_id": "string | null",
        "contacts": { "name": "string", "phone": "string", "email": "string | null" }
      }
    ],
    "total": 150,
    "page": 1,
    "totalPages": 8
  }

Notas: Páginação offset-based. Ordenado por sent_at descendente (nulos por ultimo). Join com contacts via !inner.