Überblick
Passinstance unterstützt den Export und Import vollständiger Vorlagendefinitionen als strukturierte, portable JSON-Dateien. Diese Funktion ermöglicht:
-
Umgebungsmigration: Übertragen getesteter Pass-Vorlagen aus einem
sandbox-Workspace in einenproduction-Workspace ohne manuelles Nachbauen. -
Backup & Notfallwiederherstellung: Ablage kanonischer Vorlagenkonfigurationen in Git-Repositories oder Versionskontrollsystemen (Configuration as Code).
-
Teilen & Klonen von Vorlagen: Verteilung standardisierter Treue-, Ticket- oder Mitgliedschaftslayouts auf verschiedene Kundenkonten oder Franchisenehmer.
Exportierte Dateien nutzen die kanonische Passinstance-Exportspezifikation (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', Schemaversion 1), implementiert in template-import-export.util.ts. Systemkennungen, Datenbank-Primärschlüssel, Mandanten-IDs und kryptografische Signaturzertifikate werden automatisch entfernt, um strenge Mandantenisolierung zu gewährleisten und Identitätskollisionen auszuschließen.
Systemarchitektur: Workflow für Vorlagen-Export & -Import
Spezifikation des Passinstance-Vorlagen-Exportformats
Der Exportgenerator (buildSanitizedTemplateExportPayload) erzeugt einen standardisierten JSON-Umschlag gemäß 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
}
}
}
Sicherheits- & Bereinigungsinvarianten
Um strikte Mandantenisolierung aufrechtzuerhalten und kryptografische Assets zu schützen, setzt Passinstance beim Export und Import fünf zentrale Sicherheitsinvarianten durch (template-import-export.util.ts:25-34):
1. Entfernung von Systemschlüsseln
Die folgenden Schlüssel werden beim Export strikt entfernt und beim Import abgelehnt:
-
Primär- und Fremdschlüssel:
id,customerId,tenantId,baseId,groupId. -
Revisionsmetadaten:
versionNumber,version,rowKind,status. -
Passinhaber-Datensätze:
passes,activePassesCount. -
Zeitstempel:
createdAt,updatedAt,archivedAt. -
Apple-Developer-Identität:
teamIdentifier,passTypeIdentifier,certificateId.
2. Payload-Größenbegrenzungen
-
maximum upload size limit = 5 * 1024 * 1024(5 MB): Payloads über 5 Megabyte werden sofort mit HTTP 413 abgelehnt. -
MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024(1 MB): Bei gezippten Paketen darf ein einzelner Eintrag 1 MB nicht überschreiten. -
MAX_ZIP_ENTRIES = 250: Verhindert Zip-Bomb-Dekomprimierungsangriffe. -
MAX_PLIST_DEPTH = 32: Verhindert rekursive Entity-Expansion.
3. Schutz vor Prototype Pollution
Jedes eingehende JSON-Objekt, das __proto__, constructor oder prototype enthält, wird vor der Objekterzeugung erkannt und bereinigt.
Vorlage exportieren (Dashboard & REST-API)
Im Dashboard
-
1
Öffnen Sie die Vorlage im Visuellen Editor.
-
2
Klicken Sie in der oberen CommandBar auf das Menü Weitere Aktionen (...).
-
3
Wählen Sie Als JSON exportieren.
-
4
Der Browser lädt unmittelbar
<template-slug>-export.jsonherunter.
Über die REST-API
/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
Vorlage importieren (Dashboard & REST-API)
1. Als neue Vorlage importieren (POST /api/v1/templates/import)
Erstellt eine vollständig neue Vorlage im Ziel-Workspace:
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
HTTP-Antwort (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. In einen bestehenden Entwurf importieren (POST /api/v1/templates/:id/import-draft)
Aktualisiert die DRAFT-Arbeitsrevision einer vorhandenen Vorlage, ohne live veröffentlichte Pässe zu verändern:
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
Fehlerbehebung bei Export & Import
| Symptom / Fehler | Ursache | Lösung |
|---|---|---|
Unrecognized format identifier | Im JSON fehlt "format": "passinstance-template" oder es wird ein unbekanntes Format verwendet. | Stellen Sie sicher, dass das JSON-Stammobjekt "format": "passinstance-template" und "version": 1 enthält. |
Payload exceeds 5MB limit | Große Bilder oder Binär-Assets sind direkt im JSON eingebettet. | Entfernen Sie rohe Base64-Daten und laden Sie Bilder über den Asset-Management-Endpunkt oder die Dashboard-Oberfläche hoch. |
Certificate not assigned | Exportierte Vorlagen enthalten keine Signaturzertifikate. | Dies ist beabsichtigt. Navigieren Sie nach dem Import zu Vorlageneinstellungen und weisen Sie die Apple- und Google-Wallet-Zugangsdaten des Ziel-Workspace zu. |
Lesen Sie als Nächstes Vorlagen & Pässe organisieren, um Vorlagenkataloge strukturiert zu verwalten, oder informieren Sie sich unter Vorlagenversionen & Veröffentlichung, wie importierte Entwürfe in die Produktion überführt werden.
