Descripción general
La personalización de pases de monedero para miles o millones de titulares se apoya en Propiedades personalizadas (definiciones de esquema declaradas en su plantilla) combinadas con vínculos {variable} dentro del modelo Field en las zonas header, primary, secondary, auxiliary, back y footer. En el momento de generar o actualizar el pase, Passinstance rellena estos tokens desde el diccionario structured JSON attributes del registro del pase y formatea fechas, números, monedas y notificaciones push en pantalla de bloqueo de manera nativa para Apple Wallet y Google Wallet.

Arquitectura del sistema: hidratación e indexación de campos dinámicos
Configuración paso a paso en el editor visual
-
1
Abra la sección Propiedades personalizadas de la plantilla y haga clic en + Añadir propiedad.
-
2
Defina exactamente la Clave de propiedad (por ejemplo,
firstName,memberTier,validUntil), el Tipo de datos (field data type:text,number,currency,date,dateTime,time), las reglas de validación Obligatorio / Único y valores predeterminados opcionales de respaldo. -
3
Vuelva a Campos del anverso / reverso en el editor visual.
-
4
Haga clic dentro del valor de cualquier campo y escriba
{para abrir el menú de autocompletado donde aparecen tanto sus Atributos personalizados como los Tokens del sistema integrados (como{serialNumber},{externalId},{stamps},{balance},{tierName},{expirationDate}). -
5
Cuando Apple Wallet y Google Wallet requieran distinto ajuste de etiquetas, configure opcionalmente una Anulación para Android por campo.

Importante: Mantenga las Claves de propiedad en formato
camelCaseiniciando en minúscula (holderName,validUntil). Esas claves exactas se convierten en los nombres de propiedad de la API dentro del objeto structured JSONattributesal emitir pases vía/api/v1/passeso al mapear columnas CSV en importaciones por lotes. Además, cualquierchangeMessageconfigurado en un campo debe incluir el marcador%@(por ejemplo,"Su saldo de puntos es ahora %@"), o iOS suprimirá silenciosamente la notificación de actualización en la pantalla de bloqueo.
Especificación completa del modelo Field
Cada campo vinculado a una plantilla mediante request payload (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields, footerFields mapeados a field placement type: HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER) admite las siguientes propiedades:
| Propiedad | Tipo | Valores / Formato permitidos | Comportamiento y reglas por plataforma | |
|---|---|---|---|---|
key | string | Identificador único por pase (p. ej. balance_fld) | Usado por iOS y Android para comparar diferencias entre actualizaciones push | |
label | string | Texto estático o {variable} | Mostrado en color labelColor encima o debajo del valor | |
value | `string \ | number` | Texto estático, número, fecha ISO o {variable} | Hidratado al emitir o actualizar desde Pass.attributes, externalId o tokens del sistema |
changeMessage | string | Cadena que contiene %@ (p. ej. "Nivel actualizado a %@") | Activa una alerta push nativa en la pantalla de bloqueo de iOS cuando cambia value; %@ se reemplaza por el nuevo valor formateado | |
textAlignment | PKTextAlignment | PKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentNatural | Controla la alineación horizontal en las columnas frontales de Apple Wallet | |
dateStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatea cadenas de fecha ISO 8601 según la configuración regional del dispositivo | |
timeStyle | PKDateStyle | PKDateStyleNone, PKDateStyleShort, PKDateStyleMedium, PKDateStyleLong, PKDateStyleFull | Formatea componentes horarios en la zona horaria local del titular | |
numberStyle | PKNumberStyle | PKNumberStyleDecimal, PKNumberStylePercent, PKNumberStyleScientific, PKNumberStyleSpellOut | Formatea valores numéricos con separadores de miles y decimales propios del idioma | |
dataDetectorTypes | PKDataDetectorType[] | PKDataDetectorTypePhoneNumber, PKDataDetectorTypeLink, PKDataDetectorTypeAddress, PKDataDetectorTypeCalendarEvent, PKDataDetectorTypeNone | Habilita acciones interactivas al tocar (llamar, abrir URL, abrir Mapas, añadir evento al calendario) en el reverso | |
currencyCode | string | Código ISO 4217 de 3 letras (EUR, USD, GBP, CHF) | Formatea valores numéricos como importes monetarios localizados en Apple y Google Wallet | |
attributedValue | string | Cadena HTML de enlace (<a href="https://...">Etiqueta</a>) | Compatible en backFields de Apple Wallet para mostrar enlaces web, tel: o mailto: clicables |
Reglas de etiquetas de enlace attributedValue en Apple Wallet
Apple Wallet no renderiza HTML arbitrario (<b>, <div>, <script>) dentro de los campos de un pase. Solo se permiten etiquetas de anclaje <a href="...">...</a> dentro de attributedValue en los campos back. El serializador de Passinstance (apple-pass-field.serializer.ts) elimina automáticamente etiquetas HTML no compatibles y convierte las URL válidas en entradas clicables dentro de linksModuleData en Google Wallet.
attributes structured JSON a nivel de pase e indexación GIN en database
Cuando se crea o actualiza un pase, los pares clave-valor de atributos personalizados se guardan en la columna structured JSON attributes de la tabla pass. Para garantizar filtrados en menos de un milisegundo entre millones de pases, Passinstance mantiene un índice invertido generalizado dedicado en database (attribute search index) sobre pass.attributes.
Este índice impulsa:
-
Consultas de cohortes a alta velocidad mediante
GET /api/v1/passes(filtrando por propiedades personalizadas comoattributes.tier = "VIP"oattributes.city = "Berlin"). -
Segmentación de audiencias en tiempo real en
PassProjectSegmenty Automatización de flujos de trabajo. -
Hidratación dinámica de variables sin costosas uniones de tablas relacionales.
Ejemplo de API: configurar campos dinámicos en una plantilla
Solicitud HTTP
PATCH /api/v1/templates/tmpl_01hxyz987654321 Cabeceras: 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>"
}
]
}
}
Respuesta HTTP (200 OK)
{
"success": true,
"data": {
"id": "tmpl_01hxyz987654321",
"rowKind": "DRAFT",
"updatedAt": "2026-11-15T11:20:00.000Z"
},
"statusCode": 200
}
A continuación, aprenda a validar los controles de preparación y promover borradores en Versiones de plantilla y publicación.
