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
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) ennot_registered(niet-geclaimde downloadlinks). -
Geavanceerd zoekpaneel (
Advanced Filter panel): Combineer meerdere attributen met EN/OF-logica (bijv.tier == "Gold"ENpointsBalance < 500ENexpirationDate < 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
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.
-
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
| Operatie | API-endpoint | DTO & gedrag |
|---|---|---|
| Batch Create | POST /api/v1/batch-pass-operations/create | request payload (passes[], max. 1.000 items). Geeft nieuwe passen uit met optionele externalId en bundleId. |
| Batch Update | POST /api/v1/batch-pass-operations/update | request payload (operation: "update", passIds[], updateData, optioneel bundleOptions). |
| Batch Upsert | POST /api/v1/batch-pass-operations/upsert | request payload (operation: "upsert", passData[]) op basis van tenant (customerId, externalId). |
| Batch Activate | POST /api/v1/batch-pass-operations/activate | request payload (operation: "activate", passIds[]) zet passen op status ACTIVE. |
| Batch Deactivate (Void) | POST /api/v1/batch-pass-operations/deactivate | request payload (operation: "deactivate", passIds[]) zet passen op SUSPENDED / INACTIVE en maakt barcodes ongeldig. |
| Batch Delete | POST /api/v1/batch-pass-operations/delete | request payload (passIds[]) laat passen overgaan via DELETING -> zacht verwijderd (archivedAt: new Date()). |
| Batch Bundle | POST /api/v1/bundles/batch-create | Groepeert geselecteerde pas-ID's in gedeelde pass bundle-containers (Pass.bundleId, tot 10 passen per bundel). |
Belangrijk: Controleer altijd
errorsenwarningsin derequest payload. WanneervalidateBatchOperationongeldige rijen detecteert, retourneert de controllersuccess: falsemet gedetailleerde foutdiagnoses op itemniveau inerrors[].
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
{
"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)
{
"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
{
"operation": "update",
"passIds": [
"pass_01j8k9m2n3p4q5r6",
"pass_01j8k9m9z8y7x6w5"
],
"updateData": {
"expirationDate": "2028-03-31T23:59:59Z",
"attributes": {
"seasonalOffer": "2x Winter Bonus Points"
}
}
}
HTTP-respons (200 OK)
{
"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": [...] }viarequest payload)
Bezorgingsintegratie: welke placeholder voegt de paslink in? ({passDownloadUrl})
Welke placeholder voegt de paslink in?
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-token | Canoniek / alias | Voorbeeld van opgeloste uitvoer |
|---|---|---|
{passDownloadUrl} | Canoniek | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{smartLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{downloadUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{walletDownloadUrl} | Dynamische alias | Contextbewuste 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:
| Variabele | Beschrijving |
|---|---|
{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
Foutisolatie per item: In
updateBatchPasseswordt 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
Standaard foutstructuur: Mislukte items worden gerapporteerd in
errors[]metpassId, foutbericht (error) enerrorCode:
{
"passId": "pass_01j8k9m2n3p4q5r6",
"error": "Attribute 'pointsBalance' must be a valid number",
"errorCode": "ATTR_VALIDATION"
}
-
3
Auditlogging van de werkruimte: Elke bulkoperatie genereert een vermelding in
pass audit logen 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.
