Skip to content
Hilfecenter-Anleitung · Pass-Vorlagen
3 Min. LesezeitGeprüft 2026-11-16

Als JSON exportieren und importieren

Sichern, wiederherstellen und übertragen Sie Pass-Vorlagen arbeitsbereichsübergreifend mit bereinigten JSON-Schemas und Sicherheitsrichtlinien.

In dieser Anleitung

Ü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 einen production-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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
VORLAGEN-EXPORT- & IMPORT-PIPELINE
STUFE 01 QUELL-WORKSPACE (Sandbox / Testumgebung)
Vorlage mit Feldern, benutzerdefinierten Eigenschaften, Farben, Barcodes & Co.
STUFE 02 EXPORT-BEREINIGUNGS-ENGINE (Template Export Engine)
buildSanitizedTemplateExportPayload
1
Fügt Umschlag ein: format: 'passinstance-template', version: 1
2
Entfernt Mandantengrenzen: customerId, tenantId, id, certificateId
3
Entfernt Apple-Anmeldedaten: teamIdentifier, passTypeIdentifier
4
Kodiert Retina-Bild-Referenzen oder portable CDN-URLs
STUFE 03 PORTABLES JSON-ARTEFAKT (template-export.json)
Sauberes, menschenlesbares JSON-Schema
Unabhängig von Datenbank-Zeilen-IDs oder Mandantengeheimnissen
STUFE 04 IMPORT-VALIDIERUNGS- & SICHERHEITS-ENGINE
normalizeTemplateImport
1
Größenprüfung: maximum upload size limit = 5 * 1024 * 1024 (max. 5 MB)
2
Prototype-Pollution-Schutz: Entfernt __proto__, constructor, prototype
3
Gleicht benutzerdefinierte Eigenschaften ab & legt GIN-Indizes in Zieldatenbank an
4
Weist Ziel-Workspace-Zertifikat zu & bindet lokale Mandantengrenze
STUFE 05 ZIEL-WORKSPACE (Produktion / Live)
Neue Template mit status: PUBLISHED (oder aktualisierte DRAFT-Revision)
Sofort bereit für Live-Ausgabe, PassFlow-Registrierung & CSV-Stapelkampagnen

Spezifikation des Passinstance-Vorlagen-Exportformats

Der Exportgenerator (buildSanitizedTemplateExportPayload) erzeugt einen standardisierten JSON-Umschlag gemäß 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
    }
  }
}

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. 1
    Öffnen Sie die Vorlage im Visuellen Editor.
  2. 2
    Klicken Sie in der oberen CommandBar auf das Menü Weitere Aktionen (...).
  3. 3
    Wählen Sie Als JSON exportieren.
  4. 4
    Der Browser lädt unmittelbar <template-slug>-export.json herunter.

Über die REST-API

GET /api/v1/templates/:templateId/export?format=json
Header
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

Vorlage importieren (Dashboard & REST-API)

1. Als neue Vorlage importieren (POST /api/v1/templates/import)

Erstellt eine vollständig neue Vorlage im Ziel-Workspace:

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

HTTP-Antwort (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. 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:

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

Fehlerbehebung bei Export & Import

Symptom / FehlerUrsacheLösung
Unrecognized format identifierIm 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 limitGroß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 assignedExportierte 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.

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.