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

Massen-Pass-Erstellung

Laden Sie CSV-Dateien über Stapelaktionen oder FTP/SFTP-Import hoch, ordnen Sie Spalten zu und verfolgen Sie den Jobstatus.

In dieser Anleitung

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

Vergrößerter UI-Fokus
Wichtige UI-Elemente

Panel für Batch-Importaufträge (Zoom)

Starten Sie über die Vorlagen-Übersicht einen „New import job“ und überwachen Sie laufende, fehlgeschlagene und abgeschlossene CSV-Stapelimporte.

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

Zähler für Stapelimport-Jobs und Schaltfläche für neuen Import
Zähler für Stapelimport-Jobs und Schaltfläche für neuen Import

Systemarchitektur: CSV-Stapelausgabe & Hintergrund-Job-Queue-Worker-Pipeline

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
CSV-STAPELAUSGABE & ASYNCHRONE WORKER-PIPELINE
STUFE 01 DASHBOARD-CSV-UPLOAD / API (Batch Jobs API)
1
GET/api/v1/batch-processing/templates/:templateId/sample-csv
2
POST/api/v1/batch-processing (Multipart-UTF-8-CSV-Upload)
3
POST/api/v1/batch-processing/templates/:templateId/field-mapping-recommendations
STUFE 02 SCHEMA-ZUORDNUNG & VORAB-TROCKENLAUF-VALIDIERUNG
4
PUT/api/v1/batch-processing/:id/field-mapping (CSV-HeaderSchlüssel)
5
POST/api/v1/batch-processing/:id/validate
Prüft erforderliche benutzerdefinierte Eigenschaften, ISO-Daten, numerische Typen & externalIds
Meldet zeilenweise Syntax- oder Schemafehler vor Datenbankänderungen
STUFE 03 ASYNCHRONE WORKER-PIPELINE (In-Memory-Cache)
Streamt validierte CSV-Chunks in begrenzten Transaktionen
Erstellt Pass-Datensätze, serialNumber, authenticationToken & Smart-Links
Erstellt herunterladbares Protokoll: GET/api/v1/batch-processing/:id/result.csv

Checkliste der Voraussetzungen

Voraussetzungen: Prüfen Sie vor dem Start eines CSV-Stapelimport-Jobs die folgenden Anforderungen:

1. Die Ziel-Template-Vorlage muss den Status PUBLISHED haben.

2. Ihre CSV-Datei muss in UTF-8 kodiert sein — ohne fehlerhafte Trennzeichen oder nicht maskierte Anführungszeichen.

3. Fügen Sie email- und/oder 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. 1
    Vorlage: Wählen Sie die gewünschte PUBLISHED- / PRODUCTION-Vorlage (oder öffnen Sie Pässe -> Importieren direkt aus einer Vorlage heraus).
  2. 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, expirationDate usw.) passenden Spaltenüberschriften vorbelegt ist.
  3. 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) mit externalId oder attributes.*-Schlüsseln verknüpfen.
  4. 4
    Versandoptionen (sofern aktiviert): Wählen Sie eine E-Mail-/SMS-Versandvorlage, wenn neu erstellte Pässe nach Abschluss automatisch versendet werden sollen.
  5. 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.csv mit jeder generierten serialNumber, externalId, bundleId sowie 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):

SchrittHTTP-Methode & EndpunktZweck
1. Beispiel-CSVGET /api/v1/batch-processing/templates/:templateId/sample-csvLädt eine dynamische UTF-8-CSV-Kopfzeilenvorlage passend zu den benutzerdefinierten Eigenschaften der Vorlage herunter.
2. CSV hochladenPOST /api/v1/batch-processingLädt eine Multipart-CSV-Datei oder eine JSON-Batch-Job-Definition hoch (status: NEW / READY_TO_RUN).
3. Spalten automatisch zuordnenPOST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendationsAnalysiert CSV-Spaltenüberschriften und liefert mit Konfidenzwerten bewertete Attribut-Zuordnungsvorschläge zurück.
4. Zuordnung speichernPUT /api/v1/batch-processing/:id/field-mappingSpeichert das bestätigte Wörterbuch zur Zuordnung von CSV-Spalten zu Attributen am Job.
5. Trockenlauf-ValidierungPOST /api/v1/batch-processing/:id/validateFührt eine nicht-destruktive Validierung über die CSV-Zeilen aus und gibt zeilenbezogene Warnungen/Fehler zurück.
6. Worker startenPOST /api/v1/batch-processing/:id/startReiht den Hintergrund-Worker-Job (status: RUNNING) in die Hintergrund-Job-Queue ein, um Pässe asynchron auszugeben.
7. Ergebnisse exportierenGET /api/v1/batch-processing/:id/result.csvStreamt 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

JSON
{
  "csvHeaders": [
    "Customer_ID",
    "First_Name",
    "Last_Name",
    "Loyalty_Points",
    "Card_Expiry"
  ]
}

HTTP-Antwort (200 OK)

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

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

JSON
{
  "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. 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. 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.csv ab. Die ausgegebene Tabelle enthält jede Quell-CSV-Zeile ergänzt um eine Spalte status (SUCCESS, SKIPPED oder FAILED) sowie eine Spalte errorMessage, die den Fehler erläutert (z. B. „Missing required custom property: firstName“, „Invalid ISO 8601 date format“ oder „Duplicate externalId“).
  3. 3
    Job-Details per API prüfen: Rufen Sie GET /api/v1/batch-processing/:id mit Ihrem API-Schlüssel auf. Die JSON-Antwort liefert den request payload einschließlich totalRows, processedRows, successfulRows, failedRows sowie des Arrays errorDetails[] mit genauen Zeilenindizes und Validierungsfehlercodes.
  4. 4
    Vorab-Validierung durchführen: Rufen Sie vor dem Einreihen eines Jobs mit 100.000 Zeilen stets POST /api/v1/batch-processing/:id/validate auf. 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. 1
    External-ID-Deduplizierung (duplicateStrategy): Erzwingt Ihre Vorlage eindeutige External IDs und ist duplicateStrategy auf SKIP gesetzt, werden Zeilen übersprungen, deren externalId bereits 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 Sie duplicateStrategy: "UPSERT_BY_EXTERNAL_ID".
  2. 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. 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. 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 mit PASS_LIMIT_REACHED fehl. 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. 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, 90 oder 365). Bei jeder Pass-Erstellung über CSV-Import, API oder PassFlow-Formular berechnet Passinstance automatisch:

expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).

  1. 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 Systemfeld expirationDate zu.
  2. 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. 1
    Bestandsdaten exportieren: Exportieren Sie Ihre bestehende Kundendatenbank als UTF-8-CSV einschließlich Namen, Kontaktdaten, Punkteständen, Statusstufen und bisheriger Kartennummern.
  2. 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. 3
    Historische Kennungen auf externalId abbilden: Ordnen Sie Ihre bisherige Kartennummer oder Kunden-UUID dem Systemfeld externalId von Passinstance zu. Das garantiert eine eindeutige 1:1-Kontinuität und verhindert Duplikate.
  4. 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. 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. 1
    Event-Kohorte eingrenzen: Filtern Sie im Dashboard unter Pässe (/passes) nach der Veranstaltungsvorlage oder nutzen Sie den erweiterten Suchbereich mit expirationDate < today.
  2. 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. 3
    Massenentwertung / Deaktivierung ausführen: Klicken Sie auf Massenaktionen -> Deaktivieren / Entwerten (POST /api/v1/batch-pass-operations/deactivate). Dadurch wird der Pass-Status auf VOIDED gesetzt, 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. 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 ihre externalId fü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.

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.