Panoramica
Prima che cassieri, addetti ai varchi o terminali POS possano convalidare i pass Wallet dei clienti, è necessario configurare un Luogo di validazione e associare una Configurazione Scanner (modello ScannerConfiguration) all'interno del workspace (/scanner e /scanner/configs nella Dashboard). Passinstance gestisce l'abbinamento dei dispositivi, l'obbligo di PIN operatore, la rotazione delle chiavi, il reporting telemetrico e la sincronizzazione degli snapshot offline tramite Scanner Keys API (/api/v1/scanner-keys), Validation Config API (/api/v1/validation) e Scan Validation API (/api/v1/scans).

Prerequisiti: È necessario disporre di un Modello di pass attivo pubblicato e dei permessi del workspace per gestire le configurazioni di validazione (
validation:manage, oppurescans:readper l'emissione delle chiavi) prima di generare link di abbinamento o chiavi scanner grezze.
Tipi di Configurazione Scanner ed enum principali
Passinstance separa la scansione su dispositivi portatili nativi dai link pubblici basati su browser mediante ScannerConfigurationType:
Enum (ScannerConfigurationType) | Canale | Meccanismo di autenticazione | Distribuzione tipica |
|---|---|---|---|
SMART_SCAN_APP | App Passinstance Scanner (iOS / Android) e SDK POS integrati | x-scanner-key associata (from-link o for-config) | Dispositivi portatili ai varchi di ingresso, sedi offline, casse retail. |
VALIDATION_LINK | Punto di controllo tramite browser web (/api/v1/public/validation/:configId/validate) | Link di validazione web firmato | Postazioni pop-up per eventi o desk partner senza installazione di app. |
Configurazione passo per passo
-
1
Definizione dei Luoghi di validazione: Crei punti di controllo fisici o logici (es. Ingresso Principale, Cassa 1, Lounge VIP) per segmentare le analisi di scansione e limitare quali pass possano essere riscattati in ciascuna sede (
validValidationPlaces). -
2
Creazione di una Configurazione Scanner: In Scanner -> Configurazioni Scanner (
/scanner/configs), definisca nome del profilo,type(ScannerConfigurationType), modelli consentiti (templateId/allowedTemplates),ScanMode,StoredValueOperation(NONE | ADD | SUBTRACT | SET),StoredValueAmountSource(FIXED | OPERATOR | MECHANIC), PIN operatore (unlockPinHash) e la possibilità per lo staff di cambiare profilo al volo (allowChangesViaLink: true). -
3
Abbinamento del dispositivo o provisioning della chiave:
- App mobile (SMART_SCAN_APP): Scansioni un codice QR di abbinamento (ScannerAccessLink) oppure inserisca un token di accesso per scambiarlo tramite POST /api/v1/scanner-keys/from-link. - App autenticata / Terminale POS: Dopo l'accesso utente e la selezione del profilo, emetta direttamente una chiave dedicata tramite POST /api/v1/scanner-keys/for-config.
-
4
Verifica heartbeat e sincronizzazione offline: L'app scanner verifica lo stato di salute della chiave tramite
GET /api/v1/scanner-keys/verify, accoda eventuali invii offline non riusciti fino aMAX_RETRY_ATTEMPTS = 3con headerx-idempotency-keygenerati dal client e memorizza nella cache gli snapshot dei pass tramiteGET /api/v1/scans/offline-dataset.
Architettura e ciclo di vita dell'abbinamento dispositivi
Endpoint del ciclo di vita delle chiavi scanner (Scanner Keys API)
Tutte le operazioni di provisioning delle chiavi dispositivo, cambio profilo, verifica PIN e rotazione sono esposte sotto /api/v1/scanner-keys:
| Metodo | Endpoint | Autenticazione / Guard | Descrizione |
|---|---|---|---|
| POST | /api/v1/scanner-keys/from-link | Pubblico (ScannerAccessLink, esente da CSRF) | Scambia { token, pin? } con una x-scanner-key persistente (key, restituita una sola volta). |
| POST | /api/v1/scanner-keys/for-config | JWT Workspace (scans:read) | Emette una nuova chiave scanner per un { configId } appartenente al tenant. |
| GET | /api/v1/scanner-keys/configs | x-scanner-key | Elenca le configurazioni SMART_SCAN_APP attive associate al tenant della chiave chiamante. |
| POST | /api/v1/scanner-keys/switch | x-scanner-key | Sposta la chiave su un altro { configId, pin? } quando allowChangesViaLink: true. |
| POST | /api/v1/scanner-keys/unlock-pin | x-scanner-key | Verifica { pin } rispetto a unlockPinHash con blocco automatico contro attacchi brute-force. |
| GET | /api/v1/scanner-keys/verify | x-scanner-key | Convalida lo stato della chiave, registra gli header telemetrici del dispositivo e restituisce l'avviso shouldRotate. |
| POST | /api/v1/scanner-keys/revoke | x-scanner-key | Revoca immediatamente la chiave scanner chiamante, bloccando qualsiasi successivo invio di scansione. |
| POST | /api/v1/scanner-keys/:id/rotate | JWT Workspace (scans:read) | Ruota atomicamente una chiave scanner esistente per ID e restituisce una nuova chiave segreta grezza una sola volta. |
1. Abbinamento tramite link di accesso (POST /api/v1/scanner-keys/from-link)
Quando lo staff scansiona un codice QR di configurazione nell'app Passinstance Scanner, il dispositivo scambia il token di configurazione (e l'eventuale PIN operatore se unlockPinHash è impostato) con una x-scanner-key persistente:
{
"token": "sal_9f82b1c4e7a043d19b2e",
"pin": "4829"
}
Risposta (201 Created):
{
"scannerKey": {
"id": "skey_01hxyz8912ab",
"createdAt": "2026-11-16T09:00:00.000Z",
"expiresAt": "2027-02-15T00:00:00.000Z"
},
"validationConfig": {
"id": "scfg_main_entrance_01",
"configurationId": "MAIN_ENTRANCE",
"name": "Main Entrance Gate",
"scanMode": "CHECK_IN",
"type": "SMART_SCAN_APP",
"place": "Main Entrance",
"isActive": true,
"allowChangesViaLink": true,
"templateId": "tmpl_event_vip",
"allowedTemplateIds": ["tmpl_event_vip"],
"version": 3
},
"key": "sk_live_7d9a2f4b8c1e6039a5d2e8f1"
}
Importante: Il valore
keyviene restituito una sola volta al momento della creazione o della rotazione e archiviato nel database come hash SHA-256 (hashKey). Salvikeyin modo sicuro nel keychain del dispositivo; in caso di smarrimento, invochiPOST /api/v1/scanner-keys/:id/rotate.
2. Heartbeat, telemetria e avviso di rotazione (GET /api/v1/scanner-keys/verify)
I client scanner richiamano periodicamente GET /api/v1/scanner-keys/verify con x-scanner-key e gli header di telemetria operativa per consentire agli amministratori di monitorare lo stato del parco dispositivi in tempo reale:
| Header telemetrico | Formato / Esempio | Scopo |
|---|---|---|
x-scanner-app-version | 2.4.1 (build 108) | Traccia la versione build dell'app sui terminali portatili distribuiti. |
x-scanner-device-id | ios-idfv-8841-992a | Identificativo hardware univoco per l'inventario del parco dispositivi. |
x-scanner-battery-level | 0.78 (0–1 o 0–100) | Segnala al personale operativo quando la carica degli scanner ai varchi scende sotto il 15%. |
x-scanner-queue-backlog | 12 | Numero di scansioni offline accodate localmente in attesa di sincronizzazione. |
Risposta (200 OK):
{
"valid": true,
"scannerKeyId": "skey_01hxyz8912ab",
"scannerConfigurationId": "scfg_main_entrance_01",
"validationConfigId": "scfg_main_entrance_01",
"expiresAt": "2026-11-25T12:00:00.000Z",
"daysUntilExpiration": 9,
"shouldRotate": true,
"message": "Scanner key is approaching expiration. Please rotate soon."
}
Quando daysUntilExpiration < 15, shouldRotate assume il valore true, invitando il dispositivo o l'amministratore a ruotare la credenziale tramite POST /api/v1/scanner-keys/:id/rotate.
3. Cambio profilo al volo (POST /api/v1/scanner-keys/switch)
Se una configurazione ha allowChangesViaLink: true, lo staff può spostare un singolo terminale portatile tra diversi profili SMART_SCAN_APP (ad esempio passando da Door Check-In a VIP Merchandise Redemption) senza ripetere l'abbinamento:
{
"configId": "scfg_vip_merch_02",
"pin": "9012"
}
Se la configurazione di destinazione richiede un PIN operatore, il server convalida pin rispetto a unlockPinHash prima di riassegnare la chiave. Gli operatori possono inoltre convalidare il proprio PIN autonomamente tramite POST /api/v1/scanner-keys/unlock-pin.
Sincronizzazione del dataset offline (GET /api/v1/scans/offline-dataset)
Per le sedi con connettività cellulare o Wi-Fi intermittente, gli scanner mobili sincronizzano uno snapshot compatto dei pass delimitato alla chiave (offline scan dataset) tramite GET /api/v1/scans/offline-dataset.
Parametri di query
-
cursor(stringa opzionale): Cursore di paginazione restituito dalla pagina precedente (nextCursor). -
limit(numero opzionale): Numero massimo di record per pagina. -
snapshotAt(timestamp ISO 8601 opzionale): Timestamp di sincronizzazione delta incrementale per recuperare solo i pass creati, aggiornati o annullati dopo l'ultimo snapshot.
Richiesta di esempio ed elemento pass dello snapshot (IOfflineDatasetPassResponse)
/api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
{
"config": {
"id": "scfg_main_entrance_01",
"customerTimezone": "Europe/Berlin",
"scanMode": "CHECK_IN",
"validValidationPlaces": ["Main Entrance"]
},
"snapshotAt": "2026-11-16T09:00:00.000Z",
"nextCursor": "pass_01hxyz9940",
"hasMore": true,
"items": [
{
"id": "pass_01hxyz9939",
"templateId": "tmpl_event_vip",
"serialNumber": "PI-VIP-00419",
"externalId": "crm_attendee_9012",
"barcodeValue": "PI-VIP-00419",
"status": "ACTIVE",
"voided": false,
"expirationDate": "2026-12-31T23:59:59.000Z",
"storedValue": "50.00",
"mechanicType": "NONE",
"lastSuccessfulScanAt": "2026-11-15T19:04:00.000Z",
"validationPlaces": ["Main Entrance"]
}
]
}
Esplori la compatibilità hardware e i flussi di validazione nella Pagina prodotto Scanner e in Modalità di scansione e regole di validazione.
