Skip to content
Guide du centre d'aide · Scan de passesPhase d'intégration 4
4 min de lectureVérifié 2026-11-16

Modes de scan & règles de validation

Paramétrez l'usage unique, l'entrée/sortie, la règle une fois par jour, les retours visuels et le mode hors ligne.

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

Message après scan et configurations Scanner (Zoom)

Personnalisez le message de confirmation opérateur avec des variables comme {holderName} et gérez les liens d'accès actifs.

Aperçu

Chaque scan soumis sur POST /api/v1/scans est évalué au regard de la ScannerConfiguration active (résolue soit depuis la clé x-scanner-key, soit via scannerConfigurationId / validationConfigId dans request payload) ainsi que par un pipeline déterministe à 14 règles dans Validation Rules Engine. Ensemble, ces réglages définissent si un passe enregistre une présence, s'invalide dès la première utilisation, bascule l'état d'entrée/sortie sur site, modifie une valeur prépayée ou contrôle un jeton cryptographique anti-rejeu.

Fenêtre de création d'une configuration scanner
Fenêtre de création d'une configuration scanner

Important : Les règles de validation s'exécutent de manière atomique côté serveur. Lorsqu'un scan modifie l'état d'un passe (comme VOIDED_AFTER_SCAN ou StoredValueOperation.SUBTRACT), les requêtes concurrentes dupliquées sont sérialisées par des verrous d'idempotence (x-idempotency-key) afin d'éviter toute condition de concurrence entre caisses.

Énumérations de configuration & de résultats

Lors du paramétrage des profils dans Scanner -> Scanner Configurations (/scanner/configs) ou via /api/v1/validation/configs, cinq énumérations Passinstance database pilotent le comportement du terminal et le résultat persisté :

1. Énumération ScanMode

Valeur ScanModeComportement & transition d'étatCas d'usage type
SAVE_ATTENDANCEEnregistre un événement de scan valide et exécute les mécaniques de fidélité/tampons liées sans invalider le passe.Cartes de fidélité multi-visites, abonnements de salle de sport, pass saisonniers.
VOIDED_AFTER_SCANPasse atomiquement le statut à VOIDED dès le premier scan valide ; les scans suivants renvoient ALREADY_VOIDED.Coupons à usage unique, bons promotionnels, billets d'entrée unique.
INVALIDATE_AFTER_SCANMarque le passe comme invalidé après consommation et bloque toute réutilisation sous cette configuration de validation.Passes à rachat unique et invitations restreintes.
CHECK_INFait passer l'état de présence du passe à enregistré en entrée ; rejette les nouveaux scans si déjà à l'intérieur.Entrée de conférence, portiques d'accès contrôlé.
CHECK_OUTFait passer l'état de présence d'entré à sorti.Suivi des sorties de site, comptage de jauge d'occupation.
CHECK_IN_CHECK_OUT_TOGGLEAlterne automatiquement entre CHECK_IN et CHECK_OUT à chaque scan successif.Espaces de coworking, bracelets/passes de festival multi-jours.

2. Énumérations valeur stockée, NFC & résultat de scan

Type d'énumérationValeurs autoriséesRôle
StoredValueOperationNONE, ADD, SUBTRACT, SETIndique si le scan laisse le solde inchangé, recharge du crédit (ADD), déduit un montant d'achat (SUBTRACT) ou fixe un solde (SET).
StoredValueAmountSourceFIXED, OPERATOR, MECHANICDétermine si le montant provient d'une valeur prédéfinie (FIXED), d'une saisie caissier (OPERATOR) ou de la mécanique du modèle (MECHANIC).
NfcReaderModeAUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAPConfigure la négociation de protocole sans contact pour les terminaux Apple VAS et Google Smart Tap.
scan actionINCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOPAction enregistrée dans chaque écriture du registre d'usage ou de scan (request payload autorise aussi SET).
scan statusSUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUTStatut granulaire persisté sur l'enregistrement d'audit Scan (incluant les transitions explicites d'entrée/sortie).

Le pipeline à 14 règles Validation Rules Engine

Lorsque POST /api/v1/scans reçoit une requête, Validation Rules Engine exécute 14 règles de validation ordonnées sur quatre étapes (Core -> Mechanics -> Security -> Fallback) :

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
PIPELINE DU MOTEUR DE RÈGLES MÉTIER À 14 RÈGLES
ÉTAPE 01 POST/api/v1/scans (request payload + x-scanner-key)
ÉTAPE 02 Étape 1 : Règles centrales
1
PassStatusRuleVérifier que le passe est ACTIVE (ni VOIDED ni SUSPENDED)
2
ExpirationRuleVérifier now() < expirationDate
3
TimeWindowRuleVérifier que le scan respecte les créneaux horaires autorisés
4
GeofencingRuleVérifier la position GPS scanner {lat, lng} dans le rayon
ÉTAPE 03 Étape 2 : Règles de mécaniques
5
OncePerDayRuleRejeter si déjà scanné sur la fenêtre glissante
6
StampCardAddRuleIncrémenter les tampons & évaluer le palier récompense
7
StampCardDeductRuleDéduire des tampons lors de l'échange d'une récompense
8
PrepaidCardRuleExécuter ADD / SUBTRACT / SET sur le solde prépayé
9
LoyaltyProgramRuleCalculer & appliquer pointsDelta
10
TierEvaluationRulePromouvoir de palier si le seuil est franchi
ÉTAPE 04 Étape 3 : Règles de sécurité
11
RateLimitRuleBloquer les rafales rapides de scans sur un même passe
12
AntiReplayRuleVérifier le scan nonce cryptographique issu de /scans/prepare
13
DeviceValidationRuleVérifier la clé scanner & le rattachement terminal
ÉTAPE 05 Étape 4 : Repli
14
DefaultAcceptanceRuleÉmettre decision: "SUCCESS", status: "ACCEPTED"

Chaque règle évaluée ajoute son verdict au tableau ruleTrace dans request payload, offrant une traçabilité diagnostique complète.

Jetons anti-rejeu (POST /api/v1/scans/prepare)

Pour protéger les billets et bons de forte valeur contre les captures d'écran statiques de codes-barres, les terminaux peuvent demander un scan nonce cryptographique éphémère avant l'exécution finale :

Requête

POST /api/v1/scans/prepare
En-tête
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "scannedBarcodeValue": "PI-TKT-992014",
  "scannerConfigurationId": "scfg_main_entrance_01"
}

Réponse (201 Created)

JSON
{
  "success": true,
  "data": {
    "nonce": "snonce_8841a9c2f01e4b72",
    "expiresAt": "2026-11-15T22:35:30.000Z"
  }
}

La transmission de "nonce": "snonce_8841a9c2f01e4b72" dans l'appel POST /api/v1/scans suivant valide AntiReplayRule et détruit immédiatement le nonce afin qu'il ne puisse plus être rejoué.

Schéma d'exécution de scan (POST /api/v1/scans)

Charge utile request payload

JSON
{
  "scannedBarcodeValue": "PI-LOY-449102",
  "scannerConfigurationId": "scfg_register_01",
  "nonce": "snonce_8841a9c2f01e4b72",
  "timestamp": "2026-11-15T22:35:10.000Z",
  "location": {
    "lat": 52.520008,
    "lng": 13.404954
  },
  "channel": "NFC",
  "protocol": "VAS",
  "validationData": {
    "amount": 18.50,
    "place": "Flagship Berlin Store"
  },
  "operatorId": "emp_cashier_07",
  "terminalId": "pos_term_berlin_02",
  "configurationVersion": 4
}

Charge utile request payload & codes de décision

Le moteur renvoie l'une des sept valeurs canoniques de decision : SUCCESS, FAILED, ALREADY_USED, ALREADY_VOIDED, EXPIRED, INVALID ou PENDING (lorsqu'une saisie opérateur est attendue via scanForm).

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": "RULE_ACCEPTED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "LoyaltyProgramRule", "passed": true, "pointsDelta": 185 },
    { "rule": "TierEvaluationRule", "passed": true, "upgradedTo": "GOLD" }
  ],
  "passSnapshot": {
    "id": "pass_loy_449102",
    "templateId": "tmpl_loyalty_01",
    "serialNumber": "PI-LOY-449102",
    "externalId": "crm_cust_44910",
    "status": "ACTIVE",
    "tier": "GOLD",
    "barcodeValue": "PI-LOY-449102",
    "storedValue": "42.00"
  },
  "remainingBalance": "42.00",
  "effects": {
    "oldBalance": "42.00",
    "newBalance": "42.00",
    "pointsDelta": 185,
    "transactionAmount": 18.50,
    "currency": "EUR"
  },
  "display": {
    "title": "Scan Accepted — Gold Tier!",
    "subtitle": "+185 Points awarded",
    "color": "success"
  },
  "configurationVersion": 4,
  "configurationStale": false
}

Pour auditer les scans effectués et exporter des journaux CSV, consultez Historique & résultats de scan.

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.