Überblick
Sobald Sie im Dashboard über Schnellfilter oder den erweiterten UND/ODER-Filterbereich (StickySelectionToolbar) eine Zielkohorte von Pässen eingegrenzt haben, nutzen Sie das Menü Massenaktionen in der Pässe-Symbolleiste — oder rufen Sie die Batch Operations API (/api/v1/batch-pass-operations/*) über die REST-API auf —, um strukturierte Array-Operationen für bis zu 1.000 Pässe pro Aufruf auszuführen. Im Gegensatz zu Multipart-CSV-Datei-Uploads (/api/v1/batch-processing) verarbeitet /api/v1/batch-pass-operations/* JSON-Payloads direkt und liefert elementbezogene errors und warnings im request payload zurück.
Wenn Tausende oder Zehntausende ausgegebene Pässe gleichzeitig aktualisiert werden, entkoppelt Passinstance Datenbankänderungen von der mobilen Wallet-Push-Zustellung. Änderungen werden sofort in der Datenbank gespeichert, während Aktualisierungen über ratenbegrenzte, gepoolte HTTP/2-APNs-Verbindungen an Apple-Wallet-Geräte sowie über sofortige Issuer-Class-Propagation oder einzelne Pass-Object-REST-Patches an Google-Wallet-Geräte verteilt werden.
Systemarchitektur: Massenoperationen, Queue-Drosselung & Wallet-Propagation
Ziel-Pass-Kohorten filtern
Vor der Ausführung von Massenoperationen grenzen Administratorinnen und Administratoren genau die zu ändernde Zielgruppe ein:
Schnellfilter & erweiterter UND/ODER-Filterbereich
Im Dashboard unter Pässe (/passes):
-
Vorlagenfilter: Beschränkt Aktionen auf eine bestimmte Pass-Vorlage oder ein Kampagnen-Kartendesign.
-
Statusfilter: Filtert nach Lebenszyklusstatus (
ACTIVE,INACTIVE,SUSPENDED,EXPIRED,VOIDED). -
Zustandsfilter: Unterscheidet zwischen
active_only(auf mindestens einem Gerät installiert),inactive_only(deinstalliert) undnot_registered(nicht abgerufene Download-Links). -
Erweiterte Suche (
Advanced Filter panel): Kombiniert mehrere Attribute mittels UND/ODER-Logik (z. B.tier == "Gold"UNDpointsBalance < 500UNDexpirationDate < 2027-01-01). -
Fixierte Auswahl-Symbolleiste (
StickySelectionToolbar):
- Klicken Sie auf das Haupt-Kontrollkästchen, um die aktuelle Seite auszuwählen (bis zu 100 Pässe). - Klicken Sie auf das Hinweisbanner, um alle passenden Pässe über sämtliche Seiten hinweg auszuwählen (z. B. „Alle 4.850 Pässe auswählen, die diesem Filter entsprechen“).
Kohortenauswahl per API
Über die REST-API ermitteln Sie die Ziel-Pass-UUIDs mit POST /api/v1/passes/query-builder oder POST /api/v1/passes/search und übergeben die resultierenden IDs anschließend an /batch-pass-operations/*.
Tausende ausgegebene Pässe aktualisieren
Das Aktualisieren großer Bestände ausgegebener Pässe erfordert ein ausgewogenes Zusammenspiel zwischen Datenbank-Schreibdurchsatz und den strengen Verbindungsgrenzen mobiler Wallet-Push-Gateways.
Direkte Array-Operationen vs. CSV-Stapelverarbeitung
Passinstance bietet je nach Volumen zwei unterschiedliche Wege für Massenaktualisierungen:
-
1
Direkte JSON-Array-Operationen (
POST /api/v1/batch-pass-operations/update):
- Optimal für bis zu 1.000 Pässe pro HTTP-Anfrage. - Akzeptiert ein Array aus passIds und ein gemeinsames updateData-Objekt. - Synchrone HTTP-Antwort mit individuellem Status sowie Fehlern und Warnungen für jeden Pass.
-
2
Asynchrone CSV-Stapel-Pipeline (
/api/v1/batch-processing):
- Optimal für 1.000 bis 100.000+ Pässe. - Laden Sie eine CSV-Datei mit eindeutigen Kennungen (externalId oder serialNumber) und geänderten Attributen hoch. - Setzen Sie die Operation auf UPDATE_PASSES oder UPSERT. - Worker-Queues der Hintergrund-Job-Queue verarbeiten Zeilen asynchron in begrenzten Datenbanktransaktionen zu je 50 Zeilen mit Live-Fortschrittsanzeige und herunterladbarem Ergebnisprotokoll (result.csv).
Apple Wallet APNs-HTTP/2-Drosselung & Connection-Pooling
Bei der Aktualisierung von Apple-Wallet-Pässen sendet Passinstance Push-Mitteilungen, die iOS-Geräte im Hintergrund aufwecken, damit sie das aktualisierte .pkpass-Paket von der Passinstance-API abrufen:
-
Stille Push-Mitteilungen: Pass-Mitteilungen werden mit
content-available: 1versendet. Sie zeigen keine störenden Sperrbildschirm-Pop-ups an, sofern keine lokalisierten Feldänderungsmeldungen (z. B. „Ihr Gate wurde auf B12 geändert“) konfiguriert sind. -
Persistente HTTP/2-Streams: Der Dienst
@passinstance/apnshält gepoolte, persistente HTTP/2-Verbindungen zu den Apple-Push-Servern (api.push.apple.com:443) offen. Statt für jeden Empfänger neue TLS-Handshakes auf- und abzubauen, werden Streams über aktive Verbindungen gemultiplext. -
Adaptives Rate-Limiting & Queue-Drosselung:
- Ausgehende Benachrichtigungen durchlaufen Hintergrund-Job-Queues (push-notifications, individual-push-notifications, silent-push-notifications). - Notification Rate Limiter und Notification Deduplication überwachen den Antwortstream von Apple. - Gibt APNs 429 TooManyRequests oder verbindungsbezogenen Gegendruck zurück, drosseln die Worker die Parallelität und führen ein exponentielles Backoff durch, um Token-Ungültigkeiten und IP-Sperren zu verhindern.
Google Wallet Class-Updates vs. Object-PATCH
Google Wallet nutzt eine hierarchische Architektur, die die Pass Class (die übergeordnete Vorlagendefinition) vom Pass Object (der individuellen Karte des jeweiligen Inhabers) trennt:
-
Vorlagenweite visuelle und Feld-Updates (Issuer Class):
Wenn eine globale Änderung an einer Vorlage veröffentlicht wird (z. B. Änderung des Header-Logos, der Hintergrundfarbe oder der Teilnahmebedingungen) und alle Karten ohne personalisierten Text betrifft (!hasPersonalizedMessage), ruft Passinstance die Google Wallet class sync in template.service.ts auf. Dadurch wird ein einzelner REST-PATCH an die Google Wallet API gesendet, um die Issuer Class zu aktualisieren. Da jeder ausgegebene Google-Wallet-Pass auf diese übergeordnete Class verweist, verteilen die Google-Cloud-Server das Update sofort und gleichzeitig an alle aktiven Android-Pässe, ohne Tausende einzelner API-Anfragen zu erzeugen.
-
Inhaberspezifische Attributaktualisierungen (Pass Object):
Unterscheiden sich einzelne Attribute je Pass (z. B. individuelle Punktestände, Status-Upgrades oder Kundennamen), führt Passinstance einzelne HTTP-PATCH-Aufrufe für das jeweilige Google Wallet Pass Object aus (POST /batch-pass-operations/update).
Attributvalidierung & Sicherheitsregeln
Der Batch-Update-Service (batch-pass-operations.service.ts) setzt strenge Regeln zur Datenintegrität durch:
-
Mandantenisolierung: Geschützte Felder (
customerId,tenantId,createdBy,templateId) werden automatisch aus eingehenden Payloads entfernt. Aktualisierungen können weder den Pass-Eigentümer ändern noch übergeordnete Vorlagen neu zuweisen. -
Partielle Attributvalidierung (
preValidateAttributes): Beim Aktualisieren bestehender Pässe (isUpdate = true) werden Pflichtfeldprüfungen übersprungen. Sie können eine einzelne benutzerdefinierte Eigenschaft (z. B.pointsBalance) patchen, ohne unveränderte Bestandsfelder erneut zu senden. -
Attributnormalisierung: Zeichenketten werden getrimmt, Zahlen in Float/Int konvertiert und Datumsangaben auf ISO-8601 UTC normalisiert.
Unterstützte Massenoperationen in Dashboard & API
| Operation | API-Endpunkt | DTO & Verhalten |
|---|---|---|
| Batch Create | POST /api/v1/batch-pass-operations/create | request payload (passes[], max. 1.000 Einträge). Gibt neue Pässe mit optionaler externalId und bundleId aus. |
| Batch Update | POST /api/v1/batch-pass-operations/update | request payload (operation: "update", passIds[], updateData, optionale bundleOptions). |
| Batch Upsert | POST /api/v1/batch-pass-operations/upsert | request payload (operation: "upsert", passData[]) mit Mandantenschlüssel (customerId, externalId). |
| Batch Activate | POST /api/v1/batch-pass-operations/activate | request payload (operation: "activate", passIds[]), setzt Pässe in den Status ACTIVE. |
| Batch Deactivate (Entwerten) | POST /api/v1/batch-pass-operations/deactivate | request payload (operation: "deactivate", passIds[]), versetzt Pässe in SUSPENDED / INACTIVE und macht Barcodes ungültig. |
| Batch Delete | POST /api/v1/batch-pass-operations/delete | request payload (passIds[]), überführt Pässe über DELETING in das Soft-Delete (archivedAt: new Date()). |
| Batch Bundle | POST /api/v1/bundles/batch-create | Gruppiert ausgewählte Pass-IDs in gemeinsame pass bundle-Container (Pass.bundleId, bis zu 10 Pässe pro Bundle). |
Wichtig: Prüfen Sie stets
errorsundwarningsimrequest payload. ErkenntvalidateBatchOperationungültige Zeilen, liefert der Controllersuccess: falsezusammen mit detaillierten elementbezogenen Fehlerdiagnosen inerrors[]zurück.
Referenz für programmgesteuerte Batch-Pass-Operationen (request payload)
1. Batch-Upsert von Pässen (POST /api/v1/batch-pass-operations/upsert)
Ideal für CRM-Synchronisierungen oder Neuberechnungen von Treuestufen auf Basis von externalId:
HTTP-Anfrage
POST /api/v1/batch-pass-operations/upsert Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "upsert",
"passData": [
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"pointsBalance": 1800,
"memberTier": "Platinum"
}
},
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44911",
"attributes": {
"firstName": "Hannah",
"lastName": "Abbott",
"pointsBalance": 250,
"memberTier": "Silver"
}
}
]
}
HTTP-Antwort (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"externalId": "crm_usr_44911",
"serialNumber": "PI-GOLD-2026-44911",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m9z8y7x6w5"
}
],
"message": "Successfully upserted 2 passes",
"errors": [],
"warnings": []
}
2. Batch-Update von Pässen (POST /api/v1/batch-pass-operations/update)
Aktualisiert ausgewählte passIds mit gemeinsamen updateData und optionalen bundleOptions:
POST /api/v1/batch-pass-operations/update Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "update",
"passIds": [
"pass_01j8k9m2n3p4q5r6",
"pass_01j8k9m9z8y7x6w5"
],
"updateData": {
"expirationDate": "2028-03-31T23:59:59Z",
"attributes": {
"seasonalOffer": "2x Winter Bonus Points"
}
}
}
HTTP-Antwort (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
}
],
"message": "Successfully updated 2 passes",
"errors": [],
"warnings": []
}
3. Pässe im Batch aktivieren, deaktivieren oder löschen
-
Aktivieren:
POST /api/v1/batch-pass-operations/activate({ "operation": "activate", "passIds": [...] }) -
Deaktivieren:
POST /api/v1/batch-pass-operations/deactivate({ "operation": "deactivate", "passIds": [...] }) -
Löschen:
POST /api/v1/batch-pass-operations/delete({ "passIds": [...] }überrequest payload)
Versandintegration: Welcher Platzhalter fügt den Pass-Link ein? ({passDownloadUrl})
Welcher Platzhalter fügt den Pass-Link ein?
Wenn Sie im Anschluss an Massenoperationen automatisierte E-Mail- oder SMS-Benachrichtigungen versenden, stellt Passinstance eine flexible Platzhalter-Ersetzungs-Engine bereit (pass-url-placeholder.util.ts). Der kanonische Platzhalter ist {passDownloadUrl}.
Kanonischer Platzhalter & unterstützte Aliase
Der offizielle, kanonische Platzhalter lautet {passDownloadUrl}. Passinstance unterstützt darüber hinaus abwärtskompatible Aliase:
| Platzhalter-Token | Kanonisch / Alias | Beispiel für aufgelöste Ausgabe |
|---|---|---|
{passDownloadUrl} | Kanonisch | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{smartLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{downloadUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{walletDownloadUrl} | Dynamischer Alias | Kontextabhängiger Link mit Weiterleitung je nach Client-Betriebssystem |
Formatierungsflexibilität: Passinstance normalisiert doppelte geschweifte Klammern
{{passDownloadUrl}}, snake_case{pass_download_url}und PascalCase{PassDownloadUrl}automatisch auf das kanonische Token.
Direkte Wallet-Aktionsschaltflächen & bedingte Flags
Für responsive HTML-E-Mail-Vorlagen können Sie direkte One-Tap-Wallet-Schaltflächen einbinden, anstatt ausschließlich auf die vorgeschaltete PassFlow-Seite zu verlinken:
| Variable | Beschreibung |
|---|---|
{appleWalletUrl} | Direkter binärer .pkpass-Download-Stream, der die native Apple-Wallet-Installation in iOS Safari auslöst. |
{googleWalletUrl} | Direkter „Zu Google Wallet hinzufügen“-Deep-Link (https://pay.google.com/gp/v/save/...). |
{samsungWalletUrl} | Direkter Samsung-Wallet-Speicher-Deep-Link. |
{walletButtonText} | Kontextabhängige Schaltflächenbeschriftung („Zu Apple Wallet hinzufügen“, „In Google Wallet speichern“ oder „Meinen Pass herunterladen“). |
{showAppleWalletButton} | Boolesches Flag (true/false), das anzeigt, ob Apple-Wallet-Assets konfiguriert sind. |
{showGoogleWalletButton} | Boolesches Flag, das anzeigt, ob die Google-Wallet-Integration aktiv ist. |
Teilfehler, Fehlerbehandlung & Audit-Protokollierung
Beim Aufruf von Batch-Operationen schlagen Anfragen nicht vollständig fehl, wenn lediglich eine Teilmenge der Einträge Fehler enthält:
-
1
Einzelelement-Fehlerisolierung: In
updateBatchPasseswird jeder Pass in einem isolierten Try-Catch-Block verarbeitet. Ein Fehler in Zeile 42 (z. B. ein ungültiges Datumsformat) verhindert nicht, dass die Zeilen 1–41 und 43–100 erfolgreich verarbeitet werden. -
2
Standardisierte Fehlerstruktur: Fehlgeschlagene Einträge werden in
errors[]mitpassId,error-Meldung underrorCodeaufgeführt:
{
"passId": "pass_01j8k9m2n3p4q5r6",
"error": "Attribute 'pointsBalance' must be a valid number",
"errorCode": "ATTR_VALIDATION"
}
-
3
Workspace-Audit-Protokollierung: Jede Massenoperation erzeugt einen Eintrag im
pass audit logsowie im Workspace-Audit-Log (GET /api/v1/audit-log/export.csv) mit Akteur-ID, IP-Adresse, Operationstyp, Anzahl betroffener Einträge und Zeitstempel.
Für CSV-dateibasierte Stapelimporte lesen Sie Massenerstellung von Pässen. Für die Massenentwertung über eine gesamte Vorlage hinweg siehe Pass-Lebenszyklus & Status.
