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

Vorlage aus JSON erstellen

Pass-Vorlagen programmatisch über JSON-Definitionen, Schemavalidierung und Normalisierungsregeln importieren und bereitstellen.

In dieser Anleitung

Überblick

Passinstance unterstützt das programmgesteuerte Erstellen und Konfigurieren von Pass-Vorlagen über JSON-Payloads nativ. Statt visuelle Layouts, Barcode-Kodierungen, Farben und dynamische Attribute manuell im Visuellen Editor einzurichten, können Entwicklerinnen, Entwickler und Plattform-Integratoren vollständige Vorlagenschemata direkt an die REST-API übermitteln (POST /api/v1/templates oder POST /api/v1/templates/import).

Die Backend-Vorlagen-Engine verarbeitet eingehendes JSON in der Normalisierungs- und Validierungs-Pipeline mit automatischer Schemanormalisierung, validiert Pass-Geometrien, setzt Farbinvarianten für Apple Wallet und Google Wallet durch und registriert benutzerdefinierte Eigenschaften.

Systemarchitektur: JSON-Vorlagen-Import-Pipeline

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
JSON-VORLAGEN-IMPORT-PIPELINE
STUFE 01 EXTERNER CLIENT / AUTOMATISIERUNGSSKRIPT
Übermittelt JSON-Dokument an POST/api/v1/templates oder .../templates/import
Kodiert Pass-Arten, Farben, Feldlayout-Zonen, Barcodes & Relevanzregeln
STUFE 02 VORLAGEN-IMPORT- & NORMALISIERUNGS-PIPELINE
normalizeTemplateImport (template-import-export.util.ts)
1
Größenprüfung: Erzwingt maximum upload size limit = 5 * 1024 * 1024 (5 MB)
2
Sicherheitsbereinigung: Entfernt Systemschlüssel (id, customerId, etc.)
3
Prototype-Pollution-Prüfung: Lehnt __proto__, constructor, prototype ab
4
Farbnormalisierung: Wandelt Hex-/RGB-Strings in kanonisches rgb(r, g, b) um
5
Barcode- & Transit-Mapping: Übersetzt Apple-PassKit-Enums in Standardformate
STUFE 03 DATENBANK-ABGLEICH (Template Engine)
Speichert Template-Entität mit status: PUBLISHED
Erstellt relationale Entitäten: Field[], Color, Barcode, Location[]
Initialisiert schnellen Suchindex auf Pass.attributes für definierte Felder
STUFE 04A APPLE-WALLET-KOMPILIERUNG
Erstellt Basis-pass.json-Wörterbuch und bündelt Standard-Seed-Icons/-Bilder
STUFE 04B GOOGLE-WALLET-CLASS-ERSTELLUNG
Erstellt Google Wallet Class per SDK (z. B. LoyaltyClass, EventClass)

JSON-Schema-Spezifikation für request payload

Eine gültige JSON-Vorlagendefinition muss der von POST /api/v1/templates akzeptierten Struktur von request payload entsprechen:

Eigenschaft auf oberster EbeneTypErforderlichBeschreibung
namestringJaMenschenlesbarer Name der Vorlage (z. B. "Artisan Coffee Club"). Max. 255 Zeichen.
kindPassKindJaPass-Typ-Geometrie: storeCard, coupon, eventTicket, boardingPass, generic oder posterGeneric.
organizationNamestringJaOrganisationsname, der auf Apple- und Google-Wallet-Pässen angezeigt wird.
descriptionstringJaBarrierefreie Beschreibung des Passes, die von Apple PassKit vorausgesetzt wird.
statusVorlagenstatusNeinAnfangsstatus. Standardmäßig PUBLISHED bei programmgesteuerter Erstellung.
colorsrequest payloadNeinObjekt mit backgroundColor, foregroundColor, labelColor und stripColor.
barcoderequest payloadNeinBarcode-Konfiguration (format, messageEncoding, altText, addSecurityAnimation).
fieldsrequest payloadNeinNach Zonen gruppierte Feldsammlungen (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields).
locationsrequest payload[]NeinArray aus bis zu 10 GPS-Koordinaten, die Sperrbildschirm-Benachrichtigungen auslösen.
beaconsrequest payload[]NeinArray aus bis zu 10 Bluetooth-iBeacons zur Näherungserkennung in Innenräumen.
expirationrequest payloadNeinGültigkeits- und Ablaufstrategie des Passes (none, fixed oder duration).

Das Unterobjekt colors

Apple Wallet schreibt strikt das CSS-RGB-Format (rgb(r, g, b)) für Farben vor und lehnt Hex-Werte sowie Alpha-Kanäle ab. Beim JSON-Import über Passinstance akzeptiert der Normalizer sowohl Hex- als auch RGB-Syntax und serialisiert das jeweils exakt erforderliche Format für den jeweiligen Wallet-Anbieter:

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

Das Unterobjekt barcode

JSON
{
  "format": "PKBarcodeFormatQR",
  "messageEncoding": "UTF_8",
  "altText": "{cardNumber}",
  "addSecurityAnimation": true
}

Unterstützte Formate sind: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5 und PKBarcodeFormatNone.

Validierungs- & Normalisierungsregeln (normalizeTemplateImport)

Wenn Roh-JSON an POST /api/v1/templates/import gesendet wird, führt das Backend normalizeTemplateImport aus:

  1. 1
    Normalisierung der Pass-Art: Übersetzt ältere oder alternative Stilbezeichnungen (z. B. store_card -> storeCard, event_ticket -> eventTicket, boarding_pass -> boardingPass).
  2. 2
    Erkennung des Transit-Typs: Bei boardingPass-Pässen werden transitType-Zeichenketten abgebildet (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric).
  3. 3
    Prüfung der Feldplatzierung: Stellt sicher, dass Felder in auxiliaryFields den Regeln der jeweiligen Pass-Art entsprechen (z. B. lehnen coupon-Pässe Zusatzfelder ab und leiten sie in secondaryFields um).
  4. 4
    Automatische Barcode-Fallback-Zuweisung: Ist ein 1D-Barcode (Code 128, Code 39, EAN-13) ohne Fallback konfiguriert, weist der Normalizer automatisch PKBarcodeFormatQR als Fallback-Barcode für die Apple Watch zu.
  5. 5
    Entfernung von Systemschlüsseln: Entfernt potenziell kritische Mandanten- oder interne Systemschlüssel stillschweigend (id, customerId, tenantId, certificateId, version, status, passes, createdAt, updatedAt, archivedAt).

API-Referenz: Vorlage aus JSON erstellen

HTTP-Anfrage

POST /api/v1/templates
Header
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."
    }
  ]
}

HTTP-Antwort (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
}

Häufige Fehler beim JSON-Import & Lösungen

HTTP-StatusFehlermeldungUrsache & Lösung
400 Bad RequestTemplate icon is requiredBei der Vorlagenerstellung per JSON ohne vorhandene Seed-Assets muss ein icon-Asset oder eine Data-URI angegeben oder eine bestehende Workspace-Asset-ID zugewiesen werden.
400 Bad RequestInvalid color format: must be rgb(r, g, b)Eine Farbangabe enthielt Alpha-Kanäle (rgba(0,0,0,0.5)) oder ungültige Syntax. Geben Sie standardmäßiges rgb(r, g, b) oder 6-stelliges Hex (#RRGGBB) an.
400 Bad RequestAuxiliary fields are not supported on coupon passesDer Payload enthielt auxiliaryFields für eine coupon-Pass-Art. Verschieben Sie die Zusatzfelder nach secondaryFields oder ändern Sie die Pass-Art auf storeCard.
413 Payload Too LargeImport payload exceeds 5MB limitDer JSON-Payload hat maximum upload size limit (5 MB) überschritten, meist durch eingebettete Base64-Bilddaten. Laden Sie Bilder stattdessen über den Bild-Asset-Endpunkt hoch.

Lesen Sie weiter unter Import aus Apple Pass Designer, um bestehende .passdesign-Projekte zu importieren, oder entdecken Sie Dynamische Felder & Personalisierung, um Attributvariablen zu konfigurieren.

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.