Überblick
Passinstance automatisiert den gesamten Lebenszyklus digitaler Pässe — vom Design über die kryptografische Paketierung, die Multi-Channel-Verteilung und die Validierung am Point of Sale bis hin zur stillen Push-Synchronisierung. Durch die Trennung von visuellem Layout, Geschäftslogik-Mechaniken und Gerätekommunikationsprotokollen liefert die Plattform ein einheitliches Erlebnis über die Ökosysteme von iOS und Android hinweg.
Durchgängiger technischer Ablauf
Das folgende Sequenzdiagramm beschreibt den End-to-End-Ablauf von der Vorlagenerstellung bis zur Wallet-Synchronisierung in Echtzeit:
Technischer Lebenszyklus Schritt für Schritt
1. Vorlagenerstellung & Versionierung
Jeder Pass entsteht auf Basis eines Template-Datensatzes. Passinstance verwendet eine Single-Table-Versionierung, die über TemplateRowKind (PRODUCTION, PUBLISHED, ARCHIVED, DRAFT) und template status (DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED) gesteuert wird. Änderungen im Entwurf bleiben in einer DRAFT-Revision isoliert, bis im Dashboard oder über die API POST /api/v1/templates/:id/publish aufgerufen wird. Dadurch wird der Entwurf zur kanonischen PRODUCTION-Basiszeile hochgestuft, während unveränderliche PUBLISHED- und ARCHIVED-Historien-Snapshots erhalten bleiben. Vor der Veröffentlichung prüft die Plattform über GET /api/v1/templates/:id/publish-risk-check kritische Feldänderungen und ermittelt, wie viele aktive Pässe aktualisiert werden.
2. Kryptografische Signierung, Artefaktstatus & Pass-Ausgabe
Beim Erzeugen eines Pass-Datensatzes (POST /api/v1/passes) löst die Pass-Erstellung templateId über resolvePassCreationTemplateId auf die produktive Basiszeile auf, verknüpft eine optionale mandantenweit eindeutige externalId, berücksichtigt den optionalen HTTP-Header Idempotency-Key (idempotencyKey) und initialisiert appleArtifactStatus sowie googleArtifactStatus (ArtifactStatus: NOT_GENERATED -> GENERATING -> READY \| FAILED \| INVALIDATED):
-
Apple Wallet: Beim Download bündelt
Apple Wallet Packagerdiepass.json, bis zu 13 Bild-Slots (image asset slot inklusive@2x- und@3x-Retina-Varianten) sowie lokalisiertepass.stringsin ein.pkpass-ZIP-Archiv, berechnet die Hashwerte inmanifest.jsonund signiert das Manifest mit einer abgetrennten PKCS#7-Signatur mithilfe Ihres Apple Pass Type ID- und des Apple WWDR-Zertifikats. Mehrere zusammengehörige Pässe mit derselbenbundleId(Pass.bundleId) können gemeinsam als.pkpasses-Archiv ausgeliefert werden. -
Google Wallet: Das Backend synchronisiert Klassendefinitionen (
LoyaltyClass,EventTicketClass,GenericClassusw.) mit den Google-Wallet-REST-APIs und signiert eineRS256-JWT-Save-URL (https://pay.google.com/gp/v/save/:jwt).
3. Smart-Link-Verteilung
Passinstance vergibt kanonische Smart-Präsentations-URLs (https://app.passinstance.com/d/:slug, https://app.passinstance.com/p/:passId oder /s/:token auf API-/Vanity-Hosts). Beim Aufruf durch Endkundinnen und Endkunden gilt:
-
Öffentlicher Download-Endpunkt (
GET /d/:slug/download) erkennt den User-Agent automatisch:
- iOS Safari erhält eine HTTP-Antwort mit dem MIME-Typ application/vnd.apple.pkpass, wodurch direkt der native Apple-Wallet-Hinzufügedialog geöffnet wird. - Android Chrome wird auf https://pay.google.com/gp/v/save/:jwt weitergeleitet und startet Google Wallet. - Desktop-Browser rendern die PassFlow-Downloadseite mit einem kontrastreichen QR-Code (GET /d/:slug/qr) sowie optionalem E-Mail-/SMS-Selbstversand.
4. Geräteregistrierung & Web-Service-Handshake
Sobald der Pass in Apple Wallet gespeichert wird, initiiert das iOS-Gerät das offizielle Apple-Wallet-Web-Service-Protokoll:
-
Es sendet
POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumbermit dem HeaderAuthorization: ApplePass <authenticationToken>. -
Passinstance validiert das Token, speichert das
pushTokendes Geräts in der Datenbank und überführt den Pass-Status vonAWAITING_OPT_INnachACTIVE.
5. POS-Validierung & Ausführung von Mechaniken
An der Kasse oder beim Einlass scannt das Personal den Pass mit der App Passinstance Scanner oder einem integrierten Kassensystem:
-
Eine Anfrage wird an
POST /api/v1/scansgesendet, authentifiziert überx-scanner-key. -
Der
Pass Mechanics Enginewertet die aktiven Regeln aus (z. B. Stempel gutschreiben, Prepaid-Guthaben abbuchen, Einmal-Coupons entwerten oder tägliche Anwesenheitsbeschränkungen prüfen).
6. Stille Cloud-Push-Synchronisierung
Wenn sich Pass-Daten ändern:
-
Passinstance sendet ein leeres JSON-Payload
{}über HTTP/2 an die Apple-APNs-Server. -
Das Apple-Gerät wacht still im Hintergrund auf, fragt
GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>ab und lädt das aktualisierte.pkpass-Paket herunter. -
Jedes Feld, das mit einer
changeMessageinklusive Platzhalter%@konfiguriert ist, löst eine native iOS-Sperrbildschirm-Benachrichtigung aus. -
Parallel dazu sendet Passinstance eine REST-
PATCH-Anfrage an den Google-Wallet-Endpunktwalletobjects, um die Android-Karte in Echtzeit zu aktualisieren.

Zentrale API-Endpunkte & HTTP-Methoden
| Endpunkt-Pfad | HTTP-Methode | Authentifizierung | Funktion |
|---|---|---|---|
/api/v1/templates | POST | Bearer / API Key | Neue Pass-Vorlagendefinition erstellen |
/api/v1/templates/:id/publish | POST | Bearer / API Key | Entwurfsvorlage als produktive Version veröffentlichen |
/api/v1/passes | POST | Bearer / API Key | Neuen Pass mit benutzerdefinierten Feldwerten ausgeben |
/api/v1/passes/:id | PATCH | Bearer / API Key | Bestehende Pass-Attribute aktualisieren und Push einreihen |
/api/v1/scans | POST | x-scanner-key | Pass-Barcode validieren, Mechanik ausführen, Scan protokollieren |
/v1/devices/... | POST | ApplePass <token> | Callback zur Apple-Wallet-Geräteregistrierung |
Wichtig: Updates in Apple Wallet erfolgen Pull-basiert: Passinstance überträgt keine Pass-Daten innerhalb der APNs-Benachrichtigung. Stattdessen weist ein leeres APNs-Wake-up-Signal das Apple-Gerät an, das aktuelle signierte
.pkpass-Paket sicher von den Passinstance-Servern abzurufen.
Entdecken Sie den vollständigen 6-Phasen-Onboarding-Leitfaden oder lesen Sie unsere API-Architektur.
