Crear pases nativos de Apple Wallet (archivos .pkpass) permite a las empresas entregar tarjetas de fidelización, entradas a eventos, tarjetas de embarque, cupones y carnés de socio directamente en la pantalla de bloqueo del iPhone y el Apple Watch sin obligar a los usuarios a descargar una aplicación dedicada.
Esta guía completa de 2026 abarca todo lo que los equipos de desarrollo y producto necesitan saber sobre la arquitectura de Apple PassKit, la firma criptográfica, la distribución y las actualizaciones push mediante APNs.
1. Anatomía de un pase Apple Wallet (.pkpass)
Un pase de Apple Wallet es un archivo ZIP comprimido con extensión .pkpass que contiene JSON estructurado, imágenes adaptadas por resolución y manifiestos criptográficos validados por Apple.
Estructura obligatoria del paquete
mi-pase.pkpass
├── pass.json # Diseño principal, definición de campos y metadatos
├── logo.png # Emblema superior izquierdo de la marca (160x160 @2x)
├── logo@2x.png
├── icon.png # Icono de notificación en pantalla de bloqueo (58x58 @2x)
├── icon@2x.png
├── strip.png # Imagen destacada para entradas y cupones (375x144 @2x)
├── strip@2x.png
├── manifest.json # Resúmenes SHA-1 de todos los archivos del paquete
└── signature # Firma criptográfica PKCS#7 generada con su certificado Pass Type ID
2. Configuración en Apple Developer y firma de certificados
Para firmar pases nativos de Apple Wallet, Apple exige credenciales de firma PKCS#12 derivadas de una cuenta activa de Apple Developer.
Flujo de firma paso a paso:
-
1
Pass Type ID: Registre un identificador único (p. ej.,
pass.com.suempresa.fidelidad) en el Apple Developer Portal. -
2
Solicitud de firma de certificado (CSR): Genere una clave privada RSA de 2048 bits y un archivo CSR mediante OpenSSL o Acceso a Llaveros.
-
3
Certificado Pass Type: Descargue el archivo
.ceremitido y expórtelo como contenedor.p12junto con su clave privada. -
4
Certificado intermedio WWDR: Incluya el certificado intermedio Apple Worldwide Developer Relations G6 en su cadena de confianza.
[!NOTE]
Certificados en producción: Para firmar pases de Apple Wallet en producción con la identidad verificada de su marca, cargue su certificado Pass Type ID de Apple Developer en Passinstance; la plataforma gestiona automáticamente la firma criptográfica PKCS#7, el ciclo de vida del certificado intermedio WWDR y la compilación del paquete
.pkpass.
3. Configuración de campos en pass.json
El archivo pass.json define el estilo de presentación del pase (storeCard, coupon, eventTicket, boardingPass, generic) y los campos de datos dinámicos:
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.passinstance.loyalty",
"serialNumber": "PASS-8842-2026",
"teamIdentifier": "ABC123XYZ",
"organizationName": "Artisan Coffee",
"description": "Tarjeta de fidelización Artisan Coffee",
"logoText": "Artisan Coffee",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(10, 90, 84)",
"labelColor": "rgb(164, 243, 222)",
"storeCard": {
"primaryFields": [
{
"key": "stamps",
"label": "PROGRESO DE RECOMPENSA",
"value": "8 de 10 sellos"
}
],
"secondaryFields": [
{
"key": "holder",
"label": "MIEMBRO",
"value": "Lucía Martín"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PASS-LOYALTY-8842",
"messageEncoding": "iso-8859-1"
}
],
"webServiceURL": "https://api.passinstance.com/v1/apple",
"authenticationToken": "tok_auth_demo_99182348"
}

4. Geolocalización nativa y disparadores de ubicación
Los pases de Apple Wallet admiten hasta 10 coordenadas geográficas (locations) que activan avisos pasivos nativos en la pantalla de bloqueo cuando un cliente se acerca físicamente a su tienda o recinto.
"locations": [
{
"latitude": 40.416775,
"longitude": -3.703790,
"relevantText": "¡Bienvenido de nuevo! Escanea tu tarjeta en caja para disfrutar de un 10 % de descuento."
}
]
5. Envío de actualizaciones en pantalla de bloqueo (APNs)
Cuando cambia el saldo, el nivel o la caducidad de un pase, Apple Wallet lo actualiza de forma remota mediante el servicio de notificaciones push de Apple (APNs):
-
1
Al instalarse el pase, iOS envía una petición POST a su
webServiceURLcon el token push del dispositivo (pushToken). -
2
Para actualizar el pase, envíe una notificación push APNs vacía a los servidores de Apple dirigida a ese
pushToken. -
3
iOS se activa en segundo plano, descarga el
pass.jsonactualizado desde su servidor, refresca la tarjeta y muestra un aviso en pantalla de bloqueo si se ha modificado un campo conchangeMessage.
6. Creación de pases Apple Wallet en segundos con Passinstance
En lugar de mantener flujos propios de firma con OpenSSL, infraestructura de servidores APNs y endpoints de registro de dispositivos, Passinstance automatiza todo el proceso:
import { Passinstance } from "@passinstance/sdk";
const client = new Passinstance({ apiKey: process.env.PASSINSTANCE_API_KEY });
// Emite un pase Apple Wallet con firma en vivo
const pass = await client.passes.create({
templateId: "tpl_coffee_loyalty",
data: {
holderName: "Lucía Martín",
stamps: "8 de 10 sellos",
},
});
console.log("Enlace Añadir a Apple Wallet:", pass.appleWalletUrl);

Puntos clave
-
Sin aplicación propia: Los clientes añaden los pases en un toque desde Safari, código QR, correo electrónico o enlace alojado.
-
Siempre actualizado: Los cambios de saldo se reflejan en iPhone y Apple Watch mediante el protocolo APNs de Apple.
-
Relevancia por ubicación: Las coordenadas configuradas muestran el pase en la pantalla de bloqueo cuando el usuario se aproxima a su local.





