Skip to content
Guida del Centro assistenza
3 min di letturaVerificato 2026-11-16

Report scansioni e riscatti

Esamina flussi per Luogo di validazione, totali riscatti delle meccaniche e frequenza visite clienti.

In questa guida

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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
TELEMETRIA DI VALIDAZIONE SCANSIONI E RISCATTI
FASE 01 CANALI DI INGESTION SCANNER E POS
Scanner mobile / web
POST/api/v1/scans
Terminale POS retail
POST/v1/pos/redeem
Lettore NFC hardware
`/api/v1/reader/redeem
FASE 02 MOTORE DI VALIDAZIONE A 14 REGOLE
1
Regole Core: PassStatusRuleExpirationRuleTimeWindowRule
GeofencingRule
2
Regole Meccanica: OncePerDayRuleStampCardAddRulePrepaidCardRule
LoyaltyProgramRuleTierEvaluationRule
3
Regole Sicurezza: RateLimitRuleAntiReplayRule (scan nonce)
FASE 03 ARCHIVIO REPORTISTICA SCANSIONI E MASTRO
Ripartizione
scan status | (SUCCESS, EXPIRED...)
Slicing dimensionale
scannerConfigId, | operatorId, Luogo)
Rollup mastro
alore memorizzato e delta punti

Importante: Ogni risposta di scansione registra un array completo ruleTrace insieme a operatorId, terminalId, scannerConfigurationId, externalId e coordinate GPS location — 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 metricadecision / scan status sottostanteSignificato operativo
totalScansTutti gli eventi di scansioneTotale delle presentazioni barcode o NFC ricevute dal motore di validazione nel periodo considerato.
successfulScansdecision: '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).
duplicateScansdecision: '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.
expiredScansdecision: 'EXPIRED' (EXPIRED)Presentazioni di pass la cui expirationDate è già trascorsa.
rejectedScansdecision: 'INVALID' (INVALID)Payload codice a barre non riconosciuti, mancata corrispondenza seriale cross-tenant o firme NFC crittografiche non valide.
failedScansdecision: '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. 1
    Configurazione Scanner (scannerConfigurationId): Confronti il throughput tra profili distinti (es. Check-In Varco VIP con CHECK_IN scan mode vs. Aggiunta timbri Cassa Caffè con StampCardAddRule).
  2. 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. 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. 4
    Canale e protocollo (channel, protocol): Monitori le scansioni ottiche (QR, PDF417, CODE128, AZTEC) rispetto alle presentazioni tap contactless (NFC tramite VAS, SMART_TAP, NDEF o JWT).
  5. 5
    Effetti sul mastro valore memorizzato e fedeltà (effects): Riconcili il totale stampsAdded, il pointsDelta netto e i crediti/addebiti finanziari transactionAmount per 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:

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

JSON
{
  "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

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.