Segmentation

Vista previa de audiencia combinando múltiples definiciones (NUEVO)

Combina hasta 20 definiciones DSL con UNION DISTINCT — un fan que cumpla CUALQUIERA de las definiciones cuenta una sola vez en unique_total — y devuelve el alcance de la audiencia combinada más su contactabilidad por canal, para un consent_mode dado. Evita tener que hacer N llamadas a /segments/preview cuando se quiere estimar el alcance de varios segmentos combinados (p.ej. antes de lanzar una campaña multi-segmento).

Rate limit: reutiliza el límite de /segments/preview (50 req/min) — es un endpoint de solo lectura con el mismo perfil de coste (sin paginación, sin exportación de datos), solo que evaluado sobre N definiciones en lugar de una.

consent_mode (MARKETING por defecto, o TRANSACTIONAL):

MARKETING: idéntico a /segments/preview — elegible por email significa email_marketing_status = 'ok'.
TRANSACTIONAL: opt_out y unknown siguen siendo alcanzables para email transaccional/de servicio (solo no_email/invalid_email excluyen); email_exclusions.opt_out se omite en este modo.

El consentimiento se evalúa solo contra el tenant con el que autenticó la request, nunca contra la jerarquía completa de tenants (misma regla que /segments/preview y /segments/execute).

Errores de validación (400): se reporta la primera violación encontrada, con el índice de la definición ofensiva cuando aplica (definitions[i]):

definitions vacío, no-array, o con más de 20 elementos
channels vacío, no-array, con duplicados, o con un valor fuera de EMAIL/SMS/PUSH
consent_mode distinto de MARKETING/TRANSACTIONAL
Cualquier definitions[i] con una estructura DSL inválida

post/segments/audience-preview

Request

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

Request body

channelsstring[] required

Subconjunto de canales a evaluar, sin duplicados.

consent_mode'MARKETING' | 'TRANSACTIONAL'

MARKETING (default): elegibilidad de email idéntica a /segments/preview (email_marketing_status = 'ok'). TRANSACTIONAL: opt_out y unknown siguen siendo alcanzables para email transaccional/de servicio; solo no_email/invalid_email excluyen. email_exclusions.opt_out se omite en este modo.

Example request

{
  "definitions": [
    {
      "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
    }
  ],
  "channels": [
    "EMAIL",
    "SMS",
    "PUSH"
  ]
}

Response

Audience preview generado exitosamente

successboolean required

unique_totalinteger required

Fans distintos a través de todas las definitions (UNION, contados una vez).

eligible_any_channelinteger nullable required

Alcanzables por al menos uno de los canales solicitados, o null (ver eligible).

ineligible_all_channelsinteger nullable required

unique_total - eligible_any_channel, o null (ver eligible).

computed_atstring date-time required

data_as_ofstring date-time nullable required

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,
  "unique_total": 1000,
  "eligible": {
    "email": 612,
    "sms": 430,
    "push": 210
  },
  "eligible_any_channel": 750,
  "ineligible_all_channels": 250,
  "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"
}

Changes

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