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

Exporteren en importeren als JSON

Maak back-ups, herstel en verplaats pass-templates tussen werkruimten met gestandaardiseerde JSON-schema's en beveiligingsrichtlijnen.

In deze gids

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 een production-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

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
PIPELINE VOOR SJABLOONEXPORT & -IMPORT
FASE 01 BRONWERKRUIMTE (Sandbox / Testomgeving)
Sjabloon met velden, aangepaste eigenschappen, kleuren, barcodes & relevantie
FASE 02 EXPORTSANITATIE-ENGINE (Template Export Engine)
buildSanitizedTemplateExportPayload
1
Voegt envelop toe: format: 'passinstance-template', version: 1
2
Verwijdert tenantgrenzen: customerId, tenantId, id, certificateId
3
Verwijdert Apple-inloggegevens: teamIdentifier, passTypeIdentifier
4
Codeert retina-afbeeldingsreferenties of draagbare CDN-URL's
FASE 03 DRAAGBAAR JSON-ARTEFACT (template-export.json)
Schone, goed leesbare JSON-structuur
Onafhankelijk van databaserij-ID's of tenantgeheimen
FASE 04 IMPORTVALIDATIE- & BEVEILIGINGSENGINE
normalizeTemplateImport
1
Groottebewaking: Handhaaft maximale uploadgrootte = 5 * 1024 * 1024 (5 MB)
2
Prototype-vervuilingscheck: Verwijdert __proto__, constructor, prototype
3
Stemt aangepaste eigenschappen af & maakt GIN-indexen aan in doeldatabase
4
Wijst certificaat van doelwerkruimte toe en bindt lokale tenantgrens
FASE 05 DOELWERKRUIMTE (Productie / Live)
Nieuw Template aangemaakt met status: PUBLISHED (of bijgewerkte DRAFT)
Klaar voor live uitgifte, PassFlow-inschrijving en CSV-batchcampagnes

Specificatie van het Passinstance-sjabloonexportformaat

De exportgenerator (buildSanitizedTemplateExportPayload) produceert een gestandaardiseerde JSON-envelop conform TEMPLATE_EXPORT_SCHEMA_VERSION = 1:

JSON
{
  "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. 1
    Open het sjabloon in de Visuele editor.
  2. 2
    Klik op het menu Meer acties (...) in de bovenste CommandBar.
  3. 3
    Kies Exporteren als JSON.
  4. 4
    De browser downloadt direct <template-slug>-export.json.

Via de REST API

GET /api/v1/templates/:templateId/export?format=json
Headers
X-API-Key <API_KEY>
BASH
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:

BASH
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)

JSON
{
  "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:

BASH
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 / foutmeldingOorzaakOplossing
Unrecognized format identifierDe 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 limitGrote 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 assignedGeë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.

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.