Überblick
Wenn Sie Hunderte oder Hunderttausende Karteninhaberinnen und Karteninhaber gleichzeitig anlegen möchten, stellt Passinstance eine asynchrone, fehlertolerante CSV-Stapelimport-Pipeline bereit, die auf der Batch Jobs API (/api/v1/batch-processing) und In-Memory-Cache-gestützten Hintergrund-Job-Queue-Workern basiert. Sie können UTF-8-Tabellen über das Dashboard (Massenoperationen -> Pässe importieren) hochladen, automatisierte FTP/SFTP-Importe auslösen oder die 6-stufige CSV-Pipeline programmgesteuert über die REST-API orchestrieren.

Systemarchitektur: CSV-Stapelausgabe & Hintergrund-Job-Queue-Worker-Pipeline
Checkliste der Voraussetzungen
Voraussetzungen: Prüfen Sie vor dem Start eines CSV-Stapelimport-Jobs die folgenden Anforderungen:
1. Die Ziel-
Template-Vorlage muss den StatusPUBLISHEDhaben.2. Ihre CSV-Datei muss in UTF-8 kodiert sein — ohne fehlerhafte Trennzeichen oder nicht maskierte Anführungszeichen.
3. Fügen Sie
phone-Spalten ein, wenn Sie Pass-Download-Links nach der Erstellung automatisch über Delivery-Center-Kampagnen versenden möchten.4. Konfigurieren Sie Ihre External-ID-Quelle in den Vorlageneinstellungen (
externalId), wenn Sie eine idempotente Deduplizierung über wiederholte Importe hinweg wünschen.
Schritt-für-Schritt-Workflow für den CSV-Import (Bulk Pass Wizard)
Im Dashboard unter Batch -> Stapelverarbeitung (/batch-processing) führt der Assistent durch fünf Phasen (Vorlage -> CSV hochladen -> Felder zuordnen -> Versandoptionen (optional) -> Verarbeiten):
-
1
Vorlage: Wählen Sie die gewünschte
PUBLISHED- /PRODUCTION-Vorlage (oder öffnen Sie Pässe -> Importieren direkt aus einer Vorlage heraus). -
2
CSV hochladen: Ziehen Sie eine UTF-8-CSV-Datei per Drag-and-drop in den Bereich oder laden Sie die dynamische Beispiel-CSV (
GET /api/v1/batch-processing/templates/:templateId/sample-csv) herunter, die bereits mit den zu Ihren benutzerdefinierten Eigenschaften und Systemfeldern (externalId,expirationDateusw.) passenden Spaltenüberschriften vorbelegt ist. -
3
Felder zuordnen: Überprüfen Sie die automatischen, mit Konfidenzwerten versehenen Zuordnungsvorschläge (
POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations), die Spaltenköpfe (z. B.Customer_ID,First_Name) mitexternalIdoderattributes.*-Schlüsseln verknüpfen. -
4
Versandoptionen (sofern aktiviert): Wählen Sie eine E-Mail-/SMS-Versandvorlage, wenn neu erstellte Pässe nach Abschluss automatisch versendet werden sollen.
-
5
Verarbeiten: Validieren und starten Sie den Job der Hintergrund-Job-Queue (Batch-Job-Status:
NEW,READY_TO_RUN,INTEGRATION_MAPPING_COMPLETE,SENDOUT_PENDING,RUNNING,COMPLETED,COMPLETED_WITH_ERRORS,FAILED,CANCELLED,PAUSED) und laden Sie anschließend/result.csvmit jeder generiertenserialNumber,externalId,bundleIdsowie dem Download-Link herunter.
REST-API-Referenz zur Stapelverarbeitung (Batch Jobs API)
Alle Endpunkte für CSV-Stapeljobs liegen unter /api/v1/batch-processing (unterstützte Batch-Job-Typen: CREATE_PASSES, UPDATE_PASSES, DELETE_PASSES, IMPORT_DATA, EXPORT_DATA, MIGRATION und Batch-Datenquellen: CSV_UPLOAD, API, SEGMENT, QUERY, MANUAL):
| Schritt | HTTP-Methode & Endpunkt | Zweck |
|---|---|---|
| 1. Beispiel-CSV | GET /api/v1/batch-processing/templates/:templateId/sample-csv | Lädt eine dynamische UTF-8-CSV-Kopfzeilenvorlage passend zu den benutzerdefinierten Eigenschaften der Vorlage herunter. |
| 2. CSV hochladen | POST /api/v1/batch-processing | Lädt eine Multipart-CSV-Datei oder eine JSON-Batch-Job-Definition hoch (status: NEW / READY_TO_RUN). |
| 3. Spalten automatisch zuordnen | POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations | Analysiert CSV-Spaltenüberschriften und liefert mit Konfidenzwerten bewertete Attribut-Zuordnungsvorschläge zurück. |
| 4. Zuordnung speichern | PUT /api/v1/batch-processing/:id/field-mapping | Speichert das bestätigte Wörterbuch zur Zuordnung von CSV-Spalten zu Attributen am Job. |
| 5. Trockenlauf-Validierung | POST /api/v1/batch-processing/:id/validate | Führt eine nicht-destruktive Validierung über die CSV-Zeilen aus und gibt zeilenbezogene Warnungen/Fehler zurück. |
| 6. Worker starten | POST /api/v1/batch-processing/:id/start | Reiht den Hintergrund-Worker-Job (status: RUNNING) in die Hintergrund-Job-Queue ein, um Pässe asynchron auszugeben. |
| 7. Ergebnisse exportieren | GET /api/v1/batch-processing/:id/result.csv | Streamt einen CSV-Bericht, der jeder Zeile die generierte passId, serialNumber, Download-Links und den Zeilenstatus anfügt. |
Beispiel: Vorschläge zur Feldzuordnung anfordern
POST /api/v1/batch-processing/templates/tmpl_01hxyz987654321/field-mapping-recommendations Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"csvHeaders": [
"Customer_ID",
"First_Name",
"Last_Name",
"Loyalty_Points",
"Card_Expiry"
]
}
HTTP-Antwort (200 OK)
{
"success": true,
"data": {
"recommendations": [
{ "csvColumn": "Customer_ID", "targetField": "externalId", "confidence": 0.98, "matchType": "SYSTEM" },
{ "csvColumn": "First_Name", "targetField": "attributes.firstName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
{ "csvColumn": "Last_Name", "targetField": "attributes.lastName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
{ "csvColumn": "Loyalty_Points", "targetField": "attributes.pointsBalance", "confidence": 0.89, "matchType": "CUSTOM_PROPERTY" },
{ "csvColumn": "Card_Expiry", "targetField": "expirationDate", "confidence": 0.94, "matchType": "SYSTEM" }
]
},
"statusCode": 200
}
Beispiel: Feldzuordnung bestätigen & Job validieren
PUT /api/v1/batch-processing/job_batch_77123/field-mapping Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"duplicateStrategy": "UPSERT_BY_EXTERNAL_ID",
"mappings": {
"Customer_ID": "externalId",
"First_Name": "attributes.firstName",
"Last_Name": "attributes.lastName",
"Loyalty_Points": "attributes.pointsBalance",
"Card_Expiry": "expirationDate"
}
}
Validieren und starten Sie anschließend den Worker der Hintergrund-Job-Queue:
POST /api/v1/batch-processing/job_batch_77123/validate POST /api/v1/batch-processing/job_batch_77123/start
{
"success": true,
"data": {
"id": "job_batch_77123",
"status": "RUNNING",
"jobType": "CREATE_PASSES",
"dataSource": "CSV_UPLOAD",
"totalRows": 5000,
"processedRows": 0
},
"statusCode": 200
}
Fehlerbehebung & Häufig gestellte Fragen
Wie prüfe ich, wenn ein Stapelverarbeitungs-Job fehlschlägt?
Tritt bei einem asynchronen CSV-Stapelimport ein Problem auf, prüfen Sie den Job-Status und die Protokolle entweder im Dashboard oder über die REST-API:
-
1
Job-Übersicht im Dashboard: Navigieren Sie zu Batch -> Stapelverarbeitung (
/batch-processing). Abgeschlossene Jobs mit Einzelfehlern tragen das Badge Mit Fehlern abgeschlossen (COMPLETED_WITH_ERRORS), abgebrochene Jobs das Badge Fehlgeschlagen (FAILED). -
2
Fehlerprotokoll herunterladen: Klicken Sie auf die Job-Karte und wählen Sie Fehler-CSV herunterladen oder rufen Sie
GET /api/v1/batch-processing/:id/result.csvab. Die ausgegebene Tabelle enthält jede Quell-CSV-Zeile ergänzt um eine Spaltestatus(SUCCESS,SKIPPEDoderFAILED) sowie eine SpalteerrorMessage, die den Fehler erläutert (z. B. „Missing required custom property: firstName“, „Invalid ISO 8601 date format“ oder „Duplicate externalId“). -
3
Job-Details per API prüfen: Rufen Sie
GET /api/v1/batch-processing/:idmit Ihrem API-Schlüssel auf. Die JSON-Antwort liefert denrequest payloadeinschließlichtotalRows,processedRows,successfulRows,failedRowssowie des ArrayserrorDetails[]mit genauen Zeilenindizes und Validierungsfehlercodes. -
4
Vorab-Validierung durchführen: Rufen Sie vor dem Einreihen eines Jobs mit 100.000 Zeilen stets
POST /api/v1/batch-processing/:id/validateauf. Dieser Trockenlauf überprüft Spaltenzuordnungen und Attributschemata ohne Datenbankeinträge zu erstellen und meldet Syntaxfehler noch vor dem Worker-Start.
Warum hat mein Stapelverarbeitungs-Durchlauf weniger Pässe erstellt als Zeilen in der Datei enthalten waren?
Wenn Ihre Eingabe-CSV 5.000 Zeilen enthielt, der Job jedoch nur 4.820 erstellte Pässe meldet, prüfen Sie die folgenden verifizierten Plattform-Verhaltensweisen:
-
1
External-ID-Deduplizierung (
duplicateStrategy): Erzwingt Ihre Vorlage eindeutige External IDs und istduplicateStrategyaufSKIPgesetzt, werden Zeilen übersprungen, derenexternalIdbereits einem bestehenden aktiven Pass in Ihrem Workspace zugeordnet ist (oder bereits weiter oben in derselben CSV-Datei vorkam), um doppelte Ausgaben zu verhindern. Um bestehende Pässe stattdessen zu aktualisieren, wählen SieduplicateStrategy: "UPSERT_BY_EXTERNAL_ID". -
2
Leere Zeilen oder nachgestellte Leerzeilen: Tabellenkalkulationsprogramme (Excel, Google Sheets) exportieren häufig nachgestellte Leerzeilen mit Kommas. Der CSV-Parser von Passinstance verwirft leere Zeilen automatisch, ohne den Zähler erstellter Pässe zu erhöhen.
-
3
Abgelehnte Zeilen bei der Vorab-Attributvalidierung: Zeilen mit ungültigen Datentypen (wie nicht-numerischer Text in einem Zahlenattribut, ungültige E-Mail-Syntax oder nicht parsbares Datumsformat) scheitern bei der einzelnen Zeilenprüfung und werden im Fehlerprotokoll dokumentiert, ohne den gesamten Job abzubrechen.
-
4
Kontingent für aktive Pässe ausgeschöpft (
PASS_LIMIT_REACHED): Erreicht Ihr Workspace während der Verarbeitung 100 % des im Abonnementplan enthaltenen Limits für aktive Pässe, schlagen nachfolgende Zeilen mitPASS_LIMIT_REACHEDfehl. Prüfen Sie unter Unternehmenseinstellungen -> Nutzung & Abrechnung Ihr verbleibendes Kontingent.
Ist eine Wartezeit von mehreren Stunden bei der Stapelverarbeitung normal?
-
Übliche Verarbeitungsgeschwindigkeiten: Die Worker-Queues der Hintergrund-Job-Queue in Passinstance erstellen typischerweise 500 bis 2.000 Pässe pro Minute, abhängig davon, ob kryptografische Apple-Wallet-
.pkpass-Signaturen und Barcode-Grafiken synchron erzeugt oder auf den Download-Zeitpunkt verschoben werden. Ein Stapel mit 10.000 Pässen ist in der Regel innerhalb von 5 bis 15 Minuten abgeschlossen. -
Wann mehrere Stunden normal sind:
- Sehr große Importvolumina: Extrem umfangreiche Importe (100.000 bis 500.000+ Pässe) dauern mehrere Stunden, damit Datenbank-Verbindungspools und In-Memory-Cache-Queues stabil bleiben, ohne Ihren Workspace auszubremsen. - Direkte Versandaktionen: Haben Sie eine E-Mail- oder SMS-Versandkampagne an den Stapeljob gekoppelt, werden ausgehende E-Mails entsprechend den Sendelimit-Kontingenten der verwalteten E-Mail-Zustellung (z. B. 14 bis 50 E-Mails/Sekunde) und den Verbindungsgrenzen eigener SMTP-Server gedrosselt, um die Reputation Ihrer Domain zu schützen.
-
Wann ein Job hängt oder Eingreifen erfordert:
- Verbleibt ein Job über Stunden im Status NEW oder READY_TO_RUN, wurde der Worker noch nicht gestartet. Klicken Sie im Dashboard auf Job starten oder rufen Sie POST /api/v1/batch-processing/:id/start auf. - Steht der Job im Status PAUSED, setzen Sie die Ausführung über POST /api/v1/batch-processing/:id/resume fort.
Kann ein Pass eine feste Anzahl von Tagen nach der Ausgabe ablaufen?
Ja. Passinstance unterstützt sowohl feste Kalender-Ablaufdaten als auch dynamische, fortlaufende Gültigkeitszeiträume:
-
1
Dynamische fortlaufende Laufzeit (
validityInDays): Stellen Sie im Visuellen Editor unter Gültigkeit & Ablauf die Ablaufstrategie auf Dynamische Laufzeit und legen Sie die Anzahl der Tage fest (z. B.30,90oder365). Bei jeder Pass-Erstellung über CSV-Import, API oder PassFlow-Formular berechnet Passinstance automatisch:
expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).
-
2
Zeilenweise Ablaufdatum-Überschreibung: Haben einzelne Kundinnen und Kunden individuelle Vertragsenddaten, ordnen Sie im Schritt Felder zuordnen eine CSV-Spalte mit ISO-8601-Zeitstempeln (z. B.
2027-06-30T23:59:59Z) direkt dem SystemfeldexpirationDatezu. -
3
Verlängerung nach der Ausgabe: Sie können Ablaufdaten für Tausende aktiver Pässe jederzeit über Massenoperationen verlängern oder anpassen.
Wie migriere ich bestehende Kundendaten von einem anderen Wallet-Anbieter oder CRM?
Die Migration von Altsystemen (wie Airship, PassKit, Braze oder einer internen Datenbank) zu Passinstance gelingt nahtlos:
-
1
Bestandsdaten exportieren: Exportieren Sie Ihre bestehende Kundendatenbank als UTF-8-CSV einschließlich Namen, Kontaktdaten, Punkteständen, Statusstufen und bisheriger Kartennummern.
-
2
Zielvorlage einrichten: Erstellen Sie in Passinstance eine entsprechende Vorlage. Konfigurieren Sie Ihre benutzerdefinierten Eigenschaften (z. B.
memberId,pointsBalance,tier) sowie die Barcode-Symbologie (QR, Aztec, Code 128 oder PDF417). -
3
Historische Kennungen auf
externalIdabbilden: Ordnen Sie Ihre bisherige Kartennummer oder Kunden-UUID dem SystemfeldexternalIdvon Passinstance zu. Das garantiert eine eindeutige 1:1-Kontinuität und verhindert Duplikate. -
4
CSV-Stapelimport ausführen: Laden Sie die CSV über den 5-Schritte-Assistenten hoch. Setzen Sie die Importstrategie auf
UPSERT_BY_EXTERNAL_ID, sodass bereits vorhandene Datensätze sauber aktualisiert werden. -
5
Nahtloser Übergang für Karteninhaber: Behält Ihre Organisation denselben Apple Pass Type Identifier und dasselbe Signaturzertifikat bei, erhalten Kundinnen und Kunden aktualisierte Pässe, ohne ihre bisherigen Wallet-Karten löschen zu müssen. Alternativ versenden Sie über das Delivery Center neue Smart-Download-Links mithilfe des Platzhalters
{passDownloadUrl}.
Wie bereinige ich Pässe nach dem Ende einer Veranstaltung?
Nach Abschluss eines Konzerts, Sportevents oder einer saisonalen Kampagne halten Sie Ihren Workspace aufgeräumt und geben aktives Kontingent frei:
-
1
Event-Kohorte eingrenzen: Filtern Sie im Dashboard unter Pässe (
/passes) nach der Veranstaltungsvorlage oder nutzen Sie den erweiterten Suchbereich mitexpirationDate < today. -
2
Alle passenden Pässe auswählen: Nutzen Sie das Kontrollkästchen der
StickySelectionToolbar, um die aktuelle Ansicht auszuwählen, und klicken Sie auf den Hinweis, um alle dem Filter entsprechenden Pässe über alle Seiten hinweg zu markieren. -
3
Massenentwertung / Deaktivierung ausführen: Klicken Sie auf Massenaktionen -> Deaktivieren / Entwerten (
POST /api/v1/batch-pass-operations/deactivate). Dadurch wird der Pass-Status aufVOIDEDgesetzt, ein Ungültig-Banner für den Barcode auf dem Sperrbildschirm angezeigt und die Scanner-Einlösung gesperrt — während historische Scan-Datensätze und Check-in-Teilnahmedaten für Compliance-Berichte erhalten bleiben. -
4
Soft-Delete (
DELETING->SOFT): Wenn Sie abgelaufene Event-Pässe aus der aktiven Dashboard-Ansicht entfernen möchten, wählen Sie Massenaktionen -> Löschen. Soft-gelöschte Pässe zählen nicht auf Ihr Abonnement-Limit aktiver Pässe, geben ihreexternalIdfür künftige Nutzungen frei und bleiben dennoch in historischen Audit-Exporten verfügbar.
Für direkte JSON-Array-Batch-Operationen ohne CSV-Dateien siehe Massenoperationen. Um neu importierte Pässe per E-Mail zu verteilen, lesen Sie E-Mail- & SMS-Zustellung.
