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
sandboxvers un espaceproductionsans 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
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 :
{
"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
Ouvrez le modèle dans l'éditeur visuel.
-
2
Cliquez sur le menu Plus d'actions (...) dans la barre de commandes supérieure.
-
3
Sélectionnez Exporter en JSON (Export as JSON).
-
4
Le navigateur télécharge immédiatement
<template-slug>-export.json.
Via l'API REST
/api/v1/templates/:templateId/export?format=json
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 :
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)
{
"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 :
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 / Erreur | Cause racine | Résolution |
|---|---|---|
Unrecognized format identifier | Le 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 limit | Des 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 assigned | Le 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.
