Skip to content
Helpcentrum-gids · Pass-uitgifteOnboardingfase 5
8 min leestijdGecontroleerd 2026-11-16

Passen in bulk aanmaken

Upload CSV-bestanden via Bulkacties of FTP/SFTP-import, koppel kolommen en volg de verwerkingsstatus.

In deze gids

Interactieve UI-weergaven

Openen in onboardinggids (6 fasen)

Bekijk de exacte dashboardpanelen, knoppen en ingezoomde toelichtingen bij deze gids.

Ingezoomde UI-focus
Belangrijke UI-onderdelen

Paneel voor batch-importtaken (Ingesneden)

Start een 'New import job' vanuit het sjabloonoverzicht en volg lopende, mislukte en voltooide CSV-batchverwerkingen.

Overzicht

Wanneer u honderden of honderdduizenden pashouders tegelijkertijd onboardt, biedt Passinstance een asynchrone, fouttolerante CSV-batchverwerkingspipeline op basis van de Batch Jobs API (/api/v1/batch-processing) en in-memory cache-ondersteunde wachtrijen voor achtergrondtaken. Beheerders kunnen UTF-8-spreadsheets uploaden via het Dashboard (Bulkoperaties -> Passen importeren), geautomatiseerde FTP/SFTP-imports activeren of de 6-staps CSV-pipeline programmatisch aansturen via de REST API.

Tellers voor batch-importtaken en knop voor nieuwe import
Tellers voor batch-importtaken en knop voor nieuwe import

Systeemarchitectuur: CSV-batchuitgifte & achtergrondwachtrij-pipeline

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
CSV-BATCHUITGIFTE & ASYNCHRONE WORKERPIPELINE
FASE 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
FASE 02 SCHEMAKOPPELING & PRE-FLIGHT PROEFVALIDATIE
4
PUT/api/v1/batch-processing/:id/field-mapping (Koppel CSV-koppenkeys)
5
POST/api/v1/batch-processing/:id/validate
Controleert verplichte eigenschappen, ISO-datums, getallen & externalIds
Rapporteert syntaxis- of schemafouten per rij vóór databasemutaties
FASE 03 ASYNCHRONE WORKERPIPELINE (in-memory cache)
Verwerkt gevalideerde CSV-blokken in begrensde transacties
Genereert Pass-records, serialNumber, authenticationToken & slimme links
Stelt downloadbaar resultaatrapport samen: GET.../batch-processing/:id/result.csv

Checklist met vereisten

Vereisten: Controleer de volgende voorwaarden voordat u een CSV-bulkimport start:

1. Het doelsjabloon (Template) moet de status PUBLISHED hebben.

2. Uw CSV-bestand moet zijn gecodeerd in UTF-8, zonder onjuiste scheidingstekens of niet-geëscapete aanhalingstekens.

3. Neem de kolommen email en/of phone op als u na het genereren automatisch pasdownloadlinks wilt versturen via campagnes in het Delivery Center.

4. Configureer uw External ID-bron in de sjablooninstellingen (externalId) als u idempotente ontdubbeling wilt bij herhaalde imports.

Stapsgewijze CSV-importworkflow (Bulk Pass Wizard)

In het Dashboard onder Batch -> Batchverwerking (/batch-processing) leidt de wizard beheerders door vijf stappen (Sjabloon -> CSV uploaden -> Velden koppelen -> Verzendopties (optioneel) -> Verwerken):

  1. 1
    Sjabloon: Kies het gewenste PUBLISHED- / PRODUCTION-sjabloon (of open Passen -> Importeren rechtstreeks vanuit een sjabloon).
  2. 2
    CSV uploaden: Sleep een UTF-8 CSV-bestand in het uploadveld of download de dynamische Voorbeeld-CSV (GET /api/v1/batch-processing/templates/:templateId/sample-csv), die vooraf is gevuld met kolomkoppen die aansluiten op de aangepaste eigenschappen en systeemvelden (externalId, expirationDate, enz.) van uw sjabloon.
  3. 3
    Velden koppelen: Controleer de automatische aanbevelingen met betrouwbaarheidsscores (POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations) die kolomkoppen (bijv. Customer_ID, First_Name) koppelen aan externalId of attributes.*-sleutels.
  4. 4
    Verzendopties (indien ingeschakeld): Kies een e-mail- of sms-bezorgsjabloon als nieuwe passen na voltooiing automatisch moeten worden verzonden.
  5. 5
    Verwerken: Valideer en start de achtergrondtaak (batchtaakstatussen: NEW, READY_TO_RUN, INTEGRATION_MAPPING_COMPLETE, SENDOUT_PENDING, RUNNING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELLED, PAUSED), en download vervolgens /result.csv met elk gegenereerd serialNumber, externalId, bundleId en elke downloadlink.

REST API-referentie voor batchverwerking (Batch Jobs API)

Alle endpoints voor CSV-batchtaken zijn ondergebracht onder /api/v1/batch-processing (met ondersteuning voor batchtaaktypen: CREATE_PASSES, UPDATE_PASSES, DELETE_PASSES, IMPORT_DATA, EXPORT_DATA, MIGRATION en batchgegevensbronnen: CSV_UPLOAD, API, SEGMENT, QUERY, MANUAL):

StapHTTP-methode & endpointDoel
1. Voorbeeld-CSVGET /api/v1/batch-processing/templates/:templateId/sample-csvDownloadt een dynamisch UTF-8 CSV-koppensjabloon afgestemd op de aangepaste eigenschappen van het sjabloon.
2. CSV uploadenPOST /api/v1/batch-processingUploadt een multipart CSV-bestand of JSON-batchtaakdefinitie (status: NEW / READY_TO_RUN).
3. Kolommen auto-koppelenPOST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendationsAnalyseert CSV-kolomkoppen en retourneert attribuutkoppelingsvoorstellen met betrouwbaarheidsscore.
4. Koppeling opslaanPUT /api/v1/batch-processing/:id/field-mappingSlaat het bevestigde woordenboek met CSV-kolom-naar-attribuutkoppelingen op bij de taak.
5. ProefvalidatiePOST /api/v1/batch-processing/:id/validateVoert een niet-destructieve validatieronde uit op CSV-rijen en retourneert waarschuwingen/fouten per rij.
6. Worker startenPOST /api/v1/batch-processing/:id/startPlaatst de achtergrondworker-taak in de wachtrij (status: RUNNING) om passen asynchroon uit te geven.
7. Resultaten exporterenGET /api/v1/batch-processing/:id/result.csvStreamt een CSV-rapport met toegevoegde passId, serialNumber, downloadlinks en rijstatus.

Voorbeeld: aanbevelingen voor veldkoppeling opvragen

POST /api/v1/batch-processing/templates/tmpl_01hxyz987654321/field-mapping-recommendations Headers: X-API-Key: <API_KEY> | Content-Type: application/json

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

HTTP-respons (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
}

Voorbeeld: veldkoppeling bevestigen & taak valideren

PUT /api/v1/batch-processing/job_batch_77123/field-mapping Headers: 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"
  }
}

Valideer en start vervolgens de achtergrondworker:

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
}

Probleemoplossing & veelgestelde vragen

Hoe controleer ik waarom een bulkverwerkingstaak mislukt?

Wanneer een asynchrone CSV-batchimport tegen een probleem aanloopt, inspecteert u de taakstatus en logboeken via het Dashboard of de REST API:

  1. 1
    Taakpaneel in het Dashboard: Ga naar Batch -> Batchverwerking (/batch-processing). Voltooide taken met fouten tonen de badge Voltooid met fouten (COMPLETED_WITH_ERRORS), terwijl afgebroken taken Mislukt (FAILED) tonen.
  2. 2
    Foutenlogboek downloaden: Klik op de taakkaart en kies Fouten-CSV downloaden of haal GET /api/v1/batch-processing/:id/result.csv op. Het resulterende spreadsheet bevat elke bronrij uit de CSV met een toegevoegde kolom status (SUCCESS, SKIPPED of FAILED) en een kolom errorMessage met de oorzaak (bijvoorbeeld: "Missing required custom property: firstName", "Invalid ISO 8601 date format" of "Duplicate externalId").
  3. 3
    Taakdetails inspecteren via de API: Roep GET /api/v1/batch-processing/:id aan met uw API-sleutel. De JSON-respons retourneert de request payload met totalRows, processedRows, successfulRows, failedRows en de array errorDetails[] met exacte rij-indices en validatiefoutcodes.
  4. 4
    Pre-flight validatiecontrole: Roep altijd POST /api/v1/batch-processing/:id/validate aan voordat u een taak met 100.000 rijen in de wachtrij plaatst. Deze proefstap controleert kolomkoppelingen en attribuutschema's zonder databaserecords aan te maken en meldt syntaxisfouten nog voordat workers starten.

Waarom heeft mijn bulkverwerking minder passen aangemaakt dan er rijen in het bestand stonden?

Als uw bron-CSV 5.000 rijen bevatte, maar de taak slechts 4.820 aangemaakte passen meldt, controleer dan de volgende geverifieerde platformgedragingen:

  1. 1
    Ontdubbeling op External ID (duplicateStrategy): Als uw sjabloon unieke externe ID's afdwingt en u duplicateStrategy op SKIP hebt gezet, worden rijen die een externalId delen met een bestaande actieve pas in uw werkruimte (of eerder in hetzelfde CSV-bestand voorkwamen) overgeslagen om dubbele uitgifte te voorkomen. Kies duplicateStrategy: "UPSERT_BY_EXTERNAL_ID" als u bestaande passen wilt overschrijven.
  2. 2
    Lege rijen of afsluitende witregels: Spreadsheetprogramma's (Excel, Google Sheets) exporteren vaak lege afsluitende rijen met alleen komma's. De CSV-parser van Passinstance slaat lege rijen automatisch over zonder de teller voor aangemaakte passen op te hogen.
  3. 3
    Afgewezen rijen bij pre-validatie: Rijen met ongeldige gegevenstypen (zoals niet-numerieke tekst in een numeriek attribuut, ongeldige e-mailsyntaxis of niet-parseerbare datumreeksen) falen tijdens de individuele rijvalidatie en worden vastgelegd in het foutenoverzicht zonder de volledige taak te onderbreken.
  4. 4
    Quotumbereik voor actieve passen (PASS_LIMIT_REACHED): Als uw werkruimte tijdens de verwerking 100% van de limiet voor actieve passen van uw abonnement bereikt, mislukken volgende rijen met PASS_LIMIT_REACHED. Controleer onder Bedrijfsinstellingen -> Verbruik & facturatie uw resterende quotum.

Is een wachttijd van enkele uren normaal bij bulkverwerking?

  • Standaard verwerkingssnelheden: Achtergrondworkers in Passinstance genereren doorgaans tussen 500 en 2.000 passen per minuut, afhankelijk van of dynamische cryptografische Apple Wallet .pkpass-handtekeningen en barcodeafbeeldingen synchroon worden gegenereerd of pas op het moment van downloaden. Een batch van 10.000 passen is doorgaans binnen 5 tot 15 minuten voltooid.
  • Wanneer enkele uren normaal zijn:

- Enorme importvolumes: Zeer grote imports (100.000 tot 500.000+ passen) duren enkele uren zodat database-verbindingspools en in-memory cachewachtrijen stabiel blijven zonder uw werkruimte te belasten. - Directe uitgaande verzendingen: Als u een e-mail- of sms-bezorgcampagne aan de batchtaak hebt gekoppeld, worden uitgaande e-mails begrensd volgens de verzendlimieten van beheerde e-mailbezorging (bijv. 14 tot 50 e-mails per seconde) en verbindingslimieten van eigen SMTP-servers om uw domeinreputatie te beschermen.

  • Wanneer een taak stilstaat of actie vereist:

- Als een taak urenlang op NEW of READY_TO_RUN blijft staan, is de worker nooit gestart. Klik op Taak starten in het Dashboard of roep POST /api/v1/batch-processing/:id/start aan. - Als de taakstatus PAUSED is, hervat u de uitvoering via POST /api/v1/batch-processing/:id/resume.

Kan een pas een vast aantal dagen na uitgifte verlopen?

Ja. Passinstance ondersteunt zowel vaste kalenderdatums als dynamische doorlopende geldigheidsperioden:

  1. 1
    Dynamische geldigheidsduur (validityInDays): Stel in de Visuele editor onder Geldigheid & vervaldatum de vervalstrategie in op Dynamische duur en geef het aantal dagen op (bijv. 30, 90 of 365). Wanneer een pas wordt aangemaakt via CSV-import, API of PassFlow-formulier, berekent Passinstance automatisch:

expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).

  1. 2
    Afwijkende vervaldatum per rij: Als individuele klanten unieke einddatums voor hun contract hebben, koppelt u tijdens de stap Velden koppelen een CSV-kolom met ISO 8601-tijdstempels (bijv. 2027-06-30T23:59:59Z) rechtstreeks aan het systeemveld expirationDate.
  2. 3
    Verlenging na uitgifte: U kunt vervaldatums op duizenden actieve passen op elk moment verlengen of aanpassen via Bulkoperaties.

Hoe migreer ik bestaande klantgegevens vanaf een andere wallet-provider of CRM?

Overstappen vanaf oudere systemen (zoals Airship, PassKit, Braze of een interne database) naar Passinstance verloopt soepel:

  1. 1
    Exporteer bestaande gegevens: Exporteer uw bestaande klantendatabase naar een UTF-8 CSV-bestand met namen van leden, contactgegevens, puntensaldi, niveaustatus en historische kaartnummers.
  2. 2
    Richt het doelsjabloon in: Bouw in Passinstance een overeenkomstig sjabloon. Configureer uw aangepaste eigenschappen (bijv. memberId, pointsBalance, tier) en barcodesymbologie (QR, Aztec, Code 128 of PDF417).
  3. 3
    Koppel historische identificatoren aan externalId: Koppel uw oude kaartnummer of klant-UUID aan het systeemveld externalId van Passinstance. Dit garandeert 1-op-1-continuïteit en voorkomt dubbele records.
  4. 4
    Voer de CSV-batchimport uit: Upload de CSV via de 5-stappenwizard. Stel de importstrategie in op UPSERT_BY_EXTERNAL_ID zodat reeds bestaande records netjes worden bijgewerkt.
  5. 5
    Naadloze overgang voor pashouders: Als uw organisatie dezelfde Apple Pass Type Identifier en hetzelfde ondertekeningscertificaat behoudt, ontvangen klanten bijgewerkte passen zonder hun bestaande wallet-passen te hoeven verwijderen. U kunt ook nieuwe slimme downloadlinks versturen via het Delivery Center met de placeholder {passDownloadUrl}.

Hoe ruim ik passen op na afloop van een evenement?

Houd na een concert, sportwedstrijd of seizoenscampagne uw werkruimte overzichtelijk en maak actief quotum vrij:

  1. 1
    Zoek het evenementcohort: Filter in het Dashboard onder Passen (/passes) op het evenementsjabloon of gebruik het Geavanceerde zoekpaneel om te filteren op expirationDate < today.
  2. 2
    Selecteer alle overeenkomende passen: Gebruik het selectievakje van de StickySelectionToolbar om de huidige weergave te selecteren en klik vervolgens op de melding om alle passen te selecteren die over alle pagina's aan het filter voldoen.
  3. 3
    Voer bulk-ongeldigmaking / deactivering uit: Klik op Bulkacties -> Deactiveren / Ongeldig verklaren (POST /api/v1/batch-pass-operations/deactivate). Hiermee krijgt de pas de status VOIDED, verschijnt er een melding van ongeldigheid op het toegangsscherm en wordt inwisseling door scanners geblokkeerd, terwijl historische scanlogs en aanwezigheidsgegevens bewaard blijven voor compliancerapportage.
  4. 4
    Zacht verwijderen (DELETING -> SOFT): Wilt u verlopen evenementpassen uit uw actieve dashboardoverzicht verwijderen, kies dan Bulkacties -> Verwijderen. Zacht verwijderde passen tellen niet mee voor de limiet voor actieve passen van uw abonnement en geven hun externalId weer vrij voor toekomstig gebruik, terwijl ze beschikbaar blijven in historische auditexports.

Zie voor directe JSON-array-batchoperaties zonder CSV-bestanden Bulkoperaties. Zie voor het verzenden van nieuw geïmporteerde passen per e-mail E-mail- en sms-bezorging.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.