> ## Documentation Index
> Fetch the complete documentation index at: https://internal.softcrum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fidelización

> Softcrum Fidelización es un motor headless de lealtad e incentivos. Una empresa conecta sus propios sistemas —punto de venta, ecommerce, ERP, facturación— y los eventos de comportamiento empiezan a llegar.

> Traducción. El inglés es la versión autoritativa: [`../../../modules/loyalty/prd.md`](/modules/loyalty/prd).

> Softcrum Fidelización es un motor headless de lealtad e incentivos. Una empresa conecta sus
> propios sistemas —punto de venta, ecommerce, ERP, facturación— y los eventos de comportamiento
> empiezan a llegar. Con esos eventos el motor acredita puntos, emite cupones, mueve clientes entre
> niveles, paga referidos y dispara campañas, todo desde reglas que la propia empresa configura.
> Funciona dentro de nuestra consola y portal, o completamente embebido en la experiencia de la
> empresa a través de la API pública. El motor es el producto; la interfaz es una elección.

## Para quién es

| Persona                                 | Contrata este módulo para                                                                                                                                                             |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Responsable de marketing** (tenant)   | Lanzar un programa de fidelización sin ingeniería: definir cómo se ganan puntos, qué compran, qué niveles existen y qué se envía cuándo.                                              |
| **Desarrollador** (tenant o integrador) | Conectar un sistema existente en una tarde: enviar eventos, leer saldos, canjear en el punto de venta — con garantías de idempotencia que sobreviven a reintentos y redes inestables. |
| **Finanzas** (tenant)                   | Conocer el pasivo de puntos pendiente, actualizado con la frecuencia suficiente para cerrar un mes con confianza.                                                                     |
| **Member** (cliente final del tenant)   | Ver un saldo en el que confía, entender qué le falta para el siguiente nivel y canjear sin fricción ni descarga de app.                                                               |

## El problema hoy

Una empresa que quiere un programa de fidelización elige entre dos malas opciones. Las apps
empaquetadas de loyalty para ecommerce se instalan rápido pero encierran la experiencia en un
widget y en un vertical: no pueden modelar el comportamiento de pago de un negocio de suscripción
ni los aniversarios de una empresa de servicios. Los motores enterprise sí son flexibles, pero son
compras enterprise: ciclos de venta largos, precios opacos y proyectos de integración en vez de una
tarde de trabajo.

Debajo de ambos hay una herida de pricing de la que el mercado habla constantemente. Las
plataformas de engagement dominantes cobran por cada perfil almacenado se le contacte o no, y al
menos una aplica un *ratchet* que sigue cobrando un peak mucho después de que el uso baje. El
resultado es que importar el propio histórico —lo único que hace que un programa funcione desde el
día uno— se castiga económicamente. Ser la plataforma que no hace eso es una decisión de
posicionamiento, no un descuento.

## Qué hace *(normativo)*

* Un tenant define un **programa**: sus monedas de puntos, sus reglas de acumulación, su catálogo
  de recompensas, sus niveles.
* Los eventos de comportamiento acreditan puntos mediante un **motor de reglas** cuyo contrato es
  evento → condiciones → efectos, con campañas versionadas y presupuestos.
* Los puntos viven en un **libro inmutable** con dos monedas separadas —puntos canjeables y puntos
  de estatus— y lotes FIFO con expiración real. Los saldos son una proyección, nunca una columna
  mutable.
* Puntos y cupones se **canjean** por una API idempotente que un punto de venta puede llamar sin
  riesgo, con canjes padre/hijo y una política de rollback explícita.
* Los **referidos** pagan a ambas partes, liberados por un evento calificante y no por el registro,
  con controles antifraude.
* Los **niveles** califican sobre una ventana definida, con política de descenso explícita y
  overrides por nivel sobre acumulación, precios y expiración.
* Todo emite eventos de dominio que el módulo de mensajería convierte en campañas y que el tenant
  puede consumir como webhooks salientes.

## Lo que NO hace *(normativo)*

* **No es un motor de promociones en F1.** Los descuentos dinámicos de carrito (`apply_discount`)
  están ratificados para F2 (DEC-H4); F1 deja el catálogo de efectos abierto para que agregarlo no
  cueste nada.
* **No es un sistema de pagos.** El canje mixto puntos + dinero es un requisito confirmado
  (DEC-H3), pero F1 solo reserva la costura: un `money_component` nullable y un evento de dominio.
* **No es un CDP.** Perfiles, identidades, consentimientos, eventos y segmentos pertenecen a
  `customer-core`. Fidelización consume ese núcleo; nunca lo posee.
* **Sin agregación entre programas.** Multi-programa se entrega en F1 (ADR-021), pero cada
  programa reporta sobre sí mismo. Agregar entre programas abre preguntas —de quién son los
  puntos, en qué moneda, con qué escalera de niveles— que tendrán su propia decisión cuando un
  cliente realmente lo necesite.
* **No hay gamificación en F1.** Insignias y desafíos tienen schema reservado y aterrizan en F2.
* **Nada de verticales hardcodeados.** Las taxonomías de eventos se entregan como datos
  instalables, no como código (DEC-H7). El producto debe aplicar a cualquier industria.

## Éxito

| Medida                                                                                                                      | Objetivo                                                        | Para                     |
| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------ |
| Design partner con el ciclo completo — evento entra, puntos acreditados, notificación entregada, canje en el punto de venta | operando en producción                                          | G1-Engage, 2026-11-01    |
| Tiempo desde API key hasta el primer evento aceptado                                                                        | menos de 30 minutos, sin ayuda, siguiendo el quickstart público | G1-Engage                |
| `track` p95                                                                                                                 | \<100 ms (fast-ack)                                             | certificación, pre-G1    |
| Visibilidad end-to-end del efecto (evento → puntos → notificación)                                                          | \<5 s p95                                                       | certificación, pre-G1    |
| Drift del libro detectado por la reconciliación nocturna                                                                    | cero, sostenido                                                 | primer mes en producción |

## Modelo comercial

La base facturable es el **contacto accionable** — un contacto con consentimiento activo en al
menos un canal y no suprimido (ADR-014). El histórico almacenado es gratis e ilimitado: importar
años de clientes no cuesta nada, y esa es la palanca de adopción. No hay ratchet; el conteo se
reevalúa cada ciclo en ambas direcciones.

Fidelización mide volumen: eventos registrados y mensajes, con precios unitarios publicados y
cuotas incluidas por plan (ADR-016). Dos capacidades se venden en vez de incluirse. El add-on de
**frescura de datos** sube la frecuencia de los recomputes pesados —reconciliación de drift, RFM
completo, snapshots analíticos— de nocturno hasta cada hora (DEC-G5). Y la **cantidad de programas
es un entitlement** (ADR-021): el plan base incluye una cantidad, y necesitar otro es una razón
concreta para subir de plan. Excederlo se bloquea, nunca se factura como overage — un tope duro es
la forma correcta para una capacidad que el tenant elige adoptar, a diferencia del consumo que
generan sus propios clientes.

`contact_balances` nunca forma parte de ese add-on. Un member ve su saldo en el instante en que
cambia; cobrar por eso sería cobrar por corrección.

## Fases

| Fase    | Contenido                                                                                                                                                      | Objetivo              |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **F1a** | Programas y monedas (multi-programa, ADR-021) · libro y lotes FIFO · proyección de saldo y reconciliación · motor de reglas · catálogo de recompensas · canjes | G1-Engage, 2026-11-01 |
| **F1b** | Cupones y generación masiva · reglas de acumulación · referidos · niveles · escaneos de puntos por vencer · UX de consola para reglas y niveles                | post-G1               |
| **F2**  | Insignias y desafíos · `apply_discount` · wallet passes · canje mixto puntos + dinero                                                                          | 2027                  |

## Cumplimiento y riesgo

Fidelización almacena datos transaccionales y de comportamiento sobre personas identificadas, que
es exactamente lo que la regulación de perfilamiento apunta. Dos consecuencias ya están fijadas y
condicionan el diseño:

* **La supresión es asimétrica.** Un titular que ejerce su derecho de supresión ve borrados su
  perfil y sus eventos, pero las filas del libro se **anonimizan a un tombstone, nunca se
  destruyen** (DEC-J3): la integridad contable y el derecho de supresión se reconcilian
  anonimizando, no borrando. El plazo comprometido es ≤30 días, automatizado.
* **El libro es la evidencia.** La Ley 21.719 fiscaliza evidencia operativa, no políticas. El libro
  append-only más el registro de auditoría es lo que mostraríamos.

Riesgo principal de producto: un motor de reglas lo bastante expresivo para ser útil y lo bastante
restringido para seguir siendo predecible. La mitigación es que los efectos son un catálogo
paramétrico — agregar una fila no agrega comportamiento, y la API rechaza los códigos que el
negocio todavía no soporta.

## Dependencias

`customer-core` para contactos, identidades, consentimientos, eventos y segmentos — dependencia
dura y de una sola dirección. `messaging` para toda notificación, solo mediante eventos de dominio.
`QueuePort` para efectos asíncronos, `NotificationChannelPort` para la entrega. Particionamiento de
Postgres para el flujo de eventos que alimenta el motor de reglas.

## Preguntas abiertas

Ninguna pendiente. Toda pregunta que llevaba este spec quedó respondida en el registro consolidado
([`../../../../design/open-questions-v1.md`](https://github.com/softcrumlabs/softcrum-suite/blob/master/docs/design/open-questions-v1.md), v1.1) y se
incorporó a las secciones normativas de arriba.

## Changelog

| Versión | Fecha      | Cambio                                                                             | Por qué                                    | Autor                  |
| ------- | ---------- | ---------------------------------------------------------------------------------- | ------------------------------------------ | ---------------------- |
| 0.2.0   | 2026-08-17 | Preguntas abiertas resueltas (OQ-LOY-\*) e incorporadas a las secciones normativas | El owner respondió el registro consolidado | daniel + claude-opus-5 |
| 0.1.0   | 2026-08-17 | Borrador inicial desde el registro de decisiones y el spec del módulo              | —                                          | daniel + claude-opus-5 |