O que é um arquivo pkpass? Como funcionam os passes do Apple Wallet

Você pode encontrar um arquivo terminado em .pkpass anexado a um e-mail de reserva, ou um site pode baixar um quando você toca em “Adicionar à Carteira da Apple”. Então, o que é um arquivo pkpass? É o formato que o Apple Wallet usa para todo cartão de embarque, ingresso, cartão de fidelidade e cupom que você adiciona. Este artigo explica o que tem dentro dele, como abri-lo no iPhone, por que não dá para editá-lo e quais são as suas opções quando o seu ingresso só vem em PDF.

O que é, de fato, um arquivo .pkpass

Um arquivo .pkpass é um passe completo do Wallet em um único arquivo. O nome vem de PassKit, o framework da Apple para passes. Por dentro, é um arquivo ZIP com outra extensão. Os sites costumam enviá-lo com o tipo application/vnd.apple.pkpass, para que o Safari saiba que deve entregá-lo ao Wallet em vez de salvá-lo como download.

Um passe não é uma imagem do seu ingresso. São dados estruturados: campos com rótulos (como “Portão”, “Assento” ou “Número de sócio”), o valor de um código de barras, cores e algumas imagens. O Wallet usa esses dados para desenhar o passe. É por isso que os passes têm uma aparência limpa e uniforme, e por isso o Wallet consegue fazer coisas que um PDF não faz, como mostrar o passe na Tela Bloqueada perto do horário de partida.

O que tem dentro de um arquivo pkpass

Se você copiar um arquivo .pkpass para um computador, renomeá-lo para .zip e abri-lo, normalmente vai encontrar:

• pass.json: o passe em si. Guarda o estilo do passe, os rótulos e valores dos campos, a mensagem e o formato do código de barras, as cores e extras opcionais, como uma data ou um local relevante.
• Imagens: um ícone, geralmente um logotipo, e às vezes uma faixa, miniatura ou imagem de fundo. Muitas vezes vêm em mais de uma resolução para telas diferentes.
• manifest.json: uma lista de todos os arquivos do passe, cada um com um checksum (uma espécie de impressão digital curta do conteúdo).
• signature: uma assinatura criptográfica do manifesto, feita com um certificado que a Apple emite para quem criou o passe.

Olhar por dentro não faz mal nenhum, mas não tente remontar o arquivo depois de alterá-lo. A próxima seção explica por que isso não funciona.

Por que todo passe precisa ser assinado

O Wallet só aceita um passe assinado com um certificado válido da Apple. A assinatura cobre o manifesto, e o manifesto cobre todos os arquivos. Se um único caractere mudar no pass.json, os checksums deixam de bater, e o Wallet rejeita o passe.

Isso protege você e o emissor:

• Você pode confiar que o passe não foi alterado desde que o criador o assinou.
• Companhias aéreas e locais de eventos sabem que os passes não podem ser editados às escondidas depois de enviados.
• Todo passe pode ser rastreado até um titular de certificado registrado na Apple.

A chave de assinatura é secreta. Ela precisa ficar em um servidor controlado por quem cria o passe. Não pode ser embutida em um app, porque qualquer pessoa conseguiria extraí-la. Por isso, todo app que cria passes do Wallet, incluindo apps de emissores e apps criadores de passes, precisa de um servidor para assiná-los.

Existe uma exceção mais recente para passes que você mesmo cria. No iOS 27, a Apple diz que você pode editar certos campos e mudar a aparência de um passe criado com o recurso Criar Tíquete do próprio Wallet. Ingressos assinados por uma companhia aérea ou por um organizador continuam sem poder ser editados.

Como abrir um arquivo .pkpass no iPhone

Normalmente você não precisa fazer nada de especial. No Mail, no Mensagens, no Safari e na maioria dos apps, tocar em um arquivo .pkpass abre a prévia do Wallet.

1. Toque no anexo, no link ou no botão “Adicionar à Carteira da Apple”.
2. Confira a prévia: nome, data, assento, voo ou número de sócio.
3. Toque em Adicionar no canto superior.
4. Abra o app Carteira para encontrar o passe. Se você tiver um Apple Watch emparelhado, a Apple diz que o passe também é adicionado automaticamente ao Wallet dele.

Se você salvou o arquivo no app Arquivos, tocar nele ali deve mostrar a mesma prévia. Se nada acontecer, ou se aparecer um erro, baixe o arquivo de novo a partir do e-mail ou do site original. Se continuar falhando, peça um novo passe ao emissor.

Estilos de passe e o que eles mudam

Todo passe tem um estilo, definido no pass.json, que determina o layout e parte do que ele faz:

• Cartão de embarque: voos, trens, ônibus e balsas, com origem, destino e um ícone do meio de transporte.
• Ingresso: shows, jogos, teatro, conferências.
• Cartão de loja: cartões de fidelidade, da academia, de biblioteca e de sócio.
• Cupom: ofertas e descontos.
• Genérico: qualquer coisa que não se encaixe nos outros.

Um passe também pode incluir uma data ou um local relevante. Nesse caso, o Wallet pode sugerir o passe na Tela Bloqueada perto daquele horário ou lugar. O exemplo da Apple é um cartão de embarque que aparece perto do horário de partida.

Códigos de barras dentro de um passe

O código de barras não é guardado como imagem. O pass.json guarda a mensagem e o formato do código, e o próprio Wallet o desenha. Até o iOS 26, o Wallet consegue mostrar quatro formatos: QR, PDF417, Aztec e Code 128. A partir do iOS 27, a documentação para desenvolvedores da Apple acrescenta Code 39, Codabar, EAN-13 e ITF. O UPC-A não está na lista da Apple. Um passe também pode indicar um código de barras alternativo, para que iPhones mais antigos mostrem um formato compatível.

Isso importa para passes feitos em casa. Quando o código de barras de um cartão de fidelidade está em um formato que o Wallet não consegue mostrar, um app criador de passes pode recodificar o mesmo número em outro formato. Muitos leitores ainda o leem, mas alguns caixas só aceitam o formato original. Teste um passe assim antes de depender dele.

Passes estáticos e passes que se atualizam

Um passe de uma companhia aérea ou de um organizador pode incluir o endereço de um serviço web. Com ele, o emissor pode enviar uma nova versão do passe quando algo muda, como portão, assento ou horário. O Wallet substitui o passe antigo e pode mostrar uma notificação.

Passes sem esse vínculo são estáticos: continuam exatamente como foram criados. A maioria dos passes feitos em casa é estática, então não mostra atrasos, mudanças de portão ou cancelamentos. Confira sempre essas informações com a companhia aérea, a empresa de trem ou o organizador.

Alguns ingressos nem chegam a existir como arquivo pkpass. Um código de barras que gira ou se anima a cada poucos segundos dentro do app de um organizador foi feito justamente para não poder ser copiado. Uma captura de tela dele, ou um passe criado a partir dela, não vai funcionar no leitor. Use o app do organizador para esses ingressos e leve um documento se as regras do ingresso exigirem.

Quando não existe nenhum .pkpass

Muitos ingressos e cartões nunca chegam como passe. Você pode receber um PDF, um código de barras em um e-mail ou um cartão de plástico. Suas opções, começando pelas oficiais:

1. Procure a opção do próprio emissor. A Apple recomenda procurar “Adicionar à Carteira da Apple” em um app, e-mail, mensagem ou página web. Se não houver, a Apple sugere perguntar ao emissor se ele é compatível com o Wallet. Apps de companhias aéreas e de organizadores costumam adicionar o passe para você.
2. Use o Criar Tíquete do Wallet (iOS 27). No Wallet, toque em Adicionar Cartão → Criar Tíquete. Depois, crie o passe manualmente a partir de um modelo padrão, de sócio ou de evento, ou crie-o a partir de uma foto ou captura de tela de um código de barras. O método com foto exige um iPhone 15 Pro ou posterior com Apple Intelligence. A Apple descreve esse recurso como útil para coisas como cartões de biblioteca e da academia que têm código de barras, mas não têm passe digital.
3. Use um app criador de passes. Esses apps leem o seu ingresso e criam um .pkpass assinado para você. O Kardin é um exemplo. Ele serve para um ingresso que só existe em PDF, ou para um iPhone sem Apple Intelligence. Você compartilha o PDF ou uma foto com o Kardin pelo Mail, pelo Arquivos ou pelo Fotos, ou escaneia o código de barras com a câmera. O Kardin lê a primeira página de um PDF no seu iPhone e decodifica o código de barras no formato original quando ele é QR, PDF417, Aztec ou Code 128. Em seguida, preenche os campos de um passe de voo, trem, ônibus, evento ou cartão. Você confere e edita todos os campos em uma tela de revisão antes de tocar em “Adicionar à Carteira da Apple”. A extração pode deixar escapar detalhes quando o texto está bagunçado ou pequeno, então revise a tela com atenção.

Para o passo a passo completo, veja como adicionar um ingresso em PDF ao Apple Wallet. Se você está na porta do evento agora, veja o que fazer quando o seu ingresso em PDF não tem botão do Apple Wallet.

Quanto à privacidade: como todo passe precisa ser assinado em um servidor, alguns dados precisam sair do seu telefone. Com o Kardin, seus arquivos e fotos são lidos no iPhone e nunca são enviados. Só o conteúdo do passe vai para o servidor do Kardin para ser assinado: os campos, o valor e o formato do código de barras, as cores e a data. O servidor devolve o passe assinado na hora e não o armazena. A página de segurança tem os detalhes.

Um arquivo pkpass é seguro?

Um arquivo .pkpass guarda apenas dados e imagens. Ele não consegue executar código no seu telefone, e o Wallet sempre mostra uma prévia antes de adicionar qualquer coisa. Ainda assim, pense no que o passe contém:

• Os passes no Wallet podem ser abertos sem Face ID nem código, e são sincronizados com seus outros dispositivos pelo iCloud.
• Por isso, nunca coloque números de cartão bancário, PINs, senhas, códigos de segurança do banco ou dados de documentos oficiais em um passe criado por um app de terceiros.
• Apague os passes de que você não precisa mais. No Wallet, toque no passe, depois no botão Mais, e remova-o.

Resumindo

• Um arquivo .pkpass é um pacote ZIP com os dados do passe (pass.json), imagens, uma lista de checksums e uma assinatura emitida pela Apple.
• Toque nele no Mail, no Mensagens, no Safari ou no Arquivos, confira a prévia e toque em Adicionar.
• Qualquer alteração quebra a assinatura, então corrigir um passe significa conseguir ou criar um novo.
• Passes de emissores podem se atualizar sozinhos. Passes feitos em casa costumam ser estáticos, e códigos de barras rotativos não podem virar passes.
• Não tem passe? Procure primeiro o botão do emissor, depois o Criar Tíquete do Wallet no iOS 27 e, por fim, um app criador de passes como o Kardin para PDFs e fotos.