Panoramica e architettura degli endpoint intelligenti
Ogni pass emesso e ogni link di distribuzione del modello in Passinstance viene risolto da uno Smart Download Engine sensibile alla piattaforma (modello DownloadPage e Download Page API). Anziché distribuire link separati per Apple e Android, è sufficiente condividere un unico URL canonico (passAccessUrl, /d/:slug oppure /s/:token) che ispeziona dinamicamente l'header HTTP User-Agent del client, il contesto del browser e lo stato di sicurezza prima di fornire il payload Wallet appropriato.

Rilevamento dinamico dello User-Agent e comportamento per piattaforma
-
1
iPhone e iPad (Safari su iOS): Trasmette direttamente il bundle
.pkpassfirmato crittograficamente con MIME typeContent-Type: application/vnd.apple.pkpass, aprendo immediatamente la schermata nativa iOS Aggiungi ad Apple Wallet. -
2
WebView integrate in-app su iOS (Instagram, TikTok, Facebook, LinkedIn): Poiché le WebView dei social bloccano gli stream binari
application/vnd.apple.pkpass, Passinstance rileva loUser-Agentin-app e mostra un overlay dedicato per guidare l'utente ad aprire il link nel browser nativo Safari. -
3
Dispositivi Android: Emette un redirect HTTP
302(oppure mostra il pulsante one-tap Aggiungi a Google Wallet) versohttps://pay.google.com/gp/v/save/<signed_jwt>, salvando l'oggetto cloudLoyaltyObject,EventTicketObjectoGenericObjectdirettamente in Google Wallet. -
4
Browser desktop: Visualizza una pagina PassFlow responsive con il brand aziendale e un codice QR dinamico ad alto contrasto (
GET /d/:slug/qr), insieme ai controlli self-service di inoltro via e-mail/SMS (POST /d/:slug/send-link-by-email,POST /d/:slug/send-link-by-sms) per trasferire in pochi secondi il pass sullo smartphone.
Importante: Quando l'Associazione a un solo dispositivo (
limitToOneActivePerPass: true) è attiva su un modello o su un pass (sharingProhibited), lo smart link di download si blocca automaticamente non appena un dispositivo completa la prima registrazione Apple Wallet Web Service (POST /v1/devices/:deviceLibraryIdentifier/registrations/...) oppure il callbacksavedi Google Wallet, impedendo la condivisione non autorizzata del link.
Endpoint API per smart link e pagine di download
Le rotte pubbliche di risoluzione dei download sono esposte al di fuori del prefisso /api/v1 su Public Download Page e Public Pass Recovery API (/d/:slug/* e alias /download/:slug/*, oltre alle rotte autenticate di gestione sotto /api/v1/download-pages/*):
| Metodo | Percorso endpoint | Ambito Auth | Descrizione tecnica |
|---|---|---|---|
| GET | /d/:slug | Pubblico | Router smart link d'ingresso; reindirizza i browser a /download/:slug o restituisce info JSON su richiesta; supporta ?pass=:passId, ?lang=, ?pin=. |
| GET | /d/:slug/info | Pubblico | Restituisce metadati JSON (request payload), token di branding, passaggi PassTour e disponibilità del pass. |
| GET | /d/:slug/qr | Pubblico | Genera un'immagine codice QR scansionabile che codifica lo smart URL di download. |
| GET | /d/:slug/download | Pubblico | Esegue il rilevamento dello User-Agent e consegna .pkpass (iOS) o redirect JWT Google Save (Android); rispetta ?pin= o X-Wallet-Experience-Pin. |
| POST | /d/:slug/create | Pubblico (Rate-Limited) | Emette un pass direttamente da una pagina di download (request payload: name, email?, phone?, additionalFields?). |
| POST | /d/:slug/send-link-by-email | Pubblico (Rate-Limited) | request payload ({ email, passLink? }) — invia via e-mail il link di download all'utente dalle viste desktop. |
| POST | /d/:slug/send-link-by-sms | Pubblico (Rate-Limited) | request payload ({ phoneNumber, passLink? }) — invia il link di download tramite SMS in formato E.164. |
| POST | /d/:slug/request-recovery | Pubblico (Rate-Limited) | { emailOrPhone } — invia un link di recupero rapido quando un cliente cambia telefono o smarrisce il proprio link. |
| GET | /s/:token | Pubblico | Smart link canonico associato al serialNumber / token di un singolo pass. |
Sicurezza dei token, protezione PIN e consegna secondaria
È possibile configurare protezioni granulari sugli accessi a livello di modello oppure su singola emissione pass:
-
Scadenza download (
enableDownloadUntil): Imposta un timestamp"YYYY-MM-DD HH:mm"o ISO oltre il quale i link non ancora riscattati smettono di emettere nuovi pass, mantenendo attivi quelli già installati nei Wallet dei clienti. -
Blocco su singolo dispositivo attivo (
limitToOneActivePerPass): Blocca ulteriori download quando il pass ha già una registrazione dispositivo attiva. -
Blocco con PIN (
pinquery param / headerX-Wallet-Experience-Pin): Richiede ai titolari di sbloccare con PIN i link protetti e i bundle.pkpassesprima dell'installazione nel Wallet (verificato tramitePOST /api/v1/pass-projects/:id/validate-pinsu Wallet Experiences). -
Sospensione di tutti i download (
passDownloadDeactivated): Interruttore di emergenza nelle Impostazioni del modello che blocca immediatamente nuovi download su tutti i canali senza revocare i pass già installati sui dispositivi dei clienti. -
Priorità di risoluzione pass (
?pass=:passId): La risoluzione pubblica valuta nell'ordine la disponibilità specifica del pass (P1), le impostazioni predefinite della pagina di download (P2) e il fallback del workspace (P3), mentrepass bundle(bundleId) coordina i download.pkpassestra tessere collegate. -
Overlay opzionali PassTour: Guidano gli utenti alle prime armi con Apple Wallet e Google Wallet mediante istruzioni visive interattive (Guida PassTour).
Esempio: payload per consegna secondaria e recupero
Quando un cliente visualizza un pass su computer desktop oppure perde l'accesso al proprio pass Wallet, la pagina PassFlow invoca gli endpoint pubblici di azione:
POST /d/vip-gold-2026/send-link-by-email
{
"email": "alex.rivera@example.com",
"passLink": "https://app.passinstance.com/d/vip-gold-2026?pass=pass_01j8k9m2"
}
POST /d/vip-gold-2026/request-recovery
{
"emailOrPhone": "alex.rivera@example.com"
}
Approfondisca la documentazione correlata su Distribuzione self-service, Consegna via e-mail e SMS e Trovare o recuperare il pass.
