Ü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
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 Ebene | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | Ja | Menschenlesbarer Name der Vorlage (z. B. "Artisan Coffee Club"). Max. 255 Zeichen. |
kind | PassKind | Ja | Pass-Typ-Geometrie: storeCard, coupon, eventTicket, boardingPass, generic oder posterGeneric. |
organizationName | string | Ja | Organisationsname, der auf Apple- und Google-Wallet-Pässen angezeigt wird. |
description | string | Ja | Barrierefreie Beschreibung des Passes, die von Apple PassKit vorausgesetzt wird. |
status | Vorlagenstatus | Nein | Anfangsstatus. Standardmäßig PUBLISHED bei programmgesteuerter Erstellung. |
colors | request payload | Nein | Objekt mit backgroundColor, foregroundColor, labelColor und stripColor. |
barcode | request payload | Nein | Barcode-Konfiguration (format, messageEncoding, altText, addSecurityAnimation). |
fields | request payload | Nein | Nach Zonen gruppierte Feldsammlungen (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields). |
locations | request payload[] | Nein | Array aus bis zu 10 GPS-Koordinaten, die Sperrbildschirm-Benachrichtigungen auslösen. |
beacons | request payload[] | Nein | Array aus bis zu 10 Bluetooth-iBeacons zur Näherungserkennung in Innenräumen. |
expiration | request payload | Nein | Gü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:
{
"backgroundColor": "rgb(24, 24, 27)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(161, 161, 170)",
"stripColor": "rgb(255, 255, 255)"
}
Das Unterobjekt barcode
{
"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
Normalisierung der Pass-Art: Übersetzt ältere oder alternative Stilbezeichnungen (z. B.
store_card->storeCard,event_ticket->eventTicket,boarding_pass->boardingPass). -
2
Erkennung des Transit-Typs: Bei
boardingPass-Pässen werdentransitType-Zeichenketten abgebildet (PKTransitTypeAir,PKTransitTypeTrain,PKTransitTypeBus,PKTransitTypeBoat,PKTransitTypeGeneric). -
3
Prüfung der Feldplatzierung: Stellt sicher, dass Felder in
auxiliaryFieldsden Regeln der jeweiligen Pass-Art entsprechen (z. B. lehnencoupon-Pässe Zusatzfelder ab und leiten sie insecondaryFieldsum). -
4
Automatische Barcode-Fallback-Zuweisung: Ist ein 1D-Barcode (
Code 128,Code 39,EAN-13) ohne Fallback konfiguriert, weist der Normalizer automatischPKBarcodeFormatQRals Fallback-Barcode für die Apple Watch zu. -
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
/api/v1/templates
{
"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)
{
"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-Status | Fehlermeldung | Ursache & Lösung |
|---|---|---|
| 400 Bad Request | Template icon is required | Bei 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 Request | Invalid 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 Request | Auxiliary fields are not supported on coupon passes | Der 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 Large | Import payload exceeds 5MB limit | Der 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.
