Descripción general
Las Tarjetas de fidelidad y sellos digitalizan las clásicas cartillas de papel ("Compre 8 cafés y llévese el 9.º gratis") convirtiéndolas en pases interactivos nativos de monedero móvil. Los clientes nunca pierden su tarjeta, el personal sella la compra en dos segundos mediante lectura óptica de QR y los comercios impulsan las visitas recurrentes con notificaciones automáticas en la pantalla de bloqueo.
Arquitectura del backend y enums de mecánicas
Las tarjetas de sellos digitales combinan imágenes visuales de franja (strip) con la ejecución determinista de reglas en Pass Mechanics Engine:
-
Tipo de pase (pass type):
storeCard. -
Plantillas de demostración del catálogo:
restaurant-stamp-cardycoffee-loyalty. -
Tipos de mecánica (mechanic type):
- STAMP_CARD_ADD: Incrementa el recuento actual de sellos en defaultChangeValue (habitualmente 1). - STAMP_CARD_DEDUCT: Permite a los cajeros corregir sellados accidentales o descontar sellos en canjes parciales.
-
Configuración de cuadrícula visual de sellos:
- Array StampImage: Asocia estados visuales individuales para las posiciones de sellado 0..N (renderizados en imágenes de franja de Apple y módulos gráficos de Google Wallet). - maximumValue: Total de sellos necesarios para completar la tarjeta (por ejemplo, 8 o 10). - rewardImageResourceId: Icono personalizado de trofeo o recompensa que se muestra cuando la tarjeta alcanza su capacidad máxima.
Lógica de ejecución del motor de sellos y comportamiento al límite
Cuando un operador de mostrador escanea el pase del cliente, Pass Mechanics Engine evalúa los umbrales activos:
-
1
Incremento de sello: Suma
defaultChangeValue(por defecto1) al saldo actual del pase:
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
-
2
Gestión del límite (
onCap) y semántica de acciones (scan action / transaction type):
- onCap: "noop": Cuando la tarjeta alcanza el máximo de sellos, el motor devuelve { ok: true, reason: "Card is full", appliedAction: "NOOP" }. El pase permanece completo para que el personal verifique la tarjeta y entregue la recompensa. - onCap: "reset": Dispara automáticamente el evento de recompensa y reinicia los sellos a 0: { ok: true, reason: "Card reset" }. - Comportamiento por defecto: Devuelve { ok: false, reason: "Stamp card is full" }, indicando al personal que ejecute un flujo de canje separado (POST /api/v1/mechanics/redeem o POST /api/v1/passes/:id/use con scan action: INCREMENT, DECREMENT, VALIDATE, registrado con transaction type: EARN, REDEEM, ADJUST, SCAN).
-
3
Comportamientos al reclamar la recompensa (
rewardClaimBehavior):
- RESET_TO_ZERO: Restablece todos los sellos a 0 cuando el personal realiza el canje. - START_NEW_CYCLE: Arrastra cualquier sello excedente de compras con varios artículos hacia el siguiente ciclo de recompensa. - KEEP_COMPLETED: Mantiene el estado visual completo hasta que se reclame el vale de recompensa.
-
4
Correlación con CRM (
externalId): Vincule el identificador del socio de fidelidad aPass.externalIdpara que las actualizaciones de sellos desde POS, tienda web y aplicación móvil realicen upsert limpiamente víaPOST /api/v1/passes/upsert-by-external-id.

Salvaguardas de escaneo diario (VALID_ONCE_PER_DAY)
Para prevenir sellados dobles accidentales o abusos en caja, añada la regla secundaria VALID_ONCE_PER_DAY:
-
El motor resuelve la zona horaria de la ubicación del comercio mediante
resolveCustomerTimeZone. -
Si un empleado escanea dos veces la misma tarjeta de cliente dentro del mismo día natural, el segundo escaneo devuelve un aviso informativo (
ALREADY_SCANNED_TODAY) sin añadir un segundo sello no autorizado.
Actualizaciones en la pantalla de bloqueo en tiempo real
Cada vez que se añade o se canjea un sello:
-
Passinstance envía una notificación silenciosa APNs al iPhone del cliente.
-
Apple Wallet actualiza la franja visual de sellos y muestra una alerta en la pantalla de bloqueo: "¡Ha ganado un sello! Ahora tiene 5 de 8 sellos."
-
Google Wallet actualiza el widget de la tarjeta en directo y muestra una notificación en Android.
Importante: Las imágenes dinámicas de franja de las tarjetas de sellos se generan automáticamente en resoluciones retina (@1x, @2x, @3x) mediante el motor gráfico de Passinstance, garantizando marcas de sellado nítidas en pantallas de alta densidad.
Lea nuestra guía completa de Tarjetas de sellos digitales, explore Restaurantes y cafeterías o consulte la Guía de reglas de acumulación de sellos.
