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

Design e configuração de modelos

Domine o Editor Visual: formatos, cores com validação de contraste WCAG, logótipos, imagens e códigos de barras.

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

Cores da marca e contraste WCAG (Ampliado)

Defina cores com correção automática de contraste, troca rápida, cor para passe anulado e adaptação Apple/Google.

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.

Cores da marca e verificador de contraste no editor
Cores da marca e verificador de contraste no editor

Arquitetura do sistema: Pipeline de serialização de modelos

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PIPELINE DE DESIGN E SERIALIZAÇÃO DE MODELOS
ETAPA 01 EDITOR VISUAL / API REST (/api/v1/templates)
6 Zonas Campos
(HeaderBack)
13 Slots Imagem
(@1x, @2x, @3x)
Esquema Cores
(RGB / Hex)
11 Barras e
Geofencing
ETAPA 02 MOTOR DE VALIDAÇÃO E COMPILAÇÃO DE MODELOS
Impõe restrições de geometria pass type (storeCard, eventTicket, etc.)
Converte tokens de corrgb(r, g, b) Apple e #RRGGBB Google
Gera derivados retina (@1x, @2x, @3x) no cloud object storage
Valida rácios de contraste WCAG 2.1 AA e codificação de barras (iso-8859-1 / utf-8)
ETAPA 03A APPLE WALLET (Pacote .pkpass)
Serialização dicionário pass.json
icon.png, logo@2x.png, strip.png
locations[], beacons[], nfc{}
ETAPA 03B GOOGLE WALLET (Recurso Class)
LoyaltyClass / EventTicketClass
hexBackgroundColor e heroImage
callbackOptions e config Smart Tap

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 WalletMapeamento Google WalletConteúdo típico
headerFields (HEADER)Canto superior direito junto ao logo (máx. 1–3 campos compactos)Mapeado para metadados superiores de estado/cabeçalhoSaldo de pontos, distintivo de nível VIP, n.º de porta
primaryFields (PRIMARY)Faixa central de destaque sobre ou abaixo de stripMétrica ou título principal do cartãoNome do titular, % desconto, título do evento
secondaryFields (SECONDARY)Linha diretamente abaixo dos campos principais (até 4 colunas)Linha superior de textModulesDataN.º 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 textModulesDataData 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 detalhesFAQ do evento, instruções de entrada, informações adicionais
footerFields (FOOTER)Zona inferior imediatamente adjacente ao código de barrasRótulo de rodapé do código de barrasCó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 analisador pass.json da Apple Wallet exige estritamente strings CSS em tripletos RGB sem canais alfa — por exemplo, rgb(24, 24, 27). Valores hexadecimais (#18181B) ou rgba() são normalizados automaticamente pelo serializador da Passinstance para que nenhuma sintaxe de cor inválida entre nos pacotes .pkpass.
  • Google Wallet (#RRGGBB): As classes walletobjects da 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 backgroundColor e foregroundColor / 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 no pass.json. Ao chamar a API REST da Passinstance, pode indicar rgb(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 ativoPlataforma alvoDimensões @1xDimensões @2xDimensões @3xFinalidade e colocação no layout
iconApple Wallet29 x 29 px58 x 58 px87 x 87 pxÍcone obrigatório para notificações no ecrã bloqueado e anexos de e-mail
logoApple Wallet160 x 50 px320 x 100 px480 x 150 pxLogótipo da marca no canto superior esquerdo junto a logoText e campos header
primaryLogoUnificado / Alternativa160 x 50 px320 x 100 px480 x 150 pxMarca canónica herdada pelos alvos de carteira
googlePayLogoGoogle Wallet660 x 660 px (mín.)——Logótipo do programa com recorte circular no cabeçalho Google Wallet (proporção 1:1)
stripApple (storeCard, coupon, eventTicket)375 x 123 px (eventTicket: 375 x 98 px)750 x 246 px1125 x 369 pxFaixa horizontal de ponta a ponta atrás/acima dos campos principais
backgroundApple (eventTicket, generic)180 x 220 px360 x 440 px540 x 660 pxTextura de fundo desfocada de todo o cartão
thumbnailApple (generic, membership, eventTicket)90 x 90 px180 x 180 px270 x 270 pxFoto de retrato quadrada ou selo de produto do lado direito
footerApple (boardingPass, eventTicket)286 x 15 px572 x 30 px858 x 45 pxFaixa estreita apresentada imediatamente acima do código de barras
artworkApple WWDC25 Poster Ticket375 x 480 px750 x 960 px1125 x 1440 pxImagem poster de elevado impacto para Event Tickets iOS
venueMapApple WWDC25 Event Guide375 x 375 px750 x 750 px1125 x 1125 pxMapa de lugares/planta do recinto transferível no iOS Event Guide
secondaryLogoCo-branding unificado160 x 50 px320 x 100 px480 x 150 pxDistintivo de marca secundária ou patrocinador
androidBackgroundGoogle Wallet1032 x 336 px——Substituição dedicada do banner heroImage Google Wallet (proporção 3.07:1)
androidLogoGoogle Wallet660 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 formatTipo canónicoApple Wallet nativoGoogle Wallet nativoCaso de uso típico na indústria
PKBarcodeFormatQR (PKBarcodeFormatSquare)QR_CODESim (PKBarcodeFormatQR)Sim (QR_CODE)Fidelização de retalho, check-in em eventos, leitores com câmara
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle)PDF_417Sim (PKBarcodeFormatPDF417)Sim (PDF_417)Cartões de embarque aéreos, bilhetes de transporte, identificações
PKBarcodeFormatAztecAZTECSim (PKBarcodeFormatAztec)Sim (AZTEC)Bilhetes ferroviários, passes de eventos de elevada densidade
PKBarcodeFormatCode128CODE_128Sim (PKBarcodeFormatCode128)Sim (CODE_128)Leitores laser POS de supermercado, cartões de sócio
PKBarcodeFormatCode39CODE_39Alternativa / RenderizadoSim (CODE_39)Setor automóvel, industrial e leitores de crachás
PKBarcodeFormatCodabarCODABARAlternativa / RenderizadoSim (CODABAR)Bibliotecas, laboratórios e logística
PKBarcodeFormatEAN13EAN_13Alternativa / RenderizadoSim (EAN_13)Cupões de retalho e caixas POS UPC/EAN
PKBarcodeFormatI2of5ITF (aceita ITF_14 de 14 dígitos na Google)Alternativa / RenderizadoSim (ITF_14 para 14 dígitos)Embalagem, retalho grossista e bilhetes numéricos intercalados
PKBarcodeFormatNoneNONESem código de barras apresentadoSem código de barras apresentadoPasses 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, altitude opcional, maxDistance em metros e relevantText exibido no ecrã bloqueado).
  • Beacons Bluetooth Low Energy (modelo Beacon): Até 10 Apple iBeacons (proximityUUID, identificadores de 16 bits major e minor, e relevantText) para deteção de microlocalização interior junto a entradas de loja ou torniquetes.
  • Relevância temporal (RelevantDate): Carimbo temporal ISO 8601 (relevantDate) e expirationDate que 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, bundleEnabled e maxBundleSize (até 10 passes por pacote).

6. Referência da API programática de modelos (request payload)

Listar modelos do espaço de trabalho

GET /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

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)

JSON
{
  "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.

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.