Segments API Routes

GET /api/segments

Descrição: Lista segmentos da conta com suporte a busca textual e paginação offset-based. Auth: Required

Request:

• Query params: search, page, limit, sort, order

Response:

• 200: Segment[]

---

POST /api/segments

Descrição: Cria um novo segmento com condições de filtragem. Auth: Required

Request:

• Body (segmentSchema):

  {
    "name": "string (1-200 chars)",
    "description": "string (max 1000 chars, opcional)",
    "conditions": {
      "match": "all | any",
      "groups": [
        {
          "match": "all | any",
          "conditions": [
            { "field": "string", "operator": "string", "value": "string" }
          ]
        }
      ]
    },
    "is_dynamic": true
  }

Response:

• 201: Segment
• 422: Mínimo 1 grupo, mínimo 1 condição por grupo

---

GET /api/segments/[id]

Descrição: Retorna um segmento específico.

Response:

• 200: Segment
• 404: Não encontrado

---

PUT /api/segments/[id]

Descrição: Atualiza um segmento existente (parcial).

Response:

• 200: Segment (atualizado)
• 404: Não encontrado

---

DELETE /api/segments/[id]

Descrição: Exclui um segmento permanentemente (hard delete). Audit: delete / segment

Response:

• 204: No content

---

GET /api/segments/[id]/members

Descrição: Lista membros ativos de um segmento com paginação cursor-based. Auth: Required

Request:

• Query params: limit (default 20), cursor (optional)

Response:

• 200: { data: Contact[], nextCursor: string | null, hasMore: boolean }

Notas: Apenas membros com exited_at IS NULL. Join com contacts(*). Ordenado por entered_at desc.

---

POST /api/segments/[id]/evaluate

Descrição: Recalcula os membros de um segmento manualmente. Auth: Required

Response:

• 200: { contact_count: number }

Notas: Executa buildSegmentQuery(), compara com membros atuais, faz upsert de novos e marca saídas.

---

POST /api/segments/preview

Descrição: Preview de um segmento antes de salvar. Retorna contagem e amostra de 5 contatos. Auth: Required

Request:

• Body: { conditions: { match, groups } }

Response:

• 200: { count: number, sample: Contact[] }