Panoramica
Passinstance automatizza l'intero ciclo di vita dei pass digitali tra progettazione, impacchettamento crittografico, distribuzione multicanale, validazione al punto vendita e sincronizzazione push silenziosa. Separando la configurazione del layout visivo dalle meccaniche di logica applicativa e dai protocolli di comunicazione dei dispositivi, la piattaforma garantisce un'esperienza uniforme sia su iOS sia su Android.
Sequenza tecnica end-to-end
Il seguente diagramma di sequenza descrive il flusso end-to-end dalla creazione del modello alla sincronizzazione in tempo reale con il Wallet:
Ciclo di vita tecnico passo per passo
1. Creazione e versioning del modello
Ogni pass nasce da un record Template. Passinstance adotta un versioning a tabella singola tracciato tramite TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) e template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED). Le modifiche in bozza restano isolate in una revisione DRAFT finché un operatore o un client API esegue POST /api/v1/templates/:id/publish, che promuove la bozza nella riga base canonica PRODUCTION e conserva snapshot storici immutabili PUBLISHED / ARCHIVED. Prima della pubblicazione, la piattaforma valuta GET /api/v1/templates/:id/publish-risk-check per verificare le modifiche ai campi critici e calcolare quanti pass attivi verranno aggiornati.
2. Firma crittografica, stato degli artefatti ed emissione del pass
Quando viene generato un record pass (POST /api/v1/passes), la creazione risolve templateId tramite resolvePassCreationTemplateId verso la riga base attiva, associa un externalId opzionale univoco per tenant, rispetta l'header opzionale Idempotency-Key (idempotencyKey) e inizializza appleArtifactStatus e googleArtifactStatus (ArtifactStatus: NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED):
-
Apple Wallet: Al momento del download,
Apple Wallet Packagerimpacchettapass.json, fino a 13 slot immagine (image asset slot incluse le varianti retina@2xe@3x) e filepass.stringslocalizzati in un archivio zip.pkpass, calcola gli hash dimanifest.jsone firma il manifest con crittografia PKCS#7 detached utilizzando i certificati Apple Pass Type ID e Apple WWDR. Più pass associati che condividono unbundleId(Pass.bundleId) possono essere distribuiti insieme come archivio.pkpasses. -
Google Wallet: Il backend sincronizza le definizioni di classe (
LoyaltyClass,EventTicketClass,GenericClass, ecc.) con le API REST di Google Wallet e firma un URL di salvataggio JWTRS256(https://pay.google.com/gp/v/save/:jwt).
3. Distribuzione con Smart Link
Passinstance genera URL di presentazione smart canonici (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId oppure /s/:token su host API o vanity domain). Quando l'utente finale apre il link:
-
L'endpoint pubblico di download (
GET /d/:slug/download) rileva lo User-Agent:
- Safari su iOS riceve una risposta HTTP con MIME type application/vnd.apple.pkpass, aprendo la schermata nativa di aggiunta ad Apple Wallet. - Chrome su Android viene reindirizzato a https://pay.google.com/gp/v/save/:jwt, avviando Google Wallet. - I browser desktop mostrano la pagina PassFlow di download con codice QR ad alto contrasto (GET /d/:slug/qr) e opzionale invio automatico via e-mail/SMS.
4. Registrazione dispositivo e handshake Web Service
Al momento del salvataggio in Apple Wallet, il dispositivo iOS avvia il protocollo ufficiale Apple Wallet Web Service:
-
Invia
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumbercon headerAuthorization: ApplePass <authenticationToken>. -
Passinstance convalida il token e registra il
pushTokendel dispositivo nel database, facendo transitare lo stato del pass daAWAITING_OPT_INaACTIVE.
5. Validazione al punto vendita ed esecuzione delle meccaniche
Alla cassa fisica o al varco d'ingresso, un operatore scansiona il pass utilizzando l'app Passinstance Scanner o un sistema POS integrato:
-
Viene inviata una richiesta a
POST /api/v1/scansautenticata tramitex-scanner-key. -
Pass Mechanics Enginevaluta le regole attive (ad esempio aggiunta di timbri, addebito di valore prepagato, convalida di coupon monouso o verifica di un accesso giornaliero).
6. Sincronizzazione push cloud silenziosa
Quando i dati di un pass cambiano:
-
Passinstance invia un payload JSON vuoto
{}su HTTP/2 ai server Apple APNs. -
Il dispositivo Apple si risveglia silenziosamente in background, interroga
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>e scarica il bundle.pkpassaggiornato. -
Ogni campo configurato con
changeMessagecontenente il segnaposto%@genera una notifica nativa sulla schermata di blocco di iOS. -
Contestualmente, Passinstance invia una richiesta REST
PATCHall'endpointwalletobjectsdi Google Wallet, aggiornando la tessera Android in tempo reale.

Endpoint API e verbi HTTP principali
| Percorso endpoint | Metodo HTTP | Autenticazione | Funzionalità |
|---|---|---|---|
/api/v1/templates | POST | Bearer / Chiave API | Crea una nuova definizione di modello pass |
/api/v1/templates/:id/publish | POST | Bearer / Chiave API | Promuove il modello in bozza alla versione di produzione |
/api/v1/passes | POST | Bearer / Chiave API | Emette un nuovo pass con valori di campi personalizzati |
/api/v1/passes/:id | PATCH | Bearer / Chiave API | Aggiorna gli attributi di un pass esistente e accoda il push |
/api/v1/scans | POST | x-scanner-key | Convalida il codice a barre del pass, applica la meccanica e registra la scansione |
/v1/devices/... | POST | ApplePass <token> | Callback di registrazione dispositivo di Apple Wallet |
Importante: Gli aggiornamenti di Apple Wallet sono basati su modello pull: Passinstance non invia i dati del pass dentro la notifica APNs. Un segnale vuoto di risveglio APNs indica invece al dispositivo Apple di scaricare in modo sicuro l'ultimo file
.pkpassfirmato dai server Passinstance.
Esplori la guida completa all'onboarding in 6 fasi oppure consulti la nostra Architettura API.
