Panoramica
Passinstance consente di esportare e importare definizioni complete di modelli come file JSON strutturati e portatili. Questa funzionalità abilita:
-
Migrazione tra ambienti: promuovi modelli di pass già testati da un workspace
sandboxa un workspaceproductionsenza ricrearli manualmente. -
Backup e disaster recovery: archivia configurazioni canoniche dei modelli in repository Git o sistemi di controllo versione (Configuration as Code).
-
Condivisione e clonazione dei modelli: distribuisci layout standardizzati di carte fedeltà, biglietti o tessere socio tra diversi account cliente o affiliati in franchising.
I file esportati utilizzano la specifica canonica di esportazione Passinstance (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', versione schema 1) implementata in template-import-export.util.ts. Identificatori di sistema, chiavi primarie del database, ID del tenant e certificati crittografici di firma vengono rimossi automaticamente per garantire la sicurezza multi-tenant ed evitare conflitti di identità.
Architettura di sistema: flusso di esportazione e importazione modelli
Specifica del formato di esportazione modelli Passinstance
Il generatore di esportazione (buildSanitizedTemplateExportPayload) produce un involucro JSON standardizzato conforme a 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
}
}
}
Invarianti di sicurezza e sanitizzazione
Per mantenere un rigoroso isolamento tra tenant e proteggere le risorse crittografiche, Passinstance applica i seguenti invarianti di sicurezza durante esportazione e importazione (template-import-export.util.ts:25-34):
1. Rimozione delle chiavi di sistema
Le seguenti chiavi vengono rigorosamente rimosse dai payload di esportazione e rifiutate in fase di importazione:
-
Chiavi primarie ed esterne:
id,customerId,tenantId,baseId,groupId. -
Metadati di revisione:
versionNumber,version,rowKind,status. -
Record dei titolari:
passes,activePassesCount. -
Timestamp:
createdAt,updatedAt,archivedAt. -
Identità Apple Developer:
teamIdentifier,passTypeIdentifier,certificateId.
2. Limiti di dimensione del payload
-
maximum upload size limit = 5 * 1024 * 1024(5 MB): i payload superiori a 5 megabyte vengono respinti immediatamente con HTTP 413. -
MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024(1 MB): per i pacchetti compressi, i singoli file non possono superare 1 MB. -
MAX_ZIP_ENTRIES = 250: previene attacchi di decompressione zip bomb. -
MAX_PLIST_DEPTH = 32: previene l'espansione ricorsiva delle entità.
3. Prevenzione della Prototype Pollution
Qualsiasi oggetto JSON in ingresso contenente __proto__, constructor o prototype viene rilevato e sanitizzato prima della costruzione dell'oggetto.
Esportazione di un modello (Dashboard e REST API)
Nella Dashboard
-
1
Apri il modello nell'Editor visuale.
-
2
Fai clic sul menu Altre azioni (...) nella CommandBar in alto.
-
3
Seleziona Esporta come JSON.
-
4
Il browser scarica immediatamente
<template-slug>-export.json.
Tramite 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
Importazione di un modello (Dashboard e REST API)
1. Importa come nuovo modello (POST /api/v1/templates/import)
Crea un modello completamente nuovo nel workspace di destinazione:
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
Risposta HTTP (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. Importa in una bozza esistente (POST /api/v1/templates/:id/import-draft)
Aggiorna la revisione di lavoro DRAFT di un modello esistente senza modificare i pass già pubblicati e attivi:
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
Risoluzione dei problemi di esportazione e importazione
| Sintomo / Errore | Causa principale | Soluzione |
|---|---|---|
Unrecognized format identifier | Il JSON è privo di "format": "passinstance-template" oppure usa un formato sconosciuto. | Assicurati che l'oggetto JSON radice includa "format": "passinstance-template" e "version": 1. |
Payload exceeds 5MB limit | Immagini di grandi dimensioni o asset binari sono incorporati nel JSON. | Rimuovi i dati base64 grezzi e carica le immagini tramite l'endpoint di gestione asset o l'interfaccia della dashboard. |
Certificate not assigned | Il modello esportato non trasporta i certificati di firma. | Questo comportamento è intenzionale. Dopo l'importazione, vai in Impostazioni modello e associa le credenziali Apple Wallet e Google Wallet del workspace di destinazione. |
Successivamente, approfondisci Organizzare modelli e pass per gestire i cataloghi di modelli oppure leggi Versioni dei modelli e pubblicazione per promuovere in produzione le bozze importate.
