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

Bulkoperaties

Voer groepsacties uit op gefilterde selecties: veldupdates in bulk, intrekken, verwijderen en exporteren.

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

Tabblad Passes & Bulkacties (Ingezoomd)

Gebruik na bulkimport het tabblad Passes, de filters en 'Bulk actions' om aangemaakte kaarten te controleren of bij te werken.

Overzicht

Zodra u in het Dashboard een doelcohort van passen hebt afgebakend met Snelfilters of het Geavanceerde EN/OF-filterpaneel (StickySelectionToolbar), gebruikt u het menu Bulkacties in de werkbalk van Passen — of roept u de Batch Operations API (/api/v1/batch-pass-operations/*) aan via de REST API — om gestructureerde array-operaties uit te voeren op maximaal 1.000 passen per aanroep. In tegenstelling tot multipart CSV-uploads (/api/v1/batch-processing) verwerkt /api/v1/batch-pass-operations/* JSON-payloads rechtstreeks en worden per item errors en warnings geretourneerd in de request payload.

Wanneer u duizenden of tienduizenden uitgegeven passen tegelijkertijd bijwerkt, ontkoppelt Passinstance databasemutaties van de pushbezorging naar mobiele wallets. Wijzigingen worden onmiddellijk in de database vastgelegd, terwijl updates naar Apple Wallet-apparaten worden verspreid via snelheidsbegrensde, gepoolde HTTP/2 APNs-verbindingen en naar Google Wallet-apparaten via directe Issuer Class-propagatie of afzonderlijke REST-patches op Pass Objects.

Systeemarchitectuur: bulkoperaties, wachtrijbegrenzing & wallet-propagatie

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
BULKOPERATIES VOOR PASSEN & WALLET-PROPAGATIE
FASE 01 DASHBOARD BULKWERKBALK / API (Batch Operations API)
Cohortselectie (StickySelectionToolbar / Filterpaneel / Pass-ID's)
POST/api/v1/batch-pass-operations/update (operation: "update")
POST/api/v1/batch-pass-operations/upsert (Op basis van 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 (Pre-flight payloadcontrole)
FASE 02 GEÏSOLEERDE VALIDATIE- & UITVOERINGSENGINE PER ITEM
Verwijdert tenantbeschermde sleutels (customerId, tenantId, createdBy)
Valideert attributen vooraf via preValidateAttributes (slaat verplicht over)
Normaliseert attributen via normalizeAttributes
Retourneert request payload: { success, data, message, errors, warnings }
FASE 03A APNs HTTP/2 BEGRENSDE WORKERWACHTRIJ
Achtergrondwachtrij: push-notifications
Persistente HTTP/2-verbindingspool
Snelheidsbegrenzing voorkomt 429-fout
Stille push wekt apparaat voor update
FASE 03B GOOGLE WALLET CLASS-PROPAGATIE
Sjabloonwijziging: PATCH Issuer
Class
Directe sync naar ALLE Android- passen
Individuele Pass Object PATCH voor passpecifieke dynamische attributen

Doelcohorten van passen filteren

Voordat u bulkoperaties uitvoert, selecteren beheerders het exacte publiekscohort dat moet worden aangepast:

Snelfilters & geavanceerd EN/OF-filterpaneel

In het Dashboard onder Passen (/passes):

  • Sjabloonfilter: Beperk acties tot een specifiek passjabloon of campagneontwerp.
  • Statusfilter: Filter op levenscyclusstatus (ACTIVE, INACTIVE, SUSPENDED, EXPIRED, VOIDED).
  • Installatiestatusfilter: Maak onderscheid tussen active_only (geïnstalleerd op ten minste één apparaat), inactive_only (verwijderd) en not_registered (niet-geclaimde downloadlinks).
  • Geavanceerd zoekpaneel (Advanced Filter panel): Combineer meerdere attributen met EN/OF-logica (bijv. tier == "Gold" EN pointsBalance < 500 EN expirationDate < 2027-01-01).
  • Vaste selectiewerkbalk (StickySelectionToolbar):

- Klik op het hoofdselectievakje om de huidige pagina te selecteren (tot 100 passen). - Klik op de meldingsbanner om alle overeenkomende passen over alle pagina's te selecteren (bijv. "Alle 4.850 passen selecteren die aan dit filter voldoen").

Cohortselectie via de API

Haal via de REST API de doel-UUID's van passen op met POST /api/v1/passes/query-builder of POST /api/v1/passes/search en geef de gevonden ID's vervolgens door aan /batch-pass-operations/*.


Duizenden uitgegeven passen tegelijk bijwerken

Het bijwerken van grote aantallen uitgegeven passen vereist een balans tussen schrijfsnelheid in de database en de strikte verbindingslimieten van pushnotificatiegateways voor mobiele wallets.

Directe array-operaties versus CSV-batchverwerking

Passinstance biedt twee afzonderlijke routes voor bulkupdates, afhankelijk van het volume:

  1. 1
    Directe JSON-array-operaties (POST /api/v1/batch-pass-operations/update):

- Ideaal voor maximaal 1.000 passen per HTTP-verzoek. - Accepteert een array van passIds en één enkel updateData-object. - Synchrone HTTP-respons met individuele status, fouten en waarschuwingen voor elke pas.

  1. 2
    Asynchrone CSV-batchpipeline (/api/v1/batch-processing):

- Ideaal voor 1.000 tot 100.000+ passen. - Upload een CSV met unieke identificatoren (externalId of serialNumber) en gewijzigde attributen. - Stel de bewerking in op UPDATE_PASSES of UPSERT. - Workers voor de achtergrondwachtrij verwerken rijen asynchroon in begrensde databasetransacties van 50 rijen, met live voortgangsbewaking en downloadbare resultaatrapporten (result.csv).

Apple Wallet APNs HTTP/2-begrenzing & verbindingspooling

Wanneer Apple Wallet-passen worden bijgewerkt, verstuurt Passinstance pushmeldingen die iOS-apparaten stil wakker maken om de bijgewerkte .pkpass-bundel op te halen bij de Passinstance API:

  • Stille pushmeldingen: Pasmeldingen worden verzonden met content-available: 1. Ze tonen geen opdringerige pop-ups op het toegangsscherm, tenzij gelokaliseerde veld-wijzigingsberichten (bijv. "Uw gate is gewijzigd naar B12") zijn geconfigureerd.
  • Persistente HTTP/2-streams: De @passinstance/apns-service onderhoudt gepoolde, persistente HTTP/2-verbindingen met Apple's pushservers (api.push.apple.com:443). In plaats van voor elke ontvanger opnieuw TLS-handshakes op te zetten en af te breken, worden streams gemultiplext over actieve verbindingen.
  • Adaptieve snelheidsbegrenzing & wachtrijregulering:

- Uitgaande meldingen lopen via achtergrondwachtrijen (push-notifications, individual-push-notifications, silent-push-notifications). - Notification Rate Limiter en Notification Deduplication bewaken de antwoordstream van Apple. - Als APNs 429 TooManyRequests of tegendruk op verbindingsniveau teruggeeft, schroeven workers de gelijktijdigheid terug en passen ze exponentiële back-off toe, wat ongeldige tokens en IP-blokkades voorkomt.

Google Wallet Class-updates versus Object PATCH

Google Wallet maakt gebruik van een hiërarchische architectuur die de Pass Class (de hoofdsjabloondefinitie) scheidt van het Pass Object (de individuele kaartinstantie van een pashouder):

  • Visuele & veldupdates op sjabloonniveau (Issuer Class):

Wanneer een globale wijziging op een sjabloon wordt gepubliceerd (zoals een nieuw koptekstlogo, andere achtergrondkleur of gewijzigde programmavoorwaarden) en gericht is op alle kaarten zonder gepersonaliseerde tekst (!hasPersonalizedMessage), roept Passinstance Google Wallet class sync aan in template.service.ts. Dit verzendt één enkele REST PATCH naar de Google Wallet API om de Issuer Class bij te werken. Omdat elke uitgegeven Google Wallet-pas naar deze bovenliggende Class verwijst, propageren de cloudservers van Google de update onmiddellijk naar alle actieve Android-passen tegelijk, zonder duizenden afzonderlijke API-aanroepen te genereren.

  • Pashouderspecifieke attribuutupdates (Pass Object):

Wanneer individuele attributen per pas verschillen (zoals persoonlijke puntensaldi, niveau-upgrades of aangepaste namen), voert Passinstance afzonderlijke HTTP PATCH-aanroepen uit op het specifieke Google Wallet Pass Object (POST /batch-pass-operations/update).

Attribuutvalidatie & veiligheidsregels

De batchupdateservice (batch-pass-operations.service.ts) handhaaft strikte gegevensintegriteit:

  • Tenantisolatie: Beschermde velden (customerId, tenantId, createdBy, templateId) worden automatisch verwijderd uit inkomende payloads. Updates kunnen nooit het eigendom van een pas wijzigen of bovenliggende sjablonen opnieuw toewijzen.
  • Gedeeltelijke attribuutvalidatie (preValidateAttributes): Bij het bijwerken van bestaande passen (isUpdate = true) worden controles op verplichte attributen overgeslagen. U kunt één enkele aangepaste eigenschap (bijv. pointsBalance) bijwerken zonder bestaande ongewijzigde velden opnieuw mee te sturen.
  • Attribuutnormalisatie: Tekstreeksen worden bijgesneden, getallen worden omgezet naar float/int en datums worden genormaliseerd naar ISO-8601 UTC.

Ondersteunde bulkoperaties in Dashboard & API

OperatieAPI-endpointDTO & gedrag
Batch CreatePOST /api/v1/batch-pass-operations/createrequest payload (passes[], max. 1.000 items). Geeft nieuwe passen uit met optionele externalId en bundleId.
Batch UpdatePOST /api/v1/batch-pass-operations/updaterequest payload (operation: "update", passIds[], updateData, optioneel bundleOptions).
Batch UpsertPOST /api/v1/batch-pass-operations/upsertrequest payload (operation: "upsert", passData[]) op basis van tenant (customerId, externalId).
Batch ActivatePOST /api/v1/batch-pass-operations/activaterequest payload (operation: "activate", passIds[]) zet passen op status ACTIVE.
Batch Deactivate (Void)POST /api/v1/batch-pass-operations/deactivaterequest payload (operation: "deactivate", passIds[]) zet passen op SUSPENDED / INACTIVE en maakt barcodes ongeldig.
Batch DeletePOST /api/v1/batch-pass-operations/deleterequest payload (passIds[]) laat passen overgaan via DELETING -> zacht verwijderd (archivedAt: new Date()).
Batch BundlePOST /api/v1/bundles/batch-createGroepeert geselecteerde pas-ID's in gedeelde pass bundle-containers (Pass.bundleId, tot 10 passen per bundel).

Belangrijk: Controleer altijd errors en warnings in de request payload. Wanneer validateBatchOperation ongeldige rijen detecteert, retourneert de controller success: false met gedetailleerde foutdiagnoses op itemniveau in errors[].


Programmatische referentie voor batch-pasoperaties (request payload)

1. Passen in batch upserten (POST /api/v1/batch-pass-operations/upsert)

Ideaal voor CRM-synchronisaties of herberekeningen van loyaliteitsniveaus op basis van externalId:

HTTP-verzoek

POST /api/v1/batch-pass-operations/upsert Headers: 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-respons (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. Passen in batch bijwerken (POST /api/v1/batch-pass-operations/update)

Werkt geselecteerde passIds bij met gedeelde updateData en optionele bundleOptions:

POST /api/v1/batch-pass-operations/update Headers: 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-respons (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. Passen in batch activeren, deactiveren of verwijderen

  • Activeren: POST /api/v1/batch-pass-operations/activate ({ "operation": "activate", "passIds": [...] })
  • Deactiveren: POST /api/v1/batch-pass-operations/deactivate ({ "operation": "deactivate", "passIds": [...] })
  • Verwijderen: POST /api/v1/batch-pass-operations/delete ({ "passIds": [...] } via request payload)

Wanneer u bulkoperaties laat opvolgen door geautomatiseerde e-mail- of sms-meldingen, biedt Passinstance een flexibele engine voor placeholder-substitutie (pass-url-placeholder.util.ts). Het canonieke placeholder-token is {passDownloadUrl}.

Canonieke placeholder & ondersteunde aliassen

De officiële, canonieke placeholder is {passDownloadUrl}. Passinstance ondersteunt daarnaast achterwaarts compatibele aliassen:

Placeholder-tokenCanoniek / aliasVoorbeeld van opgeloste uitvoer
{passDownloadUrl}Canoniekhttps://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}Dynamische aliasContextbewuste link die doorverwijst op basis van het besturingssysteem van de klant

Flexibele opmaak: Passinstance normaliseert dubbele accolades {{passDownloadUrl}}, snake_case {pass_download_url} en PascalCase {PassDownloadUrl} automatisch naar het canonieke token.

Directe wallet-actieknoppen & voorwaardelijke vlaggen

Voor responsieve HTML-e-mailsjablonen kunt u directe wallet-knoppen met één tik samenstellen in plaats van uitsluitend op de tussenliggende PassFlow-pagina te vertrouwen:

VariabeleBeschrijving
{appleWalletUrl}Directe binaire .pkpass-downloadstream die native Apple Wallet-installatie start in iOS Safari.
{googleWalletUrl}Directe Google Wallet Add-to-Wallet-deeplink (https://pay.google.com/gp/v/save/...).
{samsungWalletUrl}Directe Samsung Wallet-opslaandeeplink.
{walletButtonText}Contextbewust knoplabel ("Add to Apple Wallet", "Save to Google Wallet" of "Download my pass").
{showAppleWalletButton}Booleaanse vlag (true/false) die aangeeft of Apple Wallet-assets zijn geconfigureerd.
{showGoogleWalletButton}Booleaanse vlag die aangeeft of de Google Wallet-integratie actief is.

Gedeeltelijke fouten, foutafhandeling & auditlogging

Wanneer u batchoperaties aanroept, mislukken verzoeken niet in hun geheel als een deelverzameling van de items fouten bevat:

  1. 1
    Foutisolatie per item: In updateBatchPasses wordt elke pas in een geïsoleerd try-catch-blok verwerkt. Een fout op rij 42 (bijv. ongeldige datumnotatie) verhindert niet dat rijen 1–41 of 43–100 slagen.
  2. 2
    Standaard foutstructuur: Mislukte items worden gerapporteerd in errors[] met passId, foutbericht (error) en errorCode:
JSON
{
     "passId": "pass_01j8k9m2n3p4q5r6",
     "error": "Attribute 'pointsBalance' must be a valid number",
     "errorCode": "ATTR_VALIDATION"
   }
  1. 3
    Auditlogging van de werkruimte: Elke bulkoperatie genereert een vermelding in pass audit log en het auditlogboek van de werkruimte (GET /api/v1/audit-log/export.csv), waarin de actor-ID, het IP-adres, het bewerkingstype, het aantal betrokken passen en het tijdstempel worden vastgelegd.

Zie voor CSV-gebaseerde batchimports Passen in bulk aanmaken. Zie voor het massaal ongeldig verklaren van een volledig sjabloon Paslevenscyclus & statussen.

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.