Panoramica
A differenza delle tessere a timbri a soglia fissa, i Programmi premi e fedeltà modellano un accumulo continuo di punti e una progressione multi-livello (ad esempio Bronzo -> Argento -> Oro -> Platino). Passinstance mette a disposizione un motore fedeltà enterprise con regole dinamiche punti-per-spesa, valutazione automatica dei livelli, API per il riscatto premi e aggiornamenti push Wallet in tempo reale.
Architettura backend e motore fedeltà
I programmi fedeltà combinano il tracciamento continuo del saldo con definizioni strutturate dei livelli nello schema Passinstance database:
-
Tipo di pass (pass type):
storeCard(mostra il saldo punti attivo nelle zone principali in evidenza). -
Modello demo a catalogo:
retail-loyalty. -
Tipo di meccanica (mechanic type):
LOYALTY_PROGRAM. -
Modelli fedeltà principali:
- Tier: Configura le soglie richieste (es. 500 punti per Argento, 1.500 punti per Oro), i vantaggi del livello, i colori visivi personalizzati e le immagini dedicate del badge di livello. - BalanceChange: Registro transazionale immutabile che documenta ogni accredito punti, deduzione per riscatto e rettifica amministrativa.
Motore di accumulo punti e progressione livelli
Pass Mechanics Engine e Tier Progression Engine eseguono le regole fedeltà:
1. Calcolo dell'accumulo
Quando avviene un acquisto o una visita:
-
L'incremento punti utilizza
defaultChangeValuecome valore canonico, ripiegando suconfig.pointsPerScano1. -
Per integrazioni POS ed e-commerce, i punti vengono calcolati dinamicamente in base all'importo speso:
earnedPoints = floor(purchaseTotal * pointsMultiplier)
newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
-
Se
autoResetAtMaximum: trueoppureconfig.onCap === "reset", il saldo punti viene riportato aresetTargetValue(o al saldo iniziale) al raggiungimento dimaximumValue.
2. Avanzamento automatico di livello (Tier Progression Engine)
Dopo ogni variazione del saldo, Tier Progression Engine confronta i punti accumulati dal cliente con le soglie attive dei livelli:
-
Se una soglia viene superata, il servizio promuove il cliente al livello superiore.
-
Aggiorna automaticamente lo stile visivo della tessera (modificando colori di sfondo, etichette d'intestazione e icone badge del livello).
-
Attiva una push silenziosa APNs e un aggiornamento REST Google Wallet, avvisando il cliente con una notifica nativa sulla schermata di blocco: "Congratulations! You have reached Gold Tier."
API per il riscatto dei premi
Quando un cliente riscatta punti per sconti, prodotti omaggio o articoli promozionali in negozio o online:
Richiesta HTTP
/api/v1/mechanics/redeem
{
"passId": "8f94d930-b302-4fc8-9f12-000000000001",
"mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"idempotencyKey": "redeem_tx_88194"
}
Risposta HTTP (200 OK)
{
"success": true,
"newBalance": 240,
"newBalanceDecimal": "240",
"message": "Reward redeemed successfully"
}
Sincronizzazione e-commerce e multicanale
Colleghi casse in negozio e store online per mantenere un registro unificato del cliente (transaction type: EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT):
-
Connettori Shopware 6 / Shopify: Acquisiscono webhook degli ordini online (
/api/v1/automations/webhooks/shopify/:customerId,/api/v1/automations/webhooks/woocommerce/:customerIdo webhook del plugin Shopware) e accreditano automaticamente i punti sui pass Wallet associati tramiteexternalId. -
API canonica di utilizzo pass (
POST /api/v1/passes/:id/use): Endpoint programmatico consigliato per ERP, app e servizi backend per modificare saldi e punti (con controparte autenticata da scannerPOST /api/v1/scans/pass/:passId/use). L'acquisizione legacy di eventi meccanica (POST /api/v1/mechanics/:mechanicId/events) rimane supportata per retrocompatibilità, sebbene sia deprecata per nuove integrazioni.
Importante: Configuri
changeMessage: "Points balance updated to %@"sul campo principale dei punti nell'editor del modello. Ogni volta che vengono guadagnati o scalati punti, la schermata di blocco del cliente mostra immediatamente il saldo aggiornato.
Approfondisca la nostra Soluzione Fedeltà, esplori Carte fedeltà oppure consulti la Guida alle regole di progressione fedeltà.
