Skip to content
Guida del Centro assistenza · Introduzione a PassinstanceFase di onboarding 1
5 min di letturaVerificato 2026-11-16

Come funziona Passinstance

Segui l'architettura completa dalla creazione del modello e firma crittografica fino a scansione, push e analisi.

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 ingrandito
Elementi chiave dell'interfaccia

Dashboard Workspace — KPI e Trend live (Ingrandito)

A sistema avviato, monitora Active in Wallets, Removed, Not Installed insieme alle curve di creazione e registrazione.

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:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CICLO DI VITA END-TO-END DEL PASS
ATTORI DI SISTEMA COINVOLTI
P1 Admin / Client API
P2 Passinstance Core API
P3 Cloud Apple / Google
P4 Dispositivo cliente
FASE 1 RICHIESTA / AZIONE POST/api/v1/templates
›
(Layout e meccaniche)
FASE 2 RICHIESTA / AZIONE POST/api/v1/passes
FASE 3 RICHIESTA / AZIONE Firma .pkpass (PKCS#7)
FASE 4 RICHIESTA / AZIONE Genera Google JWT
›
Restituisce URL download
›
(https://app.passinstance.com/d/:slug oppure /p/:passId)
FASE 5 RICHIESTA / AZIONE Il cliente apre lo Smart Download Link
›
(Il browser rileva OS)
FASE 6 RISPOSTA Registrazione dispositivo (POST/v1/devices)
›
(pushToken Apple salvato in Passinstance database)
FASE 7 RICHIESTA / AZIONE Scansione in cassa al POS (POST/api/v1/scans)
›
(Header: x-scanner-key, Body: { scannedBarcodeValue })
FASE 8 RICHIESTA / AZIONE Esecuzione meccanica
›
(Incrementa timbri/punti)
FASE 9 RICHIESTA / AZIONE Push silenziosa APNs
›
(Payload vuoto APNs)
FASE 10 RICHIESTA / AZIONE Risveglio APNs
FASE 11 RISPOSTA Recupera pass aggiornato (GET/v1/passes)
FASE 12 RICHIESTA / AZIONE Consegna .pkpass aggiornato
›
(Avviso nativo lock-screen
›
"Balance updated to %@")

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 Packager impacchetta pass.json, fino a 13 slot immagine (image asset slot incluse le varianti retina @2x e @3x) e file pass.strings localizzati in un archivio zip .pkpass, calcola gli hash di manifest.json e firma il manifest con crittografia PKCS#7 detached utilizzando i certificati Apple Pass Type ID e Apple WWDR. Più pass associati che condividono un bundleId (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 JWT RS256 (https://pay.google.com/gp/v/save/:jwt).

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/:serialNumber con header Authorization: ApplePass <authenticationToken>.
  • Passinstance convalida il token e registra il pushToken del dispositivo nel database, facendo transitare lo stato del pass da AWAITING_OPT_IN a ACTIVE.

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/scans autenticata tramite x-scanner-key.
  • Pass Mechanics Engine valuta 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 .pkpass aggiornato.
  • Ogni campo configurato con changeMessage contenente il segnaposto %@ genera una notifica nativa sulla schermata di blocco di iOS.
  • Contestualmente, Passinstance invia una richiesta REST PATCH all'endpoint walletobjects di Google Wallet, aggiornando la tessera Android in tempo reale.
Panoramica dashboard con trend e KPI
Panoramica dashboard con trend e KPI

Endpoint API e verbi HTTP principali

Percorso endpointMetodo HTTPAutenticazioneFunzionalità
/api/v1/templatesPOSTBearer / Chiave APICrea una nuova definizione di modello pass
/api/v1/templates/:id/publishPOSTBearer / Chiave APIPromuove il modello in bozza alla versione di produzione
/api/v1/passesPOSTBearer / Chiave APIEmette un nuovo pass con valori di campi personalizzati
/api/v1/passes/:idPATCHBearer / Chiave APIAggiorna gli attributi di un pass esistente e accoda il push
/api/v1/scansPOSTx-scanner-keyConvalida il codice a barre del pass, applica la meccanica e registra la scansione
/v1/devices/...POSTApplePass <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 .pkpass firmato dai server Passinstance.

Esplori la guida completa all'onboarding in 6 fasi oppure consulti la nostra Architettura API.

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.