Skip to content
Guia da Central de Ajuda · Integrações WalletFase de integração 4
3 min de leituraVerificado 2026-11-16

Apple Wallet

Geração de pacotes .pkpass, assinatura PKCS#7, registo iOS/watchOS e chamadas Web Service PassKit.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface
Elementos-chave da interface

Pré-visualização em tempo real Dual-Wallet (Zoom)

Alterne entre Apple e Google no painel de pré-visualização para confirmar as artes, a formatação do saldo, a legibilidade do código QR e o alinhamento dos campos.

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.

Pré-visualização ao vivo de passe Apple Wallet vs Google Wallet
Pré-visualização ao vivo de passe Apple Wallet vs Google Wallet
FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
EMPACOTAMENTO .PKPASS APPLE WALLET E WEB SERVICE
ETAPA 01 CONSTRUTOR DE ARQUIVOS PKPASS (Apple Wallet Packager)
1
Serializa pass.json (formatVersion: 1, cores rgb(r,g,b), campos, NFC)
2
Hidrata Ativos Retina (icon.png, logo.png, strip.png @1x / @2x / @3x)
3
Compila Pacotes de Idiomas (<lang>.lproj/pass.strings em UTF-8)
4
Calcula Dicionário Checksum SHA-1Escreve manifest.json
5
Gera signature PKCS#7 Destacada (Cert. Pass Type + Apple WWDR G4/G6)
6
Comprime Arquivo ZIPTransmite Content-Type: application/vnd.apple.pkpass
ETAPA 02 PROTOCOLO APPLE WALLET WEB SERVICE (/v1)
Registar Dispos.: POST/v1/devices/:deviceLibId/registrations/:typeId/:sn
Obter Lista Atual.:GET/v1/devices/:deviceLibId/registrations/:typeId
Descarregar Pacote:GET/v1/passes/:passTypeId/:serialNumber
Remover Registo: DELETE/v1/devices/:deviceLibId/registrations/:typeId/:sn
Log Erros Cliente: POST/v1/log

Estrutura interna de um pacote .pkpass

Um pacote Apple Wallet .pkpass é um pacote ZIP padrão contendo cinco camadas estruturais principais:

Ficheiro / DiretórioFormato e codificaçãoFunção na Apple Wallet
pass.jsonJSON UTF-8Define 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.stringsTabela de Strings UTF-8Traduções localizadas chave-valor (ex.: de.lproj/pass.strings, fr.lproj/pass.strings) correspondidas com o idioma do sistema do iPhone.
manifest.jsonJSON UTF-8Dicioná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.
signatureDER 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 strings rgb(r, g, b). O apple-pass-field.serializer.ts da Passinstance converte automaticamente valores hexadecimais para rgb(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

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étodoCaminho do endpointEstados HTTPFinalidade
POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber201 Created, 200 OK, 401 UnauthorizedRegista o pushToken do iPhone ou Apple Watch para atualizações APNs e assinala o passe como instalado.
GET/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier200 OK, 204 No ContentDevolve { serialNumbers: [...], lastUpdated: "<tag>" } dos passes modificados desde ?passesUpdatedSince=.
GET/v1/passes/:passTypeIdentifier/:serialNumber200 OK, 304 Not Modified, 401 UnauthorizedGera 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/:serialNumber200 OK, 401 UnauthorizedRemove o registo do dispositivo quando o titular apaga o passe da Apple Wallet.
POST/v1/log200 OKRecebe 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.

Documentação de produto e API relacionada

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.