Visão geral
Um Modelo de Passe (modelo Template) define a geometria estrutural, identidade visual, zonas de layout dos campos, simbologia do código de barras e regras de relevância por localização partilhadas por todos os passes emitidos no âmbito de um programa. A Passinstance compila uma única configuração canónica do modelo em pacotes nativos Apple Wallet (.pkpass) e em definições na cloud Google Wallet (Class / Object).
Abra qualquer modelo no Painel e aceda a Editar Modelo para configurar o design e as regras de carteira lado a lado com uma pré-visualização em direto na Apple Wallet e Google Wallet, ou gira modelos programaticamente através de /api/v1/templates.

Arquitetura do sistema: Pipeline de serialização de modelos
1. Identidade, tipos de passe e zonas de layout dos campos
Ao criar um modelo, selecione o pass type / PassKind subjacente (storeCard, coupon, eventTicket, boardingPass, membership, studentId, generic, posterGeneric ou businessCard), opcionalmente combinado com theme preference (posterGeneric, posterEventTicket, bannerEventTicket, semanticBoardingPass, DARK) e transit type (PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric, PKTransitTypeTrain) para cartões de embarque. Cada tipo de passe determina como o sistema operativo móvel apresenta o cabeçalho do cartão, a imagem principal e as linhas de campos.
As 7 posições canónicas de campos (field placement type)
O modelo Field e request payload colocam elementos de dados em posições de layout distintas (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER):
Posição do campo (request payload / field placement type) | Apresentação Apple Wallet | Mapeamento Google Wallet | Conteúdo típico |
|---|---|---|---|
headerFields (HEADER) | Canto superior direito junto ao logo (máx. 1–3 campos compactos) | Mapeado para metadados superiores de estado/cabeçalho | Saldo de pontos, distintivo de nível VIP, n.º de porta |
primaryFields (PRIMARY) | Faixa central de destaque sobre ou abaixo de strip | Métrica ou título principal do cartão | Nome do titular, % desconto, título do evento |
secondaryFields (SECONDARY) | Linha diretamente abaixo dos campos principais (até 4 colunas) | Linha superior de textModulesData | N.º de sócio, lugar/fila/setor, contador de carimbos |
auxiliaryFields (AUXILIARY) | Linha adicional de metadados abaixo dos secundários (ou acima em eventTicket) | Linha secundária de textModulesData | Data de validade, loja, promotor |
backFields (BACK) | Verso deslizável do passe (suporta texto longo e ligações) | Vista expansível Detalhes (textModulesData e linksModuleData) | Termos e condições, telefone de suporte, URLs |
additionalInfoFields (ADDITIONALINFO) | Detalhes complementares e blocos de recinto iOS 18+ | Módulos auxiliares de detalhes | FAQ do evento, instruções de entrada, informações adicionais |
footerFields (FOOTER) | Zona inferior imediatamente adjacente ao código de barras | Rótulo de rodapé do código de barras | Código de segurança ou instruções para introdução manual |
2. Cores e regras de serialização por plataforma
O modelo Color persiste quatro propriedades semânticas principais de cor por modelo: backgroundColor, foregroundColor (texto dos valores dos campos), labelColor (legendas dos rótulos dos campos) e stripColor (tonalidade da sobreposição de texto sobre imagens de faixa).
-
Apple Wallet (
rgb(r, g, b)): O analisadorpass.jsonda Apple Wallet exige estritamente strings CSS em tripletos RGB sem canais alfa — por exemplo,rgb(24, 24, 27). Valores hexadecimais (#18181B) ourgba()são normalizados automaticamente pelo serializador da Passinstance para que nenhuma sintaxe de cor inválida entre nos pacotes.pkpass. -
Google Wallet (
#RRGGBB): As classeswalletobjectsda Google Wallet exigem strings hexadecimais de 6 carateres (#18181B). A Passinstance traduz os tokens de cor do modelo de forma transparente para ambas as plataformas. -
Verificação de contraste WCAG: O Editor Visual avalia em tempo real os rácios de contraste de luminância entre
backgroundColoreforegroundColor/labelColor, alertando os operadores se a tipografia ficar abaixo dos limiares de legibilidade WCAG AA.
Importante: A Apple Wallet exige estritamente cores no formato
rgb(r, g, b)e rejeita códigos hexadecimais ou canais alfa nopass.json. Ao chamar a API REST da Passinstance, pode indicarrgb(r, g, b)ou#RRGGBB— o backend normaliza e serializa automaticamente o formato exato exigido por cada plataforma.
3. Os 13 slots de ativos visuais e variantes retina
A Passinstance gere 13 slots distintos de ativos de imagem no modelo Template. Quando carrega um PNG de origem de alta resolução, o pipeline de ativos redimensiona e empacota automaticamente variantes retina @1x, @2x e @3x para a Apple Wallet enquanto aloja os URLs públicos CDN exigidos pela Google Wallet:
| Chave do slot de ativo | Plataforma alvo | Dimensões @1x | Dimensões @2x | Dimensões @3x | Finalidade e colocação no layout |
|---|---|---|---|---|---|
icon | Apple Wallet | 29 x 29 px | 58 x 58 px | 87 x 87 px | Ícone obrigatório para notificações no ecrã bloqueado e anexos de e-mail |
logo | Apple Wallet | 160 x 50 px | 320 x 100 px | 480 x 150 px | Logótipo da marca no canto superior esquerdo junto a logoText e campos header |
primaryLogo | Unificado / Alternativa | 160 x 50 px | 320 x 100 px | 480 x 150 px | Marca canónica herdada pelos alvos de carteira |
googlePayLogo | Google Wallet | 660 x 660 px (mín.) | — | — | Logótipo do programa com recorte circular no cabeçalho Google Wallet (proporção 1:1) |
strip | Apple (storeCard, coupon, eventTicket) | 375 x 123 px (eventTicket: 375 x 98 px) | 750 x 246 px | 1125 x 369 px | Faixa horizontal de ponta a ponta atrás/acima dos campos principais |
background | Apple (eventTicket, generic) | 180 x 220 px | 360 x 440 px | 540 x 660 px | Textura de fundo desfocada de todo o cartão |
thumbnail | Apple (generic, membership, eventTicket) | 90 x 90 px | 180 x 180 px | 270 x 270 px | Foto de retrato quadrada ou selo de produto do lado direito |
footer | Apple (boardingPass, eventTicket) | 286 x 15 px | 572 x 30 px | 858 x 45 px | Faixa estreita apresentada imediatamente acima do código de barras |
artwork | Apple WWDC25 Poster Ticket | 375 x 480 px | 750 x 960 px | 1125 x 1440 px | Imagem poster de elevado impacto para Event Tickets iOS |
venueMap | Apple WWDC25 Event Guide | 375 x 375 px | 750 x 750 px | 1125 x 1125 px | Mapa de lugares/planta do recinto transferível no iOS Event Guide |
secondaryLogo | Co-branding unificado | 160 x 50 px | 320 x 100 px | 480 x 150 px | Distintivo de marca secundária ou patrocinador |
androidBackground | Google Wallet | 1032 x 336 px | — | — | Substituição dedicada do banner heroImage Google Wallet (proporção 3.07:1) |
androidLogo | Google Wallet | 660 x 660 px | — | — | Substituição explícita do logótipo Google Wallet quando distinto de googlePayLogo |
4. Formatos de código de barras suportados e regras de validação
O modelo Barcode e request payload coordenam barcode format (formatos Apple Wallet incluindo os geométricos PKBarcodeFormatSquare / PKBarcodeFormatRectangle e PKBarcodeFormatNone) e valores canónicos BarcodeType (QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13, CODE_39, CODABAR, ITF), juntamente com altText (ou barcodeAlternativeText), messageEncoding (ISO_8859_1, UTF_8, ISO_8859_15, WINDOWS_1252, SHIFT_JIS), appleFallbackType e addSecurityAnimation (cintilação dinâmica anticaptura de ecrã):
| Valor barcode format | Tipo canónico | Apple Wallet nativo | Google Wallet nativo | Caso de uso típico na indústria |
|---|---|---|---|---|
PKBarcodeFormatQR (PKBarcodeFormatSquare) | QR_CODE | Sim (PKBarcodeFormatQR) | Sim (QR_CODE) | Fidelização de retalho, check-in em eventos, leitores com câmara |
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle) | PDF_417 | Sim (PKBarcodeFormatPDF417) | Sim (PDF_417) | Cartões de embarque aéreos, bilhetes de transporte, identificações |
PKBarcodeFormatAztec | AZTEC | Sim (PKBarcodeFormatAztec) | Sim (AZTEC) | Bilhetes ferroviários, passes de eventos de elevada densidade |
PKBarcodeFormatCode128 | CODE_128 | Sim (PKBarcodeFormatCode128) | Sim (CODE_128) | Leitores laser POS de supermercado, cartões de sócio |
PKBarcodeFormatCode39 | CODE_39 | Alternativa / Renderizado | Sim (CODE_39) | Setor automóvel, industrial e leitores de crachás |
PKBarcodeFormatCodabar | CODABAR | Alternativa / Renderizado | Sim (CODABAR) | Bibliotecas, laboratórios e logística |
PKBarcodeFormatEAN13 | EAN_13 | Alternativa / Renderizado | Sim (EAN_13) | Cupões de retalho e caixas POS UPC/EAN |
PKBarcodeFormatI2of5 | ITF (aceita ITF_14 de 14 dígitos na Google) | Alternativa / Renderizado | Sim (ITF_14 para 14 dígitos) | Embalagem, retalho grossista e bilhetes numéricos intercalados |
PKBarcodeFormatNone | NONE | Sem código de barras apresentado | Sem código de barras apresentado | Passes exclusivos de NFC (nfcNoBarcode: true) |
5. Geofencing, iBeacons, identificadores e relevância temporal
Os passes surgem automaticamente no ecrã bloqueado do cliente quando correspondem gatilhos físicos ou temporais de relevância:
-
Localizações GPS (modelo
Location): Até 10 coordenadas por modelo (latitude,longitude,altitudeopcional,maxDistanceem metros erelevantTextexibido no ecrã bloqueado). -
Beacons Bluetooth Low Energy (modelo
Beacon): Até 10 Apple iBeacons (proximityUUID, identificadores de 16 bitsmajoreminor, erelevantText) para deteção de microlocalização interior junto a entradas de loja ou torniquetes. -
Relevância temporal (
RelevantDate): Carimbo temporal ISO 8601 (relevantDate) eexpirationDateque apresentam bilhetes de eventos ou vales com prazo à medida que a hora marcada se aproxima. -
Definições de identificadores personalizados e agrupamento: Configure
customIdentifiersEnabled,externalIdentifierPattern,customIdentifierValidationPattern,bundleOnDownload,bundleEnabledemaxBundleSize(até10passes por pacote).
6. Referência da API programática de modelos (request payload)
Listar modelos do espaço de trabalho
/api/v1/templates?page=1&limit=20&rowKind=PRODUCTION
Criar um novo modelo (request payload)
POST /api/v1/templates Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"name": "Artisan Coffee Club - Gold",
"kind": "storeCard",
"status": "DRAFT",
"organizationName": "Artisan Roasters GmbH",
"description": "Artisan Coffee Loyalty Card",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{serialNumber}",
"addSecurityAnimation": true
},
"locations": [
{
"latitude": 52.520008,
"longitude": 13.404954,
"maxDistance": 150,
"relevantText": "Welcome back to Artisan Roasters! Tap to scan your card."
}
]
}
Resposta HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01hxyz987654321",
"groupId": "grp_01hxyz987654321",
"versionNumber": 1,
"rowKind": "DRAFT",
"status": "DRAFT",
"name": "Artisan Coffee Club - Gold",
"kind": "storeCard",
"colors": {
"backgroundColor": "rgb(20, 35, 28)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(167, 243, 208)",
"stripColor": "rgb(255, 255, 255)"
},
"createdAt": "2026-11-15T10:15:00.000Z"
},
"statusCode": 201
}
Prossiga para Campos dinâmicos e personalização para associar atributos personalizados ao layout do seu modelo, ou explore Mecânicas e funcionalidades de passes.
