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=...ouGET /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
Points d'entrée de consultation, d'audit & d'export des scans
| Méthode | Point d'entrée | Auth / Garde | Description |
|---|---|---|---|
| GET | /api/v1/scans/pass | x-scanner-key | Consultation 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/:barcodeValue | x-scanner-key | Consultation en lecture seule via paramètre de chemin retournant IPassLookupResponse. |
| GET | /api/v1/scans/result/:scanId | x-scanner-key | Récupère le résultat complet et ruleTrace d'un scan précis par son UUID scanId. |
| GET | /api/v1/scans/operations/:idempotencyKey | x-scanner-key | Retourne le reçu request payload conservé pour une clé x-idempotency-key déjà soumise. |
| GET | /api/v1/validation/scans | JWT espace / Clé API | Liste paginée des journaux de scan de l'espace de travail pour le tableau de bord (/scanner). |
| GET | /api/v1/validation/scans/:scanId | JWT espace / Clé API | Ré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/export | JWT espace / Clé API | Exporte en CSV l'historique de scans limité à une ScannerConfiguration. |
| GET | /api/v1/validation/scans/export | JWT espace / Clé API | Exporte en CSV tous les journaux de scans et validations de l'espace de travail. |
| GET | /api/v1/validation/scan-results/export/csv | JWT espace / Clé API | Diffuse 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) | Statut | reasonCode type | Action recommandée pour l'équipe / POS |
|---|---|---|---|
SUCCESS | ACCEPTED | RULE_ACCEPTED | Autoriser l'accès (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), appliquer la remise ou confirmer le débit. |
ALREADY_VOIDED | REJECTED | PASS_VOIDED_AFTER_SCAN | Refuser l'encaissement : le passe a déjà été consommé lors d'un scan à usage unique antérieur. |
ALREADY_USED | REJECTED | ONCE_PER_DAY_LIMIT_REACHED | Informer le titulaire que son quota journalier ou d'entrée (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) a déjà été utilisé. |
EXPIRED | REJECTED | PASS_EXPIRED | Inviter le client à renouveler son adhésion ou à bénéficier d'une offre active. |
FAILED | REJECTED | OUT_OF_BALANCE / GEOFENCE_MISMATCH | Consulter ruleTrace (ex. solde prépayé insuffisant ou mauvais lieu de validation). |
INVALID | REJECTED | PASS_NOT_FOUND / INVALID_NONCE | Code-barres étranger à cet espace/modèle ou nonce anti-rejeu expiré. |
PENDING | PENDING | OPERATOR_INPUT_REQUIRED | Inviter 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)
{
"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) :
/api/v1/scans/pass?barcode=PI-GFT-550192
{
"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.
