Skip to content
Guida del Centro assistenza · Progetti e organizzazione
4 min di letturaVerificato 2026-11-16

Gestire i progetti

Unisci un modello primario e modelli collegati in Wallet Experiences, bundle e passaggi per segmento.

In questa guida

Panoramica

Nella Dashboard di Passinstance, i Progetti multi-pass (modello PassProject gestito da Projects API su /api/v1/pass-projects e alias /api/v1/wallet-experiences) compaiono nell'hub Wallet Experiences (/wallet-experiences, che organizza le schede Overview, Cards, Audience, Automations, Distribution, Analytics e Settings). Un Progetto coordina un modello primario mainTemplateId insieme a modelli complementari collegati in percorsi cliente unificati, supportando gli Apple Wallet Pass Bundle (.pkpasses) (Pass.bundleId / pass bundle) e l'automazione basata su regole di segmento.

Architettura di sistema: Progetti pass, bundling .pkpasses e trigger di segmento

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
BUNDLING PROGETTO PASS (.PKPASSES) E AUTOMAZIONE SEGMENTI
FASE 01 PROGETTO PASS (PassProject e PassProjectTemplate)
PRIMARY (mainTemplateId): Abbonamento / Biglietto / Carta d'imbarco base
LINKED / VIP / CUSTOM: Voucher lounge / Parcheggio / Tessera gala
PRIVACY_MODE / INACTIVE: Layout privacy ridotto o carta associata in pausa
FASE 02A APPLE PASS BUNDLE (ZIP .pkpasses)
Raggruppa fino a 10 .pkpass firmati con lo stesso Pass.bundleId
bundle grouping mode: AUTO | `MANUA
BundleStatus: ACTIVE | CANCELLED
FASE 02B ORCHESTRATORE SEGMENTI E AUTOMAZIONI
Valuta regole PassProjectSegment su Pass.attributes (GIN) | | - Attiva azioniAutomationFl emetti pass collegato / cambia mod.

Modelli principali e ruoli dei modelli (PassProjectTemplateRole)

Ogni PassProject collega un mainTemplateId (ruolo PRIMARY sul progetto stesso) insieme a modelli complementari collegati (PassProjectTemplate, ruoli scrivibili LINKED, PRIVACY_MODE, VIP, CUSTOM, INACTIVE):

PassProjectTemplateRoleDove è memorizzatoResponsabilità funzionale nel Progetto
PRIMARYPassProject.mainTemplateIdIl pass identificativo principale (es. abbonamento stagionale, chiave camera hotel o carta fedeltà) i cui externalId e attributi cliente guidano l'esperienza.
LINKED / VIP / CUSTOMPassProjectTemplate.roleModelli complementari (es. accesso backstage VIP, buono drink, pass parcheggio) inclusi nel bundle al download oppure emessi dinamicamente da regole di segmento/automazione.
PRIVACY_MODEPassProjectTemplate.roleModello alternativo essenziale attivato automaticamente quando un titolare revoca il consenso al tracciamento/personalizzazione.
INACTIVEPassProjectTemplate.roleModello collegato temporaneamente escluso dai nuovi download in bundle senza scollegarne lo storico.

Apple Wallet Pass Bundle (.pkpasses) e Pass.bundleId

Quando il bundling è abilitato (bundleOnDownload: true, maxBundleSize fino a 10), Passinstance collega i pass complementari emessi sotto un Pass.bundleId condiviso (chiave esterna bundleId verso pass bundle):

  • Apple Wallet (archivio .pkpasses): Costruito da Pass Grouping Engine (libs/pass-bundle, /api/v1/bundles/* oppure POST /api/v1/pass-projects/:id/download-bundle). Impacchetta fino a 10 file .pkpass firmati (request payload: 2–10 pass; request payload: 1–10 pass) serviti come application/vnd.apple.pkpasses, consentendo ad iOS di proporre Aggiungi tutti.
  • Richiesta multi-pass su Google Wallet: Restituisce URL di salvataggio coordinati e link bundle (GET /api/v1/bundles/:id/google-wallet-link, PassProjectIssuanceProvider: APPLE \| GOOGLE, PassProjectIssuanceStatus: PENDING -> VALIDATING -> CREATING_PASSES -> READY \| PARTIALLY_READY \| FAILED).

Importante: Apple iOS impone un limite massimo di 10 file .pkpass all'interno di un singolo archivio .pkpasses (maxBundleSize <= 10). Ogni modello incluso in un bundle deve essere pubblicato con un certificato Apple Pass Type ID valido.

Segmenti di audience (PassProjectSegment) e flussi di automazione

I Progetti si integrano direttamente con PassProjectSegment e AutomationFlow per orchestrare percorsi dinamici multi-pass senza codice collante per webhook esterni:

  1. 1
    Valutazione dinamica dei segmenti: Definisca regole di filtro su Pass.attributes (es. attributes.spendTotal >= 500) ed esegua la valutazione tramite POST /api/v1/pass-projects/:id/segments/:segmentId/evaluate.
  2. 2
    Emissione automatica del pass associato: Quando un pass primario entra in un segmento, un AutomationFlow collegato emette automaticamente il pass complementare (LINKED / VIP) e aggiorna il relativo link di bundle/download.
  3. 3
    Passaggio a Privacy Mode: Se il consenso alla personalizzazione è disattivato, l'esperienza può migrare il pass del titolare verso il modello PRIVACY_MODE.

Riferimento REST API Pass Projects (Projects API)

Tutti gli endpoint dei progetti sono esposti sotto /api/v1/pass-projects (alias /api/v1/wallet-experiences):

Metodo HTTP ed endpointDescrizione
GET /api/v1/pass-projectsElenca tutte le Wallet Experiences (Pass Projects) nel workspace attivo.
POST /api/v1/pass-projectsCrea un nuovo PassProject con request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug).
GET /api/v1/pass-projects/:idRecupera configurazione del progetto, modelli collegati, stato di prontezza e segmenti.
PATCH /api/v1/pass-projects/:idAggiorna nome progetto, descrizione, mainTemplateId, bundleOnDownload, maxBundleSize o slug.
POST /api/v1/pass-projects/:id/templates/:templateIdCollega un modello complementare (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE).
GET / PATCH /api/v1/pass-projects/:id/bundleConfigura ordinamento del bundle, limiti (maxBundleSize) e metadati .pkpasses.
POST /api/v1/pass-projects/:id/download-bundleScarica/genera l'archivio bundle .pkpasses coordinato per un pass o un'emissione.
GET /api/v1/pass-projects/bundle-passes/:passIdElenca tutti i pass complementari raggruppati con uno specifico passId tramite bundleId.

Esempio: creare un progetto multi-pass (request payload)

POST /api/v1/pass-projects Header: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "name": "Alpine Ski Resort - VIP Winter Package",
  "description": "Season ski pass with aprés-ski voucher and privacy layout",
  "mainTemplateId": "tmpl_ski_season_pass_01",
  "bundleOnDownload": true,
  "maxBundleSize": 5,
  "slug": "alpine-vip-winter-2026"
}

Risposta HTTP (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "proj_01j9k8l7m6n5p4",
    "name": "Alpine Ski Resort - VIP Winter Package",
    "slug": "alpine-vip-winter-2026",
    "mainTemplateId": "tmpl_ski_season_pass_01",
    "bundleOnDownload": true,
    "maxBundleSize": 5,
    "createdAt": "2026-11-15T19:00:00.000Z"
  },
  "statusCode": 201
}

Consulti Architettura del bundling pass per i flussi tecnici di impacchettamento e Configurazione dei workflow per le regole di automazione trasversali tra progetti.

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.