Visão geral
A personalização de passes para carteiras digitais para milhares ou milhões de titulares assenta em Propriedades Personalizadas (definições de esquema declaradas no modelo) combinadas com associações {variable} dentro do modelo Field nas zonas header, primary, secondary, auxiliary, back e footer. No momento da geração e atualização do passe, a Passinstance hidrata estes tokens a partir do dicionário structured JSON attributes do registo de passe e formata datas, números, moedas e notificações push no ecrã bloqueado nativamente para Apple Wallet e Google Wallet.

Arquitetura do sistema: Hidratação dinâmica de campos e indexação
Configuração passo a passo no Editor Visual
-
1
Abra a secção Propriedades personalizadas do modelo e clique em + Adicionar propriedade.
-
2
Defina a Chave da Propriedade exata (por exemplo,
firstName,memberTier,validUntil), Tipo de Dados (field data type:text,number,currency,date,dateTime,time), regras de validação Obrigatório / Único e valores predefinidos opcionais. -
3
Regresse a Campos Frente / Verso no Editor Visual.
-
4
Clique dentro de qualquer valor de campo e digite
{para abrir o menu de preenchimento automático que mostra tanto os seus Atributos Personalizados como os Tokens de Sistema integrados (tais como{serialNumber},{externalId},{stamps},{balance},{tierName},{expirationDate}). -
5
Onde a Apple Wallet e a Google Wallet difiram na quebra de rótulos, configure opcionalmente uma Substituição Android por campo.

Importante: Mantenha as Chaves de Propriedade em
camelCaseminúsculo inicial (holderName,validUntil). Essas chaves exatas passam a ser os nomes das propriedades na API dentro do objeto structured JSONattributesao emitir passes via/api/v1/passesou mapear colunas CSV em importações em lote. Além disso, qualquerchangeMessageconfigurada num campo tem de incluir o marcador%@(ex.:"Your points balance is now %@"), caso contrário o iOS suprimirá silenciosamente a notificação de atualização no ecrã bloqueado.
Especificação completa do modelo Field
Cada campo associado a um modelo via request payload (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields mapeados para field placement type: HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) suporta as seguintes propriedades:
| Propriedade | Tipo | Valores permitidos / Formato | Comportamento por plataforma e regras | |
|---|---|---|---|---|
key | string | Identificador único por passe (ex.: balance_fld) | Utilizado pelo iOS e Android para calcular diferenças de valores entre atualizações push | |
label | string | Legenda estática ou {variable} | Apresentado com labelColor acima ou abaixo do valor | |
value | `string \ | number` | Texto estático, número, data ISO ou {variable} | Hidratado na emissão/atualização a partir de Pass.attributes, externalId ou tokens de sistema |
changeMessage | string | String contendo %@ (ex.: "Tier upgraded to %@") | Despoleta alerta push nativo no ecrã bloqueado iOS quando value muda; %@ é substituído pelo novo valor formatado | |
textAlignment | PKTextAlignment | PKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNatural | Controla o alinhamento horizontal nas colunas de campos frontais da Apple Wallet | |
dateStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formata strings de data ISO 8601 conforme o idioma/região do dispositivo do titular | |
timeStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formata componentes horários no fuso horário local do titular | |
numberStyle | PKNumberStyle | PKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOut | Formata valores numéricos com separadores de milhares e decimais adaptados à região | |
dataDetectorTypes | PKDataDetectorType[] | PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNone | Ativa ações interativas ao tocar (ligar, abrir URL, abrir Mapas, adicionar evento ao calendário) em campos do verso | |
currencyCode | string | Código ISO 4217 de 3 letras (EUR, USD, GBP, CHF) | Formata valores numéricos como montantes monetários localizados na Apple e Google Wallet | |
attributedValue | string | String de âncora HTML (<a href="https://...">Label</a>) | Suportado em backFields da Apple Wallet para apresentar ligações clicáveis web, tel: ou mailto: |
Regras da etiqueta âncora attributedValue na Apple Wallet
A Apple Wallet não apresenta HTML arbitrário (<b>, <div>, <script>) dentro dos campos do passe. Apenas etiquetas de âncora <a href="...">...</a> são permitidas dentro de attributedValue em campos back. O serializador da Passinstance (apple-pass-field.serializer.ts) remove automaticamente etiquetas HTML não suportadas e converte URLs válidos em entradas clicáveis linksModuleData na Google Wallet.
attributes structured JSON ao nível do passe e indexação database GIN
Quando um passe é criado ou atualizado, os pares chave-valor de atributos personalizados são armazenados na coluna structured JSON attributes da tabela pass. Para garantir filtragem em submilissegundos entre milhões de passes, a Passinstance mantém um Índice Invertido Generalizado dedicado do database (attribute search index) em pass.attributes.
Este índice alimenta:
-
Consultas rápidas de coortes via
GET /api/v1/passes(filtragem por propriedades personalizadas comoattributes.tier = "VIP"ouattributes.city = "Berlin"). -
Segmentação de público em tempo real em
PassProjectSegmente Automação de Fluxos. -
Hidratação dinâmica de variáveis sem junções relacionais dispendiosas.
Exemplo de API: Configurar campos dinâmicos num modelo
Pedido HTTP
PATCH /api/v1/templates/tmpl_01hxyz987654321 Cabeçalhos: X-API-Key: <API_KEY> | Content-Type: application/json
{
"fields": {
"headerFields": [
{
"key": "wallet_balance",
"label": "BALANCE",
"value": "{creditBalance}",
"currencyCode": "EUR",
"textAlignment": "PKTextAlignmentRight",
"changeMessage": "Your card balance was updated to %@"
}
],
"primaryFields": [
{
"key": "holder_name",
"label": "MEMBER",
"value": "{firstName} {lastName}",
"textAlignment": "PKTextAlignmentLeft"
}
],
"secondaryFields": [
{
"key": "member_since",
"label": "VALID UNTIL",
"value": "{expirationDate}",
"dateStyle": "PKDateStyleMedium",
"timeStyle": "PKDateStyleNone"
}
],
"backFields": [
{
"key": "support_link",
"label": "CUSTOMER CONCIERGE",
"value": "https://artisan-roasters.example.com/support",
"attributedValue": "<a href='https://artisan-roasters.example.com/support'>Contact VIP Concierge</a>"
}
]
}
}
Resposta HTTP (200 OK)
{
"success": true,
"data": {
"id": "tmpl_01hxyz987654321",
"rowKind": "DRAFT",
"updatedAt": "2026-11-15T11:20:00.000Z"
},
"statusCode": 200
}
De seguida, aprenda a validar os requisitos de conclusão e a promover rascunhos em Versões de modelos e publicação.
