Configurar puntos, cashback, sellos, niveles y recompensas
Loyalty está en desarrollo y no disponible comercialmente en Free, Business ni Pro. La implementación piloto interna de Marduko App combina reglas y beneficios; esta documentación técnica no concede acceso ni constituye una oferta de planes.
Qué revisar
Confirma que el negocio sea Marduko App y tenga loyalty_enabled=true; no se usa una variable de entorno.
Abre Clientes → Lealtad y conserva el programa en Borrador mientras configuras sus componentes.
Define puntos por importe, porcentaje de cashback, sellos por visita y niveles por gasto calificable.
Para descuentos crea primero una Promotion V2 y selecciónala como beneficio de la recompensa.
En Miembros inscribe al cliente. La identidad canónica no fusiona coincidencias ambiguas de correo o teléfono.
OWNER o ADMIN puede ajustar puntos o sellos con cantidad firmada y motivo obligatorio; se crea una transacción inmutable.
Con el programa Activo, una venta web o móvil genera un evento transaccional y el worker acumula desde las filas persistidas; sus reintentos no duplican premios.
Cashback Loyalty se acredita en client_wallets y wallet_transactions. Si el cashback heredado del negocio está activo, Loyalty lo omite para evitar doble premio.
Al cancelar una venta, el motor registra inversos, revoca recompensas disponibles, revierte su cashback y recalcula el nivel.
Tarjeta digital genera la URL /walletpass y un QR con la marca de LinkStar. El perfil LinkStar principal puede permanecer oculto.
La inscripción usa un solo formulario con nombre, teléfono y correo. Marduko detecta automáticamente por correo si el cliente ya existe y sólo crea uno nuevo después de verificar el código.
La verificación reutiliza el OTP central por WhatsApp de self-scheduling y usa correo como respaldo; los destinos se muestran enmascarados.
Los límites de envío y verificación se calculan con registros propios de Marduko; Loyalty y self-scheduling no dependen de Redis ni de un servicio externo de rate limiting.
Si la inscripción se queda en Enviando, la interfaz cancela la espera, vuelve a habilitar el botón y muestra el error. Los botones conservan contraste aunque LinkStar tenga blanco como color principal.
Los tokens LYL_ son opacos y revocables. El escáner sólo consulta el resumen del miembro y nunca canjea automáticamente.
Google Wallet usa una clase por programa y un objeto por miembro. La preparación comienza al verificar el OTP y Marduko conserva la fuente de verdad.
Google exige confirmación del cliente para guardar un pase. Por eso Rewards conserva el botón negro de Google Wallet; el pase no se puede agregar silenciosamente a la cuenta.
Si faltan el issuer ID o la cuenta de servicio, el pase queda No configurado; esto nunca bloquea ventas ni acumulación.
La cuenta de servicio de Google Wallet puede configurarse como JSON completo o con correo y llave privada por separado. Para emitir una tarjeta también debe existir un programa Loyalty activo y un miembro inscrito.
Un 403 de Google Wallet significa que la cuenta de servicio usada por Marduko no tiene acceso Developer al Issuer ID configurado, aunque OAuth acepte la llave. Agrégala en Google Pay & Wallet Console > Users y confirma que el Issuer ID pertenece a esa misma cuenta.
GOOGLE_WALLET_ISSUER_ID acepta sólo el ID numérico del emisor. Marduko construye automáticamente issuerId.classSuffix e issuerId.objectSuffix; nunca debe guardarse un Class ID completo en esa variable.
La sección Tarjeta digital permite preparar explícitamente la clase con el botón Preparar clase en Google Wallet y muestra el ID confirmado. Abrir la página de Lealtad por sí solo no llama a Google.
Tarjeta digital también tiene un editor independiente para Apple Wallet. Apple Loyalty necesita APPLE_WALLET_LOYALTY_PASS_TYPE_ID y su certificado de firma; no reutiliza implícitamente el Pass Type ID de Gift Cards.
Al guardar cambios en una clase Google ya aprobada, Marduko la envía como UNDER_REVIEW porque Google no acepta APPROVED como valor de PATCH. Esto conserva la clase y vuelve a someter únicamente el diseño modificado.
Los editores Apple y Google Wallet usan un solo control para heredar la identidad de LinkStar, una paleta de veinte colores comunes y pasos breves. Imágenes adicionales, reverso y enlaces están dentro de Más opciones. No se escriben códigos de color ni URLs de imágenes.
El editor sube imágenes directamente a Storage, conserva contraste explícito y usa negocio/programa en la lista de Wallet. Google separa guardar para después, prueba y publicación. Publicar actualiza la clase y encola los objetos existentes.
Un error 400 Unrecognized hex background color format se resuelve normalizando el color en la capa Wallet. LinkStar conserva transparencia y gradientes; Google recibe sólo RGB hexadecimal sólido.
El editor permite puntos, sellos, nivel, nombre y fecha de ingreso; no promete cashback, saldo monetario, membresía ni próxima recompensa. La prueba DEMO no tiene un QR de canje. Para guardar diseños hay que aplicar 202609040001_google_wallet_design.sql.
Google Wallet conserva las clases antiguas aunque Marduko cree una nueva. Una clase con un issuer incorrecto debe ignorarse o eliminarse por separado desde Google Wallet Console; Marduko no la reutiliza.