Panoramica
La creazione del primo pass Wallet prevede la configurazione di un Template visivo riutilizzabile, l'associazione di meccaniche applicative interattive, l'esecuzione di una verifica pre-pubblicazione del rischio e l'emissione di un record Pass concreto installabile su dispositivi iOS e Android.
Tappe di creazione passo per passo
Segua questo flusso in Passinstance Dashboard (Modelli -> Crea modello su /templates/new) oppure tramite la Developer API:
-
1
Scelta della geometria del layout (pass type): Scelga uno dei formati pass supportati:
- storeCard: Carte fedeltà, tessere a timbri e gift card. - coupon: Buoni promozionali monouso e voucher sconto. - eventTicket / boardingPass: Concerti, eventi sportivi, festival, conferenze oppure carte d'imbarco aeree/ferroviarie. - membership / generic / posterGeneric / studentId / businessCard: Tessere socio, pass in stile poster WWDC, badge dipendenti/studenti e biglietti da visita digitali.
-
2
Branding, colori e asset:
- Formattazione colori: Apple Wallet impone rigorosamente stringhe rgb(r, g, b) (senza canale alfa). Google Wallet accetta codici esadecimali #RRGGBB. Il selettore colore della dashboard converte automaticamente i formati e avvisa in caso di basso contrasto WCAG. - Slot immagini (image asset slot): Carichi immagini ad alta risoluzione nei 13 slot supportati (logo, primaryLogo, secondaryLogo, icon, googlePayLogo, strip, background, thumbnail, artwork, venueMap, footer, androidBackground, androidLogo).
-
3
Associazione di una meccanica pass interattiva:
- Scelga un motore regole (mechanic type): STAMP_CARD_ADD, STAMP_CARD_DEDUCT, LOYALTY_PROGRAM, PREPAID_CARD, VALID_ONCE_PER_DAY oppure RENEW_EXPIRATION.
-
4
Definizione delle zone dei campi dinamici (field placement type):
- Collochi i campi in HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO o FOOTER. - Utilizzi token dinamici tra parentesi graffe come {memberName}, {pointsBalance} o {expirationDate}. - Aggiunga stringhe Apple changeMessage contenenti %@ (ad esempio "Points updated: %@") per attivare notifiche push native nella schermata di blocco iOS.
-
5
Analisi rischi pre-pubblicazione e pubblicazione:
- La dashboard valuta GET /api/v1/templates/:id/publish-risk-check per individuare modifiche critiche che potrebbero sovrascrivere campi di pass già attivi. - Clicchi su Salva e pubblica (POST /api/v1/templates/:id/publish) per promuovere la revisione DRAFT nella riga base PRODUCTION.
-
6
Generazione e installazione del pass di test:
- Clicchi su Crea pass nella panoramica del modello (/templates/:id/overview) oppure invii una richiesta REST a POST /api/v1/passes. La creazione del pass richiama automaticamente resolvePassCreationTemplateId per associare il nuovo pass alla riga base canonica del modello.

Generazione programmatica del pass e verifica
Gli sviluppatori possono saltare la dashboard ed emettere pass Wallet personalizzati direttamente da sistemi backend o CRM utilizzando POST /api/v1/passes (request payload). Includa Idempotency-Key per retry sicuri ed externalId per la correlazione CRM, e aggiunga facoltativamente ?includePassSource=apple|google per ricevere direttamente gli artefatti sorgente del Wallet nella risposta:
Richiesta HTTP
/api/v1/passes?includePassSource=google
{
"templateId": "tmpl_9a8b7c6d5e4f",
"externalId": "cust_100248",
"attributes": {
"memberName": "Elena Rostova",
"memberNumber": "MB-94021",
"points": "150"
},
"barcodeValue": "PI-MB-94021-SECURE",
"barcodeAltText": "MB-94021",
"expirationDate": "2027-12-31 23:59"
}
Risposta HTTP (201 Created)
{
"success": true,
"data": {
"id": "pass_1a2b3c4d5e6f",
"templateId": "tmpl_9a8b7c6d5e4f",
"serialNumber": "PI-789042-XY",
"externalId": "cust_100248",
"bundleId": null,
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "NONE",
"appleArtifactStatus": "NOT_GENERATED",
"googleArtifactStatus": "READY",
"downloadUrl": "https://app.passinstance.com/d/elena-rostova-94021",
"passAccessUrl": "https://app.passinstance.com/p/pass_1a2b3c4d5e6f",
"passSource": {
"platform": "google",
"saveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
},
"createdAt": "2026-11-15T12:00:00Z"
},
"description": "Pass created successfully",
"errors": [],
"statusCode": 201
}
Test con pass di esempio in Sandbox
Durante la fase di valutazione e i test iniziali è possibile generare un pass di esempio istantaneo senza inserire record clienti completi:
-
1
Richiami
POST /api/v1/onboarding/sample-passoppure clicchi su Prova pass di esempio nello step della procedura guidata/onboarding/try-pass. -
2
Il server crea un pass effimero ed espone l'endpoint pubblico di test:
/api/v1/onboarding/sample-pass/public/:sessionId
-
3
Scansionando il codice QR mostrato con la fotocamera di un iPhone si avvia l'installazione nativa in Apple Wallet; aprendo il link su Android è possibile testare Google Wallet.
-
4
Apra Scanner (
/scanner) inPassinstance Dashboardoppure abbini l'app mobile Passinstance Scanner tramitePOST /api/v1/scanner-keys/from-linke scansioni il pass installato per verificare gli eventi di scansione in tempo reale e le notifiche push istantanee.
Importante: Testi sempre il nuovo pass pubblicato su dispositivi iOS (Apple Wallet) e Android (Google Wallet) per verificare il contrasto dei colori, l'eventuale troncamento dei testi nei campi e l'affidabilità di lettura del codice a barre prima di avviare campagne di distribuzione verso i clienti.
È tutto pronto per iniziare? Avvii la Fase 2: Progetta il tuo pass oppure esplori Creare pass Wallet con l'IA.
