Descripción general: cómo funciona la integración con Apple Wallet
Passinstance genera paquetes nativos .pkpass de Apple Wallet (Apple Wallet Packager) conformes a la especificación oficial de paquetes PassKit de Apple para iOS y watchOS. Cada pase se ensambla dinámicamente sobre la marcha como un archivo ZIP firmado criptográficamente que se entrega con el tipo MIME application/vnd.apple.pkpass.

Estructura interna de un archivo .pkpass
Un paquete .pkpass de Apple Wallet es un archivo ZIP estándar compuesto por cinco capas estructurales fundamentales:
| Archivo / Directorio | Formato y codificación | Función en Apple Wallet |
|---|---|---|
pass.json | JSON UTF-8 | Define el estilo del pase (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, campos, códigos de barras, ubicaciones y diccionario nfc. |
Recursos visuales (.png) | PNG (@1x, @2x, @3x) | Hasta 13 ranuras de imagen de plantilla convertidas a los nombres de archivo PassKit de Apple (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) en sus resoluciones retina. |
<lang>.lproj/pass.strings | Tabla de cadenas UTF-8 | Traducciones localizadas clave-valor (por ejemplo, de.lproj/pass.strings, fr.lproj/pass.strings) emparejadas con el idioma del sistema del iPhone. |
manifest.json | JSON UTF-8 | Diccionario plano que asigna cada ruta relativa dentro del paquete (excluidos manifest.json y signature) a su hash SHA-1 hexadecimal de 40 caracteres. |
signature | DER binario (PKCS#7) | Firma criptográfica PKCS#7 independiente de manifest.json, firmada con la clave privada de su Apple Pass Type ID y encadenada al certificado intermedio Apple WWDR G4/G6. |
Importante: Apple Wallet exige estrictamente que los valores cromáticos en
pass.json(backgroundColor,foregroundColor,labelColor) se serialicen como cadenasrgb(r, g, b). El componenteapple-pass-field.serializer.tsde Passinstance convierte automáticamente valores hexadecimales argb(r, g, b)y elimina los canales alfa para que iOS nunca rechace un paquete durante la validación de firma y esquema.
Ejemplo de estructura de payload pass.json
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.yourbrand.loyalty",
"serialNumber": "PI-8849-2026-X9",
"teamIdentifier": "9A8B7C6D5E",
"organizationName": "Phenix Roasters",
"description": "Phenix VIP Rewards Card",
"webServiceURL": "https://api.passinstance.com",
"authenticationToken": "b7f9e2c1a4d80931f6e5c2b8a1049d7e",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(18, 24, 38)",
"labelColor": "rgb(148, 163, 184)",
"storeCard": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "Gold"
}
],
"primaryFields": [
{
"key": "points",
"label": "POINTS BALANCE",
"value": 1450,
"changeMessage": "Your points balance updated to %@"
}
],
"backFields": [
{
"key": "support_link",
"label": "MEMBER PORTAL",
"value": "Visit https://yourbrand.com/member",
"attributedValue": "<a href=\"https://yourbrand.com/member\">Open Member Portal</a>"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PI-8849-2026-X9",
"messageEncoding": "iso-8859-1",
"altText": "PI-8849-2026-X9"
}
]
}
Endpoints del Web Service de Apple Wallet (/v1)
Cada pase activo contiene webServiceURL y un authenticationToken de al menos 16 caracteres. Los dispositivos iOS y watchOS se comunican directamente con los endpoints /v1 de Passinstance mediante la cabecera HTTP Authorization: ApplePass <authenticationToken>:
| Método | Ruta del endpoint | Estados HTTP | Propósito |
|---|---|---|---|
| POST | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 201 Created, 200 OK, 401 Unauthorized | Registra el pushToken del iPhone o Apple Watch para actualizaciones APNs y marca el pase como instalado. |
| GET | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier | 200 OK, 204 No Content | Devuelve { serialNumbers: [...], lastUpdated: "<tag>" } para los pases modificados desde ?passesUpdatedSince=. |
| GET | /v1/passes/:passTypeIdentifier/:serialNumber | 200 OK, 304 Not Modified, 401 Unauthorized | Genera y transmite el paquete .pkpass firmado más reciente al despertarse por push APNs o actualización manual. |
| DELETE | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 200 OK, 401 Unauthorized | Da de baja el dispositivo cuando el titular elimina el pase de Apple Wallet. |
| POST | /v1/log | 200 OK | Recibe arrays de diagnóstico { "logs": [...] } de dispositivos iOS si un .pkpass falla la validación en cliente. |
Explore más especificaciones técnicas en Plataforma Apple Wallet, Certificados de Apple Wallet y Protocolo sin contacto Apple VAS.
