Visão geral: Como funciona a integração Apple Wallet
A Passinstance gera pacotes nativos Apple Wallet .pkpass (Apple Wallet Packager) em conformidade com a especificação de pacotes PassKit da Apple para iOS e watchOS. Cada passe é montado dinamicamente como um pacote ZIP assinado criptograficamente e servido com o tipo MIME application/vnd.apple.pkpass.

Estrutura interna de um pacote .pkpass
Um pacote Apple Wallet .pkpass é um pacote ZIP padrão contendo cinco camadas estruturais principais:
| Ficheiro / Diretório | Formato e codificação | Função na Apple Wallet |
|---|---|---|
pass.json | JSON UTF-8 | Define o estilo do passe (storeCard, coupon, eventTicket, boardingPass, generic), passTypeIdentifier, teamIdentifier, serialNumber, authenticationToken, webServiceURL, campos, códigos de barras, localizações e dicionário nfc. |
Ativos visuais (.png) | PNG (@1x, @2x, @3x) | Até 13 slots de imagem do modelo hidratados nos nomes de ficheiro Apple PassKit (icon.png, logo.png, strip.png, thumbnail.png, background.png, footer.png, artwork.png, venueMap.png) nas várias resoluções retina. |
<lang>.lproj/pass.strings | Tabela de Strings UTF-8 | Traduções localizadas chave-valor (ex.: de.lproj/pass.strings, fr.lproj/pass.strings) correspondidas com o idioma do sistema do iPhone. |
manifest.json | JSON UTF-8 | Dicionário plano que mapeia cada caminho relativo de ficheiro no pacote (excluindo manifest.json e signature) para o respetivo hash hexadecimal SHA-1 de 40 carateres. |
signature | DER Binário (PKCS#7) | Assinatura criptográfica PKCS#7 destacada de manifest.json, assinada pela sua chave privada Apple Pass Type ID e encadeada ao certificado intermédio Apple WWDR G4/G6. |
Importante: A Apple Wallet exige estritamente que os valores de cor em
pass.json(backgroundColor,foregroundColor,labelColor) sejam serializados como stringsrgb(r, g, b). Oapple-pass-field.serializer.tsda Passinstance converte automaticamente valores hexadecimais parargb(r, g, b)e remove canais alfa para que o iOS nunca rejeite um pacote durante a verificação de assinatura e esquema.
Exemplo de estrutura de payload pass.json
{
"formatVersion": 1,
"passTypeIdentifier": "pass.com.yourbrand.loyalty",
"serialNumber": "PI-8849-2026-X9",
"teamIdentifier": "9A8B7C6D5E",
"organizationName": "Phenix Roasters",
"description": "Phenix VIP Rewards Card",
"webServiceURL": "https://api.passinstance.com",
"authenticationToken": "b7f9e2c1a4d80931f6e5c2b8a1049d7e",
"foregroundColor": "rgb(255, 255, 255)",
"backgroundColor": "rgb(18, 24, 38)",
"labelColor": "rgb(148, 163, 184)",
"storeCard": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "Gold"
}
],
"primaryFields": [
{
"key": "points",
"label": "POINTS BALANCE",
"value": 1450,
"changeMessage": "Your points balance updated to %@"
}
],
"backFields": [
{
"key": "support_link",
"label": "MEMBER PORTAL",
"value": "Visit https://yourbrand.com/member",
"attributedValue": "<a href=\"https://yourbrand.com/member\">Open Member Portal</a>"
}
]
},
"barcodes": [
{
"format": "PKBarcodeFormatQR",
"message": "PI-8849-2026-X9",
"messageEncoding": "iso-8859-1",
"altText": "PI-8849-2026-X9"
}
]
}
Endpoints do Apple Wallet Web Service (/v1)
Cada passe ativo contém webServiceURL e um authenticationToken com pelo menos 16 carateres. Os dispositivos iOS e watchOS comunicam diretamente com os endpoints /v1 da Passinstance usando o cabeçalho HTTP Authorization: ApplePass <authenticationToken>:
| Método | Caminho do endpoint | Estados HTTP | Finalidade |
|---|---|---|---|
| POST | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 201 Created, 200 OK, 401 Unauthorized | Regista o pushToken do iPhone ou Apple Watch para atualizações APNs e assinala o passe como instalado. |
| GET | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier | 200 OK, 204 No Content | Devolve { serialNumbers: [...], lastUpdated: "<tag>" } dos passes modificados desde ?passesUpdatedSince=. |
| GET | /v1/passes/:passTypeIdentifier/:serialNumber | 200 OK, 304 Not Modified, 401 Unauthorized | Gera e transmite o pacote .pkpass assinado mais recente quando acordado por um push APNs ou atualização manual (pull-to-refresh). |
| DELETE | /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber | 200 OK, 401 Unauthorized | Remove o registo do dispositivo quando o titular apaga o passe da Apple Wallet. |
| POST | /v1/log | 200 OK | Recebe matrizes de diagnóstico { "logs": [...] } de dispositivos iOS caso um .pkpass falhe a validação no cliente. |
Explore especificações técnicas adicionais em Plataforma Apple Wallet, Certificados Apple Wallet e Protocolo sem contacto Apple VAS.
