Overzicht
In het Passinstance Dashboard verschijnen meervoudige pas-Projecten (PassProject-model beheerd door Projects API op /api/v1/pass-projects en alias /api/v1/wallet-experiences) in de hub Wallet Experiences (/wallet-experiences, met de workspace-tabbladen Overview, Cards, Audience, Automations, Distribution, Analytics en Settings). Een project coördineert een primair mainTemplateId plus gekoppelde begeleidende sjablonen tot uniforme klantreizen, inclusief Apple Wallet-pasbundels (.pkpasses) (Pass.bundleId / pass bundle) en regelgebaseerde segmentautomatisering.
Systeemarchitectuur: pasprojecten, .pkpasses-bundeling & segmenttriggers
Kernmodellen & sjabloonrollen (PassProjectTemplateRole)
Elk PassProject koppelt een mainTemplateId (PRIMARY-rol op het project zelf) naast gekoppelde begeleidende sjablonen (PassProjectTemplate, schrijfrollen LINKED, PRIVACY_MODE, VIP, CUSTOM, INACTIVE):
PassProjectTemplateRole | Waar opgeslagen | Functionele verantwoordelijkheid binnen het project |
|---|---|---|
PRIMARY | PassProject.mainTemplateId | De anker-identiteitspas (bijv. Seizoenskaart, Hotelkamersleutel of Loyaliteitskaart) waarvan externalId en klanteigenschappen de ervaring aansturen. |
LINKED / VIP / CUSTOM | PassProjectTemplate.role | Begeleidende sjablonen (bijv. VIP Backstage-toegang, Drankvoucher, Parkeerkaart) die bij download worden gebundeld of dynamisch via segment-/automatiseringsregels worden uitgegeven. |
PRIVACY_MODE | PassProjectTemplate.role | Een alternatief uitgekleed sjabloon waarnaar automatisch wordt overgeschakeld wanneer een pashouder zich afmeldt voor tracking/personalisatie. |
INACTIVE | PassProjectTemplate.role | Gekoppeld sjabloon dat tijdelijk wordt onderdrukt bij nieuwe bundeldownloads zonder de geschiedenis te ontkoppelen. |
Apple Wallet-pasbundels (.pkpasses) & Pass.bundleId
Wanneer bundelen is ingeschakeld (bundleOnDownload: true, maxBundleSize tot 10), koppelt Passinstance uitgegeven begeleidende passen onder een gedeelde Pass.bundleId (bundleId FK naar pass bundle):
-
Apple Wallet (
.pkpasses-archief): Samengesteld doorPass Grouping Engine(libs/pass-bundle,/api/v1/bundles/*ofPOST /api/v1/pass-projects/:id/download-bundle). Verpakt maximaal 10 ondertekende.pkpass-bestanden (request payload: 2–10 passen;request payload: 1–10 passen) aangeboden alsapplication/vnd.apple.pkpasseszodat iOS Alles toevoegen ("Add All") toont. -
Google Wallet Multi-Pass Claim: Levert gecoördineerde bewaar-URL's en bundellinks (
GET /api/v1/bundles/:id/google-wallet-link,PassProjectIssuanceProvider:APPLE\|GOOGLE,PassProjectIssuanceStatus:PENDING->VALIDATING->CREATING_PASSES->READY\|PARTIALLY_READY\|FAILED).
Belangrijk: Apple iOS hanteert een bovengrens van 10
.pkpass-bestanden binnen één.pkpasses-archief (maxBundleSize <= 10). Elk sjabloon dat in een bundel is opgenomen moet zijn gepubliceerd met een geldig Apple Pass Type ID-certificaat.
Doelgroepsegmenten (PassProjectSegment) & automatiseringsstromen
Projecten integreren rechtstreeks met PassProjectSegment en AutomationFlow om dynamische reizen over meerdere passen te orkestreren zonder externe webhook-lijmcode:
-
1
Dynamische segmentevaluatie: Definieer filterregels over
Pass.attributes(bijv.attributes.spendTotal >= 500) en evalueer deze viaPOST /api/v1/pass-projects/:id/segments/:segmentId/evaluate. -
2
Geautomatiseerde uitgifte van begeleidende passen: Wanneer een primaire pas een segment binnenkomt, geeft een gekoppelde
AutomationFlowautomatisch een gekoppelde pas (LINKED/VIP) uit en deelt diens bijgewerkte bundel-/downloadlink. -
3
Overschakelen naar privacymodus: Als toestemming voor personalisatie is uitgeschakeld, kan de ervaring de pas van de houder migreren naar het
PRIVACY_MODE-sjabloon.
REST API-referentie voor pasprojecten (Projects API)
Alle projectendpoints zijn gekoppeld onder /api/v1/pass-projects (alias /api/v1/wallet-experiences):
| HTTP-methode & endpoint | Beschrijving |
|---|---|
GET /api/v1/pass-projects | Geeft een lijst van alle Wallet Experiences (Pasprojecten) in de actieve workspace. |
POST /api/v1/pass-projects | Maakt een nieuw PassProject aan met request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug). |
GET /api/v1/pass-projects/:id | Haalt projectconfiguratie, gekoppelde sjablonen, gereedheid en segmenten op. |
PATCH /api/v1/pass-projects/:id | Werkt projectnaam, beschrijving, mainTemplateId, bundleOnDownload, maxBundleSize of slug bij. |
POST /api/v1/pass-projects/:id/templates/:templateId | Koppelt een begeleidend sjabloon (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE). |
GET / PATCH /api/v1/pass-projects/:id/bundle | Configureert bundelvolgorde, limieten (maxBundleSize) en .pkpasses-metadata. |
POST /api/v1/pass-projects/:id/download-bundle | Downloadt of genereert het gecoördineerde .pkpasses-bundelarchief voor een pas of uitgifte. |
GET /api/v1/pass-projects/bundle-passes/:passId | Geeft een lijst van alle begeleidende passen die via bundleId met een specifiek passId zijn gegroepeerd. |
Voorbeeld: een multi-pasproject aanmaken (request payload)
POST /api/v1/pass-projects Headers: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Alpine Ski Resort - VIP Winter Package",
"description": "Season ski pass with aprés-ski voucher and privacy layout",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 5,
"slug": "alpine-vip-winter-2026"
}
HTTP-respons (201 Created)
{
"success": true,
"data": {
"id": "proj_01j9k8l7m6n5p4",
"name": "Alpine Ski Resort - VIP Winter Package",
"slug": "alpine-vip-winter-2026",
"mainTemplateId": "tmpl_ski_season_pass_01",
"bundleOnDownload": true,
"maxBundleSize": 5,
"createdAt": "2026-11-15T19:00:00.000Z"
},
"statusCode": 201
}
Bekijk Architectuur van pasbundeling voor technische verpakkingsstromen en Workflowconfiguratie voor projectoverstijgende automatiseringsregels.
