Skip to content
Guia da Central de Ajuda · Projetos e organização
4 min de leituraVerificado 2026-11-16

Gerir projetos

Agrupe um modelo principal com modelos associados em Wallet Experiences, bundles e trocas por segmento.

Neste guia

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
EMPACOTAMENTO (.PKPASSES) E AUTOMAÇÃO DE SEGMENTOS
ETAPA 01 PROJETO DE PASSES (PassProject e PassProjectTemplate)
PRIMARY (mainTemplateId): Sócio Principal / Bilhete / Embarque de Voo
LINKED / VIP / CUSTOM: Vale de Lounge / Estacionamento / Cartão Gala
PRIVACY_MODE / INACTIVE: Layout privado simplificado ou cartão em pausa
ETAPA 02A PACOTE APPLE PASS (.pkpasses ZIP)
Agrupa até 10 ficheiros .pkpass assinados com mesmo Pass.bundleId
bundle grouping mode: AUTO | `MANUA
BundleStatus: ACTIVE | CANCELLED
ETAPA 02B ORQUESTRADOR SEGMENTOS E AUTOMAÇÃO
Avalia regras PassProjectSegment sobre Pass.attributes (GIN) | | - Executa açõesAutomationFl emitir passe ligado / trocar modelo

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):

PassProjectTemplateRoleOnde é guardadoResponsabilidade funcional no projeto
PRIMARYPassProject.mainTemplateIdO 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 / CUSTOMPassProjectTemplate.roleModelos 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_MODEPassProjectTemplate.roleUm modelo alternativo simplificado ativado automaticamente quando um titular opta por desativar o rastreio/personalização.
INACTIVEPassProjectTemplate.roleModelo 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 pelo Pass Grouping Engine (libs/pass-bundle, /api/v1/bundles/* ou POST /api/v1/pass-projects/:id/download-bundle). Empacota até 10 ficheiros .pkpass assinados (request payload: 2–10 passes; request payload: 1–10 passes) servidos como application/vnd.apple.pkpasses para 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 .pkpass dentro 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. 1
    Avaliação dinâmica de segmentos: Defina regras de filtragem sobre Pass.attributes (ex.: attributes.spendTotal >= 500) e avalie via POST /api/v1/pass-projects/:id/segments/:segmentId/evaluate.
  2. 2
    Emissão automatizada de passes complementares: Quando um passe principal entra num segmento, um AutomationFlow associado emite automaticamente um passe complementar ligado (LINKED / VIP) e partilha o seu pacote/ligação de download atualizada.
  3. 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 endpointDescrição
GET /api/v1/pass-projectsLista todas as Wallet Experiences (Pass Projects) no espaço de trabalho ativo.
POST /api/v1/pass-projectsCria um novo PassProject com request payload (name, mainTemplateId, bundleOnDownload, maxBundleSize, slug).
GET /api/v1/pass-projects/:idObtém configuração do projeto, modelos associados, prontidão e segmentos.
PATCH /api/v1/pass-projects/:idAtualiza nome do projeto, descrição, mainTemplateId, bundleOnDownload, maxBundleSize ou slug.
POST /api/v1/pass-projects/:id/templates/:templateIdAssocia um modelo complementar (LINKED, VIP, PRIVACY_MODE, CUSTOM, INACTIVE).
GET / PATCH /api/v1/pass-projects/:id/bundleConfigura ordenação do pacote, limites (maxBundleSize) e metadados .pkpasses.
POST /api/v1/pass-projects/:id/download-bundleTransfere/gera o pacote coordenado .pkpasses para um passe/emissão.
GET /api/v1/pass-projects/bundle-passes/:passIdLista 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

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)

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
}

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.

Documentação de produto e API relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.