Skip to content
Hilfecenter-Anleitung · Pass-VerwaltungOnboarding-Phase 3
3 Min. LesezeitGeprüft 2026-11-16

Pässe ansehen & bearbeiten

Durchsuchen Sie ausgegebene Karten mit gespeicherten Ansichten und UND/ODER-Filtern, prüfen Sie Geräte und aktualisieren Sie Attribute.

In dieser Anleitung

Prüfen Sie passende Dashboard-Bereiche, Steuerelemente und Zoom-Hinweise zu diesem Thema.

Vergrößerter UI-Fokus1 / 2
Wichtige UI-Elemente

Ausgegebene Pässe & Zeilenaktionen (Zoom)

Testpässe im Tab Passes inspizieren, nach Status oder Installation filtern und QR-Code, Detailansicht, Bearbeitung oder Push direkt ausführen.

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

Suchfilter für Pässe und Zeilen-Telemetrie
Suchfilter für Pässe und Zeilen-Telemetrie

Systemarchitektur: Abfrage, Mutation & Vorlagenwechsel

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
PASS-ABFRAGE, PATCH-MUTATION & VORLAGENWECHSEL
STUFE 01 DASHBOARD-FILTER-BUILDER / REST-API (/api/v1/passes)
Suchen & Filtern: GET/api/v1/passes?templateId=...&status=ACTIVE&...
Teil-Update: PATCH/api/v1/passes/:id
Audit & Timeline: GET/api/v1/passes/:id/history & /timeline
Vorlagenwechsel: POST/api/v1/passes/:id/switch-template/:targetTemplateId
STUFE 02 DATABASE-QUERY-ENGINE & ATTRIBUT-INDIZIERUNG
Relationale Indizes auf (customerId, templateId, status, externalId)
Sub-Millisekunden-structured JSON-Filterung über GIN-Index attribute search index
Hängt unveränderliche Feld-Diffs an pass audit log & Scan-Timeline an
STUFE 03 WALLET-PUSH-AUSBREITUNG (WalletPropagationStatus)
Zustandsübergang: PENDINGQUEUEDSUCCEEDED
Apple Wallet: Sendet APNs-HTTP/2-Wake-PushGerät lädt neue .pkpass
Google Wallet: Führt REST-PATCH auf Cloud-walletobjects-Ressource aus

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, idempotencyKey oder Pass-id.
  • Lebenszyklus & Status: status (pass status), lifecycleStatus (PassLifecycleStatus), walletVoidStatus (WalletPropagationStatus) und Artefaktbereitschaft (appleArtifactStatus, googleArtifactStatus).
  • Wallet-Installationsstatus: Installiert, Nicht installiert oder Entfernt über Apple-Wallet- (iOS) und Google-Wallet- (Android) Geräteregistrierungen hinweg.
  • Datumsfenster: Bereichsfilter für createdAt, updatedAt, expirationDate und lastScannedAt.
  • Benutzerdefinierte structured JSON-Attribute (attribute search index): Hochgeschwindigkeitsfilter für Containment- und Vergleichsabfragen auf jedem Schlüssel in pass.attributes (z. B. attributes.memberTier = "VIP" oder attributes.pointsBalance >= 1000).
Erweitertes Filter-Panel mit UND/ODER-Bedingungs-Editor
Erweitertes Filter-Panel mit UND/ODER-Bedingungs-Editor

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 zu externalId direkt zurück, ohne dass interne UUIDs extern gespeichert werden müssen)
Header
X-API-Key <API_KEY>

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

JSON
{
  "attributes": {
    "pointsBalance": 1450,
    "memberTier": "Platinum"
  },
  "barcodeAltText": "44910-PLATINUM",
  "expirationDate": "2028-12-31 23:59"
}

HTTP-Antwort (200 OK)

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

EndpunktUmfang & zurückgegebene Daten
GET /api/v1/passes/:id/historyGibt chronologische Feld- und Attributänderungen zurück (previousValue, newValue, changedBy, `source: 'API' \'SCANNER' \'DASHBOARD' \'WORKFLOW', timestamp`).
GET /api/v1/passes/:id/timelineGibt 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

GET /api/v1/passes/pass_01j8k9m2n3p4q5r6/timeline
JSON
{
  "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

JSON
{
  "preserveAttributes": true,
  "attributeOverrides": {
    "vipLoungeAccess": "Unlimited"
  },
  "pushUpdateImmediately": true
}

Wichtig: Damit ein Pass nahtlos auf Apple-Wallet-Geräten zu :targetTemplateId wechseln kann, müssen Quell- und Zielvorlage denselben Apple passTypeIdentifier (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.

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.