Skip to content
Guia da Central de Ajuda · Modelos de passes
6 min de leituraVerificado 2026-11-16

Importar do Apple Pass Designer

Importe pastas .passdesign, arquivos Property List (.plist) e pacotes não assinados diretamente em modelos nativos do Passinstance.

Neste guia

Visão geral

Designers e engenheiros iOS que prototipam passes digitais com ferramentas de desenvolvimento macOS — como o Pass Designer oficial da Apple, o Xcode ou construtores de passes de computador de terceiros — podem importar os seus designs diretamente para a Passinstance. Não precisa de voltar a introduzir manualmente coordenadas de campos, valores de cor, tipos de código de barras nem carregar ativos de imagem um por um.

A Passinstance disponibiliza ingestão automatizada para:

  • Arquivos do Apple Pass Designer (pacotes .passdesign).
  • Documentos XML Apple Property List (.plist ou .xml).
  • Pacotes Apple Wallet assinados ou não assinados (arquivos zip .pkpass).
  • Ficheiros de metadados Apple PassKit em bruto (pass.json).

O motor de importação extrai ativos de imagem (icon.png, logo.png, strip.png, thumbnail.png), analisa o layout estrutural e normaliza-o num modelo Passinstance totalmente editável e compatível tanto com a Apple Wallet como com a Google Wallet.

Arquitetura do sistema: Motor de ingestão Apple PassKit e Plist

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
MOTOR DE INGESTÃO APPLE PASS DESIGNER
ETAPA 01 ARTEFACTOS DE ORIGEM APPLE PASS DESIGNER
Pacote .passdesign (documento do macOS Pass Designer)
.plist / .xml (formato Apple Property List)
.pkpass / .zip (pacote Apple Wallet assinado ou não assinado)
pass.json (dicionário da especificação Apple PassKit em bruto)
ETAPA 02 ANALISADOR DE INGESTÃO E SEGURANÇA
template-import-export.util.ts (parsePlistXmlToObject, parseXmlNodeTree)
Analisador XML Reforçado: Zero resolução externa de entidades (previne XXE)
Guarda de Profundidade: MAX_PLIST_DEPTH = 32 (previne estouro de pilha)
Limites Zip: MAX_ZIP_ENTRIES = 250, MAX_ZIP_ENTRY_BYTES = 1 MB
Modo Pacote Não Assinado: isUnsignedPackage: true (ignora assinatura Apple)
ETAPA 03 NORMALIZADOR DE ESQUEMA PASSKIT PARA PASSINSTANCE
Estilos ApplePassKind (storeCard, coupon, eventTicket, etc.)
Tipos PlistTipos JS (dictObject, arrayArray, realNumber)
Cores: Normaliza rgb(r, g, b) Apple e converte para hex Google Wallet
Barras: Normaliza PKBarcodeFormat* e atribui fallback watchOS
Extração de Ativos: Encaminha PNGs retina @1x, @2x, @3x para S3
ETAPA 04 MODELO CANÓNICO PASSINSTANCE (Entidade Template)
Pré-visualização interativa em direto nos simuladores Apple e Google Wallet
Pronto para emissão imediata, importação CSV em lote ou registo PassFlow

Formatos de ficheiro e extensões suportados

O carregador de ficheiros no Template Creation Wizard aceita as seguintes extensões correspondentes à expressão regular /\.(passdesign|plist|xml|pkpass|zip|json)$/i:

Formato / ExtensãoDescriçãoConteúdo extraído
.passdesignPasta de pacote ou arquivo comprimido do Apple Pass Designer.Geometria completa do passe, layouts visuais de campos, cores e todos os ativos PNG retina.
.plist / .xmlFormato XML Apple Property List.Estruturas de campos, pares rótulo/valor, tipos de trânsito, códigos de barras e regras de relevância.
.pkpassArquivo padrão de passe Apple Wallet (assinado ou não assinado).pass.json, diretórios de localização (.lproj) e ativos de imagem. A assinatura digital (signature) e o manifesto (manifest.json) são ignorados em segurança.
pass.jsonDicionário canónico Apple PassKit.Estrutura JSON padrão do Apple PassKit.

Segurança XML e proteção contra entidades (parsePlistXmlToObject)

Ao ingerir documentos Apple .plist ou .xml, a Passinstance utiliza um analisador XML interno reforçado (parsePlistXmlToObject em template-import-export.util.ts) com invariantes de segurança rigorosos:

  1. 1
    Proteção contra XXE (Zero Resolução de Entidades Externas): O analisador ignora por completo declarações <!DOCTYPE>, definições de entidades externas (SYSTEM ou PUBLIC) e referências a esquemas XML. Isto elimina vulnerabilidades de injeção XML External Entity (XXE) e Server-Side Request Forgery (SSRF).
  2. 2
    Salvaguarda de Recursão e Profundidade: A profundidade de recursão tem um limite máximo de MAX_PLIST_DEPTH = 32. Dicionários ou arrays aninhados que ultrapassem este limiar são abortados com uma exceção de validação para impedir ataques de estouro de pilha.
  3. 3
    Prevenção de Zip Bomb: Ao descompactar ficheiros zip .passdesign ou .pkpass, o motor limita o total de entradas a MAX_ZIP_ENTRIES = 250 e o tamanho descomprimido por ficheiro a MAX_ZIP_ENTRY_BYTES = 1 MB (1048576 bytes).
  4. 4
    Proteção contra Prototype Pollution: Chaves de propriedades correspondentes a __proto__, constructor ou prototype são removidas durante a construção de dicionários.

Referência de mapeamento de tipos Apple PassKit

O utilitário de importação mapeia automaticamente tipos Apple Property List e estruturas PassKit para modelos da Passinstance:

Tipo Apple PassKit / PlistEquivalente no modelo PassinstanceComportamento de normalização
<dict>Object JavaScriptMapeia para grupos de campos, objetos de cor ou dicionários de localização.
<array>Array JavaScriptMapeia para arrays de campos (headerFields, primaryFields, etc.).
<string>stringLimpa espaços em excesso e descodifica entidades XML (&amp;, &lt;, &gt;).
<integer> / <real>numberConvertido para números inteiros ou de vírgula flutuante.
<true/> / <false/>booleanConvertido para primitivas booleanas padrão de JavaScript.
<date>string ISO 8601Normalizado para carimbos temporais UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ).
<data>string Base64Descodificado de Base64 para buffers binários de ativos de imagem.

Normalização de estilo de passe para tipo de passe

Estilo de passe ApplePassKind na PassinstanceInvariantes de layout e campos
storeCardstoreCardLayout frontal com imagem de faixa; até 4 campos secundários/auxiliares.
couponcouponLayout frontal com imagem de faixa; campos auxiliares redirecionados para secundários.
eventTicketeventTicketSuporta textura de fundo, imagem de faixa e blocos de recinto iOS 18.
boardingPassboardingPassAnalisa transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) e campos principais de partida/chegada.
genericgenericLayout padrão multiusos com miniatura opcional.

Importar através do Painel (Passo a passo)

  1. 1
    Aceda a Modelos no Painel da Passinstance e clique em + Novo Modelo.
  2. 2
    No Passo 1 (Detalhes) do Template Creation Wizard:

- Clique em Importar passe existente ou arraste e largue o seu ficheiro .passdesign, .plist, .pkpass ou pass.json na zona de carregamento.

  1. 3
    O assistente analisa o ficheiro instantaneamente, extraindo:

- Nome e Descrição do Modelo: Pré-preenchidos a partir de description ou organizationName. - Tipo de Passe: Detetado automaticamente com base no dicionário de estilo de passe da Apple. - Cores: Cores de fundo, primeiro plano e rótulos preenchidas na paleta de cores. - Imagens: Ativos retina (icon.png, logo.png, strip.png) carregados para o repositório de ativos do espaço de trabalho. - Layouts de Campos: Campos de cabeçalho, principais, secundários, auxiliares e de verso posicionados nas respetivas zonas.

  1. 4
    Avance pelo Passo 2 (Tipo de Passe) e pelo Passo 3 (Aplicações de Carteira) para rever ou ativar o suporte para a Google Wallet.
  2. 5
    No Passo 4 (Conclusão), atribua um Certificado Apple Pass Type para ativar a assinatura criptográfica e clique em Concluir.

Importar através da API REST

Também pode importar pacotes do Apple Pass Designer programaticamente através de POST /api/v1/templates/import.

Pedido 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"

Resposta 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
}

Resolução de problemas na importação de passes Apple

Sintoma / ErroCausa raizResolução
Unsupported file formatA extensão do ficheiro não corresponde à lista suportada.Certifique-se de que o ficheiro termina em .passdesign, .plist, .xml, .pkpass, .zip ou .json.
Missing required icon assetO pacote Apple não continha um icon.png ou icon@2x.png.O Apple PassKit exige um ícone em todos os passes. Adicione um ficheiro de ícone PNG de 76x76 ou 114x114 ao pacote antes de importar.
Zip entry size exceededUm ativo de imagem dentro do arquivo excedeu 1 MB.Otimize imagens raster com ferramentas de compressão PNG ou carregue os ativos separadamente após a criação do modelo.
Unsigned package noticeO .pkpass importado não continha uma assinatura criptográfica válida.Normal para pacotes de prototipagem (isUnsignedPackage: true). A Passinstance aceita arquivos não assinados e assina os passes com o certificado Apple do seu espaço de trabalho aquando da emissão.

Explore Criar um modelo a partir de JSON para importações de esquemas em bruto ou Design e configuração de modelos para ajustar o estilo visual no editor.

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.