Aperçu
Chaque scan de code-barres ou présentation sans contact NFC traitée via l'application mobile Scanner, le Scanner Web, l'intégration POS (POST /v1/pos/redeem et POST /v1/pos/scan), l'orchestration de lecteurs matériels (POST /api/v1/reader/redeem) ou l'API d'exécution du scanner (POST /api/v1/scans) génère un enregistrement d'audit immuable et traçable cryptographiquement. Les rapports de scan et d'utilisation (/scanner dans le tableau de bord et /api/v1/validation/scans) agrègent ces événements par configuration de scanner, lieu de validation physique, identifiant d'opérateur et grand livre de mécanique afin d'offrir aux responsables d'exploitation une visibilité complète sur le terrain.
Chaîne de télémétrie de scan & trace des règles
Important : Chaque réponse de scan enregistre un tableau complet
ruleTraceaccompagné deoperatorId,terminalId,scannerConfigurationId,externalIdet des coordonnées GPSlocation, permettant aux équipes de conformité de vérifier exactement pourquoi un scan a été accepté ou refusé.
Définitions des métriques, scan status & détail PosOperation
Passinstance classe le trafic de validation dans les catégories canoniques définies dans PASS_ANALYTICS_METRIC_DEFINITIONS, adossées à decision in the scan response et à l'énumération Passinstance database scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) :
| Clé de métrique | decision / scan status sous-jacent | Signification opérationnelle |
|---|---|---|
totalScans | Tous les événements | Volume total de codes-barres ou présentations NFC reçus par le moteur de validation sur la période. |
successfulScans | decision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS) | Scans ayant satisfait aux 14 règles de validation et exécuté l'action de présence ou de mécanique configurée (scan action). |
duplicateScans | decision: 'ALREADY_USED' ou 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT) | Tentatives répétées sur des coupons à usage unique (VOIDED_AFTER_SCAN scan mode) ou des cartes déjà enregistrées en entrée/sortie. |
expiredScans | decision: 'EXPIRED' (EXPIRED) | Présentations de cartes dont l'expirationDate est dépassée. |
rejectedScans | decision: 'INVALID' (INVALID) | Charges utiles de codes-barres inconnues, numéros de série d'un autre tenant ou signatures NFC cryptographiques invalides. |
failedScans | decision: 'FAILED' (FAILED : p. ex. OUT_OF_BALANCE, COOLDOWN_ACTIVE) | Cartes valides refusées pour violation d'une règle métier telle que solde prépayé insuffisant, géorepérage non respecté ou délai OncePerDayRule. |
Pour les caisses intégrées appelant POST /v1/pos/redeem, les transactions enregistrent également PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) et walletPropagation (PosWalletPropagationStatus : QUEUED | SKIPPED), consultables via GET /v1/pos/admin/logs.
Rapports dimensionnels : lieux, configurations & opérateurs
Les rapports de validation peuvent être filtrés et groupés selon cinq axes opérationnels :
-
1
Configuration de scanner (
scannerConfigurationId) : Comparez les volumes entre profils distincts (par ex. Contrôle Accès VIP utilisantCHECK_IN scan modevs Caisse Café Ajout Tampon utilisantStampCardAddRule). -
2
Lieu de validation & géorepérage : Regroupez les validations par boutique, entrée de site ou rayon GPS afin de mesurer l'affluence par site physique.
-
3
Opérateur & terminal (
operatorId,terminalId) : Auditez le volume de scans et les montants saisis manuellement par caissier, nom d'appareil (deviceName) ou caisse POS. -
4
Canal & protocole (
channel,protocol) : Suivez les scans optiques (QR,PDF417,CODE128,AZTEC) face aux passages sans contact (NFCviaVAS,SMART_TAP,NDEFouJWT). -
5
Impacts de valeur prépayée & fidélité (
effects) : Rapprochez le total destampsAdded, la variation nettepointsDeltaet les crédits/débitstransactionAmountpar devise (ISO-4217).
Consulter les journaux d'audit de scan & effets via API
Schéma d'événement de scan & de charge utile du grand livre
Lors de la consultation de l'historique (GET /api/v1/validation/configs/:id/scans ou GET /api/v1/scans/result/:scanId), chaque événement fournit le contexte complet de diagnostic et financier :
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>
Charge utile de réponse (200 OK)
{
"scanId": "scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c",
"timestamp": "2026-11-16T08:42:11.304Z",
"decision": "SUCCESS",
"status": "ACCEPTED",
"reasonCode": null,
"channel": "NFC",
"protocol": "VAS",
"resolvedConfigId": "cfg_7d82a100-3c4b-4e12-9a88-112233445566",
"passSnapshot": {
"id": "pas_55a19c88-102b-4f33-8d99-ccddff001122",
"templateId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
"serialNumber": "PI-2026-994812",
"externalId": "CRM-88210",
"status": "ACTIVE",
"tier": "GOLD"
},
"effects": {
"oldBalance": "45.00",
"newBalance": "32.50",
"transactionAmount": 12.50,
"currency": "EUR",
"amountBalanceBehavior": "ADD_VALUE",
"pointsDelta": 125,
"stampsAdded": 0
},
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true },
{ "rule": "ExpirationRule", "passed": true },
{ "rule": "PrepaidCardRule", "passed": true, "deducted": 12.50 },
{ "rule": "LoyaltyProgramRule", "passed": true, "awardedPoints": 125 }
]
}
Documentation connexe
-
Exportez les historiques complets de scan et inventaires de clés scanner dans Exports de données & rapports.
-
Explorez les graphiques de télémétrie de l'espace de travail dans Tableau de bord analytique.
