Visão geral
No Painel da Passinstance, os Projetos multi-passe (modelo PassProject gerido pelo Projects API em /api/v1/pass-projects e alias /api/v1/wallet-experiences) surgem na área Wallet Experiences (/wallet-experiences, organizando os separadores Overview, Cards, Audience, Automations, Distribution, Analytics e Settings). Um Projeto coordena um mainTemplateId principal mais modelos complementares associados em jornadas unificadas de cliente, suportando Pacotes de Passes Apple Wallet (.pkpasses) (Pass.bundleId / pass bundle) e automação baseada em regras de segmentos.
Arquitetura do sistema: Projetos de passes, empacotamento .pkpasses e gatilhos de segmentos
Modelos principais e perfis de modelo (PassProjectTemplateRole)
Cada PassProject associa um mainTemplateId (perfil PRIMARY no próprio projeto) juntamente com modelos complementares ligados (PassProjectTemplate, perfis graváveis LINKED, PRIVACY_MODE, VIP, CUSTOM, INACTIVE):
PassProjectTemplateRole | Onde é guardado | Responsabilidade funcional no projeto |
|---|---|---|
PRIMARY | PassProject.mainTemplateId | O passe de identidade âncora (ex.: Passe de Época, Chave de Quarto de Hotel ou Cartão de Fidelização) cujo externalId e atributos de cliente governam a experiência. |
LINKED / VIP / CUSTOM | PassProjectTemplate.role | Modelos complementares (ex.: Acesso Backstage VIP, Vale de Bebida, Passe de Estacionamento) empacotados na transferência ou emitidos dinamicamente por regras de segmento/automação. |
PRIVACY_MODE | PassProjectTemplate.role | Um modelo alternativo simplificado ativado automaticamente quando um titular opta por desativar o rastreio/personalização. |
INACTIVE | PassProjectTemplate.role | Modelo associado temporariamente suprimido de novas transferências em pacote sem desvincular o histórico. |
Pacotes de passes Apple Wallet (.pkpasses) e Pass.bundleId
Quando o agrupamento está ativo (bundleOnDownload: true, maxBundleSize até 10), a Passinstance liga os passes complementares emitidos sob um Pass.bundleId partilhado (bundleId FK para pass bundle):
-
Apple Wallet (Pacote
.pkpasses): Construído peloPass Grouping Engine(libs/pass-bundle,/api/v1/bundles/*ouPOST /api/v1/pass-projects/:id/download-bundle). Empacota até 10 ficheiros.pkpassassinados (request payload: 2–10 passes;request payload: 1–10 passes) servidos comoapplication/vnd.apple.pkpassespara que o iOS apresente Adicionar Tudo. -
Obtenção multi-passe Google Wallet: Serve URLs de gravação coordenados e ligações de pacote (
GET /api/v1/bundles/:id/google-wallet-link,PassProjectIssuanceProvider:APPLE\|GOOGLE,PassProjectIssuanceStatus:PENDING->VALIDATING->CREATING_PASSES->READY\|PARTIALLY_READY\|FAILED).
Importante: O Apple iOS impõe um limite máximo de 10 ficheiros
.pkpassdentro de um único pacote.pkpasses(maxBundleSize <= 10). Todos os modelos incluídos num pacote têm de estar publicados com um certificado Apple Pass Type ID válido.
Segmentos de público (PassProjectSegment) e fluxos de automação
Os Projetos integram diretamente com PassProjectSegment e AutomationFlow para orquestrar jornadas dinâmicas multi-passe sem código de ligação por webhooks externos:
-
1
Avaliação dinâmica de segmentos: Defina regras de filtragem sobre
Pass.attributes(ex.:attributes.spendTotal >= 500) e avalie viaPOST /api/v1/pass-projects/:id/segments/:segmentId/evaluate. -
2
Emissão automatizada de passes complementares: Quando um passe principal entra num segmento, um
AutomationFlowassociado emite automaticamente um passe complementar ligado (LINKED/VIP) e partilha o seu pacote/ligação de download atualizada. -
3
Comutação para Modo de Privacidade: Se o consentimento de personalização for desativado, a experiência pode migrar o passe do titular para o modelo
PRIVACY_MODE.
Referência da API REST de Pass Projects (Projects API)
Todos os endpoints de projetos estão montados em /api/v1/pass-projects (alias /api/v1/wallet-experiences):
| Método HTTP e endpoint | Descrição |
|---|---|
GET /api/v1/pass-projects | Lista todas as Wallet Experiences (Pass Projects) no espaço de trabalho ativo. |
POST /api/v1/pass-projects | Cria um novo PassProject com request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug). |
GET /api/v1/pass-projects/:id | Obtém configuração do projeto, modelos associados, prontidão e segmentos. |
PATCH /api/v1/pass-projects/:id | Atualiza nome do projeto, descrição, mainTemplateId, bundleOnDownload, maxBundleSize ou slug. |
POST /api/v1/pass-projects/:id/templates/:templateId | Associa um modelo complementar (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE). |
GET / PATCH /api/v1/pass-projects/:id/bundle | Configura ordenação do pacote, limites (maxBundleSize) e metadados .pkpasses. |
POST /api/v1/pass-projects/:id/download-bundle | Transfere/gera o pacote coordenado .pkpasses para um passe/emissão. |
GET /api/v1/pass-projects/bundle-passes/:passId | Lista todos os passes complementares agrupados com um passId específico via bundleId. |
Exemplo: Criar um projeto multi-passe (request payload)
POST /api/v1/pass-projects Cabeçalhos: 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"
}
Resposta 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
}
Consulte Arquitetura de agrupamento de passes para fluxos técnicos de empacotamento e Configuração de fluxos de trabalho para regras de automação entre projetos.
