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

Massenaktionen

Führen Sie Stapelaktionen für gefilterte Kohorten aus — Massenänderungen, Stornierungen, Löschungen und gezielte Exporte.

In dieser Anleitung

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

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Tab Passes & Massenaktionen (Zoom)

Nach dem Massenimport über Passes, Filter und „Bulk actions“ generierte Karten gebündelt prüfen oder aktualisieren.

Ü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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
MASSENOPERATIONEN & WALLET-PROPAGATION
STUFE 01 DASHBOARD-MASSEN-TOOLBAR / API (Batch Operations API)
Kohortenauswahl (StickySelectionToolbar / Filterbereich / Pass-IDs)
POST/api/v1/batch-pass-operations/update (operation: "update")
POST/api/v1/batch-pass-operations/upsert (Schlüssel: externalId)
POST/api/v1/batch-pass-operations/activate (operation: "activate")
POST/api/v1/batch-pass-operations/deactivate (operation: "deactivate")
POST/api/v1/batch-pass-operations/delete (request payload)
POST/api/v1/batch-pass-operations/validate (Vorab-Payload-Prüfung)
STUFE 02 ISOLIERTE EINZELELEMENT-VALIDIERUNG & AUSFÜHRUNGS-ENGINE
Entfernt mandantengeschützte Schlüssel (customerId, tenantId, createdBy)
Vorab-Attributprüfung via preValidateAttributes (überspringt Pflichtfelder)
Normalisiert Attribute via normalizeAttributes
Liefert request payload: { success, data, message, errors, warnings }
STUFE 03A APNs-HTTP/2-GEDROSSELTE WORKER-QUEUE
Hintergrund-Job-Queue: push-notifications
Persistentes HTTP/2-Connection-Pooling
Rate-Limiting vermeidet Apple-429
Stiller Push weckt Gerät zum Abruf
STUFE 03B GOOGLE-WALLET-CLASS-PROPAGATION
Vorlagenänderung: PATCH Issuer Class
Sofort-Sync an ALLE Android-Pässe
Einzelne Pass-Object-PATCH-Aufrufe für passspezifische dynamische
Attribute

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) und not_registered (nicht abgerufene Download-Links).
  • Erweiterte Suche (Advanced Filter panel): Kombiniert mehrere Attribute mittels UND/ODER-Logik (z. B. tier == "Gold" UND pointsBalance < 500 UND expirationDate < 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. 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.

  1. 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: 1 versendet. 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/apns hä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

OperationAPI-EndpunktDTO & Verhalten
Batch CreatePOST /api/v1/batch-pass-operations/createrequest payload (passes[], max. 1.000 Einträge). Gibt neue Pässe mit optionaler externalId und bundleId aus.
Batch UpdatePOST /api/v1/batch-pass-operations/updaterequest payload (operation: "update", passIds[], updateData, optionale bundleOptions).
Batch UpsertPOST /api/v1/batch-pass-operations/upsertrequest payload (operation: "upsert", passData[]) mit Mandantenschlüssel (customerId, externalId).
Batch ActivatePOST /api/v1/batch-pass-operations/activaterequest payload (operation: "activate", passIds[]), setzt Pässe in den Status ACTIVE.
Batch Deactivate (Entwerten)POST /api/v1/batch-pass-operations/deactivaterequest payload (operation: "deactivate", passIds[]), versetzt Pässe in SUSPENDED / INACTIVE und macht Barcodes ungültig.
Batch DeletePOST /api/v1/batch-pass-operations/deleterequest payload (passIds[]), überführt Pässe über DELETING in das Soft-Delete (archivedAt: new Date()).
Batch BundlePOST /api/v1/bundles/batch-createGruppiert ausgewählte Pass-IDs in gemeinsame pass bundle-Container (Pass.bundleId, bis zu 10 Pässe pro Bundle).

Wichtig: Prüfen Sie stets errors und warnings im request payload. Erkennt validateBatchOperation ungültige Zeilen, liefert der Controller success: false zusammen mit detaillierten elementbezogenen Fehlerdiagnosen in errors[] 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

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)

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

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)

JSON
{
  "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": [...] } über request payload)

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-TokenKanonisch / AliasBeispiel für aufgelöste Ausgabe
{passDownloadUrl}Kanonischhttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{smartLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{downloadUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{walletDownloadUrl}Dynamischer AliasKontextabhä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:

VariableBeschreibung
{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. 1
    Einzelelement-Fehlerisolierung: In updateBatchPasses wird 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. 2
    Standardisierte Fehlerstruktur: Fehlgeschlagene Einträge werden in errors[] mit passId, error-Meldung und errorCode aufgeführt:
JSON
{
     "passId": "pass_01j8k9m2n3p4q5r6",
     "error": "Attribute 'pointsBalance' must be a valid number",
     "errorCode": "ATTR_VALIDATION"
   }
  1. 3
    Workspace-Audit-Protokollierung: Jede Massenoperation erzeugt einen Eintrag im pass audit log sowie 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.

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.