Skip to content
Guida del Centro assistenza · Scansione pass
4 min di letturaVerificato 2026-11-16

Storico e risultati scansioni

Verifica esiti (VALID, ALREADY_REDEEMED, EXPIRED, VOIDED), orari, punti vendita e risposte.

In questa guida

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=... o GET /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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
RICEVUTA DI SCANSIONE E PIPELINE DI ESPORTAZIONE AUDIT
ATTORI DI SISTEMA COINVOLTI
P1 Client POS / Scanner
P2 Scan Validation API (/api/v1/scans)
P3 Validation Config API (/api/v1/validation)
FASE 1 RICHIESTA / AZIONE GET/scans/pass?barcode=...
FASE 2 RISPOSTA 200 OK (IPassLookupResponse)
FASE 3 RICHIESTA / AZIONE GET/scans/operations/:idem
FASE 4 RISPOSTA 200 OK (Cached ScanResponse)
FASE 5 RICHIESTA / AZIONE GET/scans/result/:scanId
FASE 6 RISPOSTA 200 OK (Full ruleTrace)
FASE 7 RICHIESTA / AZIONE GET/validation/scan-results/export/csv
FASE 8 RISPOSTA 200 OK (flusso text/csv: scan_id, decision, operator, effects)

Endpoint di ricerca, audit ed esportazione delle scansioni

MetodoEndpointAutenticazione / GuardDescrizione
GET/api/v1/scans/passx-scanner-keyRicerca 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/:barcodeValuex-scanner-keyRicerca pass in sola lettura tramite parametro di percorso che restituisce IPassLookupResponse.
GET/api/v1/scans/result/:scanIdx-scanner-keyRecupera l'esito completo e il ruleTrace di una specifica scansione tramite il suo UUID scanId.
GET/api/v1/scans/operations/:idempotencyKeyx-scanner-keyRecupera la ricevuta request payload archiviata per un x-idempotency-key inviato in precedenza.
GET/api/v1/validation/scansJWT Workspace / Chiave APIElenca i log di scansione paginati del workspace per la Dashboard (/scanner).
GET/api/v1/validation/scans/:scanIdJWT Workspace / Chiave APIRecupera un singolo record di audit e la traccia di scansione del workspace per l'ispezione nella Dashboard.
GET/api/v1/validation/configs/:id/scans/exportJWT Workspace / Chiave APIEsporta in CSV lo storico delle scansioni limitato a una specifica ScannerConfiguration.
GET/api/v1/validation/scans/exportJWT Workspace / Chiave APIEsporta in CSV i log di scansione e riscatto dell'intero workspace.
GET/api/v1/validation/scan-results/export/csvJWT Workspace / Chiave APITrasmette 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)StatoreasonCode tipicoAzione consigliata per staff / POS
SUCCESSACCEPTEDRULE_ACCEPTEDConsente l'ingresso (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), applica lo sconto o conferma l'addebito del saldo.
ALREADY_VOIDEDREJECTEDPASS_VOIDED_AFTER_SCANRifiuta il riscatto; il pass è già stato consumato in una precedente scansione monouso.
ALREADY_USEDREJECTEDONCE_PER_DAY_LIMIT_REACHEDInforma il titolare che la quota giornaliera o di check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) è già stata utilizzata.
EXPIREDREJECTEDPASS_EXPIREDIndirizza il cliente al rinnovo dell'abbonamento o a richiedere una campagna attiva.
FAILEDREJECTEDOUT_OF_BALANCE / GEOFENCE_MISMATCHControlla i dettagli di ruleTrace (es. saldo prepagato insufficiente o punto di controllo errato).
INVALIDREJECTEDPASS_NOT_FOUND / INVALID_NONCEIl codice a barre non appartiene a questo workspace/modello oppure il nonce anti-replay è scaduto.
PENDINGPENDINGOPERATOR_INPUT_REQUIREDRichiede 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)

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"
  }
}

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

GET /api/v1/scans/pass?barcode=PI-GFT-550192
Header
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"
}

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.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.