Skip to content
Guida del Centro assistenza · Introduzione a PassinstanceFase di onboarding 2
6 min di letturaVerificato 2026-11-16

Concetti chiave e terminologia

Definizioni chiare di Modelli, Pass, Meccaniche, Attributi, Wallet Experiences (Progetti), PassFlow e Registrazioni attive.

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 ingrandito
Elementi chiave dell'interfaccia

Proprietà e attributi personalizzati (Zoom)

Definisci attributi cliente riutilizzabili ({serviceOrDuration}, {holderName}, {passReference}, {validUntil}, {memberQrToken}) e configura tipi di dati e regole.

Architettura ed entità fondamentali della piattaforma

Per realizzare flussi Wallet affidabili, sviluppatori e amministratori devono comprendere come Passinstance organizza modelli, record dinamici dei pass, meccaniche di logica applicativa e stati di registrazione dei dispositivi.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
RELAZIONI TRA ENTITÀ
FASE 01 Template (Blueprint e versioning)
Layout: StoreCard, EventTicket, Coupon, Membership
Colori, simbologia codice a barre, mapping campi, asset
FASE 02 Emissione 1:N | Collegamento regola 1:1
Pass (Istanza concreta)
SerialNumber & AuthToken
Valori campi dinamici
Status & ExpirationDate
Registrazione dispositivo 1:N (A
pass mechanic (Motore di stato)
Type: STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD,
VALID_ONCE_PER_DAY alvataggi Google)

Schema delle entità backend e mapping sui modelli Passinstance database

Ogni concetto della piattaforma corrisponde direttamente a un'entità Passinstance database strutturata all'interno dello strato database di Passinstance API:

ConcettoModello Passinstance databaseResponsabilità e attributi memorizzati
Modello (Template)TemplateMemorizza configurazione visiva, tipo di layout (pass type), relazioni asset (image asset slot), regole codice a barre, regex personalizzate per identificativi e versioning su tabella singola (groupId, versionNumber, rowKind: `PRODUCTION \PUBLISHED \ARCHIVED \DRAFT, status`: template status).
Pass (Pass)PassRappresenta una singola tessera emessa. Contiene id, serialNumber univoco, authenticationToken, downloadCode, externalId opzionale univoco per tenant, bundleId opzionale (bundleId), idempotencyKey opzionale, structured JSON attributes, expirationDate, stato degli artefatti (appleArtifactStatus, googleArtifactStatus) e flag di ciclo di vita/annullamento.
Meccanica pass (pass mechanic)pass mechanicConfigura regole stateful associate a un modello. Archivia mechanicType (mechanic type), minimumValue, maximumValue, defaultChangeValue, livelli (PassTier) e regole di gestione dei limiti massimi.
Conto prepagato (prepaid account)prepaid accountGestisce il valore monetario memorizzato per gift card e carte prepagate. Traccia i saldi in unità intere e si collega ai registri contabili immutabili prepaid ledger entry.
Bundle pass (pass bundle)pass bundleRaggruppa fino a 10 pass correlati tramite Pass.bundleId (bundle grouping mode: `AUTO \MANUAL, BundleStatus: ACTIVE \CANCELLED) per il download di archivi Apple multi-carta .pkpasses`.
Wallet Experience (PassProject)PassProjectCoordina un modello primario (mainTemplateId) e modelli collegati (PassProjectTemplateRole: `PRIMARY \LINKED \PRIVACY_MODE \INACTIVE \VIP \CUSTOM`), pagine unificate di riscatto, bundle, segmenti e flussi di automazione visivi.
PassFlow (PassFlow)PassFlowGestisce pagine multi-step di acquisizione self-service (/f/:url, PassFlowType, PassFlowStatus) con moduli personalizzabili, verifica OTP via SMS/e-mail, protezione anti-bot (SpamProtectionMode), gateway di pagamento e consegna diretta al Wallet.
Configurazione Scanner (ScannerConfiguration)ScannerConfigurationConfigura sedi fisiche di check-in (ValidationPlace), token ScannerKey con ambito limitato, modalità di validazione (ScanMode), impostazioni lettori NFC (NfcReaderMode) e sincronizzazione dataset offline.

Identificativi principali del pass e chiavi di correlazione

Nell'integrazione di CRM, checkout e-commerce o backend di biglietteria, è essenziale conoscere il ruolo esatto di ciascun identificativo su un Pass:

CampoColonna Passinstance database / AmbitoMutabilità e formatoScopo principale
idChiave primaria UUIDGenerato dal sistema, immutabileRiferimento interno della risorsa API (GET /api/v1/passes/:id).
serialNumberStringa univoca globalmenteGenerato dal sistema (o personalizzato se configurato), immutabileIdentificativo canonico Apple Wallet .pkpass e suffisso oggetto Google Wallet.
externalId@unique([customerId, externalId]) dove archivedAt IS NULLStringa fornita dal chiamante (max 255 caratteri)Chiave di business proveniente dal proprio CRM, POS o DB ticketing che abilita POST /api/v1/passes/upsert-by-external-id idempotente e la ricerca tramite GET /api/v1/passes/by-external-id/:externalId.
bundleIdbundleId (chiave esterna UUID verso pass bundle)Gestito dal sistema tramite /api/v1/bundles/* o PassProjectRaggruppa fino a 10 pass in un bundle Apple multi-carta .pkpasses o in un'esperienza unificata di richiesta.
idempotencyKey@unique([customerId, idempotencyKey])Fornito tramite header Idempotency-Key (<=128 caratteri [A-Za-z0-9._:-]+)Previene emissioni duplicate se una richiesta HTTP POST /api/v1/passes viene ritentata; verificato tramite hash SHA-256 del body della richiesta.
downloadCode / authenticationTokenToken di sicurezza per singolo passStringhe crittografiche generate dal sistemaCodice breve pubblico di download e segreto condiviso Apple Web Service Authorization: ApplePass <token>.

Enum delle macchine a stati e mappatura del ciclo di vita

I record dei pass transitano attraverso macchine a stati rigorose negli enum Passinstance database durante la creazione, la sincronizzazione Wallet e l'annullamento/eliminazione:

Stato del pass (pass status)

  • DRAFT: Predisposto come bozza non ancora emessa e non disponibile per l'installazione pubblica.
  • AWAITING_OPT_IN: Generato durante flussi di registrazione opt-in/OTP; in attesa di verifica prima dell'attivazione.
  • GENERATING: In fase di generazione asincrona del pass o degli artefatti Wallet.
  • ACTIVE: Emesso e valido. Disponibile per l'installazione nel Wallet e per la validazione tramite scanner.
  • INACTIVE: Temporaneamente sospeso/disattivato; gli scanner rifiutano la validazione finché non viene riattivato.
  • EXPIRED: Ha superato la propria expirationDate; gli scanner rifiutano con motivazione PASS_EXPIRED.
  • REDEEMED: Coupon o buono monouso che ha completato il riscatto.
  • CANCELLED, SUSPENDED, PENDING_ACTIVATION: Stati specializzati di fatturazione, amministrazione e pre-attivazione.
  • VOIDED: Revocato o annullato da un amministratore o da una regola di scansione; gli scanner rifiutano con PASS_VOIDED.

Ciclo di vita del pass, modalità di eliminazione e stato degli artefatti

  • PassLifecycleStatus: Controlla le transizioni irreversibili di annullamento ed eliminazione definitiva:
TEXT
ACTIVE  --->  VOIDING  --->  VOIDED  --->  DELETING  --->  DELETED
  • PassDeletionMode: Distingue l'eliminazione logica (SOFT, preserva lo storico di audit e libera l'univocità di externalId per i pass attivi) dalla rimozione permanente (HARD, DELETE /api/v1/passes/:id/hard).
  • ArtifactStatus (appleArtifactStatus e googleArtifactStatus): Traccia lo stato di generazione per singolo ecosistema (NOT_GENERATED, GENERATING, READY, FAILED, INVALIDATED).

Stato di annullamento e propagazione Wallet (walletVoidStatus / WalletPropagationStatus)

Traccia la propagazione asincrona dello stato di annullamento/aggiornamento verso Apple APNs e Google Wallet sul campo Pass.walletVoidStatus:

  • NONE: Nessuna propagazione in sospeso.
  • PENDING: Stato registrato nel database; in attesa di accodamento nella coda job.
  • QUEUED: Inviato ai worker background job queue di sincronizzazione Wallet.
  • SUCCEEDED: Risveglio Apple APNs o PATCH REST di Google confermato.
  • FAILED: Push verso il Wallet di destinazione non riuscito (idoneo a retry automatico o rigenerazione manuale).

Proprietà personalizzate e interpolazione dinamica dei token

Passinstance utilizza la sintassi dinamica con parentesi graffe {propertyName} per associare i dati del cliente ai campi della tessera:

  • Sintassi: Inserire {firstName}, {pointsBalance} o {membershipTier} in qualsiasi etichetta o valore di campo primario, secondario, ausiliario o sul retro.
  • Messaggi di modifica (changeMessage): Configurare changeMessage: "You earned a stamp! You now have %@ stamps." sui campi Apple Wallet. Quando il valore cambia, il token %@ viene sostituito con il nuovo valore, generando immediatamente una notifica banner nella schermata di blocco iOS.
  • Valori con collegamenti (Attributed Values): I campi sul retro di Apple Wallet supportano tag anchor HTML (<a href="https://example.com">Terms</a>) per rendere cliccabili link web, numeri di telefono e indirizzi e-mail.

Importante: La capacità di fatturazione misura i Pass Wallet attivi (il numero totale di dispositivi attualmente registrati tramite Apple APNs o oggetti Google Wallet), non le bozze non emesse né i pass scaduti.

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.