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

Versioni modello e pubblicazione

Verifica i requisiti di pubblicazione, associa certificati, passa da Bozza a Pubblicato e gestisci modifiche live.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito1 / 2
Elementi chiave dell'interfaccia

Checklist di pubblicazione — Configurazione completata (Zoom)

Verifica che Certificato di firma, Regole di convalida e Pagina di download mostrino tutti «Ready» (3 su 3 completati) prima di emettere i pass.

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.

Checklist di prontezza alla pubblicazione
Checklist di prontezza alla pubblicazione

Architettura di sistema: versioning a tabella singola e ciclo di pubblicazione

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
VERSIONING A TABELLA SINGOLA E PUBBLICAZIONE
FASE 01 Tabella Template (Discendenza revisioni a tabella singola)
groupId: UUID condiviso che collega tutte le revisioni dello stesso modello
baseId: Puntatore alla revisione canonica base PRODUCTION
versionNumber: Intero progressivo crescente (v1, v2, v3...)
rowKind (TemplateRowKind): PRODUCTION | PUBLISHED | ARCHIVED | DRAFT
status (template status): DRAFT | PUBLISHED | ARCHIVED | ...
FASE 02 VALUTATORE RISCHI E REQUISITI PRE-PUBBLICAZIONE
Verifica certificato Apple Pass Type (.p12) e collegamento Google Issuer
Risolve tutti i token {variable} rispetto alle Proprietà personalizzate
Valuta se gli aggiornamenti pianificati sovrascrivono campi critici live
FASE 03 PROMOZIONE ATOMICA E CODA DI PROPAGAZIONE WALLET
Promuove le modifiche bozza nella discendenza canonica PRODUCTION/PUBLISHED
Conserva le revisioni precedenti nello storico delle righe ARCHIVED
Se propagateUpdates: trueaccoda aggiornamenti Wallet ai titolari attivi

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):

ColonnaTipoDescrizione
groupIdUUIDIdentificativo 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.
versionNumberintegerContatore sequenziale della revisione incrementato a ogni pubblicazione.
rowKindTemplateRowKindPRODUCTION (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. 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. 2
    Campi dinamici e attributi personalizzati: Ogni token {variable} referenziato in request payload (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) deve corrispondere a una proprietà dichiarata o a un token di sistema (serialNumber, externalId, expirationDate).
  3. 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. 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. 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: true accoda push silenziose APNs HTTP/2 e aggiornamenti Google Wallet verso tutti i dispositivi registrati. Esegua sempre prima GET /api/v1/templates/:id/publish-risk-check e testi le modifiche su un singolo pass (activePassesOnly: true limita la propagazione ai soli pass attualmente attivi).

Riferimento API per pubblicazione, pianificazione e ripristino (Templates API)

1. Eseguire la verifica rischio pre-pubblicazione

GET /api/v1/templates/:id/publish-risk-check
Header
X-API-Key <API_KEY>

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

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)

JSON
{
  "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

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:

POST /api/v1/templates/:id/discard-draft
Header
X-API-Key <API_KEY>
JSON
{
  "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.

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.