Panoramica
Ogni scansione di codice a barre o tocco contactless NFC elaborato attraverso l'App Mobile Scanner, il Web Scanner, l'Integrazione POS (POST /v1/pos/redeem e POST /v1/pos/scan), l'Orchestrazione lettori hardware (POST /api/v1/reader/redeem) oppure la Scanner Runtime API (POST /api/v1/scans) genera un record di audit immutabile e tracciabile crittograficamente. I Report su scansioni e riscatti (/scanner nella Dashboard e /api/v1/validation/scans) aggregano questi eventi per configurazioni scanner, luoghi fisici di validazione, ID operatore e mastri delle meccaniche per offrire ai responsabili operativi piena visibilità sul punto vendita o sul varco.
Pipeline di telemetria delle scansioni e traccia regole
Importante: Ogni risposta di scansione registra un array completo
ruleTraceinsieme aoperatorId,terminalId,scannerConfigurationId,externalIde coordinate GPSlocation— consentendo ai team di conformità di verificare esattamente perché una scansione sia stata accettata o rifiutata.
Definizioni metriche di scansione, scan status e dettaglio PosOperation
Passinstance classifica il traffico di validazione in bucket KPI canonici definiti in PASS_ANALYTICS_METRIC_DEFINITIONS, supportati da decision in the scan response e dall'enum 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):
| Chiave metrica | decision / scan status sottostante | Significato operativo |
|---|---|---|
totalScans | Tutti gli eventi di scansione | Totale delle presentazioni barcode o NFC ricevute dal motore di validazione nel periodo considerato. |
successfulScans | decision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS) | Scansioni che hanno superato tutte le 14 regole di validazione ed eseguito la relativa azione di presenza o meccanica (scan action). |
duplicateScans | decision: 'ALREADY_USED' o 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT) | Tentativi di riutilizzo su coupon monouso (VOIDED_AFTER_SCAN scan mode) o pass già registrati in ingresso/uscita. |
expiredScans | decision: 'EXPIRED' (EXPIRED) | Presentazioni di pass la cui expirationDate è già trascorsa. |
rejectedScans | decision: 'INVALID' (INVALID) | Payload codice a barre non riconosciuti, mancata corrispondenza seriale cross-tenant o firme NFC crittografiche non valide. |
failedScans | decision: 'FAILED' (FAILED: es. OUT_OF_BALANCE, COOLDOWN_ACTIVE) | Pass validi rifiutati da una violazione di regola di business quale saldo prepagato insufficiente, mancata corrispondenza geofence o attesa OncePerDayRule. |
Per le casse retail integrate che inviano a POST /v1/pos/redeem, le transazioni registrano anche PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) e walletPropagation (PosWalletPropagationStatus: QUEUED | SKIPPED), ispezionabili tramite GET /v1/pos/admin/logs.
Reportistica multidimensionale: luoghi, configurazioni e operatori
I report di validazione possono essere filtrati e raggruppati lungo cinque dimensioni operative:
-
1
Configurazione Scanner (
scannerConfigurationId): Confronti il throughput tra profili distinti (es. Check-In Varco VIP conCHECK_IN scan modevs. Aggiunta timbri Cassa Caffè conStampCardAddRule). -
2
Luogo di validazione e geofence: Raggruppi i riscatti per filiale del punto vendita, ingresso dell'evento o raggio di coordinate GPS per misurare l'affluenza presso ciascuna sede fisica.
-
3
Operatore e terminale (
operatorId,terminalId): Verifichi il volume di scansioni e gli inserimenti manuali di importi per singolo cassiere, nome dispositivo (deviceName) o cassa POS. -
4
Canale e protocollo (
channel,protocol): Monitori le scansioni ottiche (QR,PDF417,CODE128,AZTEC) rispetto alle presentazioni tap contactless (NFCtramiteVAS,SMART_TAP,NDEFoJWT). -
5
Effetti sul mastro valore memorizzato e fedeltà (
effects): Riconcili il totalestampsAdded, ilpointsDeltanetto e i crediti/addebiti finanziaritransactionAmountper valuta (ISO-4217).
Ispezione dei log di audit scansione ed effetti sul mastro via API
Schema del payload evento scansione registrato ed effetti sul mastro
Quando si interroga lo storico delle scansioni (GET /api/v1/validation/configs/:id/scans oppure GET /api/v1/scans/result/:scanId), ciascun evento fornisce il contesto diagnostico e finanziario completo:
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>
Payload di risposta (200 OK)
{
"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 }
]
}
Documentazione correlata
-
Esporti storici completi delle scansioni e inventari delle chiavi scanner in Esportazione dati e reportistica.
-
Esplori i grafici telemetrici del workspace nella Dashboard Analytics.
