Skip to content
Guide du centre d'aide · Projets & organisationPhase d'intégration 3
6 min de lectureVérifié 2026-11-16

Organiser modèles & passes

Gardez vos catalogues propres avec conventions de nommage, filtres d'archive, unicité d'ID externe et vues sauvegardées.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé
Éléments clés de l'interface

Template Settings — Signature & External IDs (Zoom)

Vérifiez certificat de signature, ordre d'affichage Wallet, état Published et unicité des External IDs.

Aperçu

À mesure que votre organisation se développe entre campagnes saisonnières, points de vente régionaux et environnements de préproduction ou de production, Passinstance met à votre disposition des outils d'organisation d'espace de travail multiniveaux : catégorisation et étiquetage des modèles, clonage de modèles (Template Duplication Wizard), filtrage du cycle de vie rowKind (DRAFT, PUBLISHED, PRODUCTION, ARCHIVED), application de l'unicité composite sur l'identifiant externe, recherche d'attributs indexée GIN en base de données (attribute search index) et mappage de modèles inter-projets.

Architecture système : taxonomie d'espace de travail, clonage & vues enregistrées

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : TAXONOMIE, CLONAGE & VUES ENREGISTRÉES
ÉTAPE 01 ORGANISATION (Modèle Organization)
+-- Espace de production (Customer : kind = 'production')
+-- Espace sandbox (Customer : kind = 'sandbox')
ÉTAPE 02 CATALOGUE DE MODÈLES & GROUPES PROJETS (Template / PassProject)
Filtre rowKind : PUBLISHED | PRODUCTION | DRAFT | ARCHIVED
Catégorisation : tags[] programme, passType & liens PassProjectTemplate
Moteur de clonage : POST/api/v1/templates/:id/duplicate (Template Duplication Wizard)
Politique External ID : contrainte unique sur (customerId, externalId)
ÉTAPE 03 RÉPERTOIRE HAUTE VITESSE & VUES ENREGISTRÉES (Table Pass)
Index B-Tree : (customerId, templateId, status, serialNumber, externalId)
Index JSON structuré rapide (attribute search index) : requêtes instantanées
Vues enregistrées : arbres de filtres ET/OU persistés par opérateur ou espace

1. Copier un modèle : dupliquer un modèle existant (clonage & duplication)

Plutôt que de reconfigurer les couleurs, les zones de champs, les codes-barres et les schémas de propriétés personnalisées depuis zéro pour chaque nouveau programme de cartes, vous pouvez dupliquer n'importe quel modèle existant en quelques secondes.

Comment cloner dans le tableau de bord

Les opérateurs peuvent lancer le clonage d'un modèle depuis deux emplacements :

  1. 1
    Depuis le répertoire Modèles : sur n'importe quelle carte de modèle, cliquez sur le menu Trois points (...) puis sélectionnez Dupliquer (Duplicate).
  2. 2
    Depuis l'éditeur visuel : dans la barre de commandes supérieure, cliquez sur Actions -> Dupliquer le modèle (Duplicate Template).

Le parcours en 4 étapes de Template Duplication Wizard

Template Duplication Wizard accompagne les opérateurs dans la duplication d'un modèle :

  1. 1
    Étape 1 : sélectionner le modèle source : confirme le modèle d'origine et inspecte son type de passe, le nombre de champs et les images associées.
  2. 2
    Étape 2 : nom et description : pré-remplit le nom du nouveau modèle avec ${sourceTemplate.name} (Copy) et permet de saisir une description distincte.
  3. 3
    Étape 3 : personnalisation :

- Page d'inscription PassFlow liée : choisissez de cloner le formulaire d'inscription public associé via duplicatePassFlow (créant une page PassFlow /f/:newUrl indépendante) ou de créer le nouveau modèle sans formulaire attaché. - Couleurs de marque : ajustez backgroundColor, foregroundColor et labelColor. L'assistant exécute en temps réel une validation de contraste WCAG AA pour garantir la lisibilité. - Actifs visuels : choisissez de conserver les images du modèle source (icon, logo, strip, thumbnail) ou de téléverser de nouveaux actifs de marque.

  1. 4
    Étape 4 : affectation du certificat : sélectionnez un certificat de signature Apple Pass Type ID existant dans les paramètres de l'espace de travail ou importez un nouveau certificat .p12 / .cer.

2. Isolation des espaces de travail & hygiène de nommage des modèles

Passinstance cloisonne les modèles, passes, certificats et clés API au niveau de chaque espace de travail Customer au sein de votre Organization parente (POST /api/v1/organizations/current/workspaces) :

  1. 1
    Séparer les environnements par espace de travail : conservez vos brouillons expérimentaux et tests d'intégration dans un espace sandbox, et réservez votre espace production exclusivement aux programmes clients en direct.
  2. 2
    Standardiser les noms et tags de modèles : incluez le domaine du programme, la région et la version dans les titres de modèles (par exemple Loyalty-CoffeeClub-EU-v2) et associez des tags structurés (par ex. ["retail", "q4-2026", "dach"]) pour un filtrage instantané du catalogue.
  3. 3
    Archiver les modèles remplacés (rowKind: ARCHIVED) : au lieu de supprimer d'anciens modèles promotionnels auxquels des passes émis restent rattachés, passez-les au statut Archivé. Les modèles archivés disparaissent des sélecteurs actifs par défaut tout en préservant les statistiques historiques et journaux de scan sous le filtre Tous / Archivés.

3. Unicité de l'External ID, identifiants personnalisés & regroupement en bundles

Pour éviter d'émettre des passes en double entre formulaires web, terminaux de caisse (POS) et webhooks CRM, configurez les politiques d'identifiant et de regroupement dans les paramètres du modèle :

Paramètre / Propriété du modèleApplication en base de données & API
externalId (Pass.externalId)Chaîne fournie par l'appelant (255 caractères max.) indexée de manière unique pour tout passe actif non supprimé du locataire (@@unique([customerId, externalId]) WHERE archivedAt IS NULL). Les appels POST /api/v1/passes en doublon sont rejetés, tandis que POST /api/v1/passes/upsert-by-external-id met à jour sur place.
Règles d'identifiant personnalisé (Template)Configurez customIdentifiersEnabled, externalIdentifierPattern et customIdentifierValidationPattern dans les paramètres du modèle pour imposer un format regex à l'échelle de l'organisation sur les identifiants externes générés ou importés.
Regroupement multi-cartes (Pass.bundleId)Clé étrangère bundleId regroupant jusqu'à 10 passes dans un même pass bundle (bundle grouping mode : AUTO \MANUAL) pour la livraison au format .pkpasses.
Verrouillage mono-appareil (limitToOneActivePerPass)Restreint les liens de téléchargement intelligents afin qu'un même passe ne puisse pas être partagé et installé simultanément sur des appareils non autorisés.

Important : l'application de l'unicité sur externalId est vivement recommandée pour les cartes de fidélité, d'adhésion et cartes cadeaux prépayées. La suppression logique d'un passe de test (SOFT delete) renseigne archivedAt et libère immédiatement cet externalId pour réutilisation.


4. Indexation JSON structurée des attributs (attribute search index) & vues enregistrées

Chaque propriété personnalisée stockée dans Pass.attributes est automatiquement indexée par l'index inversé généralisé de la base de données (attribute search index). Les opérateurs et clients API peuvent ainsi organiser et interroger des millions de passes sans migration de schéma :

  • Vues enregistrées opérateur : dans le répertoire Passes (/passes), combinez des prédicats de filtrage ET/OU sur status (statut du passe), lifecycleStatus, walletVoidStatus (WalletPropagationStatus), bundleId, externalId, la plateforme d'appareil (APPLE_WALLET vs GOOGLE_WALLET) et les clés JSON structurées personnalisées (attributes.tier, attributes.storeId), puis sauvegardez la requête en tant que Vue enregistrée (Saved View).
  • Mappage de modèles inter-projets : regroupez des modèles associés au sein de Wallet Experiences (PassProject) plutôt que de cloner des modèles autonomes. Un même modèle peut jouer le rôle de modèle LINKED, VIP, CUSTOM ou PRIVACY_MODE à travers plusieurs conteneurs PassProject (PassProjectTemplateRole) tout en conservant une gouvernance centralisée des actifs et des mécaniques.

Référence API : duplication & filtrage de modèles

1. Dupliquer un modèle via l'API (POST /api/v1/templates/:id/duplicate)

Clone un modèle existant en recopiant ses champs de mise en page, ses couleurs, ses codes-barres et ses définitions de propriétés personnalisées :

POST /api/v1/templates/tmpl_01hxyz987654321/duplicate En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "name": "Artisan Coffee Club - Platinum Tier (Copy)",
  "duplicatePassFlow": true,
  "certificateId": "cert_01j7k8m9n2p3"
}

Réponse HTTP (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_new_clone_01h987",
    "name": "Artisan Coffee Club - Platinum Tier (Copy)",
    "kind": "storeCard",
    "status": "PUBLISHED",
    "versionNumber": 1,
    "rowKind": "PRODUCTION",
    "createdAt": "2026-11-16T21:20:00.000Z"
  },
  "statusCode": 201
}

2. Filtrer les modèles par statut, type & tags

GET /api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
En-têtes
X-API-Key <API_KEY>
JSON
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "tmpl_01hxyz987654321",
        "groupId": "grp_01hxyz987654321",
        "name": "Loyalty-CoffeeClub-EU-v2",
        "kind": "storeCard",
        "rowKind": "PRODUCTION",
        "status": "PUBLISHED",
        "versionNumber": 2,
        "tags": ["retail", "q4-2026", "dach"],
        "activePassesCount": 14820
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "statusCode": 200
}

Explorez Gérer les projets pour rassembler des passes issus de plusieurs modèles, ou consultez Comprendre votre espace de travail pour les règles d'isolation multi-espaces.

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.