Descripción general
Una Plantilla de pase (modelo Template) define la geometría estructural, la identidad visual de marca, las zonas de diseño de campos, la simbología del código de barras y las reglas de relevancia por ubicación que comparten todos los pases emitidos bajo un mismo programa. Passinstance compila una única configuración canónica de plantilla tanto en archivos nativos de Apple Wallet (.pkpass) como en definiciones en la nube de Google Wallet (Class / Object).
Abra cualquier plantilla en el panel y entre en Editar plantilla para configurar el diseño y las reglas del monedero junto con una vista previa en vivo de Apple Wallet y Google Wallet, o gestione las plantillas mediante código a través de /api/v1/templates.

Arquitectura del sistema: tubería de serialización de plantillas
1. Identidad, tipos de pase y zonas de diseño de campos
Al crear una plantilla, seleccione el pass type / PassKind subyacente (storeCard, coupon, eventTicket, boardingPass, membership, studentId, generic, posterGeneric o businessCard), combinado opcionalmente con theme preference (posterGeneric, posterEventTicket, bannerEventTicket, semanticBoardingPass, DARK) y transit type (PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric, PKTransitTypeTrain) para tarjetas de embarque. Cada tipo de pase determina cómo el sistema operativo móvil renderiza la cabecera, el gráfico principal y las filas de campos.
Las 7 posiciones canónicas de campos (field placement type)
El modelo Field y request payload ubican los elementos de datos en posiciones de diseño diferenciadas (HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, ADDITIONALINFO, FOOTER):
Posición de campo (request payload / field placement type) | Renderizado en Apple Wallet | Mapeo en Google Wallet | Contenido habitual |
|---|---|---|---|
headerFields (HEADER) | Esquina superior derecha junto al logo (máx. 1–3 campos compactos) | Mapeado a metadatos superiores de estado/cabecera | Saldo de puntos, insignia VIP, número de puerta |
primaryFields (PRIMARY) | Franja central destacada superpuesta o bajo el strip | Métrica o título principal destacado de la tarjeta | Nombre del titular, % de descuento, título del evento |
secondaryFields (SECONDARY) | Fila inmediatamente inferior a los campos principales (hasta 4 columnas) | Fila superior de textModulesData | N.º de socio, asiento/fila/sección, contador de sellos |
auxiliaryFields (AUXILIARY) | Fila adicional bajo los secundarios (o encima en eventTicket) | Fila secundaria de textModulesData | Fecha de vencimiento, sucursal, promotor |
backFields (BACK) | Reverso desplazable del pase (admite textos largos y enlaces) | Vista expandible Detalles (textModulesData y linksModuleData) | Términos y condiciones, teléfono de soporte, URL web |
additionalInfoFields (ADDITIONALINFO) | Detalles complementarios y bloques del recinto en iOS 18+ | Módulos de detalles auxiliares | Preguntas frecuentes del evento, instrucciones de acceso, avisos |
footerFields (FOOTER) | Zona inferior contigua al código de barras | Etiqueta de pie junto al código de barras | Código de seguridad o instrucciones de entrada manual |
2. Colores y reglas de serialización por plataforma
El modelo Color persiste cuatro propiedades cromáticas semánticas por plantilla: backgroundColor, foregroundColor (texto de valores de campo), labelColor (títulos de etiqueta) y stripColor (tinte del texto superpuesto sobre imágenes strip).
-
Apple Wallet (
rgb(r, g, b)): El analizadorpass.jsonde Apple Wallet exige estrictamente cadenas de triplete CSS RGB sin canal alfa, por ejemplorgb(24, 24, 27). Cualquier cadena hexadecimal (#18181B) o valorrgba()es normalizado automáticamente por el serializador de Passinstance para que nunca se incluya sintaxis de color no válida en paquetes.pkpass. -
Google Wallet (
#RRGGBB): Las claseswalletobjectsde Google Wallet requieren cadenas hexadecimales de 6 caracteres (#18181B). Passinstance traduce de forma transparente sus tokens de color para ambas plataformas. -
Verificación de contraste WCAG: El editor visual evalúa en tiempo real los ratios de contraste de luminancia entre
backgroundColoryforegroundColor/labelColor, advirtiendo a los operadores si la tipografía cae por debajo de los umbrales de legibilidad WCAG AA.
Importante: Apple Wallet exige estrictamente colores en formato
rgb(r, g, b)y rechaza códigos hexadecimales o canales alfa dentro depass.json. Al llamar a la API REST de Passinstance puede enviar tantorgb(r, g, b)como#RRGGBB: el backend normaliza y serializa automáticamente el formato exacto que requiere cada plataforma.
3. Las 13 ranuras de recursos visuales y variantes Retina
Passinstance gestiona 13 ranuras de recursos gráficos diferenciadas en el modelo Template. Cuando sube un PNG fuente en alta resolución, la tubería de recursos genera automáticamente versiones escaladas @1x, @2x y @3x para Apple Wallet mientras aloja las URL públicas de CDN exigidas por Google Wallet:
| Clave de ranura | Plataforma destino | Dimensiones @1x | Dimensiones @2x | Dimensiones @3x | Propósito y ubicación en el diseño |
|---|---|---|---|---|---|
icon | Apple Wallet | 29 x 29 px | 58 x 58 px | 87 x 87 px | Icono obligatorio para notificaciones en pantalla de bloqueo y adjuntos de correo |
logo | Apple Wallet | 160 x 50 px | 320 x 100 px | 480 x 150 px | Logotipo superior izquierdo junto a logoText y campos header |
primaryLogo | Unificado / Respaldo | 160 x 50 px | 320 x 100 px | 480 x 150 px | Marca corporativa canónica heredada por todos los monederos |
googlePayLogo | Google Wallet | 660 x 660 px (mín.) | — | — | Logotipo circular del programa en la cabecera de Google Wallet (relación 1:1) |
strip | Apple (storeCard, coupon, eventTicket) | 375 x 123 px (eventTicket: 375 x 98 px) | 750 x 246 px | 1125 x 369 px | Banner horizontal de borde a borde tras/sobre los campos principales |
background | Apple (eventTicket, generic) | 180 x 220 px | 360 x 440 px | 540 x 660 px | Textura difuminada de fondo completo en la tarjeta |
thumbnail | Apple (generic, membership, eventTicket) | 90 x 90 px | 180 x 180 px | 270 x 270 px | Retrato fotográfico cuadrado o insignia de producto en el lateral derecho |
footer | Apple (boardingPass, eventTicket) | 286 x 15 px | 572 x 30 px | 858 x 45 px | Franja estrecha impresa justo encima del código de barras |
artwork | Apple WWDC25 Poster Ticket | 375 x 480 px | 750 x 960 px | 1125 x 1440 px | Ilustración de gran formato tipo póster para Event Tickets en iOS |
venueMap | Apple WWDC25 Event Guide | 375 x 375 px | 750 x 750 px | 1125 x 1125 px | Plano descargable de asientos/recinto dentro de Apple Event Guide |
secondaryLogo | Co-branding unificado | 160 x 50 px | 320 x 100 px | 480 x 150 px | Insignia de marca patrocinadora o socia secundaria |
androidBackground | Google Wallet | 1032 x 336 px | — | — | Anulación específica del banner heroImage en Google Wallet (relación 3.07:1) |
androidLogo | Google Wallet | 660 x 660 px | — | — | Anulación explícita del logotipo de Google Wallet cuando difiere de googlePayLogo |
4. Formatos de código de barras compatibles y reglas de validación
El modelo Barcode y request payload coordinan barcode format (formatos de Apple Wallet incluidos los geométricos PKBarcodeFormatSquare / PKBarcodeFormatRectangle y PKBarcodeFormatNone) y los valores canónicos BarcodeType (QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13, CODE_39, CODABAR, ITF), junto con altText (o barcodeAlternativeText), messageEncoding (ISO_8859_1, UTF_8, ISO_8859_15, WINDOWS_1252, SHIFT_JIS), appleFallbackType y addSecurityAnimation (brillo dinámico anticaptura):
| Valor barcode format | Tipo canónico | Nativo en Apple Wallet | Nativo en Google Wallet | Caso de uso habitual |
|---|---|---|---|---|
PKBarcodeFormatQR (PKBarcodeFormatSquare) | QR_CODE | Sí (PKBarcodeFormatQR) | Sí (QR_CODE) | Fidelización minorista, registro de eventos, escáneres por cámara |
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle) | PDF_417 | Sí (PKBarcodeFormatPDF417) | Sí (PDF_417) | Tarjetas de embarque aéreas, billetes de transporte, identificaciones |
PKBarcodeFormatAztec | AZTEC | Sí (PKBarcodeFormatAztec) | Sí (AZTEC) | Billetes ferroviarios, pases de eventos de alta densidad |
PKBarcodeFormatCode128 | CODE_128 | Sí (PKBarcodeFormatCode128) | Sí (CODE_128) | Escáneres láser de supermercados en POS, tarjetas de socio |
PKBarcodeFormatCode39 | CODE_39 | Respaldo / Renderizado | Sí (CODE_39) | Lectores de automoción, industria y acreditaciones |
PKBarcodeFormatCodabar | CODABAR | Respaldo / Renderizado | Sí (CODABAR) | Bibliotecas, laboratorios y paquetería logística |
PKBarcodeFormatEAN13 | EAN_13 | Respaldo / Renderizado | Sí (EAN_13) | Cupones minoristas y cajas POS UPC/EAN |
PKBarcodeFormatI2of5 | ITF (acepta ITF_14 de 14 dígitos en Google) | Respaldo / Renderizado | Sí (ITF_14 de 14 dígitos) | Embalaje, mayoristas y tiques numéricos intercalados |
PKBarcodeFormatNone | NONE | No muestra código de barras | No muestra código de barras | Pases exclusivos por NFC (nfcNoBarcode: true) |
5. Geocercas, iBeacons, identificadores y relevancia temporal
Los pases aparecen automáticamente en la pantalla de bloqueo del cliente cuando coinciden disparadores físicos o temporales:
-
Ubicaciones GPS (modelo
Location): Hasta 10 coordenadas por plantilla (latitude,longitude,altitudeopcional,maxDistanceen metros yrelevantTextmostrado en la pantalla de bloqueo). -
Balizas Bluetooth Low Energy (modelo
Beacon): Hasta 10 iBeacons de Apple (proximityUUID, identificadores de 16 bitsmajoryminoryrelevantText) para detección de microlocalización en interiores junto a entradas o tornos. -
Relevancia temporal (
RelevantDate): Marca de tiempo ISO 8601 (relevantDate) yexpirationDateque muestran entradas de eventos o vales temporales en pantalla conforme se acerca la hora prevista. -
Ajustes de identificadores personalizados y agrupación: Configure
customIdentifiersEnabled,externalIdentifierPattern,customIdentifierValidationPattern,bundleOnDownload,bundleEnabledymaxBundleSize(hasta10pases por paquete).
6. Referencia programática de la API de plantillas (request payload)
Listar plantillas del espacio de trabajo
/api/v1/templates?page=1&limit=20&rowKind=PRODUCTION
Crear una nueva plantilla (request payload)
POST /api/v1/templates Cabeceras: 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."
}
]
}
Respuesta 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
}
Continúe con Campos dinámicos y personalización para vincular atributos personalizados al diseño de su plantilla, o explore las Mecánicas de pases y funcionalidades.
