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
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 livello | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
name | string | Sì | Nome leggibile del modello (ad es. "Artisan Coffee Club"). Max 255 caratteri. |
kind | PassKind | Sì | Geometria del tipo di pass: storeCard, coupon, eventTicket, boardingPass, generic o posterGeneric. |
organizationName | string | Sì | Nome dell'organizzazione visualizzato sui pass Apple Wallet e Google Wallet. |
description | string | Sì | Descrizione accessibile del pass richiesta da Apple PassKit. |
status | stato del modello | No | Stato iniziale. Per impostazione predefinita è PUBLISHED alla creazione programmatica. |
colors | request payload | No | Oggetto contenente backgroundColor, foregroundColor, labelColor e stripColor. |
barcode | request payload | No | Configurazione del codice a barre (format, messageEncoding, altText, addSecurityAnimation). |
fields | request payload | No | Raccolte di campi raggruppate per zona (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields). |
locations | request payload[] | No | Array fino a 10 coordinate GPS che attivano notifiche sulla schermata di blocco. |
beacons | request payload[] | No | Array fino a 10 iBeacon Bluetooth per il rilevamento di prossimità indoor. |
expiration | request payload | No | Strategia 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:
{
"backgroundColor": "rgb(24, 24, 27)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(161, 161, 170)",
"stripColor": "rgb(255, 255, 255)"
}
Il sotto-oggetto barcode
{
"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
Normalizzazione del tipo di pass: traduce nomi di stile legacy o alternativi (come
store_card->storeCard,event_ticket->eventTicket,boarding_pass->boardingPass). -
2
Rilevamento del tipo di trasporto: per i pass
boardingPass, mappa le stringhetransitType(PKTransitTypeAir,PKTransitTypeTrain,PKTransitTypeBus,PKTransitTypeBoat,PKTransitTypeGeneric). -
3
Controllo sul posizionamento dei campi: verifica che i campi inseriti in
auxiliaryFieldsrispettino le regole del tipo di pass (ad es., i passcouponrifiutano i campi ausiliari e li spostano insecondaryFields). -
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 automaticamentePKBarcodeFormatQRcome codice di fallback per Apple Watch. -
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
/api/v1/templates
{
"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)
{
"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 HTTP | Messaggio di errore | Causa principale e soluzione |
|---|---|---|
| 400 Bad Request | Template icon is required | Quando 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 Request | Invalid 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 Request | Auxiliary fields are not supported on coupon passes | Il 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 Large | Import payload exceeds 5MB limit | Il 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.
