Skip to content
Guía del Centro de ayuda · Plantillas de pases
6 min de lecturaVerificado 2026-11-16

Importar desde Apple Pass Designer

Importe carpetas .passdesign, archivos Property List (.plist) y paquetes sin firmar directamente a plantillas nativas de Passinstance.

En esta guía

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 (.plist o .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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
MOTOR DE INGESTA DE APPLE PASS DESIGNER
ETAPA 01 ARTEFACTOS DE ORIGEN DE APPLE PASS DESIGNER
Paquete .passdesign (paquete de documento de Pass Designer en macOS)
.plist / .xml (formato Apple Property List)
.pkpass / .zip (paquete de Apple Wallet firmado o sin firmar)
pass.json (diccionario sin procesar de la especificación Apple PassKit)
ETAPA 02 ANALIZADOR DE INGESTA Y SEGURIDAD
template-import-export.util.ts (parsePlistXmlToObject, parseXmlNodeTree)
Analizador XML reforzado: cero resolución de entidades externas (evita XXE)
Límite de profundidad: MAX_PLIST_DEPTH = 32 (evita desbordamiento recursivo)
Límites ZIP: MAX_ZIP_ENTRIES = 250, MAX_ZIP_ENTRY_BYTES = 1 MB
Modo paquete sin firmar: isUnsignedPackage: true (omite requisito de firma)
ETAPA 03 NORMALIZADOR DE ESQUEMA PASSKIT A PASSINSTANCE
Estilos ApplePassKind (storeCard, coupon, eventTicket, etc.)
Tipos PlistTipos JS (dictObject, arrayArray, realNumber)
Colores: normaliza rgb(r, g, b) de Apple y convierte a hex para Google Wallet
Códigos: normaliza PKBarcodeFormat* y asigna respaldo para watchOS
Extracción de activos: envía PNG retina @1x, @2x, @3x al almacén S3
ETAPA 04 PLANTILLA CANÓNICA DE PASSINSTANCE (Entidad Template)
Vista previa interactiva en vivo en el simulador de Apple y Google Wallet
Lista para emisión inmediata, importación CSV masiva o registro en PassFlow

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ónDescripciónContenido extraído
.passdesignCarpeta 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 / .xmlFormato XML Apple Property List.Estructuras de campos, pares etiqueta/valor, tipos de transporte, códigos de barras y reglas de relevancia.
.pkpassArchivo 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.jsonDiccionario 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. 1
    Protección XXE (cero resolución de entidades externas): El analizador ignora por completo las declaraciones <!DOCTYPE>, las definiciones de entidades externas (SYSTEM o PUBLIC) y las referencias de esquema XML. Esto elimina las vulnerabilidades de inyección XML External Entity (XXE) y Server-Side Request Forgery (SSRF).
  2. 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. 3
    Prevención de bombas ZIP: Al descomprimir archivos .passdesign o .pkpass, el motor limita el total de entradas a MAX_ZIP_ENTRIES = 250 y el tamaño descomprimido por archivo a MAX_ZIP_ENTRY_BYTES = 1 MB (1048576 bytes).
  4. 4
    Protección contra Prototype Pollution: Las claves de propiedad que coincidan con __proto__, constructor o prototype se 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 / PlistEquivalente en el modelo PassinstanceComportamiento de normalización
<dict>Object de JavaScriptSe asigna a grupos de campos, objetos de color o diccionarios de ubicación.
<array>Array de JavaScriptSe asigna a matrices de campos (headerFields, primaryFields, etc.).
<string>stringLimpia los espacios en blanco y decodifica entidades XML (&amp;, &lt;, &gt;).
<integer> / <real>numberSe convierte en números enteros o de coma flotante.
<true/> / <false/>booleanSe convierte en valores booleanos primitivos estándar de JavaScript.
<date>string ISO 8601Se normaliza a marcas temporales UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ).
<data>string Base64Se 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 ApplePassKind en PassinstanceInvariantes de diseño y campos
storeCardstoreCardDiseño frontal con imagen strip; hasta 4 campos secundarios/auxiliares.
couponcouponDiseño frontal con imagen strip; los campos auxiliares se redirigen a secundarios.
eventTicketeventTicketAdmite textura de fondo, imagen strip y bloques complementarios de recinto de iOS 18.
boardingPassboardingPassAnaliza transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) y campos principales de salida/llegada.
genericgenericDiseño estándar de tarjeta multipropósito con miniatura opcional.

Importar desde el panel de control (paso a paso)

  1. 1
    Vaya a Plantillas en el panel de control de Passinstance y haga clic en + Nueva plantilla.
  2. 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.

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

  1. 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.
  2. 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)

BASH
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)

JSON
{
  "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 / ErrorCausa raízSolución
Unsupported file formatLa 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 assetEl 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 exceededUn 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 noticeEl 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.

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