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.

Importante: Le regole di validazione vengono eseguite atomicamente lato server. Quando una scansione modifica lo stato del pass (come
VOIDED_AFTER_SCANoStoredValueOperation.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 ScanMode | Comportamento e transizione di stato | Caso d'uso tipico |
|---|---|---|
SAVE_ATTENDANCE | Registra 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_SCAN | Porta 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_SCAN | Contrassegna 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_IN | Porta 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_OUT | Porta lo stato di presenza del pass da checked-in a checked-out. | Tracciamento uscite dalla sede, gestione capienza. |
CHECK_IN_CHECK_OUT_TOGGLE | Alterna 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 Enum | Valori consentiti | Scopo |
|---|---|---|
StoredValueOperation | NONE, ADD, SUBTRACT, SET | Definisce se una scansione lascia intatti i saldi, ricarica credito (ADD), addebita un importo (SUBTRACT) o sovrascrive il saldo (SET). |
StoredValueAmountSource | FIXED, OPERATOR, MECHANIC | Stabilisce se l'importo della transazione proviene da un valore preimpostato (FIXED), dall'input del cassiere (OPERATOR) o dalla meccanica del modello (MECHANIC). |
NfcReaderMode | AUTO, KEYBOARD_WEDGE, APPLE_WALLET, GOOGLE_SMART_TAP | Configura la negoziazione del protocollo contactless per terminali Apple VAS e Google Smart Tap. |
| scan action | INCREMENT, DECREMENT, VALIDATE, DEBIT, CREDIT, NOOP | Azione registrata su ciascuna transazione di utilizzo pass o mastro di scansione (request payload consente anche SET). |
| scan status | SUCCESS, FAILED, PENDING, INVALID, EXPIRED, ALREADY_USED, ALREADY_VOIDED, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS, ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT | Stato 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):
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
/api/v1/scans/prepare
{
"scannedBarcodeValue": "PI-TKT-992014",
"scannerConfigurationId": "scfg_main_entrance_01"
}
Risposta (201 Created)
{
"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
{
"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).
{
"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.
