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.

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_SCANouStoredValueOperation.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 ScanMode | Comportement & transition d'état | Cas d'usage type |
|---|---|---|
SAVE_ATTENDANCE | Enregistre 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_SCAN | Passe 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_SCAN | Marque le passe comme invalidé après consommation et bloque toute réutilisation sous cette configuration de validation. | Passes à rachat unique et invitations restreintes. |
CHECK_IN | Fait 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_OUT | Fait passer l'état de présence d'entré à sorti. | Suivi des sorties de site, comptage de jauge d'occupation. |
CHECK_IN_CHECK_OUT_TOGGLE | Alterne 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ération | Valeurs autorisées | Rôle |
|---|---|---|
StoredValueOperation | NONE, ADD, SUBTRACT, SET | Indique si le scan laisse le solde inchangé, recharge du crédit (ADD), déduit un montant d'achat (SUBTRACT) ou fixe un solde (SET). |
StoredValueAmountSource | FIXED, OPERATOR, MECHANIC | Dé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). |
NfcReaderMode | AUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAP | Configure la négociation de protocole sans contact pour les terminaux Apple VAS et Google Smart Tap. |
| scan action | INCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOP | Action enregistrée dans chaque écriture du registre d'usage ou de scan (request payload autorise aussi SET). |
| scan status | SUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT | Statut 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) :
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
/api/v1/scans/prepare
{
"scannedBarcodeValue": "PI-TKT-992014",
"scannerConfigurationId": "scfg_main_entrance_01"
}
Réponse (201 Created)
{
"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
{
"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).
{
"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.
