Archivo PKPASS

1. ¿Qué es un archivo .pkpass?

Un archivo .pkpass es un paquete firmado digitalmente que entrega un único pase a Apple Wallet, la app de iPhone, iPad, Apple Watch y Mac donde los usuarios guardan tarjetas de embarque, entradas para eventos, cupones, tarjetas de fidelidad, llaves de hotel, billetes de transporte y credenciales similares. Apple presentó el formato el 11 de junio de 2012 en la WWDC con el nombre Passbook, y lo lanzó tres meses después en iOS 6, el 19 de septiembre de 2012. Pasó a llamarse Apple Wallet con iOS 9 en septiembre de 2015, un año después de que Apple Pay debutara en iOS 8.1, consolidando pases y tarjetas de pago bajo una única marca Wallet. El formato de archivo subyacente y el framework para desarrolladores —PassKit— han mantenido la compatibilidad todo el camino.

Mecánicamente, un .pkpass es un archivo ZIP renombrado con la extensión .pkpass. En su interior hay un archivo JSON llamado pass.json que describe el pase, unas cuantas imágenes PNG, un manifest.json con los hashes SHA-1 de cada uno de los demás archivos y un archivo signature que demuestra que el pase procede de un equipo registrado de Apple Developer. El tipo MIME es application/vnd.apple.pkpass: Apple Mail, Safari y la mayoría de las apps de correo modernas se basan en él para activar la previsualización de «Añadir a Apple Wallet» cuando el usuario toca el adjunto.

El formato es abierto en estructura y cerrado en confianza: los datos son JSON y PNG documentados en la Wallet Developer Guide de Apple, pero una firma PKCS#7 vincula cada pase a un certificado Pass Type ID emitido a un único equipo de Apple Developer. Cualquiera puede leer un .pkpass, pero solo ese equipo puede producir uno nuevo que Wallet acepte instalar.

Los emisores —aerolíneas, recintos, comercios, agencias de transporte, hoteles, empleadores— generan un .pkpass en su backend y se lo envían al cliente por correo electrónico, un enlace SMS o una app personalizada. El cliente toca el archivo, Wallet renderiza una previsualización y, un toque después, queda en su dispositivo. A partir de ahí, Apple Wallet puede mantener el pase actualizado a través de un canal de push, mostrarlo en la pantalla de bloqueo en el momento y lugar adecuados y (en tarjetas de embarque y entradas) entregarlo automáticamente al Apple Watch o a los lectores NFC.

Si todavía no tienes un pase con el que practicar, puedes crear uno en menos de un minuto a partir de cualquier código de barras y seguir todo lo que viene a continuación.

2. Formato de archivo .pkpass

Un .pkpass es un archivo PKZip estándar. Puedes renombrar example.pkpass a example.zip y cualquier herramienta de zip listará y extraerá su contenido. El archivo debe contener los archivos del pase en su raíz: envolverlos en una carpeta es la causa más común de que un pase hecho a mano no se instale. Por dentro, el conjunto de archivos es pequeño y previsible.

Dimensiones de las imágenes

Apple expresa los tamaños de imagen en puntos; @2x significa 2 píxeles por punto y @3x, 3. La mayoría de los emisores entregan recursos 1×, @2x y @3x para que el pase se vea nítido en cualquier pantalla, desde un Watch hasta un Pro Max. Los tamaños canónicos según la guía Pass Design and Creation de Apple son:

Las imágenes son PNG en sRGB, con canal alfa cuando la transparencia importa (icon, logo). Apple ha sido históricamente estricto con las dimensiones exactas de los strips de los cupones; un par de píxeles de más o de menos pueden producir recortes feos, pero suele instalarse igualmente.

Tipo MIME, extensión y codificación

• Extensión: .pkpass para un único pase; .pkpasses para un paquete de varios pases.
• Tipo MIME: application/vnd.apple.pkpass (único) o application/vnd.apple.pkpasses (paquete).
• Codificación de caracteres: los archivos JSON son UTF-8. Los archivos pass.strings localizados deben estar en UTF-16 si contienen cualquier carácter no ASCII; las herramientas de Apple leen mal en silencio los archivos de cadenas en UTF-8.

Localización

Para soportar varios idiomas, un emisor añade subdirectorios {lang}.lproj/; por ejemplo en.lproj/, fr.lproj/, ja.lproj/. Cada uno contiene un archivo pass.strings de pares clave/valor con traducciones y, opcionalmente, imágenes de reemplazo. En el momento de mostrar el pase, iOS escoge la localización disponible más cercana al idioma del dispositivo. La regla estricta de Apple: no pongas una imagen en el nivel superior y en una .lproj con el mismo nombre, porque produce un comportamiento indefinido.

3. Dentro de pass.json

En pass.json reside casi cada decisión interesante sobre un pase: qué aspecto tiene, qué datos muestra, dónde aparece y cómo se actualiza. El esquema está documentado en la PassKit Bundle Reference de Apple y se ha mantenido notablemente estable desde 2012.

Claves de nivel superior

Cada pase requiere seis claves; todo lo demás es opcional pero útil.

Grupos de campos

Dentro del diccionario del estilo elegido, los campos se organizan en cinco arrays: headerFields, primaryFields, secondaryFields, auxiliaryFields y backFields. Cada uno es una lista de diccionarios de campo. Los campos de cabecera aparecen arriba a la derecha del pase y son visibles incluso cuando el pase está plegado en la pila de Wallet; los campos primarios son grandes y centrales; los secundarios y auxiliares son los pares pequeños etiqueta/valor en una fila debajo; los campos del reverso son todo lo que ves al tocar la i del reverso de la tarjeta.

Un diccionario de campo necesita key (único dentro del pase) y value; todo lo demás —label, alineación, formato de fechas y números, changeMessage, dataDetectorTypes, valores con atributos en HTML— es opcional. Los campos de fecha utilizan cadenas ISO 8601 y se formatean en el dispositivo según dateStyle, timeStyle y la localización del usuario.

Los campos del reverso son especiales por dos motivos: sus cadenas value se analizan en busca de URL, números de teléfono, fechas y direcciones, y se renderizan como enlaces tocables por defecto —puedes anularlo por campo con dataDetectorTypes: []— y admiten attributedValue con un pequeño subconjunto de HTML, del cual <a href> es el más útil porque permite asociar un texto visible distinto a la URL tocable. Los campos del reverso son el único lugar de un pase donde el usuario puede tocar contenido.

Códigos de barras

Un diccionario de código de barras tiene cuatro claves: format, message, messageEncoding y un altText opcional. Los cuatro formatos soportados son PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec y PKBarcodeFormatCode128. Los formatos 2D (QR, PDF417, Aztec) se añadieron en iOS 9 junto con el nuevo array barcodes; antes de iOS 9, la clave singular barcode con Code 128 era el único mecanismo. Code 128 es un código de barras lineal 1D y no se renderiza en Apple Watch, así que los pases que vayan al Watch deben elegir QR, PDF417 o Aztec. messageEncoding es obligatorio y suele ser iso-8859-1; usa utf-8 cuando la carga útil contenga caracteres fuera de Latin-1.

Colores

El analizador de colores de Apple solo acepta la forma de función CSS rgb(R, G, B) con componentes enteros de 0 a 255. #RRGGBB, rgba() y los colores con nombre se ignoran en silencio, dejando que Wallet caiga a sus valores por defecto. Es uno de los motivos más comunes de que un pase se instale pero se vea mal: alguien pegó un valor hex y el analizador puso, sin avisar, negro sobre blanco.

Etiquetas semánticas

Desde iOS 12, el diccionario opcional semantics transporta metadatos estructurados que iOS utiliza para sugerencias de Siri, relevancia en la pantalla de bloqueo y conciencia de Apple Watch. Para un vuelo serían airlineCode + flightNumber + departureAirportCode + currentDepartureDate; para un evento, eventName + venueLocation + eventStartDate; para un pase de transporte, transitProvider + departureStationName + currentDepartureDate. Wallet usa estas etiquetas para vincular una tarjeta de embarque al rastreador de vuelos de Apple sin que el emisor tenga que montar ningún servicio web.

4. Cómo funciona la firma

La firma es lo que separa un pase auténtico de uno manipulado o falsificado. Esta es la cadena de confianza, de arriba a abajo:

• Apple Root CA: la raíz offline de Apple, incrustada en los almacenes de confianza de iOS, macOS y watchOS.
• Intermedio Apple Worldwide Developer Relations (WWDR): Apple ha rotado este intermedio varias veces. Las generaciones de la G2 a la G6 están todas emitidas y son válidas para distintos tipos de certificado; los certificados Pass Type ID han encadenado durante años a través del WWDR original (y ahora a través de generaciones más nuevas a medida que Apple las rota). La firma debe incluir la generación de WWDR a través de la que se encadena el certificado Pass Type ID. Tutoriales antiguos dejan codificado un intermedio caducado; si la firma falla, vuelve a descargar el certificado WWDR que coincida con la generación de tu Pass Type ID desde apple.com/certificateauthority.
• Certificado Pass Type ID: emitido a un único equipo de Apple Developer, atado a un único pass type identifier en DNS inverso (por ejemplo, pass.com.example.coupon). Es el certificado hoja cuya clave privada firma cada pase.

Cada certificado Pass Type ID codifica el pass type identifier como UID en su sujeto y la Team ID de 10 caracteres del equipo como OU. Apple Wallet comprueba ambos en el momento de la instalación.

El procedimiento de firma

Según la guía oficial de Apple, los pasos son:

1. Construye el paquete del pase sin firmar: pass.json más todas las imágenes, en un directorio.
2. Recorre el directorio recursivamente, calcula el SHA-1 del contenido de cada archivo y escribe el resultado en manifest.json como un objeto JSON que asocia cada ruta relativa a su digest SHA-1 en hex; por ejemplo, "icon.png" → "abc123…", "pass.json" → "def456…". No incluyas manifest.json ni signature a sí mismos.
3. Genera una firma desprendida PKCS#7 sobre los bytes de manifest.json, con la clave privada del certificado Pass Type ID. Incluye en la firma el certificado intermedio WWDR correspondiente para que Wallet pueda construir una cadena hasta la raíz de Apple, y transporta el atributo S/MIME signing-time.
4. Comprime el contenido del directorio del pase (no el directorio en sí) en un archivo con la extensión .pkpass.

La mayoría de las implementaciones de referencia utilizan OpenSSL para el paso de la firma:

openssl smime -binary -sign \
  -certfile WWDR.pem \
  -signer passcert.pem \
  -inkey passkey.pem \
  -in manifest.json \
  -out signature \
  -outform DER

Apple también incluye una pequeña herramienta en Objective-C llamada signpass dentro del archivo Wallet Companion Files que envuelve la misma lógica.

Qué valida iOS

Cuando un usuario abre un .pkpass, Apple Wallet ejecuta más o menos esta comprobación:

1. Analiza el ZIP; carga manifest.json, signature y pass.json.
2. Verifica la firma desprendida PKCS#7 sobre los bytes exactos de manifest.json.
3. Construye una cadena de certificados desde el certificado hoja, pasando por el intermedio WWDR incluido, hasta Apple Root CA, y comprueba que el hoja no esté caducado ni revocado.
4. Vuelve a calcular el hash de cada archivo del paquete y confirma que cada digest coincide con el valor de manifest.json.
5. Confirma que passTypeIdentifier en pass.json es igual al UID del certificado hoja, y que teamIdentifier es igual al OU del certificado.

Cualquier fallo produce un error genérico de instalación; iOS no le dice al usuario (ni al desarrollador) qué paso ha fallado. Por eso casi todas las sesiones de depuración «este pase no se puede instalar» empiezan verificando los hashes del manifiesto y la cadena de certificados.

Por qué no puedes volver a firmar el pase de otra persona

El certificado Pass Type ID se ata, en el momento de su emisión, a un equipo y un identificador. Apple no emitirá un certificado para el identificador de otra persona, y cambiar passTypeIdentifier en pass.json por uno tuyo rompe el manifiesto y el canal de actualizaciones push por pase basado en él. Así que, incluso teniendo el .pkpass original en la mano, no puedes volver a firmar el pase de un tercero con tu propio certificado y conseguir que se instale; es así por diseño.

5. Cómo abrir un archivo .pkpass

Dónde puedes abrir un .pkpass —y qué funciones se conservan— depende de la plataforma.

Abrir un archivo .pkpass en iPhone, iPad y Apple Watch

La experiencia nativa. Toca el adjunto .pkpass en Mail, Mensajes, Safari o Archivos: iOS reconoce el tipo MIME, abre una previsualización de Wallet a pantalla completa y ofrece un botón Añadir. Una vez añadido, el pase se sincroniza automáticamente con un Apple Watch emparejado. A partir de iOS 27 (que se lanzará en septiembre de 2026), Apple Wallet incluirá además un botón integrado Crear un pase que permitirá envolver cualquier código QR en un pase sin necesidad de cuenta de desarrollador; lo cubrimos aquí.

Abrir un archivo .pkpass en Mac

macOS no tiene una app Wallet; Wallet en Mac es solo un panel de ajustes para tarjetas de Apple Pay. Pero al hacer doble clic en un .pkpass desde el Finder se abre una app del sistema privada llamada Pass Viewer (/System/Library/CoreServices/Pass Viewer.app) que renderiza el pase y ofrece Añadir a Apple Wallet. La acción Añadir envía el pase a la cuenta de iCloud del usuario; a partir de ahí aparece en cada iPhone, iPad y Apple Watch que tenga sesión iniciada con la misma Apple ID. El propio Mac nunca almacena el pase localmente. Safari en macOS hace lo mismo cuando tocas un botón «Añadir a Apple Wallet» en una página web.

Abrir un archivo .pkpass en Android

Apple Wallet no está disponible en Android, pero, a fecha de 2026, puedes abrir un archivo .pkpass en Android de cinco maneras distintas:

• Google Wallet (nativo, parcial). Desde abril de 2024, Google Wallet en Android puede importar archivos .pkpass directamente: toca el archivo en tu gestor de archivos, en Gmail o en el navegador, y la hoja de compartir te ofrecerá Añadir a Google Wallet. El despliegue se controla por región, y los sitios web que detectan tu user-agent muchas veces ni siquiera ofrecen el archivo a un navegador Android. Como alternativa, puedes usar nuestro conversor PKPASS a Google Wallet en cualquier dispositivo para generar un enlace de guardado.
• Pass2U Wallet (com.passesalliance.wallet). La opción de terceros más popular, actualizada por última vez en enero de 2026. Importa .pkpass, sondea webServiceURL en busca de actualizaciones, puede hacer copia de seguridad en Google Drive y trae un diseñador de pases integrado.
• WalletPasses (io.walletpasses.android). Veterana, sin anuncios, admite notificaciones por geovalla e iBeacon. Última actualización en junio de 2025.
• FossWallet (nz.eloque.foss_wallet). La opción de código abierto activamente mantenida en 2026, GPL-3.0, en F-Droid. Sucesora de PassAndroid (que ya no instala los pases modernos de forma fiable).
• PassWallet (com.attidomobile.passwallet). La opción original de terceros; sigue manteniéndose, pero la interfaz acusa el paso del tiempo.

En cualquiera de ellas, los servicios NFC de valor añadido (toque al estilo de Apple Pay), la sincronización con Apple Watch y el modo Express no están disponibles. Las actualizaciones automáticas se sondean en lugar de empujarse vía APNs.

Abrir un archivo .pkpass en Windows, Linux y ChromeOS

No hay un manejador nativo. Tres buenas vías:

• Visor en el navegador. Suelta el archivo en nuestro Visor PKPASS: lo analiza todo del lado del cliente y muestra la previsualización de la tarjeta, cada campo y el pass.json en bruto.
• Convertir a PDF. Usa nuestro conversor PKPASS a PDF para obtener un A4 imprimible con el código de barras renderizado a resolución de impresión.
• Tratarlo como un ZIP. Renómbralo a .zip (Windows) o ejecuta unzip pass.pkpass (Linux/macOS) e inspecciona los archivos directamente. Útil cuando solo quieres leer pass.json.

En ChromeOS, el subsistema de Android hace que Pass2U / WalletPasses sean la instalación más fácil si quieres soporte completo de lectura y actualización. Si no, la vía del visor en el navegador funciona en cualquier Chromebook.

6. Estilos de pase

Cada .pkpass es de uno de los cinco estilos, declarado por la clave de nivel superior presente en pass.json. El estilo controla la disposición, qué imágenes se utilizan y qué hace que el pase aparezca en la pantalla de bloqueo.

Notas de comportamiento:

• boardingPass renderiza el origen y el destino como campos primarios sobredimensionados con un chevron entre ambos, con la imagen de footer justo encima del código de barras. Varios pases que comparten un groupingIdentifier se agrupan en una pila.
• eventTicket tiene dos presentaciones: un background.png a sangre (con fuerte desenfoque) con thumbnail y código de barras circular, o un strip.png en la parte superior sin thumbnail. Apple recomienda no mezclar las dos.
• coupon está dominado por la imagen del strip; el texto primario se superpone. suppressStripShine es lo más relevante aquí para diseños modernos y planos.
• storeCard suele mostrar un saldo como campo primario. Cuando hay nfc, la interfaz de canje por contacto de Wallet vive aquí.
• generic es el diseño de respaldo: logo y thumbnail pequeños a la derecha, campo primario junto al logo. Úsalo para tarjetas de socio, identificaciones; cualquier cosa que no encaje en un estilo más específico.

7. Errores y resolución de problemas

Los errores de instalación de Apple Wallet son intencionadamente genéricos: «No se puede instalar este pase en el iPhone», «Este pase no es válido», «No se ha podido añadir el pase». Todos significan lo mismo: que ha fallado uno de los pasos de validación de la sección 4, pero iOS no dice cuál. Los sospechosos habituales, ordenados por frecuencia:

En caso de duda, suelta el pase en el Visor PKPASS: te dirá si el paquete siquiera se puede analizar, si la firma está presente, si pass.json valida y qué imágenes se incluyen. La mayoría de los pases que no se instalan se siguen analizando bien en el visor, lo que reduce el problema a la firma.

8. Crear un .pkpass

Tienes tres vías prácticas para crear un .pkpass.

1. Usar una herramienta hospedada como WalletWallet. La vía más sencilla, rápida y gratuita: suelta un código de barras (o una foto de uno), elige los colores y obtén un .pkpass firmado. Pruébalo. Firmamos cada pase con nuestro propio certificado Pass Type ID, así que las instalaciones funcionan en cualquier iPhone, iPad, Watch y Mac sin que tengas que pasar por el Apple Developer Program. Guía completa de pase gratuito.
2. Hazlo tú con las herramientas de Apple. Registra un Pass Type ID en el portal de Apple Developer (membresía de 99 US$/año), descarga un certificado Pass Type ID y el intermedio WWDR correspondiente desde la página PKI de Apple, escribe tu propio pass.json, genera el manifiesto y la firma con OpenSSL o con la herramienta signpass de Apple, y comprime. Las bibliotecas maduras específicas de cada lenguaje —passkit-generator (Node), alvinbaena/passkit (Go), applepassgenerator (Python), walletkit (Rust)— se encargan por ti del hashing del manifiesto y de los pasos de firma PKCS#7.
3. Usar una plataforma emisora hospedada. Passcreator, PassNinja, Passslot y servicios similares te permiten plantillar un pase, conectar tu propio certificado y enviar valores por POST para generar pases firmados. Útil cuando quieres actualizaciones push y una API pero no quieres hacerte cargo de la renovación del certificado.

Un pase es «gratis» de hospedar pero no de emitir a escala: la membresía de Apple Developer Program cuesta 99 US$ al año por equipo, los certificados se renuevan anualmente y el push de APNs para actualizaciones de pases es gratuito pero tiene límite de tasa.

9. Preguntas frecuentes