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.
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:
| Concetto | Modello Passinstance database | Responsabilità e attributi memorizzati | |||||
|---|---|---|---|---|---|---|---|
Modello (Template) | Template | Memorizza 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) | Pass | Rappresenta 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 mechanic | Configura 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 account | Gestisce 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 bundle | Raggruppa 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) | PassProject | Coordina 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) | PassFlow | Gestisce 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) | ScannerConfiguration | Configura 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:
| Campo | Colonna Passinstance database / Ambito | Mutabilità e formato | Scopo principale |
|---|---|---|---|
id | Chiave primaria UUID | Generato dal sistema, immutabile | Riferimento interno della risorsa API (GET /api/v1/passes/:id). |
serialNumber | Stringa univoca globalmente | Generato dal sistema (o personalizzato se configurato), immutabile | Identificativo canonico Apple Wallet .pkpass e suffisso oggetto Google Wallet. |
externalId | @unique([customerId, externalId]) dove archivedAt IS NULL | Stringa 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. |
bundleId | bundleId (chiave esterna UUID verso pass bundle) | Gestito dal sistema tramite /api/v1/bundles/* o PassProject | Raggruppa 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 / authenticationToken | Token di sicurezza per singolo pass | Stringhe crittografiche generate dal sistema | Codice 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 propriaexpirationDate; gli scanner rifiutano con motivazionePASS_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 conPASS_VOIDED.
Ciclo di vita del pass, modalità di eliminazione e stato degli artefatti
-
PassLifecycleStatus: Controlla le transizioni irreversibili di annullamento ed eliminazione definitiva:
ACTIVE ---> VOIDING ---> VOIDED ---> DELETING ---> DELETED
-
PassDeletionMode: Distingue l'eliminazione logica (SOFT, preserva lo storico di audit e libera l'univocità diexternalIdper i pass attivi) dalla rimozione permanente (HARD,DELETE /api/v1/passes/:id/hard). -
ArtifactStatus(appleArtifactStatusegoogleArtifactStatus): 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 oPATCHREST 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): ConfigurarechangeMessage: "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.
