Descripción general
Los diseñadores e ingenieros de iOS que prototipan pases digitales con herramientas de desarrollo de macOS —como el Pass Designer oficial de Apple, Xcode o editores de escritorio de terceros— pueden importar sus diseños directamente en Passinstance. No es necesario volver a introducir manualmente las posiciones de los campos, los valores de color ni los tipos de código de barras, ni cargar los activos de imagen uno a uno.
Passinstance ofrece ingesta automatizada para:
-
Archivos de Apple Pass Designer (paquetes
.passdesign). -
Documentos XML de Property List de Apple (
.plisto.xml). -
Paquetes de Apple Wallet firmados o sin firmar (archivos comprimidos
.pkpass). -
Archivos de metadatos sin procesar de Apple PassKit (
pass.json).
El motor de importación extrae los activos de imagen (icon.png, logo.png, strip.png, thumbnail.png), analiza el diseño estructural y lo normaliza en una plantilla de Passinstance totalmente editable y compatible tanto con Apple Wallet como con Google Wallet.
Arquitectura del sistema: motor de ingesta de Apple PassKit y Plist
Formatos de archivo y extensiones admitidas
El cargador de archivos de Template Creation Wizard acepta las siguientes extensiones que coinciden con la expresión regular /\.(passdesign|plist|xml|pkpass|zip|json)$/i:
| Formato / Extensión | Descripción | Contenido extraído |
|---|---|---|
.passdesign | Carpeta de paquete de Apple Pass Designer o archivo comprimido. | Geometría completa del pase, distribución visual de campos, colores y todos los activos PNG retina. |
.plist / .xml | Formato XML Apple Property List. | Estructuras de campos, pares etiqueta/valor, tipos de transporte, códigos de barras y reglas de relevancia. |
.pkpass | Archivo estándar de pase de Apple Wallet (firmado o sin firmar). | pass.json, directorios de localización (.lproj) y activos de imagen. La firma digital (signature) y el manifiesto (manifest.json) se omiten de forma segura. |
pass.json | Diccionario canónico de Apple PassKit. | Estructura JSON estándar de Apple PassKit. |
Seguridad XML y protección de entidades (parsePlistXmlToObject)
Al ingerir documentos .plist o .xml de Apple, Passinstance emplea un analizador XML interno reforzado (parsePlistXmlToObject en template-import-export.util.ts) con estrictas invariantes de seguridad:
-
1
Protección XXE (cero resolución de entidades externas): El analizador ignora por completo las declaraciones
<!DOCTYPE>, las definiciones de entidades externas (SYSTEMoPUBLIC) y las referencias de esquema XML. Esto elimina las vulnerabilidades de inyección XML External Entity (XXE) y Server-Side Request Forgery (SSRF). -
2
Protección contra recursión y profundidad excesiva: La profundidad de recursión está limitada a
MAX_PLIST_DEPTH = 32. Los diccionarios o matrices anidados que superen este umbral se abortan con una excepción de validación para evitar ataques de desbordamiento de pila. -
3
Prevención de bombas ZIP: Al descomprimir archivos
.passdesigno.pkpass, el motor limita el total de entradas aMAX_ZIP_ENTRIES = 250y el tamaño descomprimido por archivo aMAX_ZIP_ENTRY_BYTES = 1 MB(1048576bytes). -
4
Protección contra Prototype Pollution: Las claves de propiedad que coincidan con
__proto__,constructoroprototypese eliminan durante la construcción del diccionario.
Referencia de mapeo de tipos de Apple PassKit
La utilidad de importación asigna automáticamente los tipos de Apple Property List y las estructuras de PassKit a los modelos de Passinstance:
| Tipo Apple PassKit / Plist | Equivalente en el modelo Passinstance | Comportamiento de normalización |
|---|---|---|
<dict> | Object de JavaScript | Se asigna a grupos de campos, objetos de color o diccionarios de ubicación. |
<array> | Array de JavaScript | Se asigna a matrices de campos (headerFields, primaryFields, etc.). |
<string> | string | Limpia los espacios en blanco y decodifica entidades XML (&, <, >). |
<integer> / <real> | number | Se convierte en números enteros o de coma flotante. |
<true/> / <false/> | boolean | Se convierte en valores booleanos primitivos estándar de JavaScript. |
<date> | string ISO 8601 | Se normaliza a marcas temporales UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ). |
<data> | string Base64 | Se decodifica desde Base64 a búferes binarios de activos para imágenes. |
Normalización de estilo de pase a tipo de pase (PassKind)
| Estilo de pase Apple | PassKind en Passinstance | Invariantes de diseño y campos |
|---|---|---|
storeCard | storeCard | Diseño frontal con imagen strip; hasta 4 campos secundarios/auxiliares. |
coupon | coupon | Diseño frontal con imagen strip; los campos auxiliares se redirigen a secundarios. |
eventTicket | eventTicket | Admite textura de fondo, imagen strip y bloques complementarios de recinto de iOS 18. |
boardingPass | boardingPass | Analiza transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) y campos principales de salida/llegada. |
generic | generic | Diseño estándar de tarjeta multipropósito con miniatura opcional. |
Importar desde el panel de control (paso a paso)
-
1
Vaya a Plantillas en el panel de control de Passinstance y haga clic en + Nueva plantilla.
-
2
En el Paso 1 (Detalles) de
Template Creation Wizard:
- Haga clic en Importar pase existente o arrastre y suelte su archivo .passdesign, .plist, .pkpass o pass.json en la zona de carga.
-
3
El asistente analiza el archivo al instante y extrae:
- Nombre y descripción de la plantilla: Precompletados a partir de description u organizationName. - Tipo de pase: Detectado automáticamente a partir del diccionario de estilo de pase de Apple. - Colores: Colores de fondo, primer plano y etiquetas cargados en la paleta de colores. - Imágenes: Activos retina (icon.png, logo.png, strip.png) cargados en el almacén de activos del espacio de trabajo. - Distribución de campos: Campos de cabecera, principales, secundarios, auxiliares y traseros colocados en sus zonas correspondientes.
-
4
Continúe por el Paso 2 (Tipo de pase) y el Paso 3 (Aplicaciones de monedero) para revisar o habilitar la compatibilidad con Google Wallet.
-
5
En el Paso 4 (Finalización), asigne un certificado Apple Pass Type para habilitar la firma criptográfica y haga clic en Finalizar.
Importar mediante la API REST
También puede importar paquetes de Apple Pass Designer mediante programación a través de POST /api/v1/templates/import.
Solicitud HTTP (multipart/form-data)
curl -X POST https://api.passinstance.com/api/v1/templates/import \
-H "X-API-Key: <API_KEY>" \
-F "file=@loyalty_pass.passdesign" \
-F "name=Imported Loyalty Card"
Respuesta HTTP (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01h8x7j6k5m4n3p2q1",
"name": "Imported Loyalty Card",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"importedFrom": "apple_pass_designer",
"imagesImported": ["icon", "logo", "strip"],
"fieldsCount": 8,
"createdAt": "2026-11-16T20:35:00.000Z"
},
"statusCode": 201
}
Resolución de problemas en la importación de pases de Apple
| Síntoma / Error | Causa raíz | Solución |
|---|---|---|
Unsupported file format | La extensión del archivo no coincide con la lista admitida. | Asegúrese de que el archivo termine en .passdesign, .plist, .xml, .pkpass, .zip o .json. |
Missing required icon asset | El paquete de Apple no contenía un archivo icon.png ni icon@2x.png. | Apple PassKit exige un icono en todos los pases. Añada un icono PNG de 76x76 o 114x114 a su paquete antes de importarlo. |
Zip entry size exceeded | Un activo de imagen dentro del archivo superó 1 MB. | Optimice las imágenes rasterizadas con herramientas de compresión PNG o cargue los activos por separado tras crear la plantilla. |
Unsigned package notice | El archivo .pkpass importado no contenía una firma criptográfica válida. | Comportamiento normal para paquetes de prototipo (isUnsignedPackage: true). Passinstance acepta archivos sin firmar y firma los pases al emitirlos usando el certificado de Apple de su espacio de trabajo. |
Explore Crear una plantilla desde JSON para importaciones de esquemas sin procesar, o Diseño y configuración de plantillas para ajustar el estilo visual en el editor.
