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
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):
PassProjectTemplateRole | Dove è memorizzato | Responsabilità funzionale nel Progetto |
|---|---|---|
PRIMARY | PassProject.mainTemplateId | Il pass identificativo principale (es. abbonamento stagionale, chiave camera hotel o carta fedeltà) i cui externalId e attributi cliente guidano l'esperienza. |
LINKED / VIP / CUSTOM | PassProjectTemplate.role | Modelli complementari (es. accesso backstage VIP, buono drink, pass parcheggio) inclusi nel bundle al download oppure emessi dinamicamente da regole di segmento/automazione. |
PRIVACY_MODE | PassProjectTemplate.role | Modello alternativo essenziale attivato automaticamente quando un titolare revoca il consenso al tracciamento/personalizzazione. |
INACTIVE | PassProjectTemplate.role | Modello 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 daPass Grouping Engine(libs/pass-bundle,/api/v1/bundles/*oppurePOST /api/v1/pass-projects/:id/download-bundle). Impacchetta fino a 10 file.pkpassfirmati (request payload: 2–10 pass;request payload: 1–10 pass) serviti comeapplication/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
.pkpassall'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
Valutazione dinamica dei segmenti: Definisca regole di filtro su
Pass.attributes(es.attributes.spendTotal >= 500) ed esegua la valutazione tramitePOST /api/v1/pass-projects/:id/segments/:segmentId/evaluate. -
2
Emissione automatica del pass associato: Quando un pass primario entra in un segmento, un
AutomationFlowcollegato emette automaticamente il pass complementare (LINKED/VIP) e aggiorna il relativo link di bundle/download. -
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 endpoint | Descrizione |
|---|---|
GET /api/v1/pass-projects | Elenca tutte le Wallet Experiences (Pass Projects) nel workspace attivo. |
POST /api/v1/pass-projects | Crea un nuovo PassProject con request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug). |
GET /api/v1/pass-projects/:id | Recupera configurazione del progetto, modelli collegati, stato di prontezza e segmenti. |
PATCH /api/v1/pass-projects/:id | Aggiorna nome progetto, descrizione, mainTemplateId, bundleOnDownload, maxBundleSize o slug. |
POST /api/v1/pass-projects/:id/templates/:templateId | Collega un modello complementare (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE). |
GET / PATCH /api/v1/pass-projects/:id/bundle | Configura ordinamento del bundle, limiti (maxBundleSize) e metadati .pkpasses. |
POST /api/v1/pass-projects/:id/download-bundle | Scarica/genera l'archivio bundle .pkpasses coordinato per un pass o un'emissione. |
GET /api/v1/pass-projects/bundle-passes/:passId | Elenca 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
{
"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)
{
"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.
