Visão geral
A Passinstance oferece suporte nativo para criar e configurar modelos de passes programaticamente através de payloads JSON. Em vez de configurar manualmente layouts visuais, codificações de códigos de barras, cores e atributos dinâmicos no Editor Visual, os programadores e integradores de plataformas podem submeter esquemas completos de modelos à API REST (POST /api/v1/templates ou POST /api/v1/templates/import).
O motor de modelos de backend processa o JSON recebido através do pipeline de normalização e validação com normalização automática de esquemas, validando as geometrias dos passes, impondo os invariantes de cor da Apple Wallet e da Google Wallet e registando propriedades personalizadas.
Arquitetura do sistema: Pipeline de ingestão de modelos JSON
Especificação do esquema JSON para request payload
Uma definição JSON válida de modelo deve respeitar a estrutura request payload aceite por POST /api/v1/templates:
| Propriedade de topo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome legível do modelo (por exemplo, "Artisan Coffee Club"). Máx. 255 carateres. |
kind | PassKind | Sim | Geometria do tipo de passe: storeCard, coupon, eventTicket, boardingPass, generic ou posterGeneric. |
organizationName | string | Sim | Nome da organização apresentado nos passes Apple Wallet e Google Wallet. |
description | string | Sim | Descrição acessível do passe exigida pelo Apple PassKit. |
status | estado do modelo | Não | Estado inicial. Predefinido para PUBLISHED aquando da criação programática. |
colors | request payload | Não | Objeto contendo backgroundColor, foregroundColor, labelColor e stripColor. |
barcode | request payload | Não | Configuração do código de barras (format, messageEncoding, altText, addSecurityAnimation). |
fields | request payload | Não | Coleções de campos agrupadas por zona (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields). |
locations | request payload[] | Não | Array de até 10 coordenadas GPS que acionam notificações no ecrã bloqueado. |
beacons | request payload[] | Não | Array de até 10 iBeacons Bluetooth para deteção de proximidade em interiores. |
expiration | request payload | Não | Estratégia de validade e expiração do passe (none, fixed ou duration). |
O subobjeto colors
A Apple Wallet impõe estritamente o formato CSS RGB (rgb(r, g, b)) para cores e rejeita valores hexadecimais ou canais alfa. Ao importar JSON através da Passinstance, o normalizador aceita sintaxe hexadecimal ou RGB e serializa o formato exato exigido por cada fornecedor de carteira:
{
"backgroundColor": "rgb(24, 24, 27)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(161, 161, 170)",
"stripColor": "rgb(255, 255, 255)"
}
O subobjeto barcode
{
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{cardNumber}",
"addSecurityAnimation": true
}
Os formatos suportados incluem: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5 e PKBarcodeFormatNone.
Regras de validação e normalização (normalizeTemplateImport)
Quando JSON em bruto é submetido a POST /api/v1/templates/import, o backend executa normalizeTemplateImport:
-
1
Normalização do Tipo de Passe: Traduz nomes de estilo legados ou alternativos (como
store_card->storeCard,event_ticket->eventTicket,boarding_pass->boardingPass). -
2
Deteção do Tipo de Trânsito: Para passes
boardingPass, mapeia stringstransitType(PKTransitTypeAir,PKTransitTypeTrain,PKTransitTypeBus,PKTransitTypeBoat,PKTransitTypeGeneric). -
3
Ajuste de Posicionamento de Campos: Valida se os campos colocados em
auxiliaryFieldscumprem as regras do tipo de passe (por exemplo, passescouponrejeitam campos auxiliares e redirecionam-nos parasecondaryFields). -
4
Atribuição de Fallback de Código de Barras: Se um código de barras 1D (
Code 128,Code 39,EAN-13) for configurado sem alternativa, o normalizador atribui automaticamentePKBarcodeFormatQRcomo código de barras de fallback para o Apple Watch. -
5
Remoção de Chaves de Sistema: Remove silenciosamente chaves de tenant perigosas ou chaves internas de sistema (
id,customerId,tenantId,certificateId,version,status,passes,createdAt,updatedAt,archivedAt).
Referência da API: Criar um modelo a partir de JSON
Pedido HTTP
/api/v1/templates
{
"name": "Acme VIP Club",
"kind": "storeCard",
"organizationName": "Acme Retail Group",
"description": "Acme VIP Rewards Card",
"colors": {
"backgroundColor": "rgb(15, 23, 42)",
"foregroundColor": "rgb(248, 250, 252)",
"labelColor": "rgb(148, 163, 184)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{externalId}"
},
"fields": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "VIP Platinum",
"textAlignment": "PKTextAlignmentRight"
}
],
"primaryFields": [
{
"key": "holder",
"label": "MEMBER",
"value": "{firstName} {lastName}"
}
],
"secondaryFields": [
{
"key": "balance",
"label": "POINTS",
"value": "{pointsBalance}",
"numberStyle": "PKNumberStyleDecimal"
}
],
"backFields": [
{
"key": "terms",
"label": "TERMS & CONDITIONS",
"value": "Valid at all participating Acme stores. Points expire after 12 months of inactivity."
}
]
},
"locations": [
{
"latitude": 40.712776,
"longitude": -74.005974,
"maxDistance": 250,
"relevantText": "Welcome to Acme Flagship! Scan your pass at checkout."
}
]
}
Resposta HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01h9x8k7m6n5p4q3r2s1",
"groupId": "grp_01h9x8k7m6n5p4q3r2s1",
"name": "Acme VIP Club",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T20:30:00.000Z",
"updatedAt": "2026-11-16T20:30:00.000Z"
},
"statusCode": 201
}
Erros comuns de ingestão JSON e resoluções
| Estado HTTP | Mensagem de erro | Causa raiz e resolução |
|---|---|---|
| 400 Bad Request | Template icon is required | Ao criar modelos via JSON sem ativos base existentes, deve ser fornecido um ativo icon ou um data URI, ou atribuído um ID de ativo existente no espaço de trabalho. |
| 400 Bad Request | Invalid color format: must be rgb(r, g, b) | Uma string de cor continha canais alfa (rgba(0,0,0,0.5)) ou sintaxe malformada. Forneça rgb(r, g, b) padrão ou hexadecimal de 6 dígitos (#RRGGBB). |
| 400 Bad Request | Auxiliary fields are not supported on coupon passes | O payload submeteu auxiliaryFields para um tipo de passe coupon. Mova os campos auxiliares para secondaryFields ou altere o tipo de passe para storeCard. |
| 413 Payload Too Large | Import payload exceeds 5MB limit | O payload JSON excedeu o maximum upload size limit (5 MB), normalmente devido a strings de imagem em base64 incorporadas. Carregue as imagens através do endpoint de ativos de imagem. |
Continue para Importar do Apple Pass Designer para importar projetos .passdesign existentes ou explore Campos dinâmicos e personalização para configurar variáveis de atributos.
