Skip to content
Helpcentrum-gids · Pass-sjablonen
4 min leestijdGecontroleerd 2026-11-16

Template maken vanuit JSON

Importeer en configureer pass-templates programmatisch via JSON-definities, schemavalidatie en normalisatieregels.

In deze gids

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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
JSON-SJABLOONIMPORTPIPELINE
FASE 01 EXTERNE CLIENT / AUTOMATISERINGSSCRIPT
Stuurt JSON-document via POST/api/v1/templates of POST.../templates/import
Codeert pastypen, kleuren, veldindelingzones, barcodes en relevantieregels
FASE 02 SJABLOONIMPORT- & NORMALISATIEPIPELINE
normalizeTemplateImport (template-import-export.util.ts)
1
Groottebewaking: Handhaaft maximale uploadgrootte = 5 * 1024 * 1024 (5 MB)
2
Beveiligingssanitatie: Verwijdert systeemsleutels (id, customerId, enz.)
3
Prototype-vervuilingscheck: Weigert __proto__, constructor, prototype
4
Kleurnormalisatie: Zet hex-/RGB-strings om naar canoniek rgb(r, g, b)
5
Barcode- & vervoersmapping: Vertaalt Apple PassKit-enums naar canoniek formaat
FASE 03 DATABASE-RECONCILER (Template Engine)
Slaat Template-entiteit op met status: PUBLISHED
Maakt relationele entiteiten aan: Field[], Color, Barcode, Location[]
Initialiseert snelle zoekindex op Pass.attributes voor opgegeven properties
FASE 04A APPLE WALLET-COMPILATIE
Genereert basis-pass.json-structuur en verpakt standaard iconen/beelden
FASE 04B GOOGLE WALLET CLASS-AANMAAK
Maakt Google Wallet Class via SDK (bijv. LoyaltyClass, EventClass)

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 hoofdniveauTypeVerplichtBeschrijving
namestringJaLeesbare naam van het sjabloon (bijv. "Artisan Coffee Club"). Maximaal 255 tekens.
kindPassKindJaGeometrie van het pastype: storeCard, coupon, eventTicket, boardingPass, generic of posterGeneric.
organizationNamestringJaOrganisatienaam die op Apple Wallet- en Google Wallet-passen wordt weergegeven.
descriptionstringJaToegankelijke beschrijving van de pas, vereist door Apple PassKit.
statussjabloonstatusNeeInitiële status. Standaard PUBLISHED bij programmatische aanmaak.
colorsrequest payloadNeeObject met backgroundColor, foregroundColor, labelColor en stripColor.
barcoderequest payloadNeeBarcodeconfiguratie (format, messageEncoding, altText, addSecurityAnimation).
fieldsrequest payloadNeeVeldverzamelingen gegroepeerd per zone (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields).
locationsrequest payload[]NeeArray van maximaal 10 GPS-coördinaten die meldingen op het toegangsscherm activeren.
beaconsrequest payload[]NeeArray van maximaal 10 Bluetooth iBeacons voor nabijheidsdetectie binnenshuis.
expirationrequest payloadNeeGeldigheids- 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:

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

Het subobject barcode

JSON
{
  "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. 1
    Normalisatie van pastype: Vertaalt verouderde of alternatieve stijlbenamingen (zoals store_card -> storeCard, event_ticket -> eventTicket, boarding_pass -> boardingPass).
  2. 2
    Detectie van vervoerstype: Koppelt voor boardingPass-passen transitType-strings (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric).
  3. 3
    Begrenzing van veldplaatsing: Controleert of velden in auxiliaryFields voldoen aan de regels van het pastype (coupon-passen weigeren bijvoorbeeld hulpvelden en plaatsen ze automatisch in secondaryFields).
  4. 4
    Automatische barcode-fallback: Als een 1D-barcode (Code 128, Code 39, EAN-13) zonder fallback wordt geconfigureerd, wijst de normalizer automatisch PKBarcodeFormatQR toe als fallback-barcode voor de Apple Watch.
  5. 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

POST /api/v1/templates
Headers
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-respons (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
}

Veelvoorkomende fouten bij JSON-import & oplossingen

HTTP-statusFoutmeldingOorzaak & oplossing
400 Bad RequestTemplate icon is requiredWanneer 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 RequestInvalid 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 RequestAuxiliary fields are not supported on coupon passesDe payload bevatte auxiliaryFields voor het pastype coupon. Verplaats hulpvelden naar secondaryFields of wijzig het pastype naar storeCard.
413 Payload Too LargeImport payload exceeds 5MB limitDe 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.

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.