Aperçu
Passinstance prend nativement en charge la création et la configuration de modèles de passes par programmation à partir de charges utiles JSON. Plutôt que de configurer manuellement la mise en page visuelle, l'encodage des codes-barres, les couleurs et les attributs dynamiques dans l'éditeur visuel, les développeurs et intégrateurs de plateforme peuvent soumettre des schémas complets de modèle à l'API REST (POST /api/v1/templates ou POST /api/v1/templates/import).
Le moteur de modèles backend fait passer le JSON entrant par le pipeline de normalisation et de validation avec normalisation automatique du schéma : il valide les géométries de passe, impose les invariants de couleur d'Apple Wallet et de Google Wallet, et enregistre les propriétés personnalisées.
Architecture système : pipeline d'ingestion de modèle JSON
Spécification du schéma JSON pour request payload
Une définition JSON de modèle valide doit respecter la structure request payload acceptée par POST /api/v1/templates :
| Propriété racine | Type | Obligatoire | Description |
|---|---|---|---|
name | string | Oui | Nom lisible du modèle (par ex. "Artisan Coffee Club"). 255 caractères maximum. |
kind | PassKind | Oui | Géométrie du type de passe : storeCard, coupon, eventTicket, boardingPass, generic ou posterGeneric. |
organizationName | string | Oui | Nom de l'organisation affiché sur les passes Apple Wallet et Google Wallet. |
description | string | Oui | Description accessible du passe exigée par Apple PassKit. |
status | template status | Non | Statut initial. Défini par défaut sur PUBLISHED lors d'une création par programmation. |
colors | request payload | Non | Objet contenant backgroundColor, foregroundColor, labelColor et stripColor. |
barcode | request payload | Non | Configuration du code-barres (format, messageEncoding, altText, addSecurityAnimation). |
fields | request payload | Non | Collections de champs regroupées par zone (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields). |
locations | request payload[] | Non | Tableau de jusqu'à 10 coordonnées GPS déclenchant des notifications sur l'écran verrouillé. |
beacons | request payload[] | Non | Tableau de jusqu'à 10 balises Bluetooth iBeacon pour la détection de proximité en intérieur. |
expiration | request payload | Non | Stratégie de validité et d'expiration du passe (none, fixed ou duration). |
Le sous-objet colors
Apple Wallet impose strictement le format CSS RGB (rgb(r, g, b)) pour les couleurs et rejette les codes hexadécimaux ou les canaux alpha. Lors d'un import JSON via Passinstance, le normalisateur accepte les syntaxes hexadécimale ou RGB et sérialise exactement le format attendu par chaque fournisseur de portefeuille :
{
"backgroundColor": "rgb(24, 24, 27)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(161, 161, 170)",
"stripColor": "rgb(255, 255, 255)"
}
Le sous-objet barcode
{
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{cardNumber}",
"addSecurityAnimation": true
}
Les formats pris en charge sont : PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5 et PKBarcodeFormatNone.
Règles de validation & de normalisation (normalizeTemplateImport)
Lorsqu'un document JSON brut est soumis à POST /api/v1/templates/import, le backend exécute normalizeTemplateImport :
-
1
Normalisation du type de passe : traduit les noms de style hérités ou alternatifs (tels que
store_card->storeCard,event_ticket->eventTicket,boarding_pass->boardingPass). -
2
Détection du type de transport : pour les passes
boardingPass, associe les chaînestransitType(PKTransitTypeAir,PKTransitTypeTrain,PKTransitTypeBus,PKTransitTypeBoat,PKTransitTypeGeneric). -
3
Recadrage du placement des champs : vérifie que les champs placés dans
auxiliaryFieldsrespectent les règles du type de passe (par ex., les passescouponrefusent les champs auxiliaires et les redirigent verssecondaryFields). -
4
Affectation d'un code-barres de repli : si un code-barres 1D (
Code 128,Code 39,EAN-13) est configuré sans solution de repli, le normalisateur attribue automatiquementPKBarcodeFormatQRcomme code-barres de secours pour Apple Watch. -
5
Suppression des clés système : élimine silencieusement les clés système internes ou propres au locataire (
id,customerId,tenantId,certificateId,version,status,passes,createdAt,updatedAt,archivedAt).
Référence API : créer un modèle depuis JSON
Requête HTTP
/api/v1/templates
{
"name": "Acme VIP Club",
"kind": "storeCard",
"organizationName": "Acme Retail Group",
"description": "Acme VIP Rewards Card",
"colors": {
"backgroundColor": "rgb(15, 23, 42)",
"foregroundColor": "rgb(248, 250, 252)",
"labelColor": "rgb(148, 163, 184)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{externalId}"
},
"fields": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "VIP Platinum",
"textAlignment": "PKTextAlignmentRight"
}
],
"primaryFields": [
{
"key": "holder",
"label": "MEMBER",
"value": "{firstName} {lastName}"
}
],
"secondaryFields": [
{
"key": "balance",
"label": "POINTS",
"value": "{pointsBalance}",
"numberStyle": "PKNumberStyleDecimal"
}
],
"backFields": [
{
"key": "terms",
"label": "TERMS & CONDITIONS",
"value": "Valid at all participating Acme stores. Points expire after 12 months of inactivity."
}
]
},
"locations": [
{
"latitude": 40.712776,
"longitude": -74.005974,
"maxDistance": 250,
"relevantText": "Welcome to Acme Flagship! Scan your pass at checkout."
}
]
}
Réponse HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01h9x8k7m6n5p4q3r2s1",
"groupId": "grp_01h9x8k7m6n5p4q3r2s1",
"name": "Acme VIP Club",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T20:30:00.000Z",
"updatedAt": "2026-11-16T20:30:00.000Z"
},
"statusCode": 201
}
Erreurs courantes d'ingestion JSON & résolutions
| Statut HTTP | Message d'erreur | Cause racine & résolution |
|---|---|---|
| 400 Bad Request | Template icon is required | Lors de la création de modèles via JSON sans actifs initiaux existants, vous devez fournir un actif icon ou un data URI, ou assigner l'identifiant d'un actif existant de l'espace de travail. |
| 400 Bad Request | Invalid color format: must be rgb(r, g, b) | Une chaîne de couleur contenait un canal alpha (rgba(0,0,0,0.5)) ou une syntaxe invalide. Fournissez une valeur standard rgb(r, g, b) ou hexadécimale à 6 chiffres (#RRGGBB). |
| 400 Bad Request | Auxiliary fields are not supported on coupon passes | La charge utile a soumis auxiliaryFields pour un type de passe coupon. Déplacez les champs auxiliaires dans secondaryFields ou changez le type de passe en storeCard. |
| 413 Payload Too Large | Import payload exceeds 5MB limit | La charge utile JSON a dépassé maximum upload size limit (5 Mo), généralement à cause d'images encodées en base64 intégrées. Téléversez plutôt les images via l'endpoint d'actifs image. |
Poursuivez avec Importer depuis Apple Pass Designer pour importer des projets .passdesign existants, ou explorez Champs dynamiques & personnalisation pour configurer des variables d'attributs.
