Vue d'ensemble
Contrairement aux cartes à tampons à seuil fixe, les programmes de points et récompenses modélisent un cumul continu de points et une progression multi-paliers (par exemple Bronze -> Argent -> Or -> Platine). Passinstance intègre un moteur de fidélité avancé offrant des règles dynamiques de conversion dépenses-points, une évaluation automatique des niveaux, des API d'échange de récompenses et des mises à jour push en temps réel dans le Wallet.
Architecture backend & moteur de fidélité
Les programmes de fidélité associent un suivi continu des soldes à des définitions de paliers structurées dans le schéma Passinstance database :
-
Type de passe (pass type) :
storeCard(affiche le solde de points actif dans les zones principales les plus visibles). -
Modèle de démonstration du catalogue :
retail-loyalty. -
Type de mécanique (mechanic type) :
LOYALTY_PROGRAM. -
Modèles centraux de fidélité :
- Tier : configure les seuils requis (ex. 500 points pour Argent, 1 500 points pour Or), les avantages du palier, des couleurs visuelles dédiées et des visuels de badge propres à chaque niveau. - BalanceChange : grand livre immuable enregistrant chaque gain de points, déduction lors d'un échange et ajustement administratif.
Moteur de cumul de points & progression de paliers
Pass Mechanics Engine et Tier Progression Engine exécutent les règles de fidélité :
1. Calcul du cumul
Lors d'un achat ou d'une visite :
-
Le pas de points utilise par défaut
defaultChangeValue(valeur canonique), ou à défautconfig.pointsPerScanou1. -
Pour les intégrations POS et e-commerce, les points sont calculés dynamiquement selon le montant dépensé :
earnedPoints = floor(purchaseTotal * pointsMultiplier)
newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
-
Si
autoResetAtMaximum: trueouconfig.onCap === "reset", le solde de points est réinitialisé àresetTargetValue(ou au solde initial) dès quemaximumValueest atteint.
2. Montées de palier automatisées (Tier Progression Engine)
Après chaque modification de solde, Tier Progression Engine compare le cumul de points du membre aux seuils des paliers actifs :
-
Si un seuil est franchi, le service promeut automatiquement le membre vers le palier supérieur.
-
Il met automatiquement à jour l'apparence visuelle de la carte (couleurs de fond, libellés d'en-tête et icônes de badge de niveau).
-
Il déclenche un push APNs silencieux et une mise à jour REST Google Wallet, prévenant le client par une notification native sur l'écran verrouillé : « Félicitations ! Vous avez atteint le niveau Or. »
API d'échange de récompenses
Lorsqu'un client échange des points contre une remise, un article offert ou un avantage en magasin ou en ligne :
Requête HTTP
/api/v1/mechanics/redeem
{
"passId": "8f94d930-b302-4fc8-9f12-000000000001",
"mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
"idempotencyKey": "redeem_tx_88194"
}
Réponse HTTP (200 OK)
{
"success": true,
"newBalance": 240,
"newBalanceDecimal": "240",
"message": "Reward redeemed successfully"
}
Synchronisation e-commerce & multicanal
Connectez vos caisses en boutique et vos boutiques en ligne afin de maintenir un grand livre client unifié (transaction type : EARN, REDEEM, ADJUST, REFUND, TRANSFER, BONUS, PENALTY, SCAN, API, ADJUSTMENT) :
-
Connecteurs Shopware 6 / Shopify : recevez les webhooks de commandes en ligne (
/api/v1/automations/webhooks/shopify/:customerId,/api/v1/automations/webhooks/woocommerce/:customerIdou les webhooks du plugin Shopware) et créditez automatiquement les cartes Wallet clients identifiées parexternalId. -
API canonique d'utilisation du passe (
POST /api/v1/passes/:id/use) : endpoint programmatique privilégié pour modifier les soldes et points depuis un ERP, une application ou un backend (avec son équivalent par clé scannerPOST /api/v1/scans/pass/:passId/use). L'ingestion historique d'événements de mécanique (POST /api/v1/mechanics/:mechanicId/events) reste prise en charge pour la rétrocompatibilité, mais est déconseillée pour les nouvelles intégrations.
Important : Configurez
changeMessage: "Solde de points mis à jour : %@"sur votre champ principal de points dans l'éditeur de modèles. À chaque gain ou déduction de points, l'écran verrouillé du client affiche immédiatement le nouveau solde.
Découvrez notre Solution Fidélité, explorez les Cartes de fidélité ou consultez le Guide des règles de progression fidélité.
