Überblick
Öffnen Sie Pässe im Dashboard (entweder im globalen Workspace-Verzeichnis oder gefiltert im Tab Pässe einer einzelnen Vorlage) bzw. fragen Sie /api/v1/passes ab, um ausgegebene Pass-Datensätze in Echtzeit einzusehen, zu filtern, zu prüfen, zu aktualisieren und zu migrieren. Jede Änderung an den Feldern oder der Vorlagenzuordnung eines Passes synchronisiert sich automatisch auf alle registrierten Apple-Wallet- und Google-Wallet-Geräte.

Systemarchitektur: Abfrage, Mutation & Vorlagenwechsel
1. Pässe suchen & filtern (GET /api/v1/passes)
Öffnen Sie im Dashboard Filter, um UND-/ODER-Bedingungsgruppen über Systemspalten und benutzerdefinierte structured JSON-Attribute zu kombinieren, und speichern Sie wiederkehrende Abfragen als Gespeicherte Ansichten (Saved Views):
-
Identität & Schlüssel:
serialNumber,externalId,bundleId,idempotencyKeyoder Pass-id. -
Lebenszyklus & Status:
status(pass status),lifecycleStatus(PassLifecycleStatus),walletVoidStatus(WalletPropagationStatus) und Artefaktbereitschaft (appleArtifactStatus,googleArtifactStatus). -
Wallet-Installationsstatus:
Installiert,Nicht installiertoderEntferntüber Apple-Wallet- (iOS) und Google-Wallet- (Android) Geräteregistrierungen hinweg. -
Datumsfenster: Bereichsfilter für
createdAt,updatedAt,expirationDateundlastScannedAt. -
Benutzerdefinierte structured JSON-Attribute (
attribute search index): Hochgeschwindigkeitsfilter für Containment- und Vergleichsabfragen auf jedem Schlüssel inpass.attributes(z. B.attributes.memberTier = "VIP"oderattributes.pointsBalance >= 1000).

Beispiel: Pässe abfragen & nach External ID suchen
-
GET /api/v1/passes?templateId=tmpl_01hxyz987654321&status=ACTIVE&externalId=crm_usr_44910&page=1&limit=25 -
GET /api/v1/passes/by-external-id/crm_usr_44910(gibt den aktiven, nicht gelöschten Pass zuexternalIddirekt zurück, ohne dass interne UUIDs extern gespeichert werden müssen)
2. Einzelnen Pass aktualisieren (PATCH /api/v1/passes/:id)
Das Aktualisieren eines Passes führt neue Werte in attributes zusammen, passt expirationDate oder barcodeValue an und reiht sofort ein Push-Update an alle Geräte ein, auf denen der Pass installiert ist. Definiert ein geändertes Feld in der Vorlage eine changeMessage mit %@, zeigt Apple Wallet eine native Sperrbildschirm-Benachrichtigung an.
HTTP-Anfrage
PATCH /api/v1/passes/pass_01j8k9m2n3p4q5r6 Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"attributes": {
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"barcodeAltText": "44910-PLATINUM",
"expirationDate": "2028-12-31 23:59"
}
HTTP-Antwort (200 OK)
{
"success": true,
"data": {
"id": "pass_01j8k9m2n3p4q5r6",
"serialNumber": "PI-GOLD-2026-44910",
"externalId": "crm_usr_44910",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"email": "marcus.vance@example.com",
"pointsBalance": 1450,
"memberTier": "Platinum"
},
"updatedAt": "2026-11-15T17:30:00.000Z"
},
"statusCode": 200
}
3. Pass-Historie & Ereignis-Timeline prüfen
Passinstance führt für jeden Pass zwei sich ergänzende Prüfprotokolle:
| Endpunkt | Umfang & zurückgegebene Daten | |||
|---|---|---|---|---|
GET /api/v1/passes/:id/history | Gibt chronologische Feld- und Attributänderungen zurück (previousValue, newValue, changedBy, `source: 'API' \ | 'SCANNER' \ | 'DASHBOARD' \ | 'WORKFLOW', timestamp`). |
GET /api/v1/passes/:id/timeline | Gibt den einheitlichen Lebenszyklus- und Interaktions-Stream zurück — inklusive Pass-Erstellung, E-Mail-/SMS-Versand, Apple-/Google-Geräteinstallationen, Scanner-Validierungen, Saldoänderungen und Push-Benachrichtigungen. |
Beispiel: Pass-Timeline abrufen
/api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
{
"success": true,
"data": {
"passId": "pass_01j8k9m2n3p4q5r6",
"events": [
{
"eventId": "evt_03",
"type": "ATTRIBUTE_UPDATED",
"summary": "pointsBalance changed from 500 to 1450",
"actor": "api_key:pi_live_99a8",
"createdAt": "2026-11-15T17:30:00.000Z"
},
{
"eventId": "evt_02",
"type": "WALLET_INSTALLED",
"platform": "APPLE_WALLET",
"deviceLibraryIdentifier": "dlib_8841209a",
"createdAt": "2026-11-15T15:10:05.000Z"
},
{
"eventId": "evt_01",
"type": "PASS_CREATED",
"summary": "Pass issued via REST API",
"createdAt": "2026-11-15T15:04:12.000Z"
}
]
},
"statusCode": 200
}
4. Vorlagenwechsel im laufenden Betrieb (POST /api/v1/passes/:id/switch-template/:targetTemplateId)
Wenn eine Kundin oder ein Kunde in ein höheres Stufendesign aufsteigt oder zwischen saisonalen Programmen wechselt, können Sie einen bestehenden Pass auf eine andere PUBLISHED-Vorlage migrieren, ohne id, serialNumber, authenticationToken oder aktive Geräteregistrierungen zu verändern.
POST /api/v1/passes/pass_01j8k9m2n3p4q5r6/switch-template/tmpl_platinum_vip_999 Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"preserveAttributes": true,
"attributeOverrides": {
"vipLoungeAccess": "Unlimited"
},
"pushUpdateImmediately": true
}
Wichtig: Damit ein Pass nahtlos auf Apple-Wallet-Geräten zu
:targetTemplateIdwechseln kann, müssen Quell- und Zielvorlage denselben ApplepassTypeIdentifier(Pass-Type-ID-Zertifikat) verwenden. Nutzt die Zielvorlage eine andere Pass Type ID, behandelt iOS ihn als neue separate Karte statt als direktes visuelles In-Place-Update.
Details zu Zustandsübergängen und Entwertungsregeln finden Sie unter Pass-Lebenszyklus & Status. Informationen zu Änderungen an mehreren Datensätzen zugleich bietet Massenaktionen.
