Descripción general
A diferencia de las tarjetas de sellos con límite fijo, los Programas de recompensas y fidelización modelan la acumulación continua de puntos y la progresión multinivel (por ejemplo, Bronce -> Plata -> Oro -> Platino). Passinstance ofrece un motor empresarial de fidelización con reglas dinámicas de puntos por compra, evaluación automática de niveles, API de canje de recompensas y actualizaciones push en tiempo real al monedero.
Arquitectura del backend y motor de fidelización
Los programas de fidelización combinan el seguimiento continuo de saldo con definiciones estructuradas de niveles en el esquema de Passinstance database:
-
Tipo de pase (pass type):
storeCard(muestra el saldo activo de puntos en zonas principales destacadas). -
Plantilla de demostración del catálogo:
retail-loyalty. -
Tipo de mecánica (mechanic type):
LOYALTY_PROGRAM. -
Modelos principales de fidelización:
- Tier: Configura umbrales de requisitos (por ejemplo, 500 puntos para Plata, 1.500 puntos para Oro), ventajas por nivel, colores visuales personalizados e insignias dedicadas por nivel. - BalanceChange: Registro de transacciones inmutable que documenta cada abono de puntos, deducción por canje y ajuste administrativo.
Motor de acumulación de puntos y progresión de niveles
Pass Mechanics Engine y Tier Progression Engine ejecutan las reglas del programa de fidelización:
1. Cálculo de acumulación
Cuando se produce una compra o visita:
-
El incremento por defecto toma
defaultChangeValue(canónico), con respaldo enconfig.pointsPerScano1. -
En integraciones con POS y comercio electrónico, los puntos se calculan dinámicamente en función del importe de compra:
earnedPoints = floor(purchaseTotal * pointsMultiplier)
newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
-
Si
autoResetAtMaximum: trueoconfig.onCap === "reset", el saldo de puntos se reinicia aresetTargetValue(o al saldo inicial) al alcanzarmaximumValue.
2. Subidas automáticas de nivel (Tier Progression Engine)
Tras cada modificación de saldo, Tier Progression Engine evalúa los puntos acumulados del socio frente a los umbrales activos de cada nivel:
-
Si se supera un umbral, el servicio promueve al socio al nivel superior.
-
Actualiza automáticamente el estilo visual de la tarjeta (cambiando colores de fondo, etiquetas de cabecera e iconos de insignia de nivel).
-
Activa un push silencioso APNs y una actualización REST en Google Wallet, notificando al cliente en pantalla de bloqueo: "¡Enhorabuena! Ha alcanzado el nivel Oro."
API de canje de recompensas
Cuando un cliente canjea puntos por descuentos, artículos gratuitos o recompensas en tienda física u online:
Solicitud HTTP
/api/v1/mechanics/redeem
{
"passId": "8f94d930-b302-4fc8-9f12-000000000001",
"mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"idempotencyKey": "redeem_tx_88194"
}
Respuesta HTTP (200 OK)
{
"success": true,
"newBalance": 240,
"newBalanceDecimal": "240",
"message": "Reward redeemed successfully"
}
Sincronización multicanal y comercio electrónico
Conecte cajas en tienda física y tiendas online para mantener un libro mayor unificado de clientes (transaction type: EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT):
-
Conectores Shopware 6 / Shopify: Reciben webhooks de pedidos online (
/api/v1/automations/webhooks/shopify/:customerId,/api/v1/automations/webhooks/woocommerce/:customerIdo webhooks del plugin de Shopware) y abonan puntos automáticamente en los pases de clientes vinculados medianteexternalId. -
API canónica de uso de pase (
POST /api/v1/passes/:id/use): Endpoint programático preferido para mutar saldos o puntos desde sistemas ERP, aplicaciones y servicios backend (con su homólogo mediante clave de escánerPOST /api/v1/scans/pass/:passId/use). La ingesta heredada de eventos de mecánica (POST /api/v1/mechanics/:mechanicId/events) sigue disponible por compatibilidad retroactiva, aunque está en desuso para nuevas integraciones.
Importante: Configure
changeMessage: "Saldo de puntos actualizado a %@"en el campo principal de puntos dentro del editor de plantillas. Cada vez que se ganen o descuenten puntos, la pantalla de bloqueo del cliente mostrará de inmediato el nuevo saldo.
Obtenga más información en nuestra Solución de fidelización, explore las Tarjetas de fidelización o consulte la Guía de reglas de progresión de fidelización.
