Skip to content
Guía del Centro de ayuda · Plantillas de pasesFase de incorporación 2
8 min de lecturaVerificado 2026-11-16

Diseño y configuración de plantillas

Domina el Editor Visual: tipos de tarjeta, colores con contraste WCAG, logotipos, imágenes y formatos de código.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado1 / 2
Elementos clave de la interfaz

Colores de marca y contraste WCAG (Ampliado)

Define colores con ajuste automático de contraste, intercambio rápido, estado anulado y adaptación Apple/Google Wallet.

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.

Colores de marca del editor y comprobador de contraste
Colores de marca del editor y comprobador de contraste

Arquitectura del sistema: tubería de serialización de plantillas

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
DISEÑO Y TUBERÍA DE SERIALIZACIÓN DE PLANTILLAS
ETAPA 01 EDITOR VISUAL / API REST (/api/v1/templates)
6 Zonas de campo
(HeaderBack)
13 Ranuras imagen
(@1x, @2x, @3x)
Esquema color
(RGB / Hex)
11 Códigos y
geocercas
ETAPA 02 MOTOR DE VALIDACIÓN Y COMPILACIÓN DE PLANTILLAS
Aplica restricciones geométricas pass type (storeCard, eventTicket, etc.)
Convierte tokens de colorrgb(r, g, b) Apple y #RRGGBB Google
Genera variantes retina (@1x, @2x, @3x) en cloud object storage
Valida contraste WCAG 2.1 AA y codificación barras (iso-8859-1/utf-8)
ETAPA 03A APPLE WALLET (Paquete .pkpass)
Serialización diccionario pass.json
icon.png, logo@2x.png, strip.png
locations[], beacons[], nfc{}
ETAPA 03B GOOGLE WALLET (Recurso Class)
LoyaltyClass / EventTicketClass
hexBackgroundColor y heroImage
callbackOptions y config Smart Tap

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 WalletMapeo en Google WalletContenido habitual
headerFields (HEADER)Esquina superior derecha junto al logo (máx. 1–3 campos compactos)Mapeado a metadatos superiores de estado/cabeceraSaldo de puntos, insignia VIP, número de puerta
primaryFields (PRIMARY)Franja central destacada superpuesta o bajo el stripMétrica o título principal destacado de la tarjetaNombre del titular, % de descuento, título del evento
secondaryFields (SECONDARY)Fila inmediatamente inferior a los campos principales (hasta 4 columnas)Fila superior de textModulesDataN.º de socio, asiento/fila/sección, contador de sellos
auxiliaryFields (AUXILIARY)Fila adicional bajo los secundarios (o encima en eventTicket)Fila secundaria de textModulesDataFecha 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 auxiliaresPreguntas frecuentes del evento, instrucciones de acceso, avisos
footerFields (FOOTER)Zona inferior contigua al código de barrasEtiqueta de pie junto al código de barrasCó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 analizador pass.json de Apple Wallet exige estrictamente cadenas de triplete CSS RGB sin canal alfa, por ejemplo rgb(24, 24, 27). Cualquier cadena hexadecimal (#18181B) o valor rgba() 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 clases walletobjects de 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 backgroundColor y foregroundColor / 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 de pass.json. Al llamar a la API REST de Passinstance puede enviar tanto rgb(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 ranuraPlataforma destinoDimensiones @1xDimensiones @2xDimensiones @3xPropósito y ubicación en el diseño
iconApple Wallet29 x 29 px58 x 58 px87 x 87 pxIcono obligatorio para notificaciones en pantalla de bloqueo y adjuntos de correo
logoApple Wallet160 x 50 px320 x 100 px480 x 150 pxLogotipo superior izquierdo junto a logoText y campos header
primaryLogoUnificado / Respaldo160 x 50 px320 x 100 px480 x 150 pxMarca corporativa canónica heredada por todos los monederos
googlePayLogoGoogle Wallet660 x 660 px (mín.)——Logotipo circular del programa en la cabecera de Google Wallet (relación 1:1)
stripApple (storeCard, coupon, eventTicket)375 x 123 px (eventTicket: 375 x 98 px)750 x 246 px1125 x 369 pxBanner horizontal de borde a borde tras/sobre los campos principales
backgroundApple (eventTicket, generic)180 x 220 px360 x 440 px540 x 660 pxTextura difuminada de fondo completo en la tarjeta
thumbnailApple (generic, membership, eventTicket)90 x 90 px180 x 180 px270 x 270 pxRetrato fotográfico cuadrado o insignia de producto en el lateral derecho
footerApple (boardingPass, eventTicket)286 x 15 px572 x 30 px858 x 45 pxFranja estrecha impresa justo encima del código de barras
artworkApple WWDC25 Poster Ticket375 x 480 px750 x 960 px1125 x 1440 pxIlustración de gran formato tipo póster para Event Tickets en iOS
venueMapApple WWDC25 Event Guide375 x 375 px750 x 750 px1125 x 1125 pxPlano descargable de asientos/recinto dentro de Apple Event Guide
secondaryLogoCo-branding unificado160 x 50 px320 x 100 px480 x 150 pxInsignia de marca patrocinadora o socia secundaria
androidBackgroundGoogle Wallet1032 x 336 px——Anulación específica del banner heroImage en Google Wallet (relación 3.07:1)
androidLogoGoogle Wallet660 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 formatTipo canónicoNativo en Apple WalletNativo en Google WalletCaso de uso habitual
PKBarcodeFormatQR (PKBarcodeFormatSquare)QR_CODESí (PKBarcodeFormatQR)Sí (QR_CODE)Fidelización minorista, registro de eventos, escáneres por cámara
PKBarcodeFormatPDF417 (PKBarcodeFormatRectangle)PDF_417Sí (PKBarcodeFormatPDF417)Sí (PDF_417)Tarjetas de embarque aéreas, billetes de transporte, identificaciones
PKBarcodeFormatAztecAZTECSí (PKBarcodeFormatAztec)Sí (AZTEC)Billetes ferroviarios, pases de eventos de alta densidad
PKBarcodeFormatCode128CODE_128Sí (PKBarcodeFormatCode128)Sí (CODE_128)Escáneres láser de supermercados en POS, tarjetas de socio
PKBarcodeFormatCode39CODE_39Respaldo / RenderizadoSí (CODE_39)Lectores de automoción, industria y acreditaciones
PKBarcodeFormatCodabarCODABARRespaldo / RenderizadoSí (CODABAR)Bibliotecas, laboratorios y paquetería logística
PKBarcodeFormatEAN13EAN_13Respaldo / RenderizadoSí (EAN_13)Cupones minoristas y cajas POS UPC/EAN
PKBarcodeFormatI2of5ITF (acepta ITF_14 de 14 dígitos en Google)Respaldo / RenderizadoSí (ITF_14 de 14 dígitos)Embalaje, mayoristas y tiques numéricos intercalados
PKBarcodeFormatNoneNONENo muestra código de barrasNo muestra código de barrasPases 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, altitude opcional, maxDistance en metros y relevantText mostrado en la pantalla de bloqueo).
  • Balizas Bluetooth Low Energy (modelo Beacon): Hasta 10 iBeacons de Apple (proximityUUID, identificadores de 16 bits major y minor y relevantText) para detección de microlocalización en interiores junto a entradas o tornos.
  • Relevancia temporal (RelevantDate): Marca de tiempo ISO 8601 (relevantDate) y expirationDate que 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, bundleEnabled y maxBundleSize (hasta 10 pases por paquete).

6. Referencia programática de la API de plantillas (request payload)

Listar plantillas del espacio de trabajo

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

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)

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
}

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.

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.