Skip to content
Guide du centre d'aide
3 min de lectureVérifié 2026-11-16

Programmes de points & récompenses

Concevez des programmes à paliers Points & Niveaux avec règles de cumul, montées en statut et alertes Wallet.

Dans ce guide

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.

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : CUMUL DE POINTS & PASSAGE DE PALIER
ACTEURS SYSTÈME PARTICIPANTS
P1 Achat POS / E-Commerce
P2 API Centrale Passinstance
P3 Tier Progression Engine
P4 Passe Wallet Client
ÉTAPE CTX CONTEXTE Achat : 120 €120 Pts
ÉTAPE 1 REQUÊTE / ACTION POST/api/v1/passes/:id/use
ÉTAPE 2 REQUÊTE / ACTION MàJ solde
›
{ action: "INCREMENT", value }
›
(actuel + pas borné)
ÉTAPE 3 REQUÊTE / ACTION Évaluer paliers
›
(Seuil franchi :
›
ArgentOr)
ÉTAPE 4 RÉPONSE Palier promu
ÉTAPE 5 REQUÊTE / ACTION Push APNs silencieux
ÉTAPE 6 RÉPONSE 200 OK (Nouveau palier)
›
& PATCH REST Google | (Carte passe en Or
›
Bannière écran verr. :
›
"Passé au niveau Or !")

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éfaut config.pointsPerScan ou 1.
  • Pour les intégrations POS et e-commerce, les points sont calculés dynamiquement selon le montant dépensé :
TEXT
earnedPoints = floor(purchaseTotal * pointsMultiplier)
  newBalance = clamp(currentBalance + earnedPoints, minimumValue, maximumValue)
  • Si autoResetAtMaximum: true ou config.onCap === "reset", le solde de points est réinitialisé à resetTargetValue (ou au solde initial) dès que maximumValue est 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

POST /api/v1/mechanics/redeem
En-têtes
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "passId": "8f94d930-b302-4fc8-9f12-000000000001",
  "mechanicId": "4a71b2d0-5e3a-4e8c-8f21-000000000002",
  "idempotencyKey": "redeem_tx_88194"
}

Réponse HTTP (200 OK)

JSON
{
  "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/:customerId ou les webhooks du plugin Shopware) et créditez automatiquement les cartes Wallet clients identifiées par externalId.
  • 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é scanner POST /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é.

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.