Segmentation

Vista previa rápida de segmento

Ejecuta una vista previa rápida del segmento retornando:

  • Estimación del total de fans que cumplen los criterios
  • Muestra de hasta 15 fans para validación

Lógica de Stanzas:

  • Criterios dentro de un stanza se unen con OR
  • Stanzas entre sí se unen con AND

Ejemplo: "Usuarios de España O Francia Y que asistieron a Rock Festival"

{
  "stanzas": [
    {
      "id": "location",
      "criteria": [
        {"criterion_id": "event_country", "operator": "eq", "value": "España"},
        {"criterion_id": "event_country", "operator": "eq", "value": "Francia"}
      ]
    },
    {
      "id": "event",
      "criteria": [
        {"criterion_id": "attended_event", "operator": "is", "value": "evt_rock"}
      ]
    }
  ]
}

Timeframes: el campo timeframe se acepta por compatibilidad pero no filtra; la ventana temporal es el modificador time_range (abajo).

Modifiers: Algunos criterios soportan modificadores:

  • distance: Radio geográfico en km
  • frequency: Número de veces (at_least, exactly, at_most)
  • time_range: Rango temporal (last 30 days, etc.), solo en criterios con supported_modifiers.time_range: true. En attended_event es la fecha de inicio del mismo evento asistido, en días naturales de Europe/Madrid, sin eventos futuros (ver el ejemplo attended_last_90_days).

Contactabilidad (NUEVO): la respuesta incluye además:

  • contactable_counts: fans contactables por email/SMS/push dentro del segmento, o null si el mart user_tenants aún no expone esas columnas (rollout gradual — ver schemaCapabilityService).
  • email_exclusions: desglose de por qué el resto no es contactable por email (no_email, invalid_email, opt_out, unknown), o null junto con contactable_counts. Invariante: estimated_fan_count = contactable_counts.email + Σ email_exclusions.
  • computed_at / data_as_of: timestamp del cálculo y de la frescura del mart, respectivamente.
  • sample_fans[].email_marketing_status: solo presente en el path enriquecido (mismo gate que contactable_counts).

El consentimiento de marketing se evalúa solo contra el tenant con el que autenticó la request (nunca contra la jerarquía completa de tenants usada para la pertenencia al segmento).

post/segments/preview

Request

  • Base URL: http://localhost:8081
  • URL: http://localhost:8081/segments/preview
  • Auth: HTTP bearer

Request body

Example request

{
  "definition": {
    "stanzas": [
      {
        "id": "stanza_001",
        "criteria": [
          {
            "id": "crit_001",
            "criterion_id": "user_age",
            "modifiers": {
              "distance": {
                "radius": 50
              },
              "frequency": {
                "count": 3
              },
              "time_range": {
                "value": 30
              }
            },
            "metadata": {
              "criteriaName": "Campañas abiertas",
              "dataType": "ENTITY",
              "category": "Interacción"
            }
          }
        ]
      }
    ],
    "limit": 50
  },
  "groups": {
    "total_groups": 10,
    "group_number": 1
  }
}

Response

Preview generado exitosamente

successboolean required
estimated_fan_countinteger required

Estimación del total de fans

computed_atstring date-time required

Timestamp ISO de cuándo se calculó este preview (reloj del servicio)

data_as_ofstring date-time nullable required

Timestamp ISO de la frescura de los datos del mart subyacente, o null cuando la contactabilidad no se pudo calcular (ver contactable_counts).

economic_data_as_ofstring date-time nullable

Solo si la definición usa un criterio económico (#57). Cambio de origen más reciente observado a la vez en el dim de compras y en el raw (source_timestamp máximo): un máximo observado, NO una marca de agua de completitud. No garantiza que estén reflejados todos los cambios anteriores: una imagen que llega tarde o que el almacén retiene puede faltar aunque el as-of sea posterior. Hoy no existe señal de completitud. Preséntese como «último cambio observado», nunca como «datos completos hasta». null si no se sabe. En un periodo sin cambios no avanza aunque el pipeline esté vivo.

economic_data_built_atstring date-time nullable

Solo con criterio económico. Construcción de purchase_economic_facts. Es vitalidad del pipeline; no es marca de agua de origen ni dice nada de completitud.

economic_data_status'CURRENT' | 'STALE' | 'UNKNOWN'

Solo con criterio económico. Estado de VITALIDAD, no de completitud. CURRENT: facts se reconstruyó dentro de la cadencia (no certifica que estén todos los cambios de origen); STALE si se han perdido dos o más ciclos de 15 min (el resultado se calculó igual, sobre la última foto); UNKNOWN si la frescura no se pudo leer.

Example response

{
  "success": true,
  "estimated_fan_count": 1247,
  "sample_fans": [
    {
      "fan_id": "usr_001",
      "first_name": "Juan",
      "last_name": "García",
      "email": "juan.garcia@example.com",
      "phone": "+34600123456",
      "dni": "12345678A",
      "email_marketing_status": "ok"
    }
  ],
  "group_metadata": {
    "total_groups": 10,
    "current_group": 1,
    "total_fans_all_groups": 52340,
    "avg_group_size": 5234,
    "assignment_method": "hash"
  },
  "contactable_counts": {
    "email": 612,
    "sms": 430,
    "push": 210
  },
  "email_exclusions": {
    "no_email": 120,
    "invalid_email": 45,
    "opt_out": 88,
    "unknown": 135
  },
  "computed_at": "2026-07-17T09:15:32.000Z",
  "data_as_of": "2026-07-16T03:00:00.000Z",
  "economic_data_as_of": "2026-09-23T09:58:12.000Z",
  "economic_data_built_at": "2026-09-23T10:00:08.000Z",
  "economic_data_status": "CURRENT",
  "edition_scopes": [
    {
      "edition_id": "6ab4f2ea8f0f4cd41813aae8",
      "revision": 6
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.