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

Architecture système : émission unitaire & upsert idempotent
Émettre manuellement un passe unitaire dans le tableau de bord
-
1
Ouvrez la page de vue d'ensemble de votre modèle Publié.
-
2
Cliquez sur Créer un passe (Create pass) dans l'en-tête supérieur (ou sous Actions rapides).
-
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
Validez pour générer le passe immédiatement.
-
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,resolvePassCreationTemplateIdrésouttemplateIdvers sa révision de basePRODUCTION/PUBLISHEDet rejette les modèles à l'étatDELETING/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
| Champ | Type | Requis | Description |
|---|---|---|---|
templateId | string (UUID) | Oui | UUID du modèle (résolu automatiquement vers sa ligne de base active PRODUCTION/PUBLISHED). |
externalId | string | Optionnel | Identifiant CRM/POS/commande unique par locataire (max. 255 car. ; unicité appliquée aux passes actifs non supprimés via @@unique([customerId, externalId])). |
serialNumber | string | Optionnel | Numéro de série personnalisé unique (généré automatiquement si omis). |
barcodeValue | string | Optionnel | Charge utile explicite du code-barres. Utilise par défaut la configuration du modèle ou une valeur générée. |
barcodeAltText / barcodeAlternativeText | string | Optionnel | Texte lisible affiché sous le code-barres pour la saisie manuelle en caisse. |
attributes | Record<string, any> | Optionnel | Dictionnaire structured JSON clé-valeur correspondant aux clés de propriétés personnalisées de votre modèle. |
expirationDate | string | Optionnel | Date/heure d'expiration (<= 10 ans dans le futur, interprétée dans le fuseau horaire de l'espace de travail). |
validityAsOfDate / validAsOfDate | string | Optionnel | Date/heure de début de validité (issuedDate). |
enableDownloadUntil | string | Optionnel | Date limite de téléchargement ("YYYY-MM-DD HH:mm" ou horodatage ISO). |
sharingProhibited | boolean | Optionnel | Surcharge le réglage anti-partage du modèle (limitToOneActivePerPass). |
validationPlaces | string[] | Optionnel | Liste spécifique de lieux de validation autorisés lorsque l'option est activée sur le modèle. |
skipDistributeOnCreate | boolean | Optionnel | Dé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
{
"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)
{
"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 à unpass bundle(/api/v1/bundles/upsertouPassProject) afin quePass.bundleIdregroupe jusqu'à10passes 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 fusionneattributes,expirationDate,status(pass status) et unchangeMessageoptionnel (<=500car.) sur le passe existant (action: "UPDATED"). -
PUT /api/v1/passes/by-external-id/:externalId: effectue un upsert à partir du paramètre d'URL:externalId(siexternalIdfigure 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 parexternalIdsans 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
{
"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)
{
"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.
