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

Creare un modello da JSON

Importa e configura modelli di pass a livello programmatico tramite definizioni JSON, convalida dello schema e regole di normalizzazione.

In questa guida

Panoramica

Passinstance offre supporto nativo per la creazione e la configurazione programmatica dei modelli di pass tramite payload JSON. Anziché impostare manualmente layout visivi, codifiche dei codici a barre, colori e attributi dinamici nell'Editor visuale, sviluppatori e integratori di piattaforma possono inviare schemi completi del modello alla REST API (POST /api/v1/templates o POST /api/v1/templates/import).

Il motore dei modelli sul backend elabora il JSON in ingresso attraverso la pipeline di normalizzazione e validazione con normalizzazione automatica dello schema, verificando le geometrie dei pass, applicando gli invarianti cromatici di Apple Wallet e Google Wallet e registrando le proprietà personalizzate.

Architettura di sistema: pipeline di importazione modelli JSON

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
PIPELINE DI IMPORTAZIONE MODELLI JSON
FASE 01 CLIENT ESTERNO / SCRIPT DI AUTOMAZIONE
Invia documento JSON via POST/api/v1/templates o POST.../templates/import
Codifica tipi di pass, colori, zone dei campi, codici a barre e regole
FASE 02 PIPELINE DI IMPORTAZIONE E NORMALIZZAZIONE MODELLI
normalizeTemplateImport (template-import-export.util.ts)
1
Controllo dimensione: impone maximum upload size limit = 5 * 1024 * 1024
2
Sanitizzazione sicurezza: rimuove chiavi di sistema (id, customerId, ecc.)
3
Protezione Prototype Pollution: rifiuta __proto__, constructor, prototype
4
Normalizzazione colori: converte hex / RGB nel formato rgb(r, g, b)
5
Mappatura barcode e transito: traduce gli enum Apple PassKit in formati canon.
FASE 03 RICONCILIATORE DATABASE (Template Engine)
Salva l'entità Template con status: PUBLISHED
Crea entità relazionali: Field[], Color, Barcode, Location[]
Inizializza l'indice di ricerca ad alta velocità su Pass.attributes
FASE 04A COMPILAZIONE APPLE WALLET
Genera il dizionario base pass.json e impacchetta icone/immagini iniziali
FASE 04B CREAZIONE CLASSE GOOGLE WALLET
Crea la Google Wallet Class via SDK (es. LoyaltyClass, EventClass)

Specifica dello schema JSON per request payload

Una definizione di modello JSON valida deve rispettare la struttura request payload accettata da POST /api/v1/templates:

Proprietà di primo livelloTipoObbligatoriaDescrizione
namestringSìNome leggibile del modello (ad es. "Artisan Coffee Club"). Max 255 caratteri.
kindPassKindSìGeometria del tipo di pass: storeCard, coupon, eventTicket, boardingPass, generic o posterGeneric.
organizationNamestringSìNome dell'organizzazione visualizzato sui pass Apple Wallet e Google Wallet.
descriptionstringSìDescrizione accessibile del pass richiesta da Apple PassKit.
statusstato del modelloNoStato iniziale. Per impostazione predefinita è PUBLISHED alla creazione programmatica.
colorsrequest payloadNoOggetto contenente backgroundColor, foregroundColor, labelColor e stripColor.
barcoderequest payloadNoConfigurazione del codice a barre (format, messageEncoding, altText, addSecurityAnimation).
fieldsrequest payloadNoRaccolte di campi raggruppate per zona (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields).
locationsrequest payload[]NoArray fino a 10 coordinate GPS che attivano notifiche sulla schermata di blocco.
beaconsrequest payload[]NoArray fino a 10 iBeacon Bluetooth per il rilevamento di prossimità indoor.
expirationrequest payloadNoStrategia di validità e scadenza del pass (none, fixed o duration).

Il sotto-oggetto colors

Apple Wallet richiede rigorosamente il formato CSS RGB (rgb(r, g, b)) per i colori e rifiuta valori esadecimali o canali alfa. Quando importi un file JSON tramite Passinstance, il normalizzatore accetta sia la sintassi esadecimale sia quella RGB e serializza il formato esatto richiesto da ciascun provider Wallet:

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

Il sotto-oggetto barcode

JSON
{
  "format": "PKBarcodeFormatQR",
  "messageEncoding": "UTF_8",
  "altText": "{cardNumber}",
  "addSecurityAnimation": true
}

I formati supportati includono: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5 e PKBarcodeFormatNone.

Regole di validazione e normalizzazione (normalizeTemplateImport)

Quando viene inviato JSON grezzo a POST /api/v1/templates/import, il backend esegue normalizeTemplateImport:

  1. 1
    Normalizzazione del tipo di pass: traduce nomi di stile legacy o alternativi (come store_card -> storeCard, event_ticket -> eventTicket, boarding_pass -> boardingPass).
  2. 2
    Rilevamento del tipo di trasporto: per i pass boardingPass, mappa le stringhe transitType (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric).
  3. 3
    Controllo sul posizionamento dei campi: verifica che i campi inseriti in auxiliaryFields rispettino le regole del tipo di pass (ad es., i pass coupon rifiutano i campi ausiliari e li spostano in secondaryFields).
  4. 4
    Assegnazione del codice a barre di fallback: se viene configurato un codice a barre 1D (Code 128, Code 39, EAN-13) senza fallback, il normalizzatore assegna automaticamente PKBarcodeFormatQR come codice di fallback per Apple Watch.
  5. 5
    Rimozione delle chiavi di sistema: elimina silenziosamente chiavi sensibili del tenant o di sistema (id, customerId, tenantId, certificateId, version, status, passes, createdAt, updatedAt, archivedAt).

Riferimento API: creare un modello da JSON

Richiesta HTTP

POST /api/v1/templates
Header
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."
    }
  ]
}

Risposta HTTP (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
}

Errori comuni di importazione JSON e soluzioni

Stato HTTPMessaggio di erroreCausa principale e soluzione
400 Bad RequestTemplate icon is requiredQuando crei modelli via JSON senza asset predefiniti esistenti, devi fornire un asset icon o un data URI, oppure assegnare l'ID di un asset già presente nel workspace.
400 Bad RequestInvalid color format: must be rgb(r, g, b)Una stringa colore conteneva un canale alfa (rgba(0,0,0,0.5)) o una sintassi malformata. Fornisci un formato standard rgb(r, g, b) o esadecimale a 6 cifre (#RRGGBB).
400 Bad RequestAuxiliary fields are not supported on coupon passesIl payload ha inviato auxiliaryFields per un tipo di pass coupon. Sposta i campi ausiliari in secondaryFields o imposta il tipo di pass su storeCard.
413 Payload Too LargeImport payload exceeds 5MB limitIl payload JSON ha superato maximum upload size limit (5 MB), di solito a causa di immagini base64 incorporate. Carica invece le immagini tramite l'endpoint dedicato agli asset grafici.

Prosegui con Importare da Apple Pass Designer per importare progetti .passdesign esistenti, oppure approfondisci Campi dinamici e personalizzazione per configurare le variabili degli attributi.

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.