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 (
.plistou.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
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ão | Descrição | Conteúdo extraído |
|---|---|---|
.passdesign | Pasta 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 / .xml | Formato XML Apple Property List. | Estruturas de campos, pares rótulo/valor, tipos de trânsito, códigos de barras e regras de relevância. |
.pkpass | Arquivo 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.json | Dicioná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
Proteção contra XXE (Zero Resolução de Entidades Externas): O analisador ignora por completo declarações
<!DOCTYPE>, definições de entidades externas (SYSTEMouPUBLIC) e referências a esquemas XML. Isto elimina vulnerabilidades de injeção XML External Entity (XXE) e Server-Side Request Forgery (SSRF). -
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
Prevenção de Zip Bomb: Ao descompactar ficheiros zip
.passdesignou.pkpass, o motor limita o total de entradas aMAX_ZIP_ENTRIES = 250e o tamanho descomprimido por ficheiro aMAX_ZIP_ENTRY_BYTES = 1 MB(1048576bytes). -
4
Proteção contra Prototype Pollution: Chaves de propriedades correspondentes a
__proto__,constructorouprototypesã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 / Plist | Equivalente no modelo Passinstance | Comportamento de normalização |
|---|---|---|
<dict> | Object JavaScript | Mapeia para grupos de campos, objetos de cor ou dicionários de localização. |
<array> | Array JavaScript | Mapeia para arrays de campos (headerFields, primaryFields, etc.). |
<string> | string | Limpa espaços em excesso e descodifica entidades XML (&, <, >). |
<integer> / <real> | number | Convertido para números inteiros ou de vírgula flutuante. |
<true/> / <false/> | boolean | Convertido para primitivas booleanas padrão de JavaScript. |
<date> | string ISO 8601 | Normalizado para carimbos temporais UTC ISO-8601 (YYYY-MM-DDTHH:MM:SSZ). |
<data> | string Base64 | Descodificado de Base64 para buffers binários de ativos de imagem. |
Normalização de estilo de passe para tipo de passe
| Estilo de passe Apple | PassKind na Passinstance | Invariantes de layout e campos |
|---|---|---|
storeCard | storeCard | Layout frontal com imagem de faixa; até 4 campos secundários/auxiliares. |
coupon | coupon | Layout frontal com imagem de faixa; campos auxiliares redirecionados para secundários. |
eventTicket | eventTicket | Suporta textura de fundo, imagem de faixa e blocos de recinto iOS 18. |
boardingPass | boardingPass | Analisa transitType (PKTransitTypeAir, PKTransitTypeTrain, etc.) e campos principais de partida/chegada. |
generic | generic | Layout padrão multiusos com miniatura opcional. |
Importar através do Painel (Passo a passo)
-
1
Aceda a Modelos no Painel da Passinstance e clique em + Novo Modelo.
-
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.
-
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.
-
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.
-
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)
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)
{
"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 / Erro | Causa raiz | Resolução |
|---|---|---|
Unsupported file format | A 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 asset | O 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 exceeded | Um 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 notice | O .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.
