Visão geral
À medida que a sua organização cresce em campanhas sazonais, filiais regionais e ambientes de staging vs. produção, a Passinstance oferece ferramentas de organização de espaços de trabalho em várias camadas: Categorização e Etiquetagem de Modelos, Clonagem de Modelos (Template Duplication Wizard), Filtragem por Ciclo de Vida rowKind (DRAFT, PUBLISHED, PRODUCTION, ARCHIVED), Aplicação de Unicidade Composta de ID Externo, Pesquisa de Atributos com Índice GIN na Base de Dados (attribute search index) e Mapeamento de Modelos entre Projetos.
Arquitetura do sistema: Taxonomia do espaço de trabalho, clonagem e vistas guardadas
1. Copiar um modelo: Duplicar um modelo existente (Clonagem e duplicação de modelos)
Em vez de reconfigurar cores, layouts de campos, códigos de barras e esquemas de propriedades personalizadas de raiz para cada novo programa de cartões, pode duplicar qualquer modelo existente em segundos.
Como clonar no Painel
Os operadores podem iniciar a clonagem de modelos a partir de dois locais:
-
1
A partir do Diretório de Modelos: Em qualquer cartão de modelo, clique no menu Três Pontos (...) e selecione Duplicar.
-
2
A partir do Editor Visual: Na barra de comandos superior, clique em Ações -> Duplicar Modelo.
O fluxo de 4 etapas do Template Duplication Wizard
O Template Duplication Wizard orienta os operadores durante a duplicação de um modelo:
-
1
Passo 1: Selecionar Modelo de Origem: Confirma o modelo de origem e inspeciona o respetivo tipo de passe, contagem de campos e imagens anexadas.
-
2
Passo 2: Nome e Descrição: Pré-preenche o nome do novo modelo com
${sourceTemplate.name} (Copy)e permite introduzir uma descrição distinta. -
3
Passo 3: Personalização:
- Página de Registo PassFlow Associada: Escolha se pretende clonar o formulário público de registo associado através de duplicatePassFlow (criando uma página PassFlow independente /f/:newUrl) ou deixar o novo modelo sem formulário associado. - Cores da Marca: Modifique backgroundColor, foregroundColor e labelColor. O assistente executa validação de contraste WCAG AA em tempo real para garantir legibilidade. - Ativos Visuais: Escolha se pretende manter as imagens do modelo de origem (icon, logo, strip, thumbnail) ou carregar novos ativos de marca.
-
4
Passo 4: Atribuição de Certificado: Selecione um certificado de assinatura Apple Pass Type ID existente nas definições do espaço de trabalho ou carregue um novo certificado
.p12/.cer.
2. Isolamento de espaços de trabalho e higiene na nomenclatura de modelos
A Passinstance isola modelos, passes, certificados e chaves de API na fronteira do espaço de trabalho Customer dentro da sua Organization principal (POST /api/v1/organizations/current/workspaces):
-
1
Separar Ambientes por Espaço de Trabalho: Mantenha rascunhos experimentais e testes de integração num espaço de trabalho
sandbox, reservando o seu espaço de trabalhoproductionexclusivamente para programas de clientes ativos. -
2
Padronizar Nomes e Etiquetas de Modelos: Inclua o domínio do programa, a região e a versão nos títulos dos modelos (por exemplo,
Loyalty-CoffeeClub-EU-v2) e associetagsestruturadas (por exemplo,["retail", "q4-2026", "dach"]) para filtragem instantânea do catálogo. -
3
Arquivar Modelos Substituídos (
rowKind: ARCHIVED): Em vez de eliminar modelos promocionais históricos que ainda possuem registos de passes emitidos associados, transite-os para Arquivado. Os modelos arquivados ficam ocultos dos seletores ativos predefinidos, preservando análises históricas e registos de leituras sob o filtro Todos / Arquivados.
3. Unicidade de ID externo, identificadores personalizados e agrupamento em pacotes
Para evitar a emissão de passes duplicados entre formulários web, terminais POS e webhooks de CRM, configure políticas de identificadores e agrupamento nas Definições do Modelo:
| Definição / Propriedade do modelo | Aplicação na base de dados e na API | |
|---|---|---|
externalId (Pass.externalId) | String fornecida pelo cliente (máx. 255 carateres) indexada de forma única por passe ativo não eliminado no tenant (@@unique([customerId, externalId]) WHERE archivedAt IS NULL). Chamadas duplicadas POST /api/v1/passes são rejeitadas, enquanto POST /api/v1/passes/upsert-by-external-id atualiza no local. | |
Regras de Identificador Personalizado (Template) | Configure customIdentifiersEnabled, externalIdentifierPattern e customIdentifierValidationPattern nas Definições do Modelo para impor formatos regex em toda a organização sobre identificadores externos gerados/importados. | |
Agrupamento de Vários Cartões (Pass.bundleId) | Chave estrangeira bundleId que liga até 10 passes num único pass bundle (bundle grouping mode: AUTO \ | MANUAL) para entrega .pkpasses. |
Vinculação a Dispositivo Único (limitToOneActivePerPass) | Restringe ligações inteligentes de transferência para que um único passe não possa ser partilhado e instalado em simultâneo em dispositivos não autorizados. |
Importante: Impor a unicidade de
externalIdé altamente recomendado para modelos de fidelização, cartões de sócio e cartões-presente pré-pagos. A eliminação lógica de um passe de teste (eliminaçãoSOFT) definearchivedAte liberta imediatamente esseexternalIdpara reutilização.
4. Indexação de atributos JSON estruturados (attribute search index) e vistas guardadas
Cada propriedade personalizada armazenada em Pass.attributes é indexada automaticamente pelo Generalized Inverted Index da base de dados (attribute search index). Isto permite a operadores e consumidores da API organizar e consultar milhões de passes sem migrações de esquema:
-
Vistas Guardadas de Operador: No diretório Passes (
/passes), combine predicados de filtro E/OU sobrestatus(estado do passe),lifecycleStatus,walletVoidStatus(WalletPropagationStatus),bundleId,externalId, plataforma de dispositivo (APPLE_WALLETvs.GOOGLE_WALLET) e chaves JSON estruturadas personalizadas (attributes.tier,attributes.storeId), e guarde a consulta como uma Vista Guardada. -
Mapeamento de Modelos entre Projetos: Agrupe modelos relacionados em Experiências de Carteira (
PassProject) em vez de clonar modelos isolados. Um único modelo pode atuar como modeloLINKED,VIP,CUSTOMouPRIVACY_MODEem vários contentoresPassProject(PassProjectTemplateRole), mantendo governação centralizada de ativos e mecânicas.
Referência da API: Duplicação e filtragem de modelos
1. Duplicar um modelo via API (POST /api/v1/templates/:id/duplicate)
Clona um modelo existente, copiando os seus campos de layout, cores, códigos de barras e definições de propriedades personalizadas:
POST /api/v1/templates/tmpl_01hxyz987654321/duplicate Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"duplicatePassFlow": true,
"certificateId": "cert_01j7k8m9n2p3"
}
Resposta HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_new_clone_01h987",
"name": "Artisan Coffee Club - Platinum Tier (Copy)",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T21:20:00.000Z"
},
"statusCode": 201
}
2. Filtrar modelos por estado, tipo e etiquetas
/api/v1/templates?rowKind=PRODUCTION&kind=storeCard&tag=retail&search=Coffee&page=1&limit=20
{
"success": true,
"data": {
"items": [
{
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"name": "Loyalty-CoffeeClub-EU-v2",
"kind": "storeCard",
"rowKind": "PRODUCTION",
"status": "PUBLISHED",
"versionNumber": 2,
"tags": ["retail", "q4-2026", "dach"],
"activePassesCount": 14820
}
],
"total": 1,
"page": 1,
"limit": 20
},
"statusCode": 200
}
Explore Gerir projetos para combinar passes de vários modelos, ou leia Compreender o seu espaço de trabalho para conhecer as regras de multi-espaços de trabalho.
