Panoramica
Ogni richiesta di validazione elaborata da Passinstance genera un record di audit immutabile contenente il campo decision valutato, il reasonCode, il ruleTrace passo per passo, i metadati dell'operatore e i saldi del pass prima e dopo l'operazione. È possibile consultare lo storico delle scansioni visivamente nella Dashboard sotto Scanner (/scanner), ispezionare singole ricevute di scansione, interrogare gli esiti di operazioni idempotenti, effettuare ricerche non modificanti del pass oppure generare esportazioni CSV complete per la riconciliazione contabile.
Importante: Le route di sola lettura (
GET /api/v1/scans/pass?barcode=...oGET /api/v1/scans/pass/:barcodeValue) consentono ai terminali POS e agli sportelli di assistenza clienti di ispezionare stato del pass,externalId, livello e saldo senza registrare un evento di scansione, incrementare contatori o annullare voucher monouso.
Architettura e flusso di interrogazione audit
Endpoint di ricerca, audit ed esportazione delle scansioni
| Metodo | Endpoint | Autenticazione / Guard | Descrizione |
|---|---|---|---|
| GET | /api/v1/scans/pass | x-scanner-key | Ricerca pass in sola lettura tramite parametro query ?barcode=... (consigliato per payload in formato URL). Non crea alcun record di scansione. |
| GET | /api/v1/scans/pass/:barcodeValue | x-scanner-key | Ricerca pass in sola lettura tramite parametro di percorso che restituisce IPassLookupResponse. |
| GET | /api/v1/scans/result/:scanId | x-scanner-key | Recupera l'esito completo e il ruleTrace di una specifica scansione tramite il suo UUID scanId. |
| GET | /api/v1/scans/operations/:idempotencyKey | x-scanner-key | Recupera la ricevuta request payload archiviata per un x-idempotency-key inviato in precedenza. |
| GET | /api/v1/validation/scans | JWT Workspace / Chiave API | Elenca i log di scansione paginati del workspace per la Dashboard (/scanner). |
| GET | /api/v1/validation/scans/:scanId | JWT Workspace / Chiave API | Recupera un singolo record di audit e la traccia di scansione del workspace per l'ispezione nella Dashboard. |
| GET | /api/v1/validation/configs/:id/scans/export | JWT Workspace / Chiave API | Esporta in CSV lo storico delle scansioni limitato a una specifica ScannerConfiguration. |
| GET | /api/v1/validation/scans/export | JWT Workspace / Chiave API | Esporta in CSV i log di scansione e riscatto dell'intero workspace. |
| GET | /api/v1/validation/scan-results/export/csv | JWT Workspace / Chiave API | Trasmette in streaming la traccia di audit completa delle scansioni con gli esiti di valutazione delle regole (text/csv). |
Esiti decisionali (request payload) rispetto a scan status persistito
L'API restituisce un enum di alto livello decision (SUCCESS | FAILED | ALREADY_USED | ALREADY_VOIDED | EXPIRED | INVALID | PENDING) in request payload, persistendo al contempo lo stato granulare scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) sul record di scansione sottostante:
Decision (request payload) | Stato | reasonCode tipico | Azione consigliata per staff / POS |
|---|---|---|---|
SUCCESS | ACCEPTED | RULE_ACCEPTED | Consente l'ingresso (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), applica lo sconto o conferma l'addebito del saldo. |
ALREADY_VOIDED | REJECTED | PASS_VOIDED_AFTER_SCAN | Rifiuta il riscatto; il pass è già stato consumato in una precedente scansione monouso. |
ALREADY_USED | REJECTED | ONCE_PER_DAY_LIMIT_REACHED | Informa il titolare che la quota giornaliera o di check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) è già stata utilizzata. |
EXPIRED | REJECTED | PASS_EXPIRED | Indirizza il cliente al rinnovo dell'abbonamento o a richiedere una campagna attiva. |
FAILED | REJECTED | OUT_OF_BALANCE / GEOFENCE_MISMATCH | Controlla i dettagli di ruleTrace (es. saldo prepagato insufficiente o punto di controllo errato). |
INVALID | REJECTED | PASS_NOT_FOUND / INVALID_NONCE | Il codice a barre non appartiene a questo workspace/modello oppure il nonce anti-replay è scaduto. |
PENDING | PENDING | OPERATOR_INPUT_REQUIRED | Richiede al cassiere di compilare i campi obbligatori in scanForm (come l'importo della transazione). |
Ispezione di una scansione completata (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"
}
}
Ricerca pass non modificante (GET /api/v1/scans/pass)
Prima di inviare una scansione modificante o un addebito POS, un terminale può interrogare lo stato attuale di un pass tramite GET /api/v1/scans/pass?barcode=PI-GFT-550192 (preferisca ?barcode= al parametro di percorso ogni volta che i codici a barre contengono barre o URL):
/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"
}
Esportazione dei log di scansione in CSV
Per la riconciliazione di turno, audit finanziari o importazione BI, è possibile esportare lo storico delle scansioni direttamente come flussi CSV UTF-8 (Content-Type: text/csv; charset=utf-8):
-
Esportazione singola configurazione:
GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16 -
Esportazione tutte le configurazioni:
GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01 -
Esportazione audit risultati completi:
GET /api/v1/validation/scan-results/export/csv
Consulti Report su scansioni e riscatti ed Esportazione dati e reportistica per le opzioni di aggregazione analitica.
