Skip to content
Guía del Centro de ayuda · Integraciones WalletFase de incorporación 4
3 min de lecturaVerificado 2026-11-16

Apple Wallet

Generación de paquetes .pkpass, firma PKCS#7, registro iOS/watchOS y respuestas al servicio web de PassKit.

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 ampliado
Elementos clave de la interfaz

Vista previa en vivo de doble Wallet (Zoom)

Alterna entre Apple y Google en el panel de vista previa para confirmar el diseño, el formato del saldo, la legibilidad del código QR y la alineación de los campos.

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.

Vista previa en vivo de pase entre Apple Wallet y Google Wallet
Vista previa en vivo de pase entre Apple Wallet y Google Wallet
FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
EMPAQUETADO .PKPASS Y WEB SERVICE DE APPLE WALLET
ETAPA 01 GENERADOR DE ARCHIVOS PKPASS (Apple Wallet Packager)
1
Serializar pass.json (formatVersion: 1, colores rgb(r,g,b), campos, NFC)
2
Hidratar recursos Retina (icon.png, logo.png, strip.png @1x/@2x/@3x)
3
Compilar paquetes de idioma (<lang>.lproj/pass.strings en UTF-8)
4
Calcular diccionario de checksums SHA-1Escribir manifest.json
5
Generar firma PKCS#7 independiente (signature) con Pass Type + WWDR G4/G6
6
Comprimir archivo ZIPEnviar como Content-Type: application/vnd.apple.pkpass
ETAPA 02 PROTOCOLO DEL WEB SERVICE DE APPLE WALLET (/v1)
Registrar dispositivo: POST/v1/devices/:deviceLibId/registrations/:typeId/:sn
Consultar cambios: GET/v1/devices/:deviceLibId/registrations/:typeId
Descargar paquete: GET/v1/passes/:passTypeId/:serialNumber
Anular registro: DELETE/v1/devices/:deviceLibId/registrations/:typeId/:sn
Registro errores: POST/v1/log

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 / DirectorioFormato y codificaciónFunción en Apple Wallet
pass.jsonJSON UTF-8Define 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.stringsTabla de cadenas UTF-8Traducciones localizadas clave-valor (por ejemplo, de.lproj/pass.strings, fr.lproj/pass.strings) emparejadas con el idioma del sistema del iPhone.
manifest.jsonJSON UTF-8Diccionario plano que asigna cada ruta relativa dentro del paquete (excluidos manifest.json y signature) a su hash SHA-1 hexadecimal de 40 caracteres.
signatureDER 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 cadenas rgb(r, g, b). El componente apple-pass-field.serializer.ts de Passinstance convierte automáticamente valores hexadecimales a rgb(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

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étodoRuta del endpointEstados HTTPPropósito
POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber201 Created, 200 OK, 401 UnauthorizedRegistra el pushToken del iPhone o Apple Watch para actualizaciones APNs y marca el pase como instalado.
GET/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier200 OK, 204 No ContentDevuelve { serialNumbers: [...], lastUpdated: "<tag>" } para los pases modificados desde ?passesUpdatedSince=.
GET/v1/passes/:passTypeIdentifier/:serialNumber200 OK, 304 Not Modified, 401 UnauthorizedGenera y transmite el paquete .pkpass firmado más reciente al despertarse por push APNs o actualización manual.
DELETE/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber200 OK, 401 UnauthorizedDa de baja el dispositivo cuando el titular elimina el pase de Apple Wallet.
POST/v1/log200 OKRecibe 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.

Documentación de producto y API relacionada

¿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.