Skip to content
Riferimento API REST e SDK

Documentazione per sviluppatori Passinstance

Crea integrazioni su larga scala per Apple Wallet (.pkpass) e Google Wallet. Emetti, aggiorna, scansiona e invia notifiche in tempo reale tramite API REST pronte per la produzione.

Ottieni chiavi API
Workbench live — gli snippet si aggiornano mentre digiti
Sicurezza

Panoramica — Come funziona la validazione dei pass

Ogni scansione di codice a barre o NFC esegue una pipeline deterministica di 14 regole (stato, scadenza, fasce orarie, geofencing, meccaniche, rate limit, anti-replay) con nonce crittografici opzionali e sincronizzazione dataset offline.

Nonce anti-replay

POST /api/v1/scans/prepare rilascia un nonce crittografico anti-replay temporaneo legato al codice a barre

Pipeline a 14 regole

PassStatus → Expiration → TimeWindow → Geofencing → Mechanics → RateLimit → AntiReplay

Sincronizzazione offline

GET /api/v1/scans/offline-dataset fornisce snapshot paginati tramite cursore per terminali offline

Abbinamento chiave scanner

POST /api/v1/scanner-keys/from-link scambia un token di abbinamento + PIN con una x-scanner-key

Configurazione scanner

3 endpoint
GEThttps://api.passinstance.com/api/v1/validation/configsChiave API
Configurazione scanner

Elenca configurazioni scanner

Elenca tutti i profili di configurazione scanner (app mobile, web scanner, POS) e i relativi permessi sui modelli.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di query2 opzionali

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/validation/configs/{id}Chiave API
Configurazione scanner

Ottieni configurazione scanner

Ottieni i dettagli di una specifica configurazione scanner, inclusi modelli consentiti, messaggio post-scansione e regole.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di percorso1 obbligatori
idstring (UUID)
Obbligatorio

UUID della configurazione scanner.

Esempio: 7a8b9c0d-1e2f-4a3b-8c9d-0e1f2a3b4c5d

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/validation/configsChiave API
Configurazione scanner

Crea configurazione scanner

Crea un nuovo profilo di configurazione scanner con modelli associati, azione di scansione predefinita e messaggio di conferma.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1

Scanner configuration profile name, allowed template UUIDs, scan mode, and optional cooldown window.

Corpo della richiesta2 obbligatori • 2 opzionali
namestring
Obbligatorio

Nome descrittivo per la configurazione dello scanner.

Esempio: Main Entrance Gate Scanners
templateIdsstring[] (UUID)
Obbligatorio

UUID dei modelli autorizzati alla validazione con questo profilo.

Esempio: ["8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"]

Codici di stato della risposta

Operazioni di scansione

4 endpoint
GEThttps://api.passinstance.com/api/v1/validation/scansChiave API
Operazioni di scansione

Elenca registri di scansione

Consulta il registro di audit paginato delle scansioni pass filtrando per modello, pass, configurazione scanner, esito e periodo.

Intestazioni1 obbligatori
X-API-Keystring
Obbligatorio

Chiave API segreta del workspace (pi_live_... o pi_test_...). In alternativa è possibile inviare Authorization: ApiKey <key>.

Esempio: pi_live_98a7b6c5d4e3f2a1
Parametri di query3 opzionali

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/scansChiave scanner
Operazioni di scansione

Elabora scansione codice a barre / NFC

Convalida un codice a barre ottico, QR o una scansione NFC Apple VAS / Google Smart Tap da un terminale o scanner mobile tramite il motore a 14 regole.

Intestazioni2 obbligatori • 2 opzionali
x-scanner-keystring
Obbligatorio

Chiave di configurazione scanner generata nella Dashboard o tramite link di associazione scanner.

Esempio: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Content-Typestring
Obbligatorio

Deve essere application/json.

Esempio: application/json

Payload Payload della richiesta con stringa codice a barre letta, nonce anti-replay opzionale, metadati canale/protocollo e contesto operatore.

Corpo della richiesta1 obbligatori • 8 opzionali
scannedBarcodeValuestring
Obbligatorio

La stringa grezza letta da QR code, PDF417, CODE128, AZTEC o tap NFC.

Esempio: PI-8891-JD-VIP

Codici di stato della risposta

POSThttps://api.passinstance.com/api/v1/scans/prepareChiave scanner
Operazioni di scansione

Prepara nonce di scansione anti-replay

Emetti un nonce crittografico anti-replay temporaneo legato al codice a barre di un pass prima di eseguire POST /api/v1/scans.

Intestazioni1 obbligatori
x-scanner-keystring
Obbligatorio

Chiave di configurazione scanner generata nella Dashboard o tramite link di associazione scanner.

Esempio: scan_key_77a8b9c0d1e2f3a4b5c6d7e8

Payload della richiesta contenente il valore del codice a barre scansionato a cui associare il nonce crittografico.

Corpo della richiesta1 obbligatori
scannedBarcodeValuestring
Obbligatorio

Stringa di codice a barre o token NFC a cui associare il nonce anti-replay.

Esempio: PI-8891-JD-VIP

Codici di stato della risposta

GEThttps://api.passinstance.com/api/v1/scans/offline-datasetChiave scanner
Operazioni di scansione

Scarica dataset offline dello scanner

Scarica un dataset di snapshot pass paginato con cursore limitato alla x-scanner-key chiamante per convalida locale offline in caso di assenza di rete.

Intestazioni1 obbligatori
x-scanner-keystring
Obbligatorio

Chiave di configurazione scanner generata nella Dashboard o tramite link di associazione scanner.

Esempio: scan_key_77a8b9c0d1e2f3a4b5c6d7e8
Parametri di query3 opzionali

Codici di stato della risposta