Skip to content
Guia da Central de Ajuda · Modelos de passesFase de integração 3
3 min de leituraVerificado 2026-11-16

Versões de modelos e publicação

Valide os requisitos de publicação, associe certificados, passe de Rascunho para Publicado e gerencie alterações.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface1 / 2
Elementos-chave da interface

Lista de verificação de publicação — Configuração concluída (Zoom)

Confirme que o Certificado de assinatura, as Regras de validação e a Página de transferência apresentam todos «Ready» (3 de 3 concluídos) antes de emitir cartões.

Visão geral

A Passinstance implementa uma arquitetura de Versionamento de Modelo em Tabela Única no modelo Template. Isto permite aos operadores iterarem em layouts, associações de campos e mecânicas dentro de um ambiente isolado DRAFT, enquanto os passes ativos emitidos continuam a funcionar sem interrupções com base na revisão PUBLISHED / PRODUCTION ativa. A emissão via API externa (POST /api/v1/passes), importações em lote CSV e inscrições públicas PassFlow exigem que o modelo atinja o estado PUBLISHED.

Lista de verificação de prontidão para publicação
Lista de verificação de prontidão para publicação

Arquitetura do sistema: Versionamento em tabela única e ciclo de publicação

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
VERSIONAMENTO EM TABELA ÚNICA E PUBLICAÇÃO
ETAPA 01 Tabela Template (Linhagem de Revisões em Tabela Única)
groupId: UUID partilhado que liga todas as revisões do mesmo modelo lógico
baseId: Ponteiro para a revisão base canónica PRODUCTION
versionNumber: Inteiro incremental monótono (v1, v2, v3...)
rowKind (TemplateRowKind): PRODUCTION | PUBLISHED | ARCHIVED | DRAFT
status (template status): DRAFT | PUBLISHED | ARCHIVED | ...
ETAPA 02 AVALIADOR DE RISCOS E REQUISITOS PRÉ-PUBLICAÇÃO
Verifica certificado Apple Pass Type (.p12) e associação Google Issuer
Resolve todos os tokens {variable} face às Propriedades Personalizadas
Avalia se atualizações agendadas podem substituir campos ativos críticos
ETAPA 03 PROMOÇÃO ATÓMICA E FILA DE PROPAGAÇÃO PARA CARTEIRAS
Promove alterações de rascunho para linhagem canónica PRODUCTION/PUBLISHED
Preserva revisões substituídas no histórico de linhas ARCHIVED
Se propagateUpdates: truecoloca atualizações em fila para titulares

Modelo de versionamento em tabela única (Template)

Cada linhagem de modelo coordena revisões através de colunas e enums na tabela de base de dados template (TemplateRowKind e template status: DRAFT, PUBLISHED, ARCHIVED, DEPRECATED, UNDER_REVIEW, DELETING, DELETED):

ColunaTipoDescrição
groupIdUUIDIdentificador imutável de linhagem partilhado por todos os snapshots históricos e linhas ativas de rascunho/produção.
baseId`UUID \null`Referencia a linha base canónica do modelo (PRODUCTION / PUBLISHED) da qual deriva a revisão.
versionNumberintegerContador sequencial de revisão incrementado na publicação.
rowKindTemplateRowKindPRODUCTION (linha base canónica ligada aos passes), PUBLISHED (snapshot publicado), ARCHIVED (versão histórica substituída) ou DRAFT (cópia de trabalho isolada).

Requisitos de verificação pré-publicação

Antes de promover uma revisão DRAFT, a Passinstance avalia cinco portas de prontidão:

  1. 1
    Design visual e ativos obrigatórios: Os ativos obrigatórios da Apple Wallet (icon, logo) e Google Wallet (googlePayLogo) (image asset slot) e as descrições da organização estão preenchidos.
  2. 2
    Campos dinâmicos e atributos personalizados: Cada token {variable} referenciado em request payload (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) corresponde a uma propriedade declarada ou token de sistema (serialNumber, externalId, expirationDate).
  3. 3
    Consistência de mecânica e validação: Os parâmetros pass mechanic associados (mechanic type), comportamentos de limite e padrões de identificadores personalizados (externalIdentifierPattern) são válidos.
  4. 4
    Credenciais criptográficas de assinatura: Um certificado válido Apple Pass Type ID e uma conta Google Wallet Issuer estão associados em Definições do Modelo.
  5. 5
    Verificação de risco de publicação (GET /api/v1/templates/:id/publish-risk-check): Deteta edições críticas em campos ou mecânicas e conflitos com publicações agendadas antes da propagação.

Importante: Publicar com propagateUpdates: true coloca em fila pushes silenciosos APNs HTTP/2 e atualizações Google Wallet nos dispositivos registados. Execute sempre GET /api/v1/templates/:id/publish-risk-check e teste primeiro as alterações num único passe (activePassesOnly: true limita a propagação aos passes atualmente ativos).

Referência da API de publicação, agendamento e reversão (Templates API)

1. Executar verificação de risco pré-publicação

GET /api/v1/templates/:id/publish-risk-check
Cabeçalhos
X-API-Key <API_KEY>

Devolve avisos de alterações críticas avaliados face aos passes ativos e a eventuais publicações agendadas pendentes (TemplatePublishRiskCheckResult encapsulado em API response envelope).

2. Publicar revisão do modelo imediatamente (request payload)

Promove a revisão em rascunho para a linhagem ativa do modelo e envia opcionalmente alterações visuais/de campos aos passes instalados:

POST /api/v1/templates/:id/publish Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "propagateUpdates": true,
  "activePassesOnly": true,
  "sendNotifications": true,
  "notificationMessage": "New seasonal card layout is live!",
  "acknowledgePublishRiskWarning": true,
  "overrideReason": "Verified holiday strip colors on test pass"
}

Resposta HTTP (200 OK)

JSON
{
  "success": true,
  "description": "Template published successfully",
  "errors": [],
  "data": {
    "id": "tmpl_01hxyz987654321",
    "groupId": "grp_01hxyz987654321",
    "versionNumber": 3,
    "rowKind": "PRODUCTION",
    "status": "PUBLISHED",
    "updatedAt": "2026-11-15T14:00:00.000Z"
  },
  "statusCode": 200
}

3. Agendar publicação futura

Coloca em fila uma revisão em rascunho para publicar automaticamente numa data/hora local do cliente ou ISO (se scheduledAt estiver no passado ou presente, o servidor publica imediatamente):

POST /api/v1/templates/:id/schedule-publication Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "scheduledAt": "2026-11-27 00:00",
  "timeZone": "Europe/Berlin",
  "activePassesOnly": true,
  "sendNotifications": false,
  "message": "Black Friday seasonal artwork activated."
}

4. Descartar rascunho de trabalho e reverter para estado ativo

Descarta alterações não guardadas/não publicadas na linha DRAFT e repõe o rascunho de trabalho para a revisão base publicada ativa:

POST /api/v1/templates/:id/discard-draft
Cabeçalhos
X-API-Key <API_KEY>
JSON
{
  "success": true,
  "description": "Template draft discarded successfully",
  "data": {
    "success": true,
    "message": "Draft discarded successfully"
  },
  "errors": [],
  "statusCode": 200
}

Assim que o seu modelo estiver publicado, prossiga para Criar passes individuais ou Criação em massa de passes.

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.