Skip to content
Guide du centre d'aide · Émission de passesPhase d'intégration 3
4 min de lectureVérifié 2026-11-16

Créer des passes individuels

Générez une carte unique depuis un modèle publié avec attributs nominatifs et lien ou QR de téléchargement immédiat.

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

Création d'une carte unitaire et Actions rapides (Zoom)

Cliquez sur « + Create pass » dans l'en-tête ou sur « Create single pass » dans les Actions rapides pour générer une carte de test.

Vue d'ensemble

L'émission de passes individuels permet aux opérateurs et aux intégrations backend de générer une carte de portefeuille numérique personnalisée à partir de n'importe quel modèle PUBLISHED. Qu'elle soit déclenchée manuellement depuis le panneau Créer un passe du tableau de bord ou par programmation via l'API REST, l'opération attribue un serialNumber et un authenticationToken cryptographiquement uniques, hydrate tous les champs dynamiques {variable}, signe le paquet Apple .pkpass ainsi que le JWT Google Wallet et retourne immédiatement une URL de distribution intelligente (passAccessUrl).

Actions rapides de modèle pour créer un passe unitaire
Actions rapides de modèle pour créer un passe unitaire

Architecture système : émission unitaire & upsert idempotent

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : ÉMISSION UNITAIRE & UPSERT IDEMPOTENT
ÉTAPE 01 PANNEAU TABLEAU DE BORD / CRM / BACKEND POS
Émission standard : POST/api/v1/passes (request payload)
Upsert idempotent : POST/api/v1/passes/upsert-by-external-id
ÉTAPE 02 SERVICE D'ÉMISSION DES PASSES (Pass Issuance Engine)
1
Vérifie que Template est PUBLISHED & rattaché à l'espace (customerId)
2
Évalue la clé composite (customerId, externalId) pour la déduplication
3
Génère serialNumber unique & authenticationToken hex sur 32 octets
4
Valide attributes structured JSON selon le schéma des propriétés du modèle
5
Enregistre Pass (status: ACTIVE) & initialise le grand livre pass mechanic
ÉTAPE 03 SIGNATURE WALLET & CRÉATION DU LIEN INTELLIGENT
Génère le lien de téléchargement intelligent (passAccessUrl) & endpoint QR
Prépare le flux Apple .pkpass signé & le JWT Google Wallet Save
Retourne API response (request payload) avec 201 Created ou 200 OK

Émettre manuellement un passe unitaire dans le tableau de bord

  1. 1
    Ouvrez la page de vue d'ensemble de votre modèle Publié.
  2. 2
    Cliquez sur Créer un passe (Create pass) dans l'en-tête supérieur (ou sous Actions rapides).
  3. 3
    Renseignez chaque propriété personnalisée obligatoire affichée dans le formulaire (par exemple : nom du client, e-mail/téléphone si requis pour l'envoi, nombre initial de tampons ou externalId).
  4. 4
    Validez pour générer le passe immédiatement.
  5. 5
    Copiez l'URL de téléchargement unique (passAccessUrl), affichez le QR code d'installation à scanner avec un smartphone ou déclenchez l'envoi d'un e-mail de remise directement depuis le panneau de détails du passe.

Prérequis : Publiez votre modèle (POST /api/v1/templates/:id/publish) avec des identifiants Apple Pass Type ID / Google Wallet valides avant d'émettre des passes en production. En interne, resolvePassCreationTemplateId résout templateId vers sa révision de base PRODUCTION/PUBLISHED et rejette les modèles à l'état DELETING/DELETED (BadRequestException / NotFoundException).

Référence API d'émission programmatique

1. Créer un nouveau passe (POST /api/v1/passes)

Crée un nouvel enregistrement de passe via request payload, en tenant compte de l'en-tête HTTP optionnel Idempotency-Key (idempotencyKey, max. 128 caractères correspondant à [A-Za-z0-9._:-]+, protégé par empreinte SHA-256 de la requête) et des paramètres de requête optionnels ?includePassSource=apple|google et ?pin=.

Paramètres de requête request payload

ChampTypeRequisDescription
templateIdstring (UUID)OuiUUID du modèle (résolu automatiquement vers sa ligne de base active PRODUCTION/PUBLISHED).
externalIdstringOptionnelIdentifiant CRM/POS/commande unique par locataire (max. 255 car. ; unicité appliquée aux passes actifs non supprimés via @@unique([customerId, externalId])).
serialNumberstringOptionnelNuméro de série personnalisé unique (généré automatiquement si omis).
barcodeValuestringOptionnelCharge utile explicite du code-barres. Utilise par défaut la configuration du modèle ou une valeur générée.
barcodeAltText / barcodeAlternativeTextstringOptionnelTexte lisible affiché sous le code-barres pour la saisie manuelle en caisse.
attributesRecord<string, any>OptionnelDictionnaire structured JSON clé-valeur correspondant aux clés de propriétés personnalisées de votre modèle.
expirationDatestringOptionnelDate/heure d'expiration (<= 10 ans dans le futur, interprétée dans le fuseau horaire de l'espace de travail).
validityAsOfDate / validAsOfDatestringOptionnelDate/heure de début de validité (issuedDate).
enableDownloadUntilstringOptionnelDate limite de téléchargement ("YYYY-MM-DD HH:mm" ou horodatage ISO).
sharingProhibitedbooleanOptionnelSurcharge le réglage anti-partage du modèle (limitToOneActivePerPass).
validationPlacesstring[]OptionnelListe spécifique de lieux de validation autorisés lorsque l'option est activée sur le modèle.
skipDistributeOnCreatebooleanOptionnelDésactive la diffusion automatique post-création (e-mail/SMS) lors d'une émission par API.

Exemple de requête

POST /api/v1/passes?includePassSource=google En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "serialNumber": "PI-GOLD-2026-44910",
  "barcodeValue": "PI-GOLD-2026-44910",
  "barcodeAltText": "44910-GOLD",
  "expirationDate": "2027-12-31 23:59",
  "attributes": {
    "firstName": "Marcus",
    "lastName": "Vance",
    "email": "marcus.vance@example.com",
    "pointsBalance": 500,
    "memberTier": "Gold"
  }
}

Exemple de réponse (API response envelope)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01j8k9m2n3p4q5r6",
    "templateId": "tmpl_01hxyz987654321",
    "customerId": "cust_ws_88219",
    "externalId": "crm_usr_44910",
    "bundleId": null,
    "idempotencyKey": "crm_usr_44910_v1",
    "serialNumber": "PI-GOLD-2026-44910",
    "authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
    "downloadCode": "dl_94f8a1",
    "barcodeValue": "PI-GOLD-2026-44910",
    "barcodeAltText": "44910-GOLD",
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "NONE",
    "appleArtifactStatus": "NOT_GENERATED",
    "googleArtifactStatus": "READY",
    "downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "pointsBalance": 500,
      "memberTier": "Gold"
    },
    "expirationDate": "2027-12-31T23:59:00.000Z",
    "createdAt": "2026-11-15T15:04:12.000Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Astuce — Regroupement multi-passes (bundleId) : Si vous créez des passes associés pour un foyer, plusieurs segments de vol ou une commande VIP événementielle, rattachez-les à un pass bundle (/api/v1/bundles/upsert ou PassProject) afin que Pass.bundleId regroupe jusqu'à 10 passes dans un seul lien .pkpasses / de retrait unifié.

2. Upsert idempotent & recherche par identifiant externe (request payload)

Dans les intégrations pilotées par webhooks (Shopify, HubSpot ou caisses POS), les nouvelles tentatives réseau peuvent renvoyer la même requête à plusieurs reprises. Passinstance met à disposition des endpoints dédiés à externalId restreints à vos passes locataires actifs (archivedAt: null) :

  • POST /api/v1/passes/upsert-by-external-id : crée un passe si aucun passe actif ne correspond à externalId (action: "CREATED"), ou fusionne attributes, expirationDate, status (pass status) et un changeMessage optionnel (<=500 car.) sur le passe existant (action: "UPDATED").
  • PUT /api/v1/passes/by-external-id/:externalId : effectue un upsert à partir du paramètre d'URL :externalId (si externalId figure dans le corps JSON, il doit correspondre, ou peut être omis).
  • GET /api/v1/passes/by-external-id/:externalId : récupère directement le passe actif par externalId sans avoir à stocker nos UUID internes à l'extérieur.

Exemple de requête

POST /api/v1/passes/upsert-by-external-id En-têtes : X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "status": "ACTIVE",
  "changeMessage": "Tier updated to Platinum (%@ pts)",
  "attributes": {
    "pointsBalance": 750,
    "memberTier": "Platinum"
  }
}

Exemple de réponse (200 OK)

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "pass_01j8k9m2n3p4q5r6",
      "externalId": "crm_usr_44910",
      "serialNumber": "PI-GOLD-2026-44910",
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

Pour l'intégration CSV à grand volume ou la génération par lots de tableaux JSON, consultez Création de passes en masse et Opérations en masse.

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.