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.

Arquitetura do sistema: Versionamento em tabela única e ciclo de publicação
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):
| Coluna | Tipo | Descrição | |
|---|---|---|---|
groupId | UUID | Identificador 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. |
versionNumber | integer | Contador sequencial de revisão incrementado na publicação. | |
rowKind | TemplateRowKind | PRODUCTION (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
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
Campos dinâmicos e atributos personalizados: Cada token
{variable}referenciado emrequest payload(HEADER,PRIMARY,SECONDARY,AUXILIARY,BACK,ADDITIONALINFO,FOOTER) corresponde a uma propriedade declarada ou token de sistema (serialNumber,externalId,expirationDate). -
3
Consistência de mecânica e validação: Os parâmetros
pass mechanicassociados (mechanic type), comportamentos de limite e padrões de identificadores personalizados (externalIdentifierPattern) são válidos. -
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
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: truecoloca em fila pushes silenciosos APNs HTTP/2 e atualizações Google Wallet nos dispositivos registados. Execute sempreGET /api/v1/templates/:id/publish-risk-checke teste primeiro as alterações num único passe (activePassesOnly: truelimita 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
/api/v1/templates/:id/publish-risk-check
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
{
"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)
{
"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
{
"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:
/api/v1/templates/:id/discard-draft
{
"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.
