Skip to content
Helpcentrum-gids · Projecten & ordening
3 min leestijdGecontroleerd 2026-11-16

Projecten beheren

Bundel een hoofdsjabloon met gekoppelde sjablonen tot Wallet Experiences, bundels en segmentwissels.

In deze gids

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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
PASPROJECTBUNDELING (.PKPASSES) & SEGMENTAUTOMATISERING
FASE 01 PASPROJECT (PassProject & PassProjectTemplate)
PRIMARY (mainTemplateId): Ankerpas (lidmaatschap / ticket / instapkaart)
LINKED / VIP / CUSTOM: Begeleidende loungevoucher / parkeer- / galapas
PRIVACY_MODE / INACTIVE: Beperkte privacylay-out of gepauzeerde pas
FASE 02A APPLE-PASBUNDEL (.pkpasses ZIP)
Bundelt max. 10 ondertekende .pkpass bestanden met gedeeld Pass.bundleId
bundle grouping mode: AUTO | `MANUA
BundleStatus: ACTIVE | CANCELLED
FASE 02B SEGMENT- & AUTOMATISERINGSORKESTRATOR
Toetst PassProjectSegment-regels aan Pass.attributes (GIN) | | - TriggertAutomationFlow`-a gekoppelde pas / sjabloon wisselen

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):

PassProjectTemplateRoleWaar opgeslagenFunctionele verantwoordelijkheid binnen het project
PRIMARYPassProject.mainTemplateIdDe anker-identiteitspas (bijv. Seizoenskaart, Hotelkamersleutel of Loyaliteitskaart) waarvan externalId en klanteigenschappen de ervaring aansturen.
LINKED / VIP / CUSTOMPassProjectTemplate.roleBegeleidende sjablonen (bijv. VIP Backstage-toegang, Drankvoucher, Parkeerkaart) die bij download worden gebundeld of dynamisch via segment-/automatiseringsregels worden uitgegeven.
PRIVACY_MODEPassProjectTemplate.roleEen alternatief uitgekleed sjabloon waarnaar automatisch wordt overgeschakeld wanneer een pashouder zich afmeldt voor tracking/personalisatie.
INACTIVEPassProjectTemplate.roleGekoppeld 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 door Pass Grouping Engine (libs/pass-bundle, /api/v1/bundles/* of POST /api/v1/pass-projects/:id/download-bundle). Verpakt maximaal 10 ondertekende .pkpass-bestanden (request payload: 2–10 passen; request payload: 1–10 passen) aangeboden als application/vnd.apple.pkpasses zodat 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. 1
    Dynamische segmentevaluatie: Definieer filterregels over Pass.attributes (bijv. attributes.spendTotal >= 500) en evalueer deze via POST /api/v1/pass-projects/:id/segments/:segmentId/evaluate.
  2. 2
    Geautomatiseerde uitgifte van begeleidende passen: Wanneer een primaire pas een segment binnenkomt, geeft een gekoppelde AutomationFlow automatisch een gekoppelde pas (LINKED / VIP) uit en deelt diens bijgewerkte bundel-/downloadlink.
  3. 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 & endpointBeschrijving
GET /api/v1/pass-projectsGeeft een lijst van alle Wallet Experiences (Pasprojecten) in de actieve workspace.
POST /api/v1/pass-projectsMaakt een nieuw PassProject aan met request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug).
GET /api/v1/pass-projects/:idHaalt projectconfiguratie, gekoppelde sjablonen, gereedheid en segmenten op.
PATCH /api/v1/pass-projects/:idWerkt projectnaam, beschrijving, mainTemplateId, bundleOnDownload, maxBundleSize of slug bij.
POST /api/v1/pass-projects/:id/templates/:templateIdKoppelt een begeleidend sjabloon (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE).
GET / PATCH /api/v1/pass-projects/:id/bundleConfigureert bundelvolgorde, limieten (maxBundleSize) en .pkpasses-metadata.
POST /api/v1/pass-projects/:id/download-bundleDownloadt of genereert het gecoördineerde .pkpasses-bundelarchief voor een pas of uitgifte.
GET /api/v1/pass-projects/bundle-passes/:passIdGeeft 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

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)

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

Gerelateerde product- en ontwikkelaarsdocs

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.