Skip to content
Guide du centre d'aide · Encaissements & transactionsPhase d'intégration 2
4 min de lectureVérifié 2026-11-16

Points de fidélité & tampons

Ajoutez des tampons au scan, gérez les remises à zéro après récompense, le crédit de points et les seuils de statut.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Sélecteur « Ajouter une mécanique » (Zoom)

Choisissez parmi 6 mécaniques intégrées : Carte à tampons, Échange de tampons, Valeur stockée, Points et paliers, Validation quotidienne ou Prolongation d'expiration.

Aperçu

Passinstance traite les poinçons de cartes à tampons, l'accumulation de points de fidélité, les changements automatiques de palier et l'échange de récompenses grâce aux services Loyalty & Stamp Engine, Pass Mechanics API et Tier Progression Engine. Vos équipes et systèmes backend peuvent déclencher ces mises à jour via un scan en caisse (POST /api/v1/scans), une exécution directe depuis scanner (POST /api/v1/scans/pass/:passId/use), un appel API authentifié sur espace (POST /api/v1/passes/:id/use), une caisse POS (POST /v1/pos/redeem) ou un échange explicite de récompense (POST /api/v1/mechanics/redeem).

Important : Toutes les mutations de solde de fidélité et tous les rachats de récompenses s'exécutent dans des transactions atomiques avec contrôle strict d'idempotence (en-tête Idempotency-Key ou champ idempotencyKey). Après chaque modification de tampon, de point ou de palier, Passinstance régénère automatiquement les visuels dynamiques de bannière (strip) et envoie les mises à jour push silencieuses vers Apple Wallet et Google Wallet.

Architecture & flux d'exécution des mécaniques

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
CUMUL FIDÉLITÉ, PASSAGE DE PALIER & ÉCHANGE RÉCOMPENSE
ACTEURS SYSTÈME PARTICIPANTS
P1 Scanner / Terminal POS
P2 Loyalty & Stamp Engine / Mécaniques
P3 Tier Progression Engine & Wallet Push
ÉTAPE 1 REQUÊTE / ACTION POST/api/v1/scans
ÉTAPE 2 REQUÊTE / ACTION Exécuter ScanAction / Mécanique:
›
{ action: "INCREMENT" }
›
INCREMENT / DECREMENT
›
CREDIT / DEBIT / SET
›
STAMP_CARD / LOYALTY_PROGRAM
ÉTAPE 3 REQUÊTE / ACTION Contrôler seuils de palier
ÉTAPE 4 REQUÊTE / ACTION Charger visuels & couleurs du palier
ÉTAPE 5 RÉPONSE Persister solde & journal
ÉTAPE 6 RÉPONSE 200 OK (resultingValue)
ÉTAPE 7 REQUÊTE / ACTION Émettre événements
›
8. Push APNs & Google Wallet
›
POINTS_UPDATED / TIER_CHANGED
›
(Grille & badge palier à jour)

Actions autorisées & points d'entrée d'état des mécaniques

request payload accepte sept actions explicites (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET), correspondant à la taxonomie du registre scan action (INCREMENT \| DECREMENT \| VALIDATE \| DEBIT \| CREDIT \| NOOP) :

Point d'entréeAuth / GardeRôle principal
POST /api/v1/scans/pass/:passId/usex-scanner-keyAjout de tampon, attribution de points ou modification de solde déclenché par le scanner via request payload.
POST /api/v1/passes/:id/useJWT espace / Clé APIModification de tampons ou points déclenchée par CRM ou webhook sur un passe.
POST /api/v1/mechanics/redeemClé Scanner ou JWT (request payload)Exécute la consommation complète d'une carte à tampons ou d'une récompense (action: 'DECREMENT').
GET /api/v1/mechanics/:mechanicId/passes/:passId/stateClé Scanner ou JWTRetourne le solde actuel de tampons/points ainsi que les indicateurs allowedActions.
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledgerClé Scanner ou JWTListe l'historique des transactions de la mécanique (?limit=50, max 500).
GET /api/v1/balance-changesJWT espace / Clé APIInterroge l'historique des variations de soldes fidélité et prépayés à l'échelle de l'espace.

Points d'entrée pour le cumul & l'échange de récompenses

1. Exécution directe d'une mécanique (POST /api/v1/scans/pass/:passId/use)

Une fois qu'un scanner ou terminal POS a identifié le passe (GET /api/v1/scans/pass?barcode=...), il peut créditer des tampons, ajouter des points ou décrémenter directement via l'UUID :passId avec request payload :

POST /api/v1/scans/pass/pass_loy_884120/use
En-têtes
x-scanner-key sk_live_cafe_counter_01
Idempotency-Key 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Content-Type application/json
JSON
{
  "action": "INCREMENT",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "amount": "2",
  "deviceId": "ios-idfv-cafe-03",
  "operatorId": "barista_03",
  "location": "Main Counter"
}
Champ (request payload)TypeValidation / Notes
actionenum (optionnel, défaut INCREMENT)Valeur parmi 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'.
mechanicIdUUID (optionnel)Vérifie la mécanique cible rattachée à ce passe.
amountchaîne décimale (optionnel)Doit respecter /^\d+(\.\d{1,6})?$/ (ex. "2" ou "12.90").
deviceId / operatorId / locationchaînes (optionnel)Consignés dans le journal d'audit pour le rapprochement d'équipe.
idempotencyKeychaîne (optionnel)Doit correspondre à l'en-tête Idempotency-Key si les deux sont fournis.

Réponse (200 OK — IPassUseResponse) :

JSON
{
  "success": true,
  "data": {
    "scanId": "scan_01hxyz8820ab",
    "passId": "pass_loy_884120",
    "action": "INCREMENT",
    "success": true,
    "resultingValue": "8"
  },
  "description": "Pass INCREMENT successfully",
  "errors": [],
  "statusCode": 200
}

2. Échanger une récompense débloquée (POST /api/v1/mechanics/redeem)

Lorsqu'un client réclame une récompense obtenue sur sa carte à tampons ou dépense ses unités accumulées, appelez POST /api/v1/mechanics/redeem avec request payload :

POST /api/v1/mechanics/redeem En-têtes : x-scanner-key: sk_live_cafe_counter_01 (ou Authorization: Bearer <jwt>) Idempotency-Key: 4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872 Content-Type: application/json

JSON
{
  "passId": "a1b2c3d4-e5f6-4a7b-8c9d-0123456789ab",
  "mechanicId": "11111111-2222-4333-8444-555555555555",
  "ruleId": "default",
  "idempotencyKey": "4f8b92c1-7a1e-4b33-9c12-4b1c30a9d872"
}

(Remarque : passId et mechanicId — ainsi que le champ optionnel idempotencyKey du corps JSON — doivent être des UUID valides ; s'il est fourni, ruleId doit être égal à "default".)

Réponse (200 OK — IRedeemResponse) :

JSON
{
  "success": true,
  "newBalance": 0,
  "newBalanceDecimal": "0",
  "reward": "default",
  "message": "Reward redeemed successfully"
}

Montées de palier automatiques (Tier Progression Engine)

Dès qu'un scan, un appel POST /api/v1/scans/pass/:passId/use ou POST /v1/pos/redeem (operation: "ADD_POINTS" ou "ADD_STAMPS") modifie le solde de points ou de visites d'un passe, Tier Progression Engine évalue les seuils de paliers configurés sur le modèle :

  1. 1
    Évaluation du seuil : Vérifie si le nouveau solde fait entrer le membre dans un palier supérieur (ex. Bronze : 0–249, Silver : 250–499, Gold : 500+).
  2. 2
    Hydratation visuelle & ressources : Remplace automatiquement les couleurs d'arrière-plan, bannières/strips et champs de statut propres au nouveau palier sur le passe.
  3. 3
    Alerte de félicitation sur écran verrouillé : Déclenche une notification Apple Wallet via changeMessage (ex. « Félicitations ! Vous venez d'atteindre le palier Gold ») et émet le déclencheur workflow TIER_CHANGED pour automatiser des avantages de bienvenue.

Approfondissez la configuration de vos programmes dans Cartes de fidélité à tampons et l'automatisation des récompenses dans Configuration des workflows.

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.