Overzicht
Passinstance ondersteunt het exporteren en importeren van volledige sjabloondefinities als gestructureerde, draagbare JSON-bestanden. Deze functionaliteit maakt het volgende mogelijk:
-
Omgevingsmigratie: Geteste passjablonen overzetten van een
sandbox-werkruimte naar eenproduction-werkruimte zonder handmatige heropbouw. -
Back-up & noodherstel: Canonieke sjabloonconfiguraties opslaan in Git-repositories of versiebeheersystemen (Configuration as Code).
-
Sjablonen delen & klonen: Gestandaardiseerde loyaliteits-, ticket- of lidmaatschapsontwerpen verspreiden over verschillende klantaccounts of franchisenemers.
Geëxporteerde bestanden volgen de canonieke Passinstance-exportspecificatie (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', schemaversie 1), geïmplementeerd in template-import-export.util.ts. Systeemidentificatoren, primaire databasesleutels, tenant-ID's en cryptografische ondertekeningscertificaten worden automatisch verwijderd om multi-tenantbeveiliging te garanderen en identiteitsconflicten te voorkomen.
Systeemarchitectuur: workflow voor sjabloonexport & -import
Specificatie van het Passinstance-sjabloonexportformaat
De exportgenerator (buildSanitizedTemplateExportPayload) produceert een gestandaardiseerde JSON-envelop conform TEMPLATE_EXPORT_SCHEMA_VERSION = 1:
{
"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
}
}
}
Beveiligings- & sanitatie-invarianten
Om strikte tenantisolatie te waarborgen en cryptografische assets te beschermen, handhaaft Passinstance tijdens export en import vijf kerninvarianten voor beveiliging (template-import-export.util.ts:25-34):
1. Verwijderen van systeemsleutels
De volgende sleutels worden strikt verwijderd uit exportpayloads en geweigerd tijdens import:
-
Primaire en vreemde sleutels:
id,customerId,tenantId,baseId,groupId. -
Revisiemetadata:
versionNumber,version,rowKind,status. -
Pashoudergegevens:
passes,activePassesCount. -
Tijdstempels:
createdAt,updatedAt,archivedAt. -
Apple Developer-identiteit:
teamIdentifier,passTypeIdentifier,certificateId.
2. Limieten voor payloadgrootte
-
Maximale uploadgrootte =
5 * 1024 * 1024(5 MB): Payloads groter dan 5 megabyte worden direct geweigerd met HTTP 413. -
MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024(1 MB): Voor gecomprimeerde pakketten mag geen enkel afzonderlijk bestand groter zijn dan 1 MB. -
MAX_ZIP_ENTRIES = 250: Voorkomt decompressie-aanvallen met zip-bommen. -
MAX_PLIST_DEPTH = 32: Voorkomt recursieve entiteitsexpansie.
3. Bescherming tegen prototype-vervuiling
Elk inkomend JSON-object met __proto__, constructor of prototype wordt gemarkeerd en opgeschoond voordat objecten worden aangemaakt.
Een sjabloon exporteren (Dashboard & REST API)
In het Dashboard
-
1
Open het sjabloon in de Visuele editor.
-
2
Klik op het menu Meer acties (...) in de bovenste CommandBar.
-
3
Kies Exporteren als JSON.
-
4
De browser downloadt direct
<template-slug>-export.json.
Via de REST API
/api/v1/templates/:templateId/export?format=json
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
Een sjabloon importeren (Dashboard & REST API)
1. Importeren als nieuw sjabloon (POST /api/v1/templates/import)
Maakt een volledig nieuw sjabloon aan in de doelwerkruimte:
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-respons (201 Created)
{
"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. Importeren in een bestaand concept (POST /api/v1/templates/:id/import-draft)
Werkt de actieve DRAFT-revisie van een bestaand sjabloon bij zonder live gepubliceerde passen aan te passen:
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
Probleemoplossing bij export & import
| Symptoom / foutmelding | Oorzaak | Oplossing |
|---|---|---|
Unrecognized format identifier | De JSON mist "format": "passinstance-template" of gebruikt een onbekend formaat. | Controleer of de hoofd-JSON "format": "passinstance-template" en "version": 1 bevat. |
Payload exceeds 5MB limit | Grote afbeeldingen of binaire assets zijn rechtstreeks in de JSON opgenomen. | Verwijder ruwe base64-gegevens en upload afbeeldingen via het endpoint voor assetbeheer of de gebruikersinterface van het dashboard. |
Certificate not assigned | Geëxporteerde sjablonen bevatten geen ondertekeningscertificaten. | Dit is opzettelijk. Ga na het importeren naar Sjablooninstellingen en koppel de Apple- en Google Wallet-inloggegevens van de doelwerkruimte. |
Ontdek vervolgens Sjablonen & passen organiseren om sjablooncatalogi te beheren, of lees Sjabloonversies & publiceren om geïmporteerde concepten naar productie te brengen.
