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-Keyou champidempotencyKey). 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
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ée | Auth / Garde | Rôle principal |
|---|---|---|
POST /api/v1/scans/pass/:passId/use | x-scanner-key | Ajout de tampon, attribution de points ou modification de solde déclenché par le scanner via request payload. |
POST /api/v1/passes/:id/use | JWT espace / Clé API | Modification de tampons ou points déclenchée par CRM ou webhook sur un passe. |
POST /api/v1/mechanics/redeem | Clé 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/state | Clé Scanner ou JWT | Retourne le solde actuel de tampons/points ainsi que les indicateurs allowedActions. |
GET /api/v1/mechanics/:mechanicId/passes/:passId/ledger | Clé Scanner ou JWT | Liste l'historique des transactions de la mécanique (?limit=50, max 500). |
GET /api/v1/balance-changes | JWT espace / Clé API | Interroge 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 :
/api/v1/scans/pass/pass_loy_884120/use
{
"action": "INCREMENT",
"mechanicId": "11111111-2222-4333-8444-555555555555",
"amount": "2",
"deviceId": "ios-idfv-cafe-03",
"operatorId": "barista_03",
"location": "Main Counter"
}
Champ (request payload) | Type | Validation / Notes |
|---|---|---|
action | enum (optionnel, défaut INCREMENT) | Valeur parmi 'INCREMENT', 'DECREMENT', 'DEBIT', 'CREDIT', 'VALIDATE', 'NOOP', 'SET'. |
mechanicId | UUID (optionnel) | Vérifie la mécanique cible rattachée à ce passe. |
amount | chaîne décimale (optionnel) | Doit respecter /^\d+(\.\d{1,6})?$/ (ex. "2" ou "12.90"). |
deviceId / operatorId / location | chaînes (optionnel) | Consignés dans le journal d'audit pour le rapprochement d'équipe. |
idempotencyKey | chaîne (optionnel) | Doit correspondre à l'en-tête Idempotency-Key si les deux sont fournis. |
Réponse (200 OK — IPassUseResponse) :
{
"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
{
"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) :
{
"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
É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
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
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 workflowTIER_CHANGEDpour 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.
