Programas de lealtad: puntos, cashback, visitas y niveles
Cómo funciona el programa combinado de Marduko, qué saldos son canjeables y cómo se conserva el historial.
Un programa, varios componentes
Loyalty reúne puntos, cashback, visitas o sellos y niveles dentro de un programa. Cada componente se puede activar por separado sin crear programas paralelos.
Durante el piloto el módulo está disponible únicamente para Marduko App. No depende de variables de entorno; el permiso del negocio y la validación del servidor fallan cerrados.
Saldos e historial
Puntos y sellos usan un ledger inmutable. Un ajuste nunca reescribe una operación anterior: crea una nueva fila con importe firmado, motivo y usuario.
Cashback es dinero y por eso utiliza el wallet de clientes y sus transacciones monetarias. Loyalty no mantiene un segundo saldo de dinero.
El gasto calificable determina el nivel. Canjear puntos disponibles no reduce el gasto calificable ni degrada el nivel.
Niveles
Los niveles se ordenan por umbral de gasto calificable y pueden multiplicar la acumulación de puntos. Bronce, Plata y Oro son ejemplos iniciales; OWNER o ADMIN puede editar nombres, límites y multiplicadores.
Al terminar o cancelar una venta, Loyalty recalcula automáticamente el nivel desde el historial vigente.
Recompensas y Promotions V2
Una recompensa explica por qué el cliente obtuvo un beneficio. Para descuentos o productos gratis, Loyalty desbloquea una Promotion V2 existente; Checkout continúa aplicándola y registrando su redención.
También se preparan bonos de puntos, crédito wallet y beneficios manuales. No existe un segundo motor de descuentos.
Acumulación y reversas automáticas
Cada venta web o móvil confirmada genera, dentro de la misma transacción, un evento para el motor de Loyalty. Un worker lo procesa de forma idempotente usando la venta y sus conceptos ya persistidos.
Puntos, sellos y gasto calificable se registran en el ledger de Loyalty. El cashback se acredita en el wallet. Si el negocio conserva activo el cashback heredado, el cashback de Loyalty se omite para impedir una doble acreditación.
Al cancelar una venta se registran movimientos inversos, se revocan recompensas aún disponibles, se revierte el crédito wallet asociado y se recalcula el nivel. Una falla del worker nunca deshace ni bloquea la venta.
Alcance y piloto
La configuración actual usa alcance por negocio o ubicación. La identidad canónica vive en la organización para poder reconocer al mismo cliente entre ubicaciones sin fusionar correos o teléfonos ambiguos.
Durante el piloto, la acumulación automática sólo funciona en Marduko App con el permiso explícito loyalty_enabled. Web y móvil comparten el mismo outbox y motor.
Diseños independientes de Google y Apple Wallet
Tarjeta digital incluye editores separados para Google y Apple Wallet. Un solo interruptor usa automáticamente nombre, color y logo de LinkStar; al personalizar, se elige entre veinte colores populares sin escribir códigos.
La configuración se divide en pasos breves: marca, información principal y mensaje. Imágenes adicionales, reverso y enlaces permanecen dentro de Más opciones para mantener limpia la pantalla.
Las imágenes se suben directamente a Storage; nunca se solicita pegar una URL. Los saldos, niveles, sellos y códigos reales siguen viniendo de Marduko.
Guardar para después sólo conserva el borrador. Publicar actualiza los pases sin alterar puntos ni compras.
Tarjeta digital, privacidad y escáner
La ruta pública /walletpass hereda logo, colores y tipografía de LinkStar, incluso cuando el perfil principal no está publicado. Requiere programa activo e inscripción pública habilitada. Si el color de marca es demasiado claro para un botón sobre fondo blanco, se usa automáticamente un acento con contraste.
La inscripción pide nombre, teléfono y correo en un solo formulario. Marduko busca una coincidencia exacta y única por correo; si existe, continúa con esa cuenta, y si no existe crea al cliente únicamente después de verificar el código. El cliente no necesita elegir si ya estaba registrado.
El cliente se verifica con el mismo OTP central por WhatsApp usado en self-scheduling, con correo como respaldo. Las respuestas enmascaran el destino y nunca incluyen IDs, teléfono o correo completos. Los límites de envío e intentos se validan con registros propios de Marduko, sin depender de un proveedor externo de rate limiting.
La tarjeta usa un token opaco LYL_ revocable; la base sólo guarda su hash. Al escanearlo, el personal ve puntos, nivel y recompensas, pero ningún beneficio se canjea automáticamente.
La página Rewards muestra puntos, sellos, nivel, recompensas y actividad limitada. El saldo monetario detallado exige una autorización más fuerte.
Google Wallet
Google Wallet es una proyección del saldo de Marduko: una clase representa el programa y un objeto representa a cada miembro. Marduko y su ledger siguen siendo la fuente de verdad.
Al verificar el OTP, Marduko prepara el pase y abre inmediatamente la confirmación oficial de Google Wallet. Las actualizaciones posteriores se ejecutan en una cola independiente; una caída o configuración faltante de Google nunca bloquea Checkout ni revierte una venta.
Los cambios individuales usan PATCH sobre el objeto del miembro. Cambios de marca pertenecen a la clase del programa, no a cada saldo.
Google exige que el cliente confirme el guardado del pase. Rewards conserva un botón negro como respaldo para volver a abrir esa confirmación sin crear duplicados.
GOOGLE_WALLET_ISSUER_ID debe contener únicamente el ID numérico asignado por Google. Marduko agrega automáticamente el sufijo de la clase por programa y el sufijo único del objeto por miembro; nunca se configura un Class ID completo.
Si Google responde 403 con un issuer numérico correcto, la llave es reconocida por OAuth pero la cuenta de servicio no tiene acceso al issuer configurado. Agrégala con rol Developer en Google Pay & Wallet Console > Users.
Apple Wallet
Apple Loyalty genera un pase storeCard firmado por miembro. Marduko conserva los puntos, nivel y sellos como fuente de verdad y Apple Wallet sólo presenta una proyección actualizable.
Loyalty necesita APPLE_WALLET_LOYALTY_PASS_TYPE_ID. El certificado y llave específicos pueden configurarse con el prefijo APPLE_WALLET_LOYALTY_; si no se proporcionan, Marduko usa los valores generales de firma sólo cuando corresponden al mismo Pass Type ID.
El Web Service de PassKit registra el dispositivo y sirve las versiones nuevas del pase. La configuración o caída de Apple nunca bloquea una venta.