Skip to content
Hilfecenter-Anleitung · Wallet-Updates & Benachrichtigungen
2 Min. LesezeitGeprüft 2026-11-16

Bestehende Pässe aktualisieren

Erfahren Sie, wie serverseitige Feldänderungen stille APNs-Updates bei Apple und Objekt-Patches bei Google Wallet auslösen.

In dieser Anleitung

Ü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.

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
WALLET-UPDATE- & PROPAGATIONS-PIPELINE
STUFE 01 AUSLÖSER VON DATENÄNDERUNGEN
Einzel-Update: PATCH/api/v1/passes/:id oder .../upsert-by-external-id
Batch-Array: POST/api/v1/batch-pass-operations/update
Vorlagen-Pub.: POST/api/v1/templates/:id/publish (propagateUpdates: true)
Scanner / POS: POST/api/v1/scans / POST/v1/pos/redeem / /reader/redeem
STUFE 02 DATENBANK-COMMIT & PROPAGATIONS-ZUSTANDSÜBERGANG
1
Pass-Revision hochzählen & Audit-Eintrag in pass audit log speichern
2
walletVoidStatus (WalletPropagationStatus): NONEPENDINGQUEUED
3
background job queue-Propagations-Job einreihen (wallet-propagation Queue)
Apple-Wallet-Geräteregistrierungen
STUFE 03A
1
Apple Push Delivery sendet HTTP/2 le Push {} an jedes registrierte Gerät
2
iOS wacht auf & fragt ab:GET/v1/devices/.../registrations
3
iOS lädt signiertes .pkpass:GET/v1/passes/:typeId/:serial
Google-Wallet-Cloud-Objekt
STUFE 03B n | | 1. Google Wallet Sync führt a
REST-PATCH auf walletobjects/v1/... aus
2
Google Cloud pusht den neuen Objektstand via Play Services direkt auf Android-Geräte
STUFE 04 ABSCHLIESSENDE TELEMETRIE & PROPAGATIONSSTATUS-UPDATE
walletVoidStatus (WalletPropagationStatus): SUCCEEDED o. FAILED

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-EnumBedeutung & Betriebszustand
NONEPass wurde neu erstellt oder es wurde noch keine Wallet-sichtbare Synchronisierung eingereiht.
PENDINGEine Feld-, Mechanik-, Storno- oder Vorlagenänderung wurde festgeschrieben und wartet auf Übergabe an background job queue.
QUEUEDIn die in-memory cache/background job queue-Wallet-Propagations-Worker-Queue zur APNs- und Google-REST-Ausführung eingereiht.
SUCCEEDEDDie APNs-Push-Nachricht wurde von Apples HTTP/2-Gateway akzeptiert (200 OK) und/oder der Google-Wallet-REST-PATCH war erfolgreich.
FAILEDDie 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/publish mit propagateUpdates: true werden Aktualisierungsjobs an alle aktiven Pässe dieser Vorlage verteilt (eingrenzbar über activePassesOnly: true). Führen Sie vorab stets GET /api/v1/templates/:id/publish-risk-check aus, um kritische Änderungen und deren Auswirkungen zu prüfen.

API-Endpunkte zum Aktualisieren von Pässen

MethodeEndpunkt-PfadBeschreibung
PATCH/api/v1/passes/:idAktualisiert benutzerdefinierte Attribute, Status, Ablaufdatum oder Barcode-Payload eines einzelnen Passes und stößt Wallet-Propagation an.
POST/api/v1/passes/upsert-by-external-idErstellt 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/updateAktualisiert ausgewählte passIds in einem Batch-Aufruf (request payload) und reiht Propagationsjobs ein.
POST/api/v1/templates/:id/publishSchaltet einen Vorlagenentwurf live (request payload mit propagateUpdates: true) und aktualisiert aktive Pässe dieser Vorlage.

Beispiel: Einzel-Pass-Update & Auslösung der Propagation

JSON
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):

JSON
{
  "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)

JSON
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 VOIDED oder EXPIRED reguläre Marketing-Pushs, sofern auf der Vorlage nicht updateVoidedExpiredPasses: true aktiviert wurde.

Verwandte Abläufe finden Sie unter Push-Benachrichtigungen, Pässe ansehen & bearbeiten und Vorlagenversionen & Veröffentlichung.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.