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

Modalità di scansione e regole

Imposta riscatto singolo, check-in/out, limite giornaliero, messaggi operatori e regole cache offline.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito
Elementi chiave dell'interfaccia

Messaggio post-scansione e configurazioni Scanner (Zoom)

Personalizza il messaggio di conferma per l'operatore usando segnaposto come {holderName} e gestisci i link di accesso attivi.

Panoramica

Ogni scansione inviata a POST /api/v1/scans viene valutata rispetto alla ScannerConfiguration attiva (risolta tramite la x-scanner-key associata oppure tramite scannerConfigurationId / validationConfigId in request payload) e a una pipeline deterministica Validation Rules Engine a 14 regole. Insieme, queste impostazioni stabiliscono se un pass registra una presenza, si annulla al primo utilizzo, alterna lo stato di check-in in sede, modifica il valore memorizzato o impone nonce crittografici anti-replay.

Finestra modale creazione configurazione scanner
Finestra modale creazione configurazione scanner

Importante: Le regole di validazione vengono eseguite atomicamente lato server. Quando una scansione modifica lo stato del pass (come VOIDED_AFTER_SCAN o StoredValueOperation.SUBTRACT), eventuali richieste concorrenti duplicate vengono serializzate tramite blocchi di idempotenza (x-idempotency-key) per prevenire race condition tra più casse.

Configurazione ed enumerazioni degli esiti

Quando si configurano profili di validazione in Scanner -> Configurazioni Scanner (/scanner/configs) oppure tramite /api/v1/validation/configs, cinque enumerazioni Passinstance database controllano il comportamento del terminale e gli esiti persistenti delle scansioni:

1. Enum ScanMode

Valore ScanModeComportamento e transizione di statoCaso d'uso tipico
SAVE_ATTENDANCERegistra un evento di scansione valido ed esegue le meccaniche fedeltà/timbri collegate senza annullare il pass.Carte fedeltà multi-visita, abbonamenti palestra, abbonamenti stagionali.
VOIDED_AFTER_SCANPorta atomicamente lo stato del pass su VOIDED alla prima scansione valida; le scansioni successive restituiscono ALREADY_VOIDED.Coupon monouso, buoni promozionali, biglietti d'ingresso singoli.
INVALIDATE_AFTER_SCANContrassegna il pass come invalidato dopo il riscatto e ne blocca l'accettazione futura sotto la configurazione di validazione.Pass a singolo riscatto e voucher ospiti con restrizioni.
CHECK_INPorta lo stato di presenza del pass su registrato (checked-in); rifiuta ulteriori check-in se l'utente è già all'interno.Ingressi a sessioni di conferenze, varchi ad accesso controllato.
CHECK_OUTPorta lo stato di presenza del pass da checked-in a checked-out.Tracciamento uscite dalla sede, gestione capienza.
CHECK_IN_CHECK_OUT_TOGGLEAlterna automaticamente tra CHECK_IN e CHECK_OUT alle scansioni successive.Spazi di co-working, braccialetti/pass per festival multi-giorno.

2. Enumerazioni per valore memorizzato, NFC ed esito scansione

Tipo EnumValori consentitiScopo
StoredValueOperationNONE, ADD, SUBTRACT, SETDefinisce se una scansione lascia intatti i saldi, ricarica credito (ADD), addebita un importo (SUBTRACT) o sovrascrive il saldo (SET).
StoredValueAmountSourceFIXED, OPERATOR, MECHANICStabilisce se l'importo della transazione proviene da un valore preimpostato (FIXED), dall'input del cassiere (OPERATOR) o dalla meccanica del modello (MECHANIC).
NfcReaderModeAUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAPConfigura la negoziazione del protocollo contactless per terminali Apple VAS e Google Smart Tap.
scan actionINCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOPAzione registrata su ciascuna transazione di utilizzo pass o mastro di scansione (request payload consente anche SET).
scan statusSUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUTStato granulare persistito sul record di audit Scan (comprese le transizioni esplicite di check-in/check-out).

La pipeline a 14 regole Validation Rules Engine

Quando POST /api/v1/scans riceve un payload, Validation Rules Engine esegue 14 regole di validazione prioritizzate in quattro stadi (Core -> Mechanics -> Security -> Fallback):

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PIPELINE MOTORE DI VALIDAZIONE A 14 REGOLE
FASE 01 POST/api/v1/scans (request payload + x-scanner-key)
FASE 02 Stadio 1: Regole Core
1
PassStatusRuleVerifica pass ACTIVE (non VOIDED / SUSPENDED)
2
ExpirationRuleVerifica now() < expirationDate
3
TimeWindowRuleVerifica scansione entro fascia oraria/orari consentiti
4
GeofencingRuleVerifica GPS scanner {lat, lng} entro il raggio
FASE 03 Stadio 2: Regole Mechanics
5
OncePerDayRuleRifiuta se già scansionato nella finestra mobile
6
StampCardAddRuleIncrementa contatore timbri e valuta traguardo
7
StampCardDeductRuleScala timbri per riscatto premio
8
PrepaidCardRuleEsegue ADD / SUBTRACT / SET sul valore memorizzato
9
LoyaltyProgramRuleCalcola e applica pointsDelta
10
TierEvaluationRulePromuove il livello del pass al superamento soglia
FASE 04 Stadio 3: Regole Security
11
RateLimitRulePreviene raffiche rapide di scansioni su un pass
12
AntiReplayRuleVerifica scan nonce crittografico da /scans/prepare
13
DeviceValidationRuleVerifica chiave scanner e associazione terminale
FASE 05 Stadio 4: Fallback
14
DefaultAcceptanceRuleEmette decision: "SUCCESS", status: "ACCEPTED"

Ogni regola valutata durante la scansione aggiunge il proprio risultato di esecuzione all'array ruleTrace in request payload, fornendo una traccia diagnostica completa.

Nonce anti-replay (POST /api/v1/scans/prepare)

Per proteggere biglietti e voucher ad alto valore da screenshot statici dei codici a barre, i terminali possono richiedere un scan nonce crittografico a breve scadenza prima dell'esecuzione finale:

Richiesta

POST /api/v1/scans/prepare
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "scannedBarcodeValue": "PI-TKT-992014",
  "scannerConfigurationId": "scfg_main_entrance_01"
}

Risposta (201 Created)

JSON
{
  "success": true,
  "data": {
    "nonce": "snonce_8841a9c2f01e4b72",
    "expiresAt": "2026-11-15T22:35:30.000Z"
  }
}

Passando "nonce": "snonce_8841a9c2f01e4b72" nel successivo payload POST /api/v1/scans, si soddisfa AntiReplayRule e si consuma immediatamente il nonce affinché non possa essere riutilizzato.

Schema di esecuzione scansione (POST /api/v1/scans)

Payload request payload

JSON
{
  "scannedBarcodeValue": "PI-LOY-449102",
  "scannerConfigurationId": "scfg_register_01",
  "nonce": "snonce_8841a9c2f01e4b72",
  "timestamp": "2026-11-15T22:35:10.000Z",
  "location": {
    "lat": 52.520008,
    "lng": 13.404954
  },
  "channel": "NFC",
  "protocol": "VAS",
  "validationData": {
    "amount": 18.50,
    "place": "Flagship Berlin Store"
  },
  "operatorId": "emp_cashier_07",
  "terminalId": "pos_term_berlin_02",
  "configurationVersion": 4
}

Payload request payload e codici decisionali

Il motore restituisce uno dei sette valori canonici di decision: SUCCESS, FAILED, ALREADY_USED, ALREADY_VOIDED, EXPIRED, INVALID oppure PENDING (quando è richiesto un input operatore tramite scanForm).

JSON
{
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": "RULE_ACCEPTED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "LoyaltyProgramRule", "passed": true, "pointsDelta": 185 },
    { "rule": "TierEvaluationRule", "passed": true, "upgradedTo": "GOLD" }
  ],
  "passSnapshot": {
    "id": "pass_loy_449102",
    "templateId": "tmpl_loyalty_01",
    "serialNumber": "PI-LOY-449102",
    "externalId": "crm_cust_44910",
    "status": "ACTIVE",
    "tier": "GOLD",
    "barcodeValue": "PI-LOY-449102",
    "storedValue": "42.00"
  },
  "remainingBalance": "42.00",
  "effects": {
    "oldBalance": "42.00",
    "newBalance": "42.00",
    "pointsDelta": 185,
    "transactionAmount": 18.50,
    "currency": "EUR"
  },
  "display": {
    "title": "Scan Accepted — Gold Tier!",
    "subtitle": "+185 Points awarded",
    "color": "success"
  },
  "configurationVersion": 4,
  "configurationStale": false
}

Per l'audit delle scansioni completate e l'esportazione dei log CSV, consulti Storico ed esiti delle scansioni.

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.