Skip to content
Guide du centre d'aide · Démarrage rapidePhase d'intégration 2
4 min de lectureVérifié 2026-11-16

Créer votre première carte Wallet

Concevez un modèle, assignez une mécanique, liez des variables dynamiques, publiez et testez sur votre téléphone.

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é1 / 2
Éléments clés de l'interface

Répertoire des modèles & barre d'adoption (Zoom)

Filtrez vos modèles, suivez les installations vs suppressions par modèle et ouvrez aperçu, Éditeur Visuel ou création unitaire.

Vue d'ensemble

La création de votre premier passe Wallet consiste à configurer un Template visuel réutilisable, lui associer des mécaniques métier interactives, exécuter une analyse de risque avant publication et émettre un enregistrement Pass concret installable sur les appareils iOS et Android.

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : CRÉATION & INSTALLATION DU PREMIER PASSE
ÉTAPE 01
1
CONCEPTION DU MODÈLE (POST/api/v1/templates)
Sélectionner pass type (storeCard, coupon, eventTicket, membership)
Configurer les couleurs (rgb(r,g,b) Apple, #RRGGBB Google) & les visuels
Associer pass mechanic (STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD)
ÉTAPE 02
2
ANALYSE DE RISQUE & PUBLICATION (POST/api/v1/templates/:id/publish)
Évaluer GET/api/v1/templates/:id/publish-risk-check
Promouvoir la révision de rowKind = DRAFT vers rowKind = PRODUCTION
ÉTAPE 03
3
ÉMISSION DU PASSE & INSTALLATION WALLET (POST/api/v1/passes)
En-tête optionnel Idempotency-Key (idempotencyKey) & externalId
Hydrater les attributes structured JSON (memberName, points, barcodeValue)
Diffuser l'URL intelligente (/p/:passId / /d/:slug)Ajout iOS/Android

Étapes de création pas à pas

Suivez ce workflow dans Passinstance Dashboard (Modèles -> Créer un modèle sur /templates/new) ou via l'API développeur :

  1. 1
    Sélectionner le format de mise en page (pass type) : choisissez l'un des formats de passe pris en charge :

- storeCard : cartes de fidélité, cartes à tampons et cartes cadeaux. - coupon : bons promotionnels à usage unique et coupons de réduction. - eventTicket / boardingPass : concerts, compétitions sportives, festivals, conférences ou cartes d'embarquement aérien/ferroviaire. - membership / generic / posterGeneric / studentId / businessCard : cartes de membre, cartes poster WWDC, badges employé/étudiant et cartes de visite numériques.

  1. 2
    Identité de marque, couleurs & visuels :

- Format des couleurs : Apple Wallet impose strictement des chaînes rgb(r, g, b) (sans canal alpha). Google Wallet accepte le format hexadécimal #RRGGBB. Le sélecteur de couleurs du tableau de bord convertit automatiquement les formats et signale un contraste WCAG insuffisant. - Emplacements d'images (image asset slot) : importez des visuels haute résolution dans les 13 emplacements pris en charge (logo, primaryLogo, secondaryLogo, icon, googlePayLogo, strip, background, thumbnail, artwork, venueMap, footer, androidBackground, androidLogo).

  1. 3
    Associer une mécanique interactive de passe :

- Choisissez un moteur de règles (mechanic type) : STAMP_CARD_ADD, STAMP_CARD_DEDUCT, LOYALTY_PROGRAM, PREPAID_CARD, VALID_ONCE_PER_DAY ou RENEW_EXPIRATION.

  1. 4
    Définir les zones de champs dynamiques (field placement type) :

- Positionnez vos champs dans HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO ou FOOTER. - Utilisez des jetons dynamiques entre accolades tels que {memberName}, {pointsBalance} ou {expirationDate}. - Ajoutez des chaînes changeMessage Apple contenant %@ (par exemple "Points mis à jour : %@") pour déclencher des notifications push natives sur l'écran verrouillé iOS.

  1. 5
    Analyse de risque avant publication & publication :

- Le tableau de bord interroge GET /api/v1/templates/:id/publish-risk-check pour détecter les modifications critiques susceptibles d'écraser des champs sur des passes déjà actifs. - Cliquez sur Enregistrer et publier (POST /api/v1/templates/:id/publish) pour promouvoir la révision DRAFT en ligne de base PRODUCTION.

  1. 6
    Générer & installer un passe de test :

- Cliquez sur Créer un passe dans la vue d'ensemble du modèle (/templates/:id/overview) ou envoyez une requête REST vers POST /api/v1/passes. La création appelle automatiquement resolvePassCreationTemplateId afin de lier le nouveau passe à la ligne de base canonique du modèle.

Liste des modèles et actions rapides de création
Liste des modèles et actions rapides de création

Génération programmatique de passe & vérification

Les développeurs peuvent contourner le tableau de bord et émettre des passes personnalisés directement depuis leurs systèmes backend ou CRM via POST /api/v1/passes (request payload). Incluez Idempotency-Key pour sécuriser les relances et externalId pour la corrélation CRM, et ajoutez éventuellement ?includePassSource=apple|google pour recevoir directement les artefacts sources Wallet dans la réponse :

Requête HTTP

POST /api/v1/passes?includePassSource=google
En-têtes
X-API-Key <API_KEY>
Content-Type application/json
Idempotency-Key order-94021-pass-init
JSON
{
  "templateId": "tmpl_9a8b7c6d5e4f",
  "externalId": "cust_100248",
  "attributes": {
    "memberName": "Elena Rostova",
    "memberNumber": "MB-94021",
    "points": "150"
  },
  "barcodeValue": "PI-MB-94021-SECURE",
  "barcodeAltText": "MB-94021",
  "expirationDate": "2027-12-31 23:59"
}

Réponse HTTP (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_1a2b3c4d5e6f",
    "templateId": "tmpl_9a8b7c6d5e4f",
    "serialNumber": "PI-789042-XY",
    "externalId": "cust_100248",
    "bundleId": null,
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "NONE",
    "appleArtifactStatus": "NOT_GENERATED",
    "googleArtifactStatus": "READY",
    "downloadUrl": "https://app.passinstance.com/d/elena-rostova-94021",
    "passAccessUrl": "https://app.passinstance.com/p/pass_1a2b3c4d5e6f",
    "passSource": {
      "platform": "google",
      "saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "createdAt": "2026-11-15T12:00:00Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Test d'un passe échantillon en bac à sable

Pendant l'évaluation et vos premiers essais, vous pouvez générer un passe échantillon instantané sans saisir de fiche client complète :

  1. 1
    Appelez POST /api/v1/onboarding/sample-pass ou cliquez sur Try Sample Pass dans l'étape /onboarding/try-pass de l'assistant.
  2. 2
    Le serveur crée un passe éphémère et expose l'endpoint public suivant :
GET /api/v1/onboarding/sample-pass/public/:sessionId
  1. 3
    Scannez le QR code affiché avec l'appareil photo d'un iPhone pour déclencher l'ajout natif dans Apple Wallet, ou ouvrez le lien sur Android pour tester Google Wallet.
  2. 4
    Ouvrez le Scanner (/scanner) dans Passinstance Dashboard ou appairez l'application mobile Passinstance Scanner via POST /api/v1/scanner-keys/from-link et scannez le passe installé pour tester les événements de scan en direct et les notifications push instantanées.

Important : Testez toujours votre nouveau modèle publié sur des appareils iOS (Apple Wallet) et Android (Google Wallet) afin de vérifier le contraste des couleurs, l'absence de troncature de texte et la fiabilité de lecture du code-barres avant de lancer des campagnes de diffusion clients.

Prêt à démarrer ? Lancez la Phase 2 : Concevoir votre carte ou découvrez Créer des passes Wallet avec l'IA.

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.