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

Installazione e configurazione Scanner

Crea Luoghi di validazione e profili Scanner (App mobile o Web Scanner) e installa l'app Passinstance Scanner.

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 ingrandito1 / 2
Elementi chiave dell'interfaccia

Procedura guidata «Crea configurazione Scanner» (Zoom)

Imposta nome della configurazione, descrizione, tipo Mobile App e durata del messaggio di conferma per generare un profilo scanner sicuro.

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

Luoghi di validazione e controlli di configurazione Scanner
Luoghi di validazione e controlli di configurazione Scanner

Prerequisiti: È necessario disporre di un Modello di pass attivo pubblicato e dei permessi del workspace per gestire le configurazioni di validazione (validation:manage, oppure scans:read per 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)CanaleMeccanismo di autenticazioneDistribuzione tipica
SMART_SCAN_APPApp Passinstance Scanner (iOS / Android) e SDK POS integratix-scanner-key associata (from-link o for-config)Dispositivi portatili ai varchi di ingresso, sedi offline, casse retail.
VALIDATION_LINKPunto di controllo tramite browser web (/api/v1/public/validation/:configId/validate)Link di validazione web firmatoPostazioni pop-up per eventi o desk partner senza installazione di app.

Configurazione passo per passo

  1. 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. 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. 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.

  1. 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 a MAX_RETRY_ATTEMPTS = 3 con header x-idempotency-key generati dal client e memorizza nella cache gli snapshot dei pass tramite GET /api/v1/scans/offline-dataset.

Architettura e ciclo di vita dell'abbinamento dispositivi

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
ABBINAMENTO DISPOSITIVO SCANNER E SINCRONIZZAZIONE TELEMETRIA
ATTORI DI SISTEMA COINVOLTI
P1 Dispositivo / App Scanner
P2 Scanner Keys API
P3 Scan Validation API
FASE 1 RICHIESTA / AZIONE POST/scanner-keys/
›
from-link {token, pin?}
FASE 2 RISPOSTA 201 Created
›
{ scannerKey,
›
alidationConfig,
›
key: "sk_live_..." }
FASE 3 RICHIESTA / AZIONE GET/scanner-keys/verify
›
Header: x-scanner-key,
›
x-scanner-battery-level,
›
x-scanner-queue-backlog
FASE 4 RISPOSTA 200 OK { shouldRotate }
FASE 5 RICHIESTA / AZIONE GET/scans/offline-dataset ?cursor=...&limit=500
FASE 6 RISPOSTA 200 OK { items, nextCursor, snapshotAt }

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:

MetodoEndpointAutenticazione / GuardDescrizione
POST/api/v1/scanner-keys/from-linkPubblico (ScannerAccessLink, esente da CSRF)Scambia { token, pin? } con una x-scanner-key persistente (key, restituita una sola volta).
POST/api/v1/scanner-keys/for-configJWT Workspace (scans:read)Emette una nuova chiave scanner per un { configId } appartenente al tenant.
GET/api/v1/scanner-keys/configsx-scanner-keyElenca le configurazioni SMART_SCAN_APP attive associate al tenant della chiave chiamante.
POST/api/v1/scanner-keys/switchx-scanner-keySposta la chiave su un altro { configId, pin? } quando allowChangesViaLink: true.
POST/api/v1/scanner-keys/unlock-pinx-scanner-keyVerifica { pin } rispetto a unlockPinHash con blocco automatico contro attacchi brute-force.
GET/api/v1/scanner-keys/verifyx-scanner-keyConvalida lo stato della chiave, registra gli header telemetrici del dispositivo e restituisce l'avviso shouldRotate.
POST/api/v1/scanner-keys/revokex-scanner-keyRevoca immediatamente la chiave scanner chiamante, bloccando qualsiasi successivo invio di scansione.
POST/api/v1/scanner-keys/:id/rotateJWT 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:

JSON
{
  "token": "sal_9f82b1c4e7a043d19b2e",
  "pin": "4829"
}

Risposta (201 Created):

JSON
{
  "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 key viene restituito una sola volta al momento della creazione o della rotazione e archiviato nel database come hash SHA-256 (hashKey). Salvi key in modo sicuro nel keychain del dispositivo; in caso di smarrimento, invochi POST /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 telemetricoFormato / EsempioScopo
x-scanner-app-version2.4.1 (build 108)Traccia la versione build dell'app sui terminali portatili distribuiti.
x-scanner-device-idios-idfv-8841-992aIdentificativo hardware univoco per l'inventario del parco dispositivi.
x-scanner-battery-level0.78 (0–1 o 0–100)Segnala al personale operativo quando la carica degli scanner ai varchi scende sotto il 15%.
x-scanner-queue-backlog12Numero di scansioni offline accodate localmente in attesa di sincronizzazione.

Risposta (200 OK):

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

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

GET /api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "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.

Documentazione prodotto e API 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.