Lectura de campañas de puntos desde GET

Esta guía está orientada al equipo de integraciones que interpreta campañas de puntos y wallet ya creadas al consultar listados desde GetAListOfScoreCampaigns (equivalente interno: GET /points) y las alinea con el ticket enviado a la Streaming API.

Alcance: campañas de puntos/wallet según el evento configurado en when: carrito (after_create_activity), triggers (slug de trigger configurado en la Company), eventos personalizados (after_create_custom_entity) o asignación directa (manual). Los challenges no forman parte de esta guía (se documentan aparte). La gramática JSON de rule_* es la misma que en descuentos salvo restricciones por when y ciclo de vida de saldo.

Índice

• Contenido de la guía
• Modelo canónico
• Modalidades de acumulación (puntos vs wallet)
• Audiencia en puntos (select_customers)
• Referencia por evento (when)
• Cómo leer una campaña paso a paso
• Asignación directa (manual)
• Checklist para integraciones
• Páginas relacionadas

---

Contenido de la guía

Página	Qué cubre
Respuesta GET	Query params, metadatos, activación/caducidad, parseo JSON
Condiciones	rule_conditions: AND/OR, catálogos cliente/carrito/líneas/tienda
Aplicación	rule_application: alcance del otorgamiento en líneas
Efectos	rule_effects: tipos, distribución, limits, bundle, scores[] en ticket

Modelo canónico

Campo	Qué representa
rule_conditions	Condiciones de victoria: ¿cuándo puede otorgarse la campaña?
rule_application	Aplicación: ¿sobre qué líneas se calcula el otorgamiento?
rule_effects	Efecto: cuántos puntos/saldo y cómo se distribuye

Usa siempre rule_conditions, rule_application, rule_effects (no rules_* ni alias legacy). rule_application no es distribución; la distribución va en rule_effects.distribution.

---

Modalidades de acumulación (puntos vs wallet)

En un programa de fidelización, Loyal Guru soporta dos formas de presentar la acumulación al customer:

Modalidad	Qué percibe el customer	Ejemplo de naming
Puntos	Unidades (puntos, millas, likes, …); por defecto en la plataforma: puntos	«Acumula puntos»
Wallet (dinero)	Saldo monetario directo en un monedero, sin concepto de puntos	«Carga saldo en tu wallet»

Internamente el motor trata ambos casos de la misma forma: el customer acumula un valor con potencial monetario. La Company elige cómo mostrarlo y operarlo en Owner App y en integraciones mediante accrual_mode (configuración de Company):

accrual_mode	Comportamiento
points	Textos y flujos orientados a puntos; la Streaming API convierte y muestra en unidades de puntos según el score_exchange de la moneda.
money	Textos y flujos orientados a wallet/dinero; la acumulación se expresa y redime en importe monetario.

El motor es uniforme; cambian la presentación y parte de la lógica de la Streaming API (acumular, mostrar, redimir). Al leer campañas desde GET, revisa currency y, si viene, accrual_mode en el ítem de data[] — ver Respuesta GET.

El detalle de cómo interpretar rule_effects.value (siempre en moneda) está en Efectos — Valor monetario de value.

---

Audiencia en puntos (select_customers)

En puntos/wallet no existen campañas all_customers (masivas sin customer concreto). Para acreditar saldo hace falta un customer identificado; el motor no puede otorgar puntos «al aire» como un descuento de folleto masivo.

Valor en GET / Owner App	Uso en puntos
loyalty	Customers enrolados en el club (habitual en carrito, triggers y asignación directa).
targeted	Entrega dirigida (audiencia concreta / voucher).
all_customers	No aplica en puntos — solo en descuentos.

Si ves select_customers: "all_customers" en un listado de puntos, trátalo como dato inconsistente o legacy; la configuración válida es loyalty o targeted.

---

Referencia por evento (when)

Cada campaña de puntos tiene un único when. Eso determina qué efectos, distribuciones y bloques rule_* son válidos.

Evento	when (API)	Efectos	Distribuciones	rule_conditions	rule_application	select_customers
Carrito	after_create_activity	Los 6 tipos	Las 3 + reglas por tipo	Catálogo completo (como descuentos)	Líneas, costes adicionales y pagos	loyalty, targeted
Trigger	Slug configurado en la Company	Solo direct_value	Solo total	Sin condiciones de ticket	Sin bloque	loyalty
Evento personalizado	after_create_custom_entity	percentage, ratio, direct_value	Solo total	Atributos del evento	Campo numérico del evento	loyalty, targeted
Asignación directa	manual	Solo direct_value	Solo total	Vacío obligatorio	Sin bloque	loyalty

Detalle de cada efecto y distribución: Efectos. Matriz ampliada y ejemplos por tipo en las mismas páginas enlazadas.

---

Cómo leer una campaña paso a paso

1. Metadatos y vigencia — id, name, active, available_from / available_to, category, currency, accrual_mode (si aplica). Ver Respuesta de GET /points.
2. Evento (when) y audiencia — Identifica el evento (carrito, trigger, evento personalizado, asignación directa). Revisa select_customers: solo loyalty o targeted (ver Audiencia). Ver Reglas de acumulación.
3. Condiciones de victoria — Parsea rule_conditions (string JSON). En manual, puede venir vacío: {"conditions":{"and":[]}}. Ver Condiciones.
4. Aplicación — rule_application limita líneas; si falta, el alcance depende del when y del efecto. Ver Aplicación.
5. Efecto — rule_effects: type, value, unit (ratio), distribution, limits, rule_group. Ver Efectos.
6. Activación y caducidad — activation_period_type, activation_delay, expiration_period_type, availability_duration explican saldo pendiente vs disponible.
7. Límites de victoria — once, once_limit, presupuesto — ver Límites (distinto de rule_effects.limits).

---

Asignación directa (manual)

Campañas de puntos/wallet que el operador dispara sin ticket de compra. En GET se identifican con when: "manual"; el listado admite GET /points?when=manual.

Al leer una campaña de asignación directa, comprueba este perfil (creación: API de campañas):

Aspecto	Valor habitual en manual
rule_conditions	Vacío: {"conditions":{"and":[]}}
rule_effects	Solo direct_value; distribution: "total"; rule_group: false
select_customers	"loyalty" (customers enrolados)
rule_application	Suele omitirse (sin líneas de carrito)
Otorgamiento en ticket	No aplica carrito; el saldo se asigna por flujo operativo/admin, no vía scores[] de POST /activities

---

Checklist para integraciones

• GET /points con filtros correctos (when, customer_id, countries, …); ?when=manual para asignación directa.
• Paginación: next_token_starts_after → starting_after hasta agotar data[].
• Mapear GetAListOfScoreCampaigns a rule_conditions, rule_application, rule_effects.
• Parsear JSON si los campos rule_* vienen serializados.
• Validar restricciones por when con la matriz por evento (efectos, distribuciones, rule_conditions, rule_application).
• Comprobar que select_customers no sea all_customers.
• Con accrual_mode: points, convertir rule_effects.value (moneda) a puntos con el score_exchange de la currency de la campaña.
• Revisar activación/caducidad antes de reportar «no acreditó».
• En ticket: validar scores[] (otorgamiento) frente a rule_effects del GET; effects[] es para descuentos.

Páginas relacionadas

• Reglas de acumulación — triggers y configuración en Owner App
• Límites — frecuencia de victoria y presupuesto
• API de campañas — creación con formato plano