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

Exporter et importer au format JSON

Sauvegardez, restaurez et transférez des modèles de cartes entre espaces de travail à l'aide de schémas JSON sécurisés.

Dans ce guide

Aperçu

Passinstance permet d'exporter et d'importer des définitions complètes de modèles sous forme de fichiers JSON structurés et portables. Cette fonctionnalité facilite :

  • La migration d'environnement : promouvoir des modèles de passes testés depuis un espace de travail sandbox vers un espace production sans reconstruction manuelle.
  • La sauvegarde & la reprise après sinistre : archiver les configurations canoniques de modèles dans des dépôts Git ou systèmes de gestion de versions (Configuration as Code).
  • Le partage & le clonage de modèles : diffuser des mises en page standardisées de fidélité, billetterie ou adhésion entre différents comptes clients ou franchisés.

Les fichiers exportés respectent la spécification d'export canonique de Passinstance (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', version de schéma 1) implémentée dans template-import-export.util.ts. Les identifiants système, clés primaires de base de données, identifiants de locataire et certificats de signature cryptographiques sont automatiquement retirés afin de garantir l'isolation multi-locataire et d'éviter toute collision d'identité.

Architecture système : flux d'export & d'import de modèle

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : PIPELINE D'EXPORT & D'IMPORT DE MODÈLE
ÉTAPE 01 ESPACE DE TRAVAIL SOURCE (Sandbox / Tests)
Modèle avec champs, propriétés personnalisées, couleurs, codes-barres et lieux
ÉTAPE 02 MOTEUR D'ASSAINISSEMENT À L'EXPORT (Template Export Engine)
buildSanitizedTemplateExportPayload
1
Injecte l'enveloppe : format: 'passinstance-template', version: 1
2
Retire les bornes locataire : customerId, tenantId, id, certificateId
3
Retire les identifiants Apple : teamIdentifier, passTypeIdentifier
4
Encode les références d'images Retina ou des URL CDN portables
ÉTAPE 03 ARTEFACT JSON PORTABLE (template-export.json)
Schéma JSON propre et lisible
Indépendant des IDs de base de données et des secrets du locataire
ÉTAPE 04 MOTEUR DE VALIDATION & DE SÉCURITÉ À L'IMPORT
normalizeTemplateImport
1
Garde de taille : maximum upload size limit = 5 * 1024 * 1024 (5 Mo max)
2
Protection pollution de prototype : retire __proto__, constructor, etc.
3
Réconcilie les propriétés personnalisées et crée les index GIN en base cible
4
Assigne le certificat de l'espace cible et lie la borne locataire locale
ÉTAPE 05 ESPACE DE TRAVAIL DE DESTINATION (Production / Live)
Nouveau Template créé avec status: PUBLISHED (ou révision DRAFT MAJ)
Prêt pour l'émission en direct, les PassFlows et les imports CSV par lot

Spécification du format d'export de modèle Passinstance

Le générateur d'export (buildSanitizedTemplateExportPayload) produit une enveloppe JSON standardisée conforme à TEMPLATE_EXPORT_SCHEMA_VERSION = 1 :

JSON
{
  "format": "passinstance-template",
  "version": 1,
  "exportedAt": "2026-11-16T20:40:00.000Z",
  "template": {
    "name": "Artisan Coffee Club - Gold Tier",
    "kind": "storeCard",
    "organizationName": "Artisan Roasters",
    "description": "Artisan Coffee Loyalty Card",
    "colors": {
      "backgroundColor": "rgb(20, 35, 28)",
      "foregroundColor": "rgb(255, 255, 255)",
      "labelColor": "rgb(167, 243, 208)",
      "stripColor": "rgb(255, 255, 255)"
    },
    "barcode": {
      "format": "PKBarcodeFormatQR",
      "messageEncoding": "UTF_8",
      "altText": "{cardNumber}",
      "addSecurityAnimation": true
    },
    "fields": {
      "headerFields": [
        {
          "key": "tier",
          "label": "TIER",
          "value": "Gold Member",
          "textAlignment": "PKTextAlignmentRight"
        }
      ],
      "primaryFields": [
        {
          "key": "holder",
          "label": "MEMBER",
          "value": "{firstName} {lastName}"
        }
      ],
      "secondaryFields": [
        {
          "key": "balance",
          "label": "POINTS BALANCE",
          "value": "{pointsBalance}",
          "numberStyle": "PKNumberStyleDecimal"
        }
      ],
      "auxiliaryFields": [
        {
          "key": "since",
          "label": "MEMBER SINCE",
          "value": "{memberSince}",
          "dateStyle": "PKDateStyleMedium"
        }
      ],
      "backFields": [
        {
          "key": "terms",
          "label": "TERMS & CONDITIONS",
          "value": "Points are earned on every purchase. Terms subject to change."
        }
      ]
    },
    "locations": [
      {
        "latitude": 52.520008,
        "longitude": 13.404954,
        "maxDistance": 150,
        "relevantText": "Welcome to Artisan Roasters! Scan your card for points."
      }
    ],
    "sharing": {
      "sharingProhibited": false
    }
  }
}

Invariants de sécurité & d'assainissement

Pour maintenir une isolation multi-locataire stricte et protéger vos actifs cryptographiques, Passinstance applique des invariants de sécurité rigoureux lors de l'export et de l'import (template-import-export.util.ts:25-34) :

1. Suppression des clés système

Les clés suivantes sont systématiquement supprimées des charges utiles exportées et rejetées à l'import :

  • Clés primaires et étrangères : id, customerId, tenantId, baseId, groupId.
  • Métadonnées de révision : versionNumber, version, rowKind, status.
  • Données des titulaires : passes, activePassesCount.
  • Horodatages : createdAt, updatedAt, archivedAt.
  • Identité Apple Developer : teamIdentifier, passTypeIdentifier, certificateId.

2. Limites de taille de charge utile

  • maximum upload size limit = 5 * 1024 * 1024 (5 Mo) : toute charge utile dépassant 5 mégaoctets est rejetée immédiatement avec un code HTTP 413.
  • MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024 (1 Mo) : dans les archives compressées, aucun fichier individuel ne peut excéder 1 Mo.
  • MAX_ZIP_ENTRIES = 250 : protège contre les attaques par bombe de décompression (zip bomb).
  • MAX_PLIST_DEPTH = 32 : protège contre l'expansion récursive d'entités.

3. Prévention de la pollution de prototype

Tout objet JSON entrant contenant __proto__, constructor ou prototype est détecté et assaini avant la construction de l'objet.

Exporter un modèle (tableau de bord & API REST)

Dans le tableau de bord

  1. 1
    Ouvrez le modèle dans l'éditeur visuel.
  2. 2
    Cliquez sur le menu Plus d'actions (...) dans la barre de commandes supérieure.
  3. 3
    Sélectionnez Exporter en JSON (Export as JSON).
  4. 4
    Le navigateur télécharge immédiatement <template-slug>-export.json.

Via l'API REST

GET /api/v1/templates/:templateId/export?format=json
En-têtes
X-API-Key <API_KEY>
BASH
curl -X GET "https://api.passinstance.com/api/v1/templates/tmpl_01h9x8k7m6n5p4/export?format=json" \
  -H "X-API-Key: <API_KEY>" \
  -o template-export.json

Importer un modèle (tableau de bord & API REST)

1. Importer en tant que nouveau modèle (POST /api/v1/templates/import)

Crée un tout nouveau modèle dans l'espace de travail de destination :

BASH
curl -X POST "https://api.passinstance.com/api/v1/templates/import" \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d @template-export.json

Réponse HTTP (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_new_destination_01",
    "name": "Artisan Coffee Club - Gold Tier",
    "kind": "storeCard",
    "status": "PUBLISHED",
    "versionNumber": 1,
    "rowKind": "PRODUCTION",
    "createdAt": "2026-11-16T20:45:00.000Z"
  },
  "statusCode": 201
}

2. Importer dans un brouillon existant (POST /api/v1/templates/:id/import-draft)

Met à jour la révision de travail DRAFT d'un modèle existant sans altérer les passes publiés en production :

BASH
curl -X POST "https://api.passinstance.com/api/v1/templates/tmpl_existing_01/import-draft" \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d @template-export.json

Dépannage de l'export & de l'import

Symptôme / ErreurCause racineRésolution
Unrecognized format identifierLe JSON ne contient pas "format": "passinstance-template" ou utilise un format inconnu.Vérifiez que la racine JSON inclut "format": "passinstance-template" et "version": 1.
Payload exceeds 5MB limitDes images volumineuses ou des actifs binaires sont intégrés dans le JSON.Supprimez les données base64 brutes et téléversez les images via l'endpoint de gestion d'actifs ou l'interface du tableau de bord.
Certificate not assignedLe modèle exporté n'embarque pas les certificats de signature.Ce comportement est intentionnel. Après l'import, accédez aux Paramètres du modèle et associez les identifiants Apple Wallet et Google Wallet de l'espace de travail cible.

Poursuivez avec Organiser vos modèles & passes pour gérer vos catalogues de modèles, ou consultez Versions de modèles & publication pour promouvoir vos brouillons importés en production.

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.