Skip to content
Guide du centre d'aide · Projets & organisation
4 min de lectureVérifié 2026-11-16

Gérer les projets

Regroupez un modèle principal et des modèles liés en Wallet Experiences, bundles et bascules par segment.

Dans ce guide

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

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE : BUNDLING PROJET (.PKPASSES) & AUTOMATISATION PAR SEGMENTS
ÉTAPE 01 PROJET DE PASSES (PassProject & PassProjectTemplate)
PRIMARY (mainTemplateId) : Carte d'ancrage (Abonnement / Billet / Vol)
LINKED / VIP / CUSTOM : Bon salon VIP / Parking / Carte Gala associée
PRIVACY_MODE / INACTIVE : Variante confidentialité réduite ou en pause
ÉTAPE 02A BUNDLE APPLE PASS (ZIP .pkpasses)
Regroupe jusqu'à 10 .pkpass signés partageant le même Pass.bundleId
bundle grouping mode : AUTO | `MANU
BundleStatus : ACTIVE | CANCELLED
ÉTAPE 02B ORCHESTRATEUR SEGMENTS & AUTOMATION
Évalue PassProjectSegment sur les attributs Pass.attributes (GIN)
L| | - DéclencheAutomationFlow`
émettre passe lié / changer modèle

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

PassProjectTemplateRoleEmplacementResponsabilité fonctionnelle dans le projet
PRIMARYPassProject.mainTemplateIdLe 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 / CUSTOMPassProjectTemplate.roleModèles compagnons (accès VIP coulisses, bon boisson, ticket parking) regroupés au téléchargement ou émis dynamiquement par segment/automatisation.
PRIVACY_MODEPassProjectTemplate.roleModèle alternatif allégé activé automatiquement lorsqu'un titulaire refuse le suivi ou la personnalisation.
INACTIVEPassProjectTemplate.roleModè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 par Pass Grouping Engine (libs/pass-bundle, /api/v1/bundles/* ou POST /api/v1/pass-projects/:id/download-bundle). Empaquette jusqu'à 10 fichiers .pkpass signés (request payload : 2–10 passes ; request payload : 1–10 passes) servis en application/vnd.apple.pkpasses afin 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 .pkpass dans 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. 1
    Évaluation dynamique des segments : Définissez des filtres sur Pass.attributes (ex. attributes.spendTotal >= 500) et évaluez via POST /api/v1/pass-projects/:id/segments/:segmentId/evaluate.
  2. 2
    Émission automatique de cartes compagnes : Lorsqu'un passe principal entre dans un segment, un AutomationFlow attaché émet automatiquement le passe compagnon (LINKED / VIP) et partage son lien de bundle actualisé.
  3. 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 & EndpointDescription
GET /api/v1/pass-projectsListe toutes les Wallet Experiences (Pass Projects) de l'espace actif.
POST /api/v1/pass-projectsCrée un nouveau PassProject avec request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug).
GET /api/v1/pass-projects/:idRécupère la configuration du projet, les modèles liés, l'état de préparation et les segments.
PATCH /api/v1/pass-projects/:idMet à jour le nom, la description, mainTemplateId, bundleOnDownload, maxBundleSize ou slug.
POST /api/v1/pass-projects/:id/templates/:templateIdAssocie un modèle compagnon (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE).
GET / PATCH /api/v1/pass-projects/:id/bundleConfigure l'ordre du bundle, les limites (maxBundleSize) et les métadonnées .pkpasses.
POST /api/v1/pass-projects/:id/download-bundleGénère et télécharge l'archive .pkpasses coordonnée pour une carte ou une émission.
GET /api/v1/pass-projects/bundle-passes/:passIdListe 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

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)

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
}

Consultez Architecture Pass Bundling pour les flux techniques d'empaquetage et Configuration des workflows pour les règles d'automatisation inter-projets.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.