Skip to content
Guide du centre d'aide · Modèles de passes
5 min de lectureVérifié 2026-11-16

Créer un modèle à partir de JSON

Importez et provisionnez des modèles de cartes par programmation à l'aide de définitions JSON, de la validation de schéma et de règles de normalisation.

Dans ce guide

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

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : PIPELINE D'INGESTION DE MODÈLE JSON
ÉTAPE 01 CLIENT EXTERNE / SCRIPT D'AUTOMATISATION
Envoie le document JSON via POST/api/v1/templates ou .../templates/import
Décrit types de passe, couleurs, zones de champs, codes-barres et pertinence
ÉTAPE 02 PIPELINE D'INGESTION & DE NORMALISATION DE MODÈLES
normalizeTemplateImport (template-import-export.util.ts)
1
Garde de taille : applique maximum upload size limit = 5 * 1024 * 1024 (5 Mo)
2
Assainissement sécurité : retire les clés système (id, customerId, etc.)
3
Protection pollution de prototype : rejette __proto__, constructor, etc.
4
Normalisation des couleurs : convertit hex / RGB vers rgb(r, g, b) canonique
5
Mappage codes-barres & transport : traduit les enums Apple PassKit
ÉTAPE 03 RÉCONCILIATEUR BASE DE DONNÉES (Template Engine)
Persiste l'entité Template avec status: PUBLISHED
Crée les entités relationnelles : Field[], Color, Barcode, Location[]
Initialise l'index de recherche rapide sur Pass.attributes pour les propriétés
ÉTAPE 04A COMPILATION APPLE WALLET
Génère le dictionnaire pass.json et empaquette les icônes par défaut
ÉTAPE 04B CRÉATION DE CLASSE GOOGLE WALLET
Crée la classe Google Wallet via SDK (ex. LoyaltyClass, EventClass)

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é racineTypeObligatoireDescription
namestringOuiNom lisible du modèle (par ex. "Artisan Coffee Club"). 255 caractères maximum.
kindPassKindOuiGéométrie du type de passe : storeCard, coupon, eventTicket, boardingPass, generic ou posterGeneric.
organizationNamestringOuiNom de l'organisation affiché sur les passes Apple Wallet et Google Wallet.
descriptionstringOuiDescription accessible du passe exigée par Apple PassKit.
statustemplate statusNonStatut initial. Défini par défaut sur PUBLISHED lors d'une création par programmation.
colorsrequest payloadNonObjet contenant backgroundColor, foregroundColor, labelColor et stripColor.
barcoderequest payloadNonConfiguration du code-barres (format, messageEncoding, altText, addSecurityAnimation).
fieldsrequest payloadNonCollections de champs regroupées par zone (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields).
locationsrequest payload[]NonTableau de jusqu'à 10 coordonnées GPS déclenchant des notifications sur l'écran verrouillé.
beaconsrequest payload[]NonTableau de jusqu'à 10 balises Bluetooth iBeacon pour la détection de proximité en intérieur.
expirationrequest payloadNonStraté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 :

JSON
{
  "backgroundColor": "rgb(24, 24, 27)",
  "foregroundColor": "rgb(255, 255, 255)",
  "labelColor": "rgb(161, 161, 170)",
  "stripColor": "rgb(255, 255, 255)"
}

Le sous-objet barcode

JSON
{
  "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. 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. 2
    Détection du type de transport : pour les passes boardingPass, associe les chaînes transitType (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric).
  3. 3
    Recadrage du placement des champs : vérifie que les champs placés dans auxiliaryFields respectent les règles du type de passe (par ex., les passes coupon refusent les champs auxiliaires et les redirigent vers secondaryFields).
  4. 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 automatiquement PKBarcodeFormatQR comme code-barres de secours pour Apple Watch.
  5. 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

POST /api/v1/templates
En-têtes
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "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)

JSON
{
  "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 HTTPMessage d'erreurCause racine & résolution
400 Bad RequestTemplate icon is requiredLors 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 RequestInvalid 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 RequestAuxiliary fields are not supported on coupon passesLa 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 LargeImport payload exceeds 5MB limitLa 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.

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.