.pkpass é o formato de arquivo que a Apple Wallet usa para passes: cartões de embarque, cartões de fidelidade, cupons, ingressos de eventos. Não é um app e não é uma imagem. É um arquivo ZIP assinado com uma estrutura específica, e assim que você entende o que tem dentro dele, a maioria das dúvidas sobre passes da Wallet se resolve sozinha. No Brasil, esse formato aparece cada vez mais por trás dos cartões de fidelidade de apps como iFood, Mercado Livre e redes de varejo — qualquer marca que queira um cartão que o cliente adiciona no celular e some do bolso menos vezes.
Dentro de um arquivo .pkpass: o que realmente tem lá
Renomeie um .pkpass para .zip, descompacte, e você vai encontrar um punhado pequeno de arquivos. Quatro deles importam:
- pass.json — o pass em si. Campos, cores, código de barras, o texto que aparece na frente e no verso. É aqui que um cartão de embarque vira um cartão de embarque e um cartão de café vira um cartão de café.
- manifest.json — uma lista de todos os arquivos do pacote com um hash SHA-1 de cada um. É a folha de conferência que prova que nada foi alterado.
- signature — uma assinatura criptográfica do manifest, gerada com um certificado emitido pela Apple. É essa parte que faz a Wallet confiar no pass. Sem assinatura válida, não tem pass.
- Imagens — icon.png, logo.png e qualquer arte de faixa ou miniatura, geralmente em resoluções 1x, 2x e 3x para telas diferentes.
Isso é o pacote inteiro. O design mora no pass.json, as imagens ficam do lado, e o manifest mais a signature existem para provar que o conjunto é autêntico e não foi mexido. Um recipiente propositalmente simples e verificável.
Você precisa de uma conta de desenvolvedor Apple para criar um
Resposta curta: sim para criar, não para receber.
O arquivo de assinatura é o que obriga a conta. Ele precisa ser gerado com um certificado Pass Type ID, e você só consegue um desses através de uma conta de desenvolvedor Apple, que custa US$ 99 por ano. Sem esse certificado, dá para montar todo o resto do arquivo certinho e mesmo assim a Wallet vai recusar o pass, porque não dá pra verificar quem o emitiu.
Seus clientes não precisam saber nada disso. A conta de desenvolvedor é uma exigência para quem emite, a empresa que cria e assina os passes, não para a pessoa que adiciona um ao celular dela. Ela só toca em Adicionar. O trabalho com o certificado acontece uma vez só, do seu lado, bem antes de um pass chegar a alguém.
.pkpass vs. um wallet pass genérico
As pessoas falam “wallet pass” de forma solta, então vale deixar claro. Um .pkpass é especificamente o formato da Apple. O Google Wallet usa um mecanismo totalmente diferente, baseado em objetos de pass definidos pela API dele, e não em um arquivo assinado para baixar.
Ou seja, um .pkpass é um tipo de wallet pass, o da Apple. Se você está construindo para as duas plataformas — e no Brasil, com Android dominando mais de 85% do mercado, isso quase sempre é obrigatório —, você está gerando um .pkpass da Apple e um objeto do Google Wallet a partir dos mesmos dados, não um único arquivo que funciona em tudo. Para o cliente é a mesma ideia; por trás, são dois caminhos técnicos diferentes.
Como abrir ou testar um arquivo .pkpass
Algumas formas práticas de inspecionar um antes de colocar no ar:
- Num iPhone ou Mac, dois toques ou abrir o arquivo já mostra a prévia da Wallet, exatamente como o cliente veria.
- Para ver o que tem por dentro, renomeie o arquivo para .zip, descompacte e abra o pass.json em qualquer editor de texto. É o jeito mais rápido de conferir campos, cores e valores de código de barras.
- Para validar a assinatura, a ferramenta signpass da Apple e vários validadores de pass online dizem se o manifest e o certificado estão corretos. Um pass que abre bem no seu próprio aparelho ainda pode falhar para outras pessoas se a assinatura estiver errada.
Pulando o formato do arquivo por completo
A maioria de quem precisa de passes de Wallet nunca quer encostar no pass.json, gerenciar um certificado de assinatura ou depurar um hash de manifest. O que essas empresas querem é um cartão que o cliente consiga adicionar, que se atualiza quando os dados mudam. O formato é meio, não o objetivo.
Você não precisa mexer no formato .pkpass. A Pushwoosh cuida da assinatura e do empacotamento; você só cuida do design do cartão. Isso vale tanto para um cartão de fidelidade de e-commerce quanto para um pass de evento — os dados dos seus clientes passam por uma infraestrutura certificada SOC 2 Type I e ISO 27001:2022, em conformidade com GDPR e HIPAA, com data centers na UE e nos EUA. Veja mais em Wallet Passes.
