Overzicht
Passinstance biedt native ondersteuning voor het programmatisch aanmaken en configureren van passjablonen via JSON-payloads. In plaats van visuele indelingen, barcodecoderingen, kleuren en dynamische attributen handmatig in te stellen in de Visuele editor, kunnen ontwikkelaars en platformintegrators volledige sjabloonschema's aanleveren via de REST API (POST /api/v1/templates of POST /api/v1/templates/import).
De backend-sjabloonengine verwerkt inkomende JSON via de normalisatie- en validatiepipeline met automatische schemanormalisatie, valideert pasgeometrieën, handhaaft de kleurinvarianten van Apple Wallet en Google Wallet en registreert aangepaste eigenschappen.
Systeemarchitectuur: JSON-sjabloonimportpipeline
JSON-schemaspecificatie voor request payload
Een geldige JSON-sjabloondefinitie moet voldoen aan de request payload-structuur die wordt geaccepteerd door POST /api/v1/templates:
| Eigenschap op hoofdniveau | Type | Verplicht | Beschrijving |
|---|---|---|---|
name | string | Ja | Leesbare naam van het sjabloon (bijv. "Artisan Coffee Club"). Maximaal 255 tekens. |
kind | PassKind | Ja | Geometrie van het pastype: storeCard, coupon, eventTicket, boardingPass, generic of posterGeneric. |
organizationName | string | Ja | Organisatienaam die op Apple Wallet- en Google Wallet-passen wordt weergegeven. |
description | string | Ja | Toegankelijke beschrijving van de pas, vereist door Apple PassKit. |
status | sjabloonstatus | Nee | Initiële status. Standaard PUBLISHED bij programmatische aanmaak. |
colors | request payload | Nee | Object met backgroundColor, foregroundColor, labelColor en stripColor. |
barcode | request payload | Nee | Barcodeconfiguratie (format, messageEncoding, altText, addSecurityAnimation). |
fields | request payload | Nee | Veldverzamelingen gegroepeerd per zone (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields). |
locations | request payload[] | Nee | Array van maximaal 10 GPS-coördinaten die meldingen op het toegangsscherm activeren. |
beacons | request payload[] | Nee | Array van maximaal 10 Bluetooth iBeacons voor nabijheidsdetectie binnenshuis. |
expiration | request payload | Nee | Geldigheids- en vervalstrategie van de pas (none, fixed of duration). |
Het subobject colors
Apple Wallet vereist strikt het CSS RGB-formaat (rgb(r, g, b)) voor kleuren en weigert hex-waarden of alfakanalen. Bij het importeren van JSON via Passinstance accepteert de normalizer zowel hex- als RGB-notatie en serialiseert hij het exact vereiste formaat voor elke wallet-provider:
{
"backgroundColor": "rgb(24, 24, 27)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(161, 161, 170)",
"stripColor": "rgb(255, 255, 255)"
}
Het subobject barcode
{
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{cardNumber}",
"addSecurityAnimation": true
}
Ondersteunde formaten zijn onder andere: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5 en PKBarcodeFormatNone.
Validatie- & normalisatieregels (normalizeTemplateImport)
Wanneer ruwe JSON wordt ingediend bij POST /api/v1/templates/import, voert de backend normalizeTemplateImport uit:
-
1
Normalisatie van pastype: Vertaalt verouderde of alternatieve stijlbenamingen (zoals
store_card->storeCard,event_ticket->eventTicket,boarding_pass->boardingPass). -
2
Detectie van vervoerstype: Koppelt voor
boardingPass-passentransitType-strings (PKTransitTypeAir,PKTransitTypeTrain,PKTransitTypeBus,PKTransitTypeBoat,PKTransitTypeGeneric). -
3
Begrenzing van veldplaatsing: Controleert of velden in
auxiliaryFieldsvoldoen aan de regels van het pastype (coupon-passen weigeren bijvoorbeeld hulpvelden en plaatsen ze automatisch insecondaryFields). -
4
Automatische barcode-fallback: Als een 1D-barcode (
Code 128,Code 39,EAN-13) zonder fallback wordt geconfigureerd, wijst de normalizer automatischPKBarcodeFormatQRtoe als fallback-barcode voor de Apple Watch. -
5
Verwijderen van systeemsleutels: Verwijdert geruisloos gevoelige tenant- of interne systeemsleutels (
id,customerId,tenantId,certificateId,version,status,passes,createdAt,updatedAt,archivedAt).
API-referentie: een sjabloon maken vanuit JSON
HTTP-verzoek
/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-respons (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
}
Veelvoorkomende fouten bij JSON-import & oplossingen
| HTTP-status | Foutmelding | Oorzaak & oplossing |
|---|---|---|
| 400 Bad Request | Template icon is required | Wanneer sjablonen via JSON worden aangemaakt zonder bestaande basisassets, moet een icon-asset of data-URI worden meegegeven, of een bestaande asset-ID uit de werkruimte worden toegewezen. |
| 400 Bad Request | Invalid color format: must be rgb(r, g, b) | Een kleurstring bevatte alfakanalen (rgba(0,0,0,0.5)) of een ongeldige syntaxis. Geef een standaard rgb(r, g, b) of 6-cijferige hex-waarde (#RRGGBB) op. |
| 400 Bad Request | Auxiliary fields are not supported on coupon passes | De payload bevatte auxiliaryFields voor het pastype coupon. Verplaats hulpvelden naar secondaryFields of wijzig het pastype naar storeCard. |
| 413 Payload Too Large | Import payload exceeds 5MB limit | De JSON-payload overschreed de maximale uploadlimiet van 5 MB, meestal door ingesloten base64-afbeeldingen. Upload afbeeldingen in plaats daarvan via het endpoint voor afbeeldingsassets. |
Ga verder naar Importeren vanuit Apple Pass Designer om bestaande .passdesign-projecten te importeren, of bekijk Dynamische velden & personalisatie om attribuutvariabelen in te richten.
