Aperçu
Dans le tableau de bord Passinstance, les Projets multi-cartes (modèle PassProject géré par Projects API sur /api/v1/pass-projects et l'alias /api/v1/wallet-experiences) s'affichent dans le hub Wallet Experiences (/wallet-experiences, structuré autour des onglets Overview, Cards, Audience, Automations, Distribution, Analytics et Settings). Un projet coordonne un modèle principal mainTemplateId avec des modèles complémentaires liés au sein d'un parcours client unifié, en prenant en charge les bundles Apple Wallet (.pkpasses) (Pass.bundleId / pass bundle) et l'automatisation par segments.
Architecture système : projets, bundles .pkpasses & déclencheurs par segments
Modèles de base & rôles de modèles (PassProjectTemplateRole)
Chaque PassProject associe un mainTemplateId (rôle PRIMARY sur le projet lui-même) à des modèles compagnons (PassProjectTemplate, rôles inscriptibles LINKED, PRIVACY_MODE, VIP, CUSTOM, INACTIVE) :
PassProjectTemplateRole | Emplacement | Responsabilité fonctionnelle dans le projet |
|---|---|---|
PRIMARY | PassProject.mainTemplateId | Le passe identitaire d'ancrage (par ex. abonnement saisonnier, clé d'hôtel ou carte de fidélité) dont externalId et les attributs pilotent l'expérience. |
LINKED / VIP / CUSTOM | PassProjectTemplate.role | Modèles compagnons (accès VIP coulisses, bon boisson, ticket parking) regroupés au téléchargement ou émis dynamiquement par segment/automatisation. |
PRIVACY_MODE | PassProjectTemplate.role | Modèle alternatif allégé activé automatiquement lorsqu'un titulaire refuse le suivi ou la personnalisation. |
INACTIVE | PassProjectTemplate.role | Modèle lié temporairement exclu des nouveaux téléchargements de bundle sans rompre l'historique existant. |
Bundles Apple Wallet (.pkpasses) & Pass.bundleId
Lorsque le regroupement est activé (bundleOnDownload: true, maxBundleSize jusqu'à 10), Passinstance relie les cartes compagnes émises sous un même Pass.bundleId (bundleId vers pass bundle) :
-
Apple Wallet (Archive
.pkpasses) : Générée parPass Grouping Engine(libs/pass-bundle,/api/v1/bundles/*ouPOST /api/v1/pass-projects/:id/download-bundle). Empaquette jusqu'à 10 fichiers.pkpasssignés (request payload: 2–10 passes ;request payload: 1–10 passes) servis enapplication/vnd.apple.pkpassesafin qu'iOS propose Tout ajouter. -
Récupération multi-cartes Google Wallet : Fournit les liens de sauvegarde coordonnés et liens de bundle (
GET /api/v1/bundles/:id/google-wallet-link,PassProjectIssuanceProvider:APPLE\|GOOGLE,PassProjectIssuanceStatus:PENDING->VALIDATING->CREATING_PASSES->READY\|PARTIALLY_READY\|FAILED).
Important : Apple iOS impose un maximum strict de 10 fichiers
.pkpassdans une même archive.pkpasses(maxBundleSize <= 10). Chaque modèle inclus dans un bundle doit être publié avec un certificat Apple Pass Type ID valide.
Segments d'audience (PassProjectSegment) & flux d'automatisation
Les projets s'intègrent directement à PassProjectSegment et AutomationFlow pour orchestrer des parcours multi-cartes dynamiques sans code de liaison webhook externe :
-
1
Évaluation dynamique des segments : Définissez des filtres sur
Pass.attributes(ex.attributes.spendTotal >= 500) et évaluez viaPOST /api/v1/pass-projects/:id/segments/:segmentId/evaluate. -
2
Émission automatique de cartes compagnes : Lorsqu'un passe principal entre dans un segment, un
AutomationFlowattaché émet automatiquement le passe compagnon (LINKED/VIP) et partage son lien de bundle actualisé. -
3
Basculement en mode confidentialité : Si le consentement à la personnalisation est retiré, l'expérience migre la carte du titulaire vers le modèle
PRIVACY_MODE.
Référence API REST des projets (Projects API)
Tous les endpoints de projets sont exposés sous /api/v1/pass-projects (alias /api/v1/wallet-experiences) :
| Méthode HTTP & Endpoint | Description |
|---|---|
GET /api/v1/pass-projects | Liste toutes les Wallet Experiences (Pass Projects) de l'espace actif. |
POST /api/v1/pass-projects | Crée un nouveau PassProject avec request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug). |
GET /api/v1/pass-projects/:id | Récupère la configuration du projet, les modèles liés, l'état de préparation et les segments. |
PATCH /api/v1/pass-projects/:id | Met à jour le nom, la description, mainTemplateId, bundleOnDownload, maxBundleSize ou slug. |
POST /api/v1/pass-projects/:id/templates/:templateId | Associe un modèle compagnon (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE). |
GET / PATCH /api/v1/pass-projects/:id/bundle | Configure l'ordre du bundle, les limites (maxBundleSize) et les métadonnées .pkpasses. |
POST /api/v1/pass-projects/:id/download-bundle | Génère et télécharge l'archive .pkpasses coordonnée pour une carte ou une émission. |
GET /api/v1/pass-projects/bundle-passes/:passId | Liste toutes les cartes compagnes regroupées avec un passId donné via bundleId. |
Exemple : Créer un projet multi-cartes (request payload)
POST /api/v1/pass-projects En-têtes : 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"
}
Réponse HTTP (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
}
Consultez Architecture Pass Bundling pour les flux techniques d'empaquetage et Configuration des workflows pour les règles d'automatisation inter-projets.
