Overzicht & slimme endpointarchitectuur
Elke uitgegeven pas en distributielink van een sjabloon in Passinstance loopt via een platformherkennende Smart Download Engine (DownloadPage-model en Download Page API). In plaats van afzonderlijke Apple- en Android-links te verspreiden, deelt u één canonieke URL (passAccessUrl, /d/:slug of /s/:token) die dynamisch de HTTP User-Agent, browsercontext en beveiligingsstatus van de client inspecteert voordat de juiste wallet-payload wordt geleverd.

Dynamische User-Agent-detectie & platformgedrag
-
1
iPhone & iPad (iOS Safari): Streamt de cryptografisch ondertekende
.pkpass-bundel rechtstreeks met MIME-typeContent-Type: application/vnd.apple.pkpass, waardoor direct het native iOS-venster Toevoegen aan Apple Wallet ("Add to Apple Wallet") opent. -
2
Ingesloten iOS in-app webviews (Instagram, TikTok, Facebook, LinkedIn): Omdat ingebouwde sociale webviews binaire
application/vnd.apple.pkpass-streams blokkeren, detecteert Passinstance de in-appUser-Agenten toont een speciale Safari-overdrachtsoverlay die de pashouder vraagt de link in native Safari te openen. -
3
Android-apparaten: Stuurt een HTTP
302-omleiding (of toont een knop Toevoegen aan Google Wallet) die verwijst naarhttps://pay.google.com/gp/v/save/<signed_jwt>, waarmee het cloudobjectLoyaltyObject,EventTicketObjectofGenericObjectdirect in Google Wallet wordt geplaatst. -
4
Desktopbrowsers: Rendert een responsieve PassFlow-pagina in huisstijl met een contrastrijke dynamische QR-code (
GET /d/:slug/qr) naast selfservice-opties voor doorsturen per e-mail of sms (POST /d/:slug/send-link-by-email,POST /d/:slug/send-link-by-sms), zodat desktopgebruikers de pas binnen enkele seconden naar hun smartphone kunnen overzetten.
Belangrijk: Wanneer Koppeling aan één apparaat (
limitToOneActivePerPass: true) is ingeschakeld op een sjabloon of pas (sharingProhibited), vergrendelt de slimme downloadlink zich automatisch zodra een apparaat zijn eerste Apple Wallet Web Service-registratie (POST /v1/devices/:deviceLibraryIdentifier/registrations/...) of Google Walletsave-callback afrondt, waarmee ongeautoriseerd delen van links wordt geblokkeerd.
API-endpoints voor slimme links & downloadpagina's
Openbare routes voor het afhandelen van downloads zijn buiten het voorvoegsel /api/v1 gemount op Public Download Page en Public Pass Recovery API (/d/:slug/* en alias /download/:slug/*, plus geauthenticeerde beheerroutes onder /api/v1/download-pages/*):
| Methode | Endpointpad | Auth-bereik | Technische beschrijving |
|---|---|---|---|
| GET | /d/:slug | Openbaar | Toegangsrouter voor slimme links; leidt browsers om naar /download/:slug of levert desgevraagd JSON-info; ondersteunt ?pass=:passId, ?lang=, ?pin=. |
| GET | /d/:slug/info | Openbaar | Retourneert JSON-metadata (request payload), merkinstellingen, PassTour-stappen en pasbeschikbaarheid. |
| GET | /d/:slug/qr | Openbaar | Genereert een scanbare QR-codeafbeelding die de slimme download-URL codeert. |
| GET | /d/:slug/download | Openbaar | Voert User-Agent-detectie uit en levert .pkpass (iOS) of Google Save JWT-omleiding (Android); respecteert ?pin= of X-Wallet-Experience-Pin. |
| POST | /d/:slug/create | Openbaar (Rate-limited) | Geeft direct een pas uit vanaf een downloadpagina (request payload: name, email?, phone?, additionalFields?). |
| POST | /d/:slug/send-link-by-email | Openbaar (Rate-limited) | request payload ({ email, passLink? }) — mailt de downloadlink naar de gebruiker vanuit desktopweergaven. |
| POST | /d/:slug/send-link-by-sms | Openbaar (Rate-limited) | request payload ({ phoneNumber, passLink? }) — verstuurt de downloadlink via E.164-sms. |
| POST | /d/:slug/request-recovery | Openbaar (Rate-limited) | { emailOrPhone } — stuurt een herstellink wanneer een klant van telefoon wisselt of de link kwijt is. |
| GET | /s/:token | Openbaar | Canonieke slimme link gekoppeld aan een individueel serialNumber / token van een pas. |
Tokenbeveiliging, PIN-bescherming & secundaire bezorging
U kunt fijnmazige toegangsbeveiliging instellen op sjabloonniveau of per individuele pasuitgifte:
-
Vervaldatum van download (
enableDownloadUntil): Stel een tijdstip ("YYYY-MM-DD HH:mm"of ISO-tijdstempel) in waarna niet-geclaimde downloadlinks geen nieuwe passen meer uitgeven, terwijl reeds geïnstalleerde passen in klantwallets actief blijven. -
Vergrendeling op één actief apparaat (
limitToOneActivePerPass): Blokkeert hernieuwde downloads zodra de pas een actieve apparaatregistratie heeft. -
PIN-vergrendeling (
pin-queryparameter /X-Wallet-Experience-Pin-header): Vereis dat pashouders met een PIN beveiligde downloadlinks en.pkpasses-bundels ontgrendelen vóór wallet-installatie (gecontroleerd viaPOST /api/v1/pass-projects/:id/validate-pinbij Wallet Experiences). -
Alle downloads pauzeren (
passDownloadDeactivated): Noodschakelaar in Sjablooninstellingen die nieuwe downloads over alle kanalen direct pauzeert zonder passen die al op klantapparaten zijn geïnstalleerd in te trekken. -
Prioriteit bij pasresolutie (
?pass=:passId): Openbare resolutie evalueert passpecifieke beschikbaarheid (P1), downloadpagina-standaarden (P2) en workspace-terugval (P3), terwijlpass bundle(bundleId).pkpasses-downloads over gekoppelde kaarten coördineert. -
Optionele PassTour-overlays: Begeleid nieuwe gebruikers van Apple Wallet en Google Wallet met interactieve visuele instructies (PassTour-gids).
Voorbeeld: payloads voor secundaire bezorging & herstel
Wanneer een klant een pas op een desktopcomputer bekijkt of toegang tot zijn wallet-pas verliest, roept de PassFlow-pagina de openbare actie-endpoints aan:
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"
}
Bekijk verwante documentatie over Selfservice-distributie, E-mail- & sms-bezorging en Uw pas vinden of herstellen.
