Skip to content
Guida del Centro assistenza · Modelli di pass
3 min di letturaVerificato 2026-11-16

Esportare e importare come JSON

Esegui backup, ripristino e trasferimento di modelli di pass tra aree di lavoro utilizzando schemi JSON igienizzati e protezioni di sicurezza.

In questa guida

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 sandbox a un workspace production senza 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

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PIPELINE DI ESPORTAZIONE E IMPORTAZIONE MODELLI
FASE 01 WORKSPACE DI ORIGINE (Sandbox / Test)
Modello con campi, proprietà personalizzate, colori, barcode e regole
FASE 02 MOTORE DI SANITIZZAZIONE EXPORT (Template Export Engine)
buildSanitizedTemplateExportPayload
1
Inserisce involucro: format: 'passinstance-template', version: 1
2
Rimuove confini tenant: customerId, tenantId, id, certificateId
3
Rimuove credenziali Apple: teamIdentifier, passTypeIdentifier
4
Codifica riferimenti asset retina o URL CDN portatili
FASE 03 ARTEFATTO JSON PORTATILE (template-export.json)
Schema JSON pulito e leggibile
Indipendente dagli ID di riga del database o dai segreti del tenant
FASE 04 MOTORE DI VALIDAZIONE E SICUREZZA IN IMPORTAZIONE
normalizeTemplateImport
1
Controllo dimensione: impone maximum upload size limit = 5 * 1024 * 1024
2
Protezione Prototype Pollution: rimuove __proto__, constructor, prototype
3
Riconcilia proprietà personalizzate e crea indici GIN nel DB di destinazione
4
Assegna il certificato del workspace destinazione e vincola il tenant locale
FASE 05 WORKSPACE DI DESTINAZIONE (Production / Live)
Nuovo Template creato con status: PUBLISHED (o revisione DRAFT aggiorn.)
Pronto per emissione live, iscrizioni PassFlow e campagne batch CSV

Specifica del formato di esportazione modelli Passinstance

Il generatore di esportazione (buildSanitizedTemplateExportPayload) produce un involucro JSON standardizzato conforme a 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
    }
  }
}

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. 1
    Apri il modello nell'Editor visuale.
  2. 2
    Fai clic sul menu Altre azioni (...) nella CommandBar in alto.
  3. 3
    Seleziona Esporta come JSON.
  4. 4
    Il browser scarica immediatamente <template-slug>-export.json.

Tramite REST API

GET /api/v1/templates/:templateId/export?format=json
Header
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

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:

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

Risposta HTTP (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. 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:

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

Risoluzione dei problemi di esportazione e importazione

Sintomo / ErroreCausa principaleSoluzione
Unrecognized format identifierIl 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 limitImmagini 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 assignedIl 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.

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.