Skip to content
Guide du centre d'aide · Modèles de passes
6 min de lectureVérifié 2026-11-16

Importer depuis Apple Pass Designer

Importez des dossiers .passdesign, des fichiers Property List (.plist) et des packages non signés directement dans les modèles Passinstance natifs.

Dans ce guide

Aperçu

Les designers et ingénieurs iOS qui prototypent des passes numériques à l'aide d'outils développeur macOS — tels que Pass Designer officiel d'Apple, Xcode ou des éditeurs de passes tiers sur poste de travail — peuvent importer leurs créations directement dans Passinstance. Vous n'avez pas à ressaisir manuellement les coordonnées de champs, les valeurs de couleurs, les types de codes-barres ni à téléverser les actifs image un par un.

Passinstance assure l'ingestion automatisée de :

  • Archives Apple Pass Designer (bundles .passdesign).
  • Documents XML Apple Property List (.plist ou .xml).
  • Paquets Apple Wallet signés ou non signés (archives zip .pkpass).
  • Fichiers bruts de métadonnées Apple PassKit (pass.json).

Le moteur d'import extrait les actifs image (icon.png, logo.png, strip.png, thumbnail.png), analyse la mise en page structurelle et la normalise en un modèle Passinstance entièrement modifiable, compatible à la fois avec Apple Wallet et Google Wallet.

Architecture système : moteur d'ingestion Apple PassKit & Plist

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : MOTEUR D'INGESTION APPLE PASS DESIGNER
ÉTAPE 01 ARTEFACTS SOURCES APPLE PASS DESIGNER
Bundle .passdesign (paquet document macOS Pass Designer)
.plist / .xml (format Apple Property List)
.pkpass / .zip (archive Apple Wallet signée ou non signée)
pass.json (dictionnaire brut selon la spécification Apple PassKit)
ÉTAPE 02 ANALYSEUR D'INGESTION & DE SÉCURITÉ
template-import-export.util.ts (parsePlistXmlToObject, parseXmlNodeTree)
Parseur XML durci : aucune résolution d'entité externe (bloque attaques XXE)
Garde de profondeur : MAX_PLIST_DEPTH = 32 (prévient débordement récursif)
Limites Zip : MAX_ZIP_ENTRIES = 250, MAX_ZIP_ENTRY_BYTES = 1 Mo
Mode paquet non signé : isUnsignedPackage: true (sans signature Apple req.)
ÉTAPE 03 NORMALISATEUR DE SCHÉMA PASSKITPASSINSTANCE
Styles ApplePassKind (storeCard, coupon, eventTicket, etc.)
Types PlistTypes JS (dictObject, arrayArray, realNumber)
Couleurs : normalise rgb(r, g, b) Apple et convertit en hex Google Wallet
Codes-barres : normalise PKBarcodeFormat* et assigne le repli watchOS
Extraction d'actifs : stocke les PNG Retina @1x, @2x, @3x sur S3
ÉTAPE 04 MODÈLE PASSINSTANCE CANONIQUE (Entité Template)
Aperçu interactif en direct dans le simulateur Apple Wallet & Google Wallet
Prêt pour l'émission immédiate, l'import CSV par lot ou l'inscription PassFlow

Formats de fichiers & extensions pris en charge

Le composant de téléversement dans Template Creation Wizard accepte les extensions correspondant à l'expression régulière /\.(passdesign|plist|xml|pkpass|zip|json)$/i :

Format / ExtensionDescriptionContenu extrait
.passdesignDossier bundle Apple Pass Designer ou archive compressée.Géométrie complète du passe, mise en page visuelle des champs, couleurs et tous les actifs PNG Retina.
.plist / .xmlFormat XML Apple Property List.Structures de champs, paires libellé/valeur, types de transport, codes-barres et règles de pertinence.
.pkpassArchive Apple Wallet standard (signée ou non signée).pass.json, répertoires de localisation (.lproj) et actifs image. La signature numérique (signature) et le manifeste (manifest.json) sont ignorés en toute sécurité.
pass.jsonDictionnaire Apple PassKit canonique.Structure JSON Apple PassKit standard.

Sécurité XML & protection contre les entités (parsePlistXmlToObject)

Lors de l'ingestion de documents Apple .plist ou .xml, Passinstance utilise un analyseur XML interne durci (parsePlistXmlToObject dans template-import-export.util.ts) appliquant des invariants de sécurité stricts :

  1. 1
    Protection XXE (zéro résolution d'entité externe) : le parseur ignore totalement les déclarations <!DOCTYPE>, les définitions d'entités externes (SYSTEM ou PUBLIC) et les références de schéma XML. Cela élimine les vulnérabilités d'injection XML External Entity (XXE) et de Server-Side Request Forgery (SSRF).
  2. 2
    Garde-fou de récursion et de profondeur : la profondeur d'imbrication est plafonnée à MAX_PLIST_DEPTH = 32. Les dictionnaires ou tableaux imbriqués dépassant ce seuil sont interrompus par une exception de validation afin d'empêcher tout débordement de pile.
  3. 3
    Prévention des bombes Zip : lors de la décompression des archives .passdesign ou .pkpass, le moteur limite le nombre total d'entrées à MAX_ZIP_ENTRIES = 250 et la taille décompressée par fichier à MAX_ZIP_ENTRY_BYTES = 1 Mo (1048576 octets).
  4. 4
    Protection contre la pollution de prototype : les clés de propriété correspondant à __proto__, constructor ou prototype sont supprimées lors de la construction des dictionnaires.

Référence de correspondance des types Apple PassKit

L'utilitaire d'import mappe automatiquement les types Apple Property List et les structures PassKit vers les modèles Passinstance :

Type Apple PassKit / PlistÉquivalent modèle PassinstanceComportement de normalisation
<dict>Object JavaScriptConverti en groupes de champs, objets couleur ou dictionnaires de géolocalisation.
<array>Array JavaScriptConverti en tableaux de champs (headerFields, primaryFields, etc.).
<string>stringNettoie les espaces et déséchappe les entités XML (&amp;, &lt;, &gt;).
<integer> / <real>numberConverti en nombres à virgule flottante ou entiers.
<true/> / <false/>booleanConverti en primitives booléennes JavaScript standard.
<date>string ISO 8601Normalisé en horodatages ISO-8601 UTC (YYYY-MM-DDTHH:MM:SSZ).
<data>string Base64Décodé depuis le Base64 en tampons binaires d'actifs pour les images.

Normalisation du style de passe vers PassKind

Style de passe ApplePassKind PassinstanceInvariants de mise en page & champs
storeCardstoreCardMise en page recto avec image bandeau (strip) ; jusqu'à 4 champs secondaires/auxiliaires.
couponcouponMise en page recto avec image bandeau (strip) ; les champs auxiliaires sont redirigés vers les champs secondaires.
eventTicketeventTicketPrend en charge la texture d'arrière-plan, l'image bandeau et les blocs compagnons de lieu iOS 18.
boardingPassboardingPassAnalyse transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) et les champs principaux départ/arrivée.
genericgenericMise en page polyvalente standard avec miniature (thumbnail) facultative.

Importer via le tableau de bord (étape par étape)

  1. 1
    Accédez à Modèles (Templates) dans le tableau de bord Passinstance et cliquez sur + Nouveau modèle (+ New Template).
  2. 2
    À l'Étape 1 (Détails) de Template Creation Wizard :

- Cliquez sur Importer un passe existant (Import existing pass) ou glissez-déposez votre fichier .passdesign, .plist, .pkpass ou pass.json dans la zone de dépôt.

  1. 3
    L'assistant analyse le fichier instantanément et en extrait :

- Nom et description du modèle : pré-remplis depuis description ou organizationName. - Type de passe (PassKind) : détecté automatiquement d'après le dictionnaire de style Apple. - Couleurs : couleurs d'arrière-plan, de premier plan et de libellé appliquées à la palette. - Images : actifs Retina (icon.png, logo.png, strip.png) téléversés dans le stockage d'actifs de l'espace de travail. - Mise en page des champs : champs d'en-tête, primaires, secondaires, auxiliaires et verso placés dans leurs zones respectives.

  1. 4
    Poursuivez avec l'Étape 2 (Type de passe) et l'Étape 3 (Applications Wallet) pour vérifier ou activer la prise en charge Google Wallet.
  2. 5
    À l'Étape 4 (Finalisation), assignez un certificat Apple Pass Type afin d'activer la signature cryptographique, puis cliquez sur Terminer.

Importer via l'API REST

Vous pouvez également importer des paquets Apple Pass Designer par programmation via POST /api/v1/templates/import.

Requête 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"

Réponse 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
}

Dépannage de l'import Apple Pass

Symptôme / ErreurCause racineRésolution
Unsupported file formatL'extension du fichier ne figure pas dans la liste prise en charge.Vérifiez que votre fichier se termine par .passdesign, .plist, .xml, .pkpass, .zip ou .json.
Missing required icon assetLe paquet Apple ne contenait ni icon.png ni icon@2x.png.Apple PassKit exige une icône pour chaque passe. Ajoutez une icône PNG 76x76 ou 114x114 à votre paquet avant de l'importer.
Zip entry size exceededUn actif image dans l'archive dépasse 1 Mo.Optimisez vos images matricielles avec un outil de compression PNG ou téléversez les actifs séparément après création du modèle.
Unsigned package noticeLe fichier .pkpass importé ne comportait pas de signature cryptographique valide.Comportement normal pour les paquets de prototypage (isUnsignedPackage: true). Passinstance accepte les archives non signées et signe les passes à l'émission avec le certificat Apple de votre espace de travail.

Découvrez Créer un modèle depuis JSON pour les imports de schéma brut ou Design & configuration des modèles pour ajuster le rendu visuel dans l'éditeur.

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.