Panoramica
Passinstance implementa un'architettura di versioning dei modelli su tabella singola sul modello Template. Ciò consente agli operatori di iterare su layout, associazioni di campi e meccaniche all'interno di uno spazio di lavoro DRAFT isolato, mentre i pass attivi già emessi continuano a funzionare senza interruzioni sulla revisione attiva PUBLISHED / PRODUCTION. L'emissione tramite API esterna (POST /api/v1/passes), le importazioni CSV batch e le iscrizioni pubbliche PassFlow richiedono che il modello raggiunga lo stato PUBLISHED.

Architettura di sistema: versioning a tabella singola e ciclo di pubblicazione
Modello di versioning su tabella singola (Template)
Ogni linea di discendenza del modello coordina le proprie revisioni tramite colonne ed enum nella tabella database template (TemplateRowKind e template status: DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED):
| Colonna | Tipo | Descrizione | |
|---|---|---|---|
groupId | UUID | Identificativo immutabile della linea di discendenza condiviso tra tutti gli snapshot storici e le righe attive bozza/produzione. | |
baseId | `UUID \ | null` | Riferimento alla riga base canonica del modello (PRODUCTION / PUBLISHED) da cui deriva la revisione. |
versionNumber | integer | Contatore sequenziale della revisione incrementato a ogni pubblicazione. | |
rowKind | TemplateRowKind | PRODUCTION (riga base canonica associata ai pass), PUBLISHED (snapshot pubblicato), ARCHIVED (versione storica sostituita) o DRAFT (copia di lavoro isolata). |
Verifiche preliminari alla pubblicazione
Prima di promuovere una revisione DRAFT, Passinstance valuta cinque requisiti fondamentali:
-
1
Design visivo e asset obbligatori: Gli asset richiesti da Apple Wallet (
icon,logo) e Google Wallet (googlePayLogo) (image asset slot) e la descrizione dell'organizzazione devono essere compilati. -
2
Campi dinamici e attributi personalizzati: Ogni token
{variable}referenziato inrequest payload(HEADER,PRIMARY,SECONDARY,AUXILIARY,BACK,ADDITIONALINFO,FOOTER) deve corrispondere a una proprietà dichiarata o a un token di sistema (serialNumber,externalId,expirationDate). -
3
Coerenza tra meccaniche e regole di validazione: I parametri di
pass mechanic(mechanic type), i comportamenti al raggiungimento del limite massimo e i pattern per identificativi personalizzati (externalIdentifierPattern) devono risultare validi. -
4
Credenziali crittografiche di firma: Un certificato Apple Pass Type ID valido e un account Google Wallet Issuer devono essere collegati nelle Impostazioni del modello.
-
5
Verifica rischio di pubblicazione (
GET /api/v1/templates/:id/publish-risk-check): Individua modifiche critiche ai campi o alle meccaniche ed eventuali conflitti con pubblicazioni pianificate prima della propagazione.
Importante: Pubblicare con
propagateUpdates: trueaccoda push silenziose APNs HTTP/2 e aggiornamenti Google Wallet verso tutti i dispositivi registrati. Esegua sempre primaGET /api/v1/templates/:id/publish-risk-checke testi le modifiche su un singolo pass (activePassesOnly: truelimita la propagazione ai soli pass attualmente attivi).
Riferimento API per pubblicazione, pianificazione e ripristino (Templates API)
1. Eseguire la verifica rischio pre-pubblicazione
/api/v1/templates/:id/publish-risk-check
Restituisce gli avvisi relativi a modifiche critiche valutati sui pass attivi e sulle eventuali pubblicazioni pianificate in coda (TemplatePublishRiskCheckResult incapsulato in API response envelope).
2. Pubblicare immediatamente la revisione del modello (request payload)
Promuove la revisione in bozza nella discendenza live del modello e propaga facoltativamente le modifiche visive o di campo ai pass installati:
POST /api/v1/templates/:id/publish Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"propagateUpdates": true,
"activePassesOnly": true,
"sendNotifications": true,
"notificationMessage": "New seasonal card layout is live!",
"acknowledgePublishRiskWarning": true,
"overrideReason": "Verified holiday strip colors on test pass"
}
Risposta HTTP (200 OK)
{
"success": true,
"description": "Template published successfully",
"errors": [],
"data": {
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"versionNumber": 3,
"rowKind": "PRODUCTION",
"status": "PUBLISHED",
"updatedAt": "2026-11-15T14:00:00.000Z"
},
"statusCode": 200
}
3. Pianificare una pubblicazione futura
Accoda una revisione in bozza affinché venga pubblicata automaticamente a una data e ora locale del cliente o ISO (se scheduledAt è nel passato o presente, il server pubblica immediatamente):
POST /api/v1/templates/:id/schedule-publication Header: X-API-Key: <API_KEY> | Content-Type: application/json
{
"scheduledAt": "2026-11-27 00:00",
"timeZone": "Europe/Berlin",
"activePassesOnly": true,
"sendNotifications": false,
"message": "Black Friday seasonal artwork activated."
}
4. Scartare la bozza di lavoro e ripristinare lo stato live
Scarta le modifiche non salvate/non pubblicate nella riga DRAFT e riporta la bozza di lavoro alla revisione base attiva già pubblicata:
/api/v1/templates/:id/discard-draft
{
"success": true,
"description": "Template draft discarded successfully",
"data": {
"success": true,
"message": "Draft discarded successfully"
},
"errors": [],
"statusCode": 200
}
Una volta pubblicato il modello, prosegua con Creare pass individuali oppure Creazione massiva di pass.
