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

Historique & résultats de scan

Auditez les statuts (VALID, ALREADY_REDEEMED, EXPIRED, VOIDED), l'horodatage, les lieux et réponses.

Dans ce guide

Aperçu

Chaque requête de validation traitée par Passinstance génère un enregistrement d'audit immuable contenant la decision évaluée, le reasonCode, le détail étape par étape ruleTrace, les métadonnées opérateur ainsi que les soldes avant et après opération. Vous pouvez consulter l'historique visuellement dans le tableau de bord sous Scanner (/scanner), inspecter chaque reçu de scan, retrouver le résultat d'une opération idempotente, interroger un passe sans modification ou exporter l'intégralité en CSV pour votre rapprochement comptable.

Important : Les routes de consultation en lecture seule (GET /api/v1/scans/pass?barcode=... ou GET /api/v1/scans/pass/:barcodeValue) permettent aux caisses et services client de vérifier le statut, l'externalId, le palier et le solde d'un passe sans enregistrer d'événement de scan, incrémenter de compteur ni invalider un coupon à usage unique.

Architecture & flux de consultation d'audit

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
REÇU DE SCAN & PIPELINE D'EXPORT D'AUDIT
ACTEURS SYSTÈME PARTICIPANTS
P1 Client POS / Scanner
P2 Scan Validation API (/api/v1/scans)
P3 Validation Config API (/api/v1/validation)
ÉTAPE 1 REQUÊTE / ACTION GET/scans/pass?barcode=...
ÉTAPE 2 RÉPONSE 200 OK (IPassLookupResponse)
ÉTAPE 3 REQUÊTE / ACTION GET/scans/operations/:idem
ÉTAPE 4 RÉPONSE 200 OK (Cached ScanResponse)
ÉTAPE 5 REQUÊTE / ACTION GET/scans/result/:scanId
ÉTAPE 6 RÉPONSE 200 OK (Full ruleTrace)
ÉTAPE 7 REQUÊTE / ACTION GET/validation/scan-results/export/csv
ÉTAPE 8 RÉPONSE 200 OK (flux text/csv : scan_id, decision, operator, effects)

Points d'entrée de consultation, d'audit & d'export des scans

MéthodePoint d'entréeAuth / GardeDescription
GET/api/v1/scans/passx-scanner-keyConsultation en lecture seule via le paramètre ?barcode=... (recommandé pour les valeurs contenant des URLs). N'enregistre pas de scan.
GET/api/v1/scans/pass/:barcodeValuex-scanner-keyConsultation en lecture seule via paramètre de chemin retournant IPassLookupResponse.
GET/api/v1/scans/result/:scanIdx-scanner-keyRécupère le résultat complet et ruleTrace d'un scan précis par son UUID scanId.
GET/api/v1/scans/operations/:idempotencyKeyx-scanner-keyRetourne le reçu request payload conservé pour une clé x-idempotency-key déjà soumise.
GET/api/v1/validation/scansJWT espace / Clé APIListe paginée des journaux de scan de l'espace de travail pour le tableau de bord (/scanner).
GET/api/v1/validation/scans/:scanIdJWT espace / Clé APIRécupère un enregistrement d'audit de scan et sa trace pour inspection dans le tableau de bord.
GET/api/v1/validation/configs/:id/scans/exportJWT espace / Clé APIExporte en CSV l'historique de scans limité à une ScannerConfiguration.
GET/api/v1/validation/scans/exportJWT espace / Clé APIExporte en CSV tous les journaux de scans et validations de l'espace de travail.
GET/api/v1/validation/scan-results/export/csvJWT espace / Clé APIDiffuse la piste d'audit complète des scans avec résultats d'évaluation des règles (text/csv).

Décisions retournées (request payload) vs statut persisté scan status

L'API retourne une énumération de haut niveau decision (SUCCESS \| FAILED \| ALREADY_USED \| ALREADY_VOIDED \| EXPIRED \| INVALID \| PENDING) dans request payload, tout en enregistrant en base le statut détaillé scan status (SUCCESS \| FAILED \| PENDING \| INVALID \| EXPIRED \| ALREADY_USED \| ALREADY_VOIDED \| CHECK_IN_SUCCESS \| CHECK_OUT_SUCCESS \| ALREADY_CHECKED_IN \| ALREADY_CHECKED_OUT) sur l'événement de scan :

Décision (request payload)StatutreasonCode typeAction recommandée pour l'équipe / POS
SUCCESSACCEPTEDRULE_ACCEPTEDAutoriser l'accès (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), appliquer la remise ou confirmer le débit.
ALREADY_VOIDEDREJECTEDPASS_VOIDED_AFTER_SCANRefuser l'encaissement : le passe a déjà été consommé lors d'un scan à usage unique antérieur.
ALREADY_USEDREJECTEDONCE_PER_DAY_LIMIT_REACHEDInformer le titulaire que son quota journalier ou d'entrée (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) a déjà été utilisé.
EXPIREDREJECTEDPASS_EXPIREDInviter le client à renouveler son adhésion ou à bénéficier d'une offre active.
FAILEDREJECTEDOUT_OF_BALANCE / GEOFENCE_MISMATCHConsulter ruleTrace (ex. solde prépayé insuffisant ou mauvais lieu de validation).
INVALIDREJECTEDPASS_NOT_FOUND / INVALID_NONCECode-barres étranger à cet espace/modèle ou nonce anti-rejeu expiré.
PENDINGPENDINGOPERATOR_INPUT_REQUIREDInviter l'opérateur à saisir les champs requis dans scanForm (comme le montant de la transaction).

Inspecter un scan terminé (GET /api/v1/scans/result/:scanId)

JSON
{
  "scanId": "scan_01hxyz7712ab",
  "idempotencyKey": "idem_reg04_20261116_0091",
  "timestamp": "2026-11-16T09:42:11.000Z",
  "decision": "ALREADY_USED",
  "status": "REJECTED",
  "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true, "durationMs": 1 },
    { "rule": "ExpirationRule", "passed": true, "durationMs": 1 },
    {
      "rule": "OncePerDayRule",
      "passed": false,
      "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
      "lastScanAt": "2026-11-16T06:15:04.000Z",
      "durationMs": 3
    }
  ],
  "passSnapshot": {
    "id": "pass_gym_8821",
    "templateId": "tmpl_gym_member",
    "serialNumber": "PI-GYM-8821",
    "externalId": "crm_member_8821",
    "status": "ACTIVE"
  }
}

Consultation sans mutation (GET /api/v1/scans/pass)

Avant de soumettre un scan modifiant l'état ou un débit caisse, un terminal peut consulter l'état courant du passe via GET /api/v1/scans/pass?barcode=PI-GFT-550192 (privilégiez ?barcode= au paramètre de chemin dès que les codes-barres contiennent des barres obliques ou des URLs) :

GET /api/v1/scans/pass?barcode=PI-GFT-550192
En-tête
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "passId": "pass_gft_550192",
  "templateId": "tmpl_giftcard_eur",
  "templateName": "Retail Gift Card",
  "serialNumber": "PI-GFT-550192",
  "externalId": "shopify_cust_550192",
  "status": "ACTIVE",
  "storedValue": "75.00",
  "expirationDate": "2027-12-31T23:59:59.000Z",
  "isExpired": false,
  "isVoided": false,
  "barcodeValue": "PI-GFT-550192",
  "attributes": {
    "holderName": "Elena Rostova"
  },
  "checkedAt": "2026-11-16T10:15:00.000Z"
}

Exporter les journaux de scan en CSV

Pour les rapprochements de caisse, audits financiers ou intégrations BI, exportez directement les historiques de scan en flux CSV UTF-8 (Content-Type: text/csv; charset=utf-8) :

  • Export d'une configuration précise : GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16
  • Export toutes configurations : GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01
  • Export complet de piste d'audit : GET /api/v1/validation/scan-results/export/csv

Consultez Rapports de scan & validation et Exports de données & reporting pour les options d'agrégation analytique.

Documentation produit et développeur associée

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.