Panoramica
La configurazione di un account Passinstance inizializza un workspace tenant isolato, imposta le preferenze regionali e guida attraverso una pipeline di onboarding automatizzata per generare pass dimostrativi pronti per il test su Apple Wallet e Google Wallet.
Pipeline di onboarding e macchina a stati
Passinstance gestisce l'inizializzazione dell'account tramite una macchina a stati OnboardingSession automatizzata, supportata da Onboarding API:
Fasi ed enum dell'onboarding
La sessione transita attraverso gli esatti valori dell'enum OnboardingStep:
-
1
WALLET_SETUP: Esamina e accetta i termini di emissione Wallet della piattaforma (googleWalletAccepted) e prepara le credenziali demo predefinite. -
2
PERSONALIZE: Seleziona il modello di business e la fascia di volume mensile prevista:
- EVALUATING: Test delle funzionalità ed esplorazione della sandbox. - UP_TO_500: Negozi boutique, club locali, sedi specializzate. - RANGE_500_5000: Retailer in crescita, palestre regionali, eventi di medie dimensioni. - RANGE_5000_25000: Franchising multi-sede e grandi associazioni di soci. - RANGE_25000_PLUS / ENTERPRISE: Biglietteria ad alto volume, programmi fedeltà retail nazionali, carte d'imbarco aeree o di trasporto.
-
3
GENERATING_DEMOS: Il backend accoda job in background che creano modelli demo nelle categorieOnboardingUseCase(LOYALTY_AND_CUSTOMER_CARDS,MEMBERSHIP_CARDS,TICKETING,VOUCHERS_OR_COUPONS,GIFT_CARDS_OR_PREPAID_CARDS,BUSINESS_CARDS,EMPLOYEE_IDS,INSURANCE_WARRANTY_AND_SERVICE_CARDS,OTHER). -
4
TRY_PASS: Genera un pass di esempio effimero con un codice QR scansionabile per l'installazione immediata sullo smartphone. -
5
DONE: Conclude l'onboarding e sblocca l'intera dashboard amministrativa (/dashboard).
Riferimento API del Controller di Onboarding
Gli sviluppatori e gli script di provisioning automatizzato possono controllare l'onboarding in modo programmatico sotto /api/v1/onboarding:
| Percorso endpoint | Metodo | Auth | Payload / Parametri | Descrizione |
|---|---|---|---|---|
/api/v1/onboarding | GET | Bearer | Nessuno | Recupera lo stato attuale della sessione di onboarding, il passaggio attivo e le demo generate. |
/api/v1/onboarding/wallet-setup | PUT | Bearer | { "googleWalletAccepted": true } | Accetta i termini di emissione Wallet e predispone la configurazione Google Wallet predefinita. |
/api/v1/onboarding/personalize | PUT | Bearer | { expectedPassVolume, useCases: [] } | Salva la fascia di volume aziendale e gli elementi OnboardingUseCase selezionati. |
/api/v1/onboarding/demos | POST | Bearer | Nessuno | Avvia la generazione asincrona dei modelli demo (QUEUED -> READY). |
/api/v1/onboarding/demos | GET | Bearer | Nessuno | Interroga l'avanzamento della generazione demo per i casi d'uso richiesti. |
/api/v1/onboarding/demos/:type/retry | POST | Bearer | Parametro URL :type | Ritenta la generazione di un modello demo se un tipo di catalogo specifico ha avuto esito negativo. |
/api/v1/onboarding/sample-pass | POST | Bearer | { templateId? } | Genera un pass di prova live per l'installazione immediata nel Wallet. |
/api/v1/onboarding/sample-pass/public/:sessionId | GET | Nessuna | Parametro URL :sessionId | Endpoint pubblico non autenticato per visualizzare e installare il pass di esempio su mobile. |
/api/v1/onboarding/complete | POST | Bearer | { skipSamplePass?: boolean } | Imposta la sessione di onboarding su DONE. |
Checklist di configurazione dell'account
Segua questi passaggi in Passinstance Dashboard per preparare il workspace al lancio in produzione:
-
1
Verifica workspace ed e-mail: Confermi il proprio indirizzo e-mail al momento della registrazione (qualsiasi indirizzo e-mail valido è accettato) per consolidare le credenziali amministrative del tenant, già configurate con un certificato Apple demo e un emittente Google Wallet gestito.
-
2
Configurazione delle impostazioni regionali: Visiti Impostazioni -> Generali (
/settings/workspace/general) oppure inviiPUT /api/v1/customer/:customerId/regional-settingsper configurare:
- Fuso orario: Valuta i limiti giornalieri di scansione e i timestamp locali (es. Europe/Berlin, America/New_York). - Valuta: Imposta la valuta ISO 4217 predefinita per i saldi prepagati (es. EUR, USD, GBP). - Lingua predefinita: Imposta la lingua principale per i campi Wallet localizzati.
-
3
Configurazione del certificato Apple Wallet (Produzione): In Impostazioni -> Wallet -> Certificati Apple (
/settings/workspace/wallet), generi una Certificate Signing Request tramitePOST /api/v1/certificates/generate-csr, la carichi sull'Apple Developer Portal sotto Pass Type IDs e importi il file.cerfirmato tramitePOST /api/v1/certificates. -
4
Configurazione di Google Wallet Issuer (Produzione): Sotto Impostazioni -> Wallet -> Google Wallet, esegua la configurazione (
POST /api/v1/google-wallet/setup) e verifichi lo stato (GET /api/v1/google-wallet/status) per visualizzare il proprio Google Issuer ID e ilcollectorIddi Smart Tap. -
5
Ruoli del team e controllo accessi: Sotto Impostazioni -> Accesso -> Membri e ruoli (
/settings/workspace/access), inviti i collaboratori utilizzando i ruoli dell'organizzazione (OrganizationMemberRole:OWNER,ADMIN,MEMBER) insieme ai ruoli RBAC del workspace (DEFAULT_ROLES:super-admin,admin,editor,user,customer) e imponga l'autenticazione a due fattori (enforceTwoFactorAuth).
Prerequisiti: Per emettere pass di produzione con branding personalizzato in Apple Wallet è necessario disporre di un abbonamento attivo ad Apple Developer Program (99 USD/anno) per generare un certificato Apple Pass Type ID (
pass.com.yourcompany.app). I test durante l'onboarding in sandbox utilizzano certificati demo Passinstance.
Esamini i Piani e fasce di capacità disponibili oppure proceda direttamente alla Fase 2: Progetta il tuo pass.
