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

Rapports de scan & validation

Consultez le volume par lieu de validation, les cumuls d'encaissement et la fréquence de visite des porteurs.

Dans ce guide

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

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE : TÉLÉMÉTRIE DE VALIDATION & D'UTILISATION DES SCANS
ÉTAPE 01 CANAUX D'INGESTION SCANNER & POS
Scanner Mobile / Web
POST/api/v1/scans
Terminal POS Point
POST/v1/pos/redeem
Lecteur NFC matériel
`/api/v1/reader/redeem
ÉTAPE 02 MOTEUR DE VALIDATION MÉTIER À 14 RÈGLES
1
Règles cœur : PassStatusRuleExpirationRuleTimeWindowRule
GeofencingRule
2
Mécaniques : OncePerDayRuleStampCardAddRulePrepaidCardRule
LoyaltyProgramRuleTierEvaluationRule
3
Sécurité : RateLimitRuleAntiReplayRule (scan nonce)
ÉTAPE 03 ENTREPÔT ANALYTIQUE DE SCANS & GRAND LIVRE
Ventilation scan status| D
(SUCCESS, EXPIRED, CHECK_IN_SUCCESS...)
oupage dimensionnel| | A
(scannerConfigId, operatorId, Lieu)
égats solde &
variation points du grand livre

Important : Chaque réponse de scan enregistre un tableau complet ruleTrace accompagné de operatorId, terminalId, scannerConfigurationId, externalId et des coordonnées GPS location, 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étriquedecision / scan status sous-jacentSignification opérationnelle
totalScansTous les événementsVolume total de codes-barres ou présentations NFC reçus par le moteur de validation sur la période.
successfulScansdecision: '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).
duplicateScansdecision: '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.
expiredScansdecision: 'EXPIRED' (EXPIRED)Présentations de cartes dont l'expirationDate est dépassée.
rejectedScansdecision: 'INVALID' (INVALID)Charges utiles de codes-barres inconnues, numéros de série d'un autre tenant ou signatures NFC cryptographiques invalides.
failedScansdecision: '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. 1
    Configuration de scanner (scannerConfigurationId) : Comparez les volumes entre profils distincts (par ex. Contrôle Accès VIP utilisant CHECK_IN scan mode vs Caisse Café Ajout Tampon utilisant StampCardAddRule).
  2. 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. 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. 4
    Canal & protocole (channel, protocol) : Suivez les scans optiques (QR, PDF417, CODE128, AZTEC) face aux passages sans contact (NFC via VAS, SMART_TAP, NDEF ou JWT).
  5. 5
    Impacts de valeur prépayée & fidélité (effects) : Rapprochez le total de stampsAdded, la variation nette pointsDelta et les crédits/débits transactionAmount par 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 :

HTTP
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)

JSON
{
  "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

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.