Skip to content
Guida del Centro assistenza · Avvio rapidoFase di onboarding 2
4 min di letturaVerificato 2026-11-16

Crea il tuo primo pass Wallet

Disegna un modello, assegna una meccanica, collega variabili dinamiche, pubblica e testa sullo smartphone.

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

Elenco Template e barra di adozione (Ingrandito)

Filtra i template, monitora Installati vs. Rimossi per template e apri anteprime, Visual Editor o creazione pass singolo.

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.

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CREAZIONE E INSTALLAZIONE PRIMO PASS
FASE 01
1
CREAZIONE MODELLO (POST/api/v1/templates)
Seleziona pass type (storeCard, coupon, eventTicket, membership)
Configura colori (rgb(r,g,b) Apple, #RRGGBB Google) e risorse visive
Associa pass mechanic (STAMP_CARD_ADD, LOYALTY_PROGRAM, PREPAID_CARD)
FASE 02
2
VERIFICA RISCHIO PRE-PUBBLICAZIONE E PROMOZIONE (POST/api/v1/templates/:id/publish)
Valuta GET/api/v1/templates/:id/publish-risk-check
Promuove la revisione da rowKind = DRAFT a rowKind = PRODUCTION
FASE 03
3
EMISSIONE PASS E INSTALLAZIONE WALLET (POST/api/v1/passes)
Header opzionale Idempotency-Key (idempotencyKey) & externalId
Popola structured JSON attributes (memberName, points, barcodeValue)
Consegna Smart URL (/p/:passId / /d/:slug)Installa su iOS / 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. 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.

  1. 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).

  1. 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.

  1. 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.

  1. 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.

  1. 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.

Elenco modelli e azioni rapide di creazione
Elenco modelli e azioni rapide di creazione

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

POST /api/v1/passes?includePassSource=google
Header
X-API-Key <API_KEY>
Content-Type application/json
Idempotency-Key order-94021-pass-init
JSON
{
  "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)

JSON
{
  "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. 1
    Richiami POST /api/v1/onboarding/sample-pass oppure clicchi su Prova pass di esempio nello step della procedura guidata /onboarding/try-pass.
  2. 2
    Il server crea un pass effimero ed espone l'endpoint pubblico di test:
GET /api/v1/onboarding/sample-pass/public/:sessionId
  1. 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.
  2. 4
    Apra Scanner (/scanner) in Passinstance Dashboard oppure abbini l'app mobile Passinstance Scanner tramite POST /api/v1/scanner-keys/from-link e 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.

Documentazione prodotto e API correlata

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.