Überblick: Wie Live-Pass-Synchronisierung funktioniert
Anders als statische PDF-Tickets oder Barcode-Bilder bleiben von Passinstance verwaltete digitale Wallet-Pässe auch nach der Installation mit der Cloud verbunden. Sobald sich ein Pass-Attribut, ein Mechanik-Saldo (Stempel, Treuepunkte, Prepaid-Guthaben), eine Statusstufe oder das Vorlagendesign ändert, orchestriert Passinstance eine asynchrone Wallet-Propagations-Pipeline, die die aktive Karte auf iPhone, Apple Watch und Android-Gerät aktualisiert.
Lebenszyklus des Wallet-Propagationsstatus (walletVoidStatus / WalletPropagationStatus)
Jeder Pass-Datensatz verfolgt den Ausbreitungs- und Stornostatus über Apple- und Google-Cloud-Netzwerke hinweg im Feld Pass.walletVoidStatus (WalletPropagationStatus):
| Status-Enum | Bedeutung & Betriebszustand |
|---|---|
NONE | Pass wurde neu erstellt oder es wurde noch keine Wallet-sichtbare Synchronisierung eingereiht. |
PENDING | Eine Feld-, Mechanik-, Storno- oder Vorlagenänderung wurde festgeschrieben und wartet auf Übergabe an background job queue. |
QUEUED | In die in-memory cache/background job queue-Wallet-Propagations-Worker-Queue zur APNs- und Google-REST-Ausführung eingereiht. |
SUCCEEDED | Die APNs-Push-Nachricht wurde von Apples HTTP/2-Gateway akzeptiert (200 OK) und/oder der Google-Wallet-REST-PATCH war erfolgreich. |
FAILED | Die Auslieferung ist auf einen Upstream-Fehler gestoßen (z. B. abgelaufenes Apple-Pass-Type-Zertifikat, widerrufenes APNs-Token 410 Gone oder Google-API-Kontingentfehler). |
Wichtig: Beim Veröffentlichen eines Vorlagenentwurfs über
POST /api/v1/templates/:id/publishmitpropagateUpdates: truewerden Aktualisierungsjobs an alle aktiven Pässe dieser Vorlage verteilt (eingrenzbar überactivePassesOnly: true). Führen Sie vorab stetsGET /api/v1/templates/:id/publish-risk-checkaus, um kritische Änderungen und deren Auswirkungen zu prüfen.
API-Endpunkte zum Aktualisieren von Pässen
| Methode | Endpunkt-Pfad | Beschreibung |
|---|---|---|
| PATCH | /api/v1/passes/:id | Aktualisiert benutzerdefinierte Attribute, Status, Ablaufdatum oder Barcode-Payload eines einzelnen Passes und stößt Wallet-Propagation an. |
| POST | /api/v1/passes/upsert-by-external-id | Erstellt oder aktualisiert idempotent einen über (customerId, externalId) gefundenen Pass (PUT /api/v1/passes/by-external-id/:externalId ebenfalls unterstützt). |
| POST | /api/v1/batch-pass-operations/update | Aktualisiert ausgewählte passIds in einem Batch-Aufruf (request payload) und reiht Propagationsjobs ein. |
| POST | /api/v1/templates/:id/publish | Schaltet einen Vorlagenentwurf live (request payload mit propagateUpdates: true) und aktualisiert aktive Pässe dieser Vorlage. |
Beispiel: Einzel-Pass-Update & Auslösung der Propagation
PATCH /api/v1/passes/c41a8d20-6e11-4f3b-9a81-0029d81a4f10
{
"attributes": {
"points": 1450,
"tier": "Platinum",
"nextReward": "Free Espresso"
},
"expirationDate": "2027-12-31 23:59"
}
Antwort (200 OK):
{
"id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"externalId": "cust_884910",
"serialNumber": "PI-8849-2026-X9",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"updatedAt": "2026-11-15T14:22:10.114Z"
}
Beispiel: Batch-Array-Pass-Update (request payload)
POST /api/v1/batch-pass-operations/update
{
"operation": "update",
"passIds": [
"c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"9b2f1e44-8a10-4c92-a711-5530e91b2c01"
],
"updateData": {
"attributes": {
"seasonalOffer": "Winter Bonus Points"
}
}
}
Warum Synchronisierungszeiten je Gerät variieren können
-
Flugmodus & Datensparmodus: iOS-Geräte im Flugmodus oder Stromsparmodus verschieben APNs-Hintergrundabrufe, bis wieder WLAN- oder Mobilfunkempfang besteht.
-
Schalter für automatische Updates: Kundinnen und Kunden, die auf der Rückseite ihres Apple-Wallet-Passes Automatische Updates deaktiviert haben, müssen in Apple Wallet manuell nach unten ziehen, um das aktuelle
.pkpass-Paket abzurufen. -
Unterdrückung entwerteter Pässe: Standardmäßig unterdrücken Pässe im Status
VOIDEDoderEXPIREDreguläre Marketing-Pushs, sofern auf der Vorlage nichtupdateVoidedExpiredPasses: trueaktiviert wurde.
Verwandte Abläufe finden Sie unter Push-Benachrichtigungen, Pässe ansehen & bearbeiten und Vorlagenversionen & Veröffentlichung.
