Vue d'ensemble
Les cartes de fidélité à tampons numérisent les cartes papier à poinçonner traditionnelles (« 8 cafés achetés, le 9e offert ») sous forme de passes Wallet mobiles interactifs et natifs. Les clients ne perdent plus leur carte, les équipes valident un passage en deux secondes par scan optique QR, et les commerçants stimulent les visites répétées grâce aux notifications automatiques sur écran verrouillé.
Architecture backend & énumérations de mécanique
Les cartes à tampons numériques combinent des bannières visuelles dynamiques avec l'exécution déterministe des règles dans Pass Mechanics Engine :
-
Type de passe (pass type) :
storeCard. -
Modèles de démonstration du catalogue :
restaurant-stamp-cardetcoffee-loyalty. -
Types de mécanique (mechanic type) :
- STAMP_CARD_ADD : incrémente le compteur de tampons actif de defaultChangeValue (généralement 1). - STAMP_CARD_DEDUCT : permet aux caissiers de corriger un tampon ajouté par erreur ou de déduire des tampons lors d'un échange partiel.
-
Configuration visuelle de la grille de tampons :
- Tableau StampImage : associe un visuel distinct pour chaque état de progression 0..N (affiché dans l'image strip Apple et les visuels modulaires Google Wallet). - maximumValue : nombre total de tampons requis pour compléter la carte (ex. 8 ou 10). - rewardImageResourceId : icône de trophée ou de récompense affichée lorsque la carte atteint sa capacité maximale.
Logique d'exécution du moteur de tampons & gestion du plafond
Lorsqu'un opérateur au comptoir scanne la carte du client, Pass Mechanics Engine évalue les seuils configurés :
-
1
Incrément de tampon : ajoute
defaultChangeValue(par défaut1) au solde actuel du passe :
newStamps = clamp(currentStamps + defaultChangeValue, 0, maximumValue)
-
2
Gestion du plafond (
onCap) & sémantique d'action (scan action / transaction type) :
- onCap: "noop" : lorsque la carte atteint le maximum de tampons, le moteur retourne { ok: true, reason: "Card is full", appliedAction: "NOOP" }. Le passe reste plein afin que l'équipe puisse constater la carte complétée et remettre la récompense. - onCap: "reset" : déclenche automatiquement l'événement de récompense et remet les tampons à 0 : { ok: true, reason: "Card reset" }. - Comportement par défaut : retourne { ok: false, reason: "Stamp card is full" }, invitant l'équipe à déclencher le flux d'encaissement dédié (POST /api/v1/mechanics/redeem ou POST /api/v1/passes/:id/use avec scan action : INCREMENT, DECREMENT, VALIDATE, consigné avec transaction type : EARN, REDEEM, ADJUST, SCAN).
-
3
Comportements de réclamation de récompense (
rewardClaimBehavior) :
- RESET_TO_ZERO : remet tous les tampons à 0 lors de la validation de la récompense par l'équipe. - START_NEW_CYCLE : reporte les tampons excédentaires issus d'achats groupés sur le cycle de récompense suivant. - KEEP_COMPLETED : conserve l'état complet visuel jusqu'à ce que le bon de récompense soit réclamé.
-
4
Corrélation CRM (
externalId) : liez l'identifiant de votre membre fidélité àPass.externalIdafin que caisse POS, boutique en ligne et application mobile synchronisent les tampons viaPOST /api/v1/passes/upsert-by-external-id.

Garde-fou de scan quotidien (VALID_ONCE_PER_DAY)
Pour empêcher les doubles tampons accidentels ou les abus en caisse, rattachez la règle secondaire VALID_ONCE_PER_DAY :
-
Le moteur résout le fuseau horaire du point de vente via
resolveCustomerTimeZone. -
Si un vendeur scanne deux fois la même carte client au cours d'une même journée calendaire, le second scan renvoie un avertissement explicite (
ALREADY_SCANNED_TODAY) sans ajouter de tampon supplémentaire non autorisé.
Mises à jour sur l'écran verrouillé en temps réel
Dès qu'un tampon est ajouté ou utilisé :
-
Passinstance envoie une notification APNs silencieuse vers l'iPhone du client.
-
Apple Wallet actualise la bannière visuelle de tampons et affiche une alerte sur l'écran verrouillé : « Vous avez gagné un tampon ! Vous avez maintenant 5 tampons sur 8. »
-
Google Wallet met à jour le widget en direct de la carte et affiche une notification sur Android.
Important : Les images de bannière dynamiques des cartes à tampons sont générées automatiquement en résolutions Retina (@1x, @2x, @3x) par le moteur graphique Passinstance, garantissant un rendu parfaitement net des tampons sur les écrans haute densité.
Consultez notre guide complet des Cartes à tampons numériques, explorez Restaurants & cafés ou parcourez le Guide des règles de collecte de tampons.
