API Apple Wallet PassKit

A API PassKit Designer permite que você crie, atualize, baixe e gerencie passes do Apple Wallet programaticamente. Ela suporta as mesmas operações que o construtor de passes no Painel de Controle realiza. Use-a para emitir cartões de fidelidade, cupons, ingressos para eventos, cartões de embarque e cartões de loja, e para enviar atualizações ao vivo para passes já instalados nos dispositivos de seus usuários.

Pré-requisito: certificado PassKit

Antes de poder criar passes para um aplicativo, um certificado de assinatura iOS PassKit deve ser configurado para esse aplicativo. O certificado é gerenciado no Painel de Controle da Pushwoosh. Sem ele, as solicitações create e update falham. Consulte Configuração de passe do Apple Wallet para iOS.

URL Base

https://apple-passkit.svc-nue.pushwoosh.com

Todos os endpoints são servidos por HTTPS. As solicitações e respostas usam application/json, a menos que seja indicado o contrário.

Autenticação

Cada solicitação deve incluir um cabeçalho Authorization com seu token de acesso à API da Pushwoosh:

Authorization: Token <api-token>

A conta proprietária do token deve ser a proprietária do aplicativo referenciado por applicationCode. Uma solicitação para um aplicativo que pertence a outra conta retorna 403 Forbidden.

Convenções

• Nomenclatura de campos: Os campos JSON usam lowerCamelCase (por exemplo, passTypeIdentifier, serialNumber, backgroundColor).
• Campos não preenchidos: as respostas incluem todos os campos, mesmo quando vazios ou com valor zero.
• Dados binários: campos bytes como pkpassData e data de imagem são strings codificadas em Base64 em JSON.
• Números de série: o serialNumber é sempre atribuído pelo servidor quando um passe é criado. Qualquer valor que você enviar na criação é ignorado; ele identifica o passe para todas as operações posteriores.

Respostas de erro

A API mapeia códigos de status internos para códigos de status HTTP:

Status HTTP	Significado
400 Bad Request	Argumento inválido — um campo obrigatório está ausente ou malformado.
401 Unauthorized	Cabeçalho Authorization ausente ou inválido.
403 Forbidden	O aplicativo não pertence à conta do chamador.
404 Not Found	O passe, modelo ou aplicativo não foi encontrado.
503 Service Unavailable	O serviço está em sua capacidade máxima ou temporariamente indisponível.

Endpoints

Método	Caminho	Descrição
POST	/api/pass/validate	Validar uma configuração de passe
POST	/api/pass/create	Criar um novo .pkpass
POST	/api/pass/update/{serialNumber}	Atualizar um passe existente e notificar os dispositivos
GET	/api/passes	Listar todos os passes de um aplicativo
GET	/api/pass/{applicationCode}/{serialNumber}	Obter um único passe
GET	/api/pass/{applicationCode}/{serialNumber}/download	Baixar o .pkpass de um passe existente
DELETE	/api/pass/{applicationCode}/{serialNumber}	Excluir um passe
GET	/api/pass/{serialNumber}/registrations	Listar dispositivos registrados para um passe
GET	/api/config	Obter a configuração PassKit do aplicativo
GET	/api/templates	Listar modelos de passe disponíveis
GET	/api/templates/{filename}	Obter um único modelo

Criar um passe

Gera, assina e armazena um novo passe, e então retorna seu número de série atribuído pelo servidor.

POST /api/pass/create

Dica

Para obter o próprio arquivo .pkpass, chame Baixar um passe (ou construa um link de instalação / código QR) com o número de série retornado.

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
pass	objeto	Sim	O objeto de passe que descreve o passe.
images	array de objetos	Não	Imagens do passe (ícone, logo, etc.). icon e logo são necessários para um passe válido.
userId	string	Sim	O User ID da Pushwoosh para o qual o passe é emitido.
applicationCode	string	Sim	O código do aplicativo Pushwoosh.

Nota

Na criação, se teamIdentifier, passTypeIdentifier ou organizationName forem omitidos, eles assumirão os valores do certificado configurado do aplicativo. formatVersion assume o padrão 1. O serialNumber é atribuído pelo servidor.

Exemplo de solicitação

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

Resposta

Campo	Tipo	Descrição
serialNumber	string	Identidade única atribuída pelo servidor do passe criado. Use-a para buscar o passe (Obter um passe) ou baixar o .pkpass (Baixar um passe).
message	string	Mensagem de resultado.

Exemplo de resposta

{
  "serialNumber": "a1b2c3d4-1234-5678-9abc-def012345678",
  "message": "Pass created successfully"
}

Validar um passe

Verifica uma configuração de passe em relação às especificações da Apple sem criar um arquivo. Útil antes de chamar a criação.

POST /api/pass/validate

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
pass	objeto	Sim	O objeto de passe a ser validado.

Resposta

Campo	Tipo	Descrição
valid	boolean	Se o passe passa na validação.
errors	array de strings	Problemas bloqueadores que devem ser corrigidos.
warnings	array de strings	Avisos não bloqueadores.

Atualizar um passe

Regenera o passe com novo conteúdo, o assina novamente, incrementa sua tag de atualização e envia uma notificação push silenciosa para cada dispositivo que registrou o passe. O iOS então busca e instala a versão atualizada em segundo plano.

POST /api/pass/update/{serialNumber}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
serialNumber	string	O número de série retornado quando o passe foi criado.

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
updates	objeto	Sim	O objeto de passe completo com o novo conteúdo.
applicationCode	string	Sim	O código do aplicativo Pushwoosh.

O serialNumber (do caminho) e o token de autenticação do passe são preservados pelo servidor, independentemente do que você enviar.

Resposta

Campo	Tipo	Descrição
success	boolean	Se a atualização foi bem-sucedida.
updateTag	integer	Nova tag de atualização (um timestamp Unix).
message	string	Mensagem de resultado.

Listar passes

Retorna uma lista paginada e ordenada dos passes armazenados para um aplicativo.

GET /api/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
applicationCode	string	Sim	O código do aplicativo Pushwoosh.
orderBy	string	Não	Campo de ordenação: UPDATED (padrão) ou CREATED.
orderDirection	string	Não	Direção da ordenação: DESC (padrão, mais recentes primeiro) ou ASC.
page	integer	Não	Índice da página baseado em zero. O padrão é 0.
perPage	integer	Não	Tamanho da página. 0 ou omitido usa o padrão do servidor.

Resposta

Campo	Tipo	Descrição
passes	array de objetos	A página atual de registros de passe.
page	integer	O índice da página retornada.
perPage	integer	O tamanho da página usado para esta resposta.
total	integer	Número total de passes para o aplicativo em todas as páginas.

Exemplo de resposta

{
  "passes": [ /* pass records */ ],
  "page": 0,
  "perPage": 20,
  "total": 137
}

Obter um passe

Retorna um único passe armazenado, incluindo seu objeto de passe completo.

GET /api/pass/{applicationCode}/{serialNumber}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
applicationCode	string	O código do aplicativo Pushwoosh.
serialNumber	string	O número de série do passe.

Resposta

Retorna { "pass": { ... } }, um único registro de passe.

Baixar um passe

Retorna o arquivo .pkpass armazenado de um passe existente.

GET /api/pass/{applicationCode}/{serialNumber}/download

Resposta

Campo	Tipo	Descrição
pkpassData	string (Base64)	O arquivo .pkpass.
filename	string	Nome de arquivo sugerido.

Excluir um passe

Remove um registro de passe e seu arquivo .pkpass armazenado.

DELETE /api/pass/{applicationCode}/{serialNumber}

Resposta

Campo	Tipo	Descrição
success	boolean	Se o passe foi excluído.
message	string	Mensagem de resultado.

Obter registros de passe

Lista os dispositivos que adicionaram o passe e estão registrados para atualizações.

GET /api/pass/{serialNumber}/registrations?applicationCode=XXXXX-XXXXX

Resposta

Retorna { "registrations": [ ... ] }, onde cada item tem:

Campo	Tipo	Descrição
deviceLibraryIdentifier	string	Identificador da biblioteca de dispositivos da Apple.
pushToken	string	O token de push do passe para o dispositivo.

Obter configuração

Retorna a configuração PassKit resolvida para um aplicativo a partir de seu certificado.

GET /api/config?applicationCode=XXXXX-XXXXX

Resposta

Campo	Tipo	Descrição
teamIdentifier	string	ID da Equipe Apple do certificado.
passTypeIdentifier	string	ID do Tipo de Passe do certificado.
organizationName	string	Nome da organização do certificado.
hasCertificate	boolean	Se um certificado está configurado.
webServiceUrl	string	URL base do serviço web do passe. Os clientes constroem um link de instalação anexando /v1/passes/{passType}/{serial}?token={authToken}.

Modelos

Liste os modelos de passe disponíveis ou busque um como um objeto de passe que você pode usar como ponto de partida.

GET /api/templates — retorna { "templates": [ { "filename", "name", "description", "style" } ] }.

GET /api/templates/{filename} — retorna { "template": { ...pass object... } }.

Compartilhar um passe como um código QR

Para permitir que os usuários adicionem um passe escaneando um código QR (ou tocando em um link), codifique a URL de instalação do passe em um código QR. A URL é construída a partir de valores que você já recebe da API:

{webServiceUrl}/v1/passes/{passTypeIdentifier}/{serialNumber}?token={authenticationToken}

Parte da URL	Onde obter
webServiceUrl	GET /api/config → webServiceUrl
passTypeIdentifier	registro de passe → pass.passTypeIdentifier (de listar/obter)
serialNumber	registro de passe → serialNumber
authenticationToken	registro de passe → pass.authenticationToken

Exemplo:

https://apple-passkit.svc-nue.pushwoosh.com/v1/passes/pass.com.acme.loyalty/a1b2c3d4-1234-5678-9abc-def012345678?token=AbC123XyZ

Renderize esta URL como um código QR com qualquer biblioteca de QR. Quando um usuário a escaneia, seu dispositivo abre o link, baixa o .pkpass mais recente e o Wallet solicita que ele o adicione — o que também registra o dispositivo para atualizações.

Referência de objetos

Objeto de passe

Campo	Tipo	Descrição
formatVersion	integer	Versão do formato do passe. O padrão é 1.
passTypeIdentifier	string	ID do Tipo de Passe da Apple (pass.com.yourcompany.passtype). O padrão vem do certificado.
serialNumber	string	Atribuído pelo servidor na criação; identifica o passe.
teamIdentifier	string	ID da Equipe Apple. O padrão vem do certificado.
organizationName	string	Organização exibida no passe. O padrão vem do certificado.
description	string	Descrição legível por humanos (exigida pela Apple).
boardingPass / coupon / eventTicket / storeCard / generic	objeto	O estilo do passe. Exatamente um deve ser definido. Consulte grupos de campos.
backgroundColor	string	Cor de fundo, rgb(r, g, b).
foregroundColor	string	Cor do primeiro plano (texto), rgb(r, g, b).
labelColor	string	Cor do rótulo do campo, rgb(r, g, b).
logoText	string	Texto exibido ao lado do logo.
suppressStripShine	boolean	Desativa o efeito de brilho na imagem da faixa.
barcodes	array	Códigos de barras exibidos no passe.
locations	array	Localizações que tornam o passe relevante.
beacons	array	Beacons que tornam o passe relevante.
relevantDate	string	Data ISO 8601 quando o passe se torna relevante.
maxDistance	integer	Distância máxima (metros) para relevância de localização.
expirationDate	string	Data de expiração ISO 8601.
voided	boolean	Marca o passe como nulo.
groupingIdentifier	string	Agrupa passes relacionados (ingressos de eventos/cartões de embarque).
userInfo	objeto (mapa)	Dados de aplicativo de chave/valor arbitrários.

Nota

authenticationToken e webServiceUrl são gerenciados pelo serviço e não precisam ser definidos pelos clientes da API.

Objeto de grupo de campos

Cada estilo de passe (boardingPass, coupon, eventTicket, storeCard, generic) agrupa campos em áreas:

Campo	Tipo	Descrição
headerFields	array	Exibido no cabeçalho do passe (visível quando empilhado no Wallet).
primaryFields	array	Campos mais proeminentes.
secondaryFields	array	Abaixo dos campos primários.
auxiliaryFields	array	Campos adicionais abaixo dos secundários.
backFields	array	Exibido no verso do passe.

boardingPass adicionalmente tem transitType (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat ou PKTransitTypeGeneric).

Objeto de campo

Campo	Tipo	Descrição
key	string	Chave de campo única dentro do passe.
label	string	Rótulo do campo.
value	string	Valor do campo (texto ou número como string).
changeMessage	string	Mensagem exibida quando o valor muda (use %@ como o marcador de posição).
textAlignment	string	Valor PKTextAlignment.
dateStyle / timeStyle	string	PKDateStyle para formatação de data/hora.
isRelative	boolean	Mostra a data relativa a agora.
numberStyle	string	PKNumberStyle para formatação de número.
currencyCode	string	Código de moeda ISO 4217.
dataDetectorTypes	array de strings	Detectores de dados a serem aplicados ao valor.

Objeto de código de barras

Campo	Tipo	Descrição
format	string	PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec ou PKBarcodeFormatCode128.
message	string	Dados codificados no código de barras.
messageEncoding	string	Codificação de texto, tipicamente iso-8859-1.
altText	string	Texto exibido abaixo do código de barras.

Objeto de localização

Campo	Tipo	Descrição
latitude	number	Latitude.
longitude	number	Longitude.
altitude	number	Altitude em metros.
relevantText	string	Texto exibido na tela de bloqueio perto desta localização.

Objeto de beacon

Campo	Tipo	Descrição
proximityUuid	string	UUID de proximidade iBeacon.
major	integer	Valor principal.
minor	integer	Valor secundário.
relevantText	string	Texto exibido na tela de bloqueio perto deste beacon.

Objeto de imagem do passe

Campo	Tipo	Descrição
imageType	string	Um de icon, logo, strip, background, footer, thumbnail. icon e logo são obrigatórios.
data	string (Base64)	Bytes da imagem.
contentType	string	Tipo MIME, por exemplo, image/png.

Objeto de registro de passe

Retornado pelos endpoints de listar/obter.

Campo	Tipo	Descrição
serialNumber	string	Número de série do passe.
passTypeIdentifier	string	ID do Tipo de Passe.
organizationName	string	Nome da organização.
description	string	Descrição do passe.
createdAt	string	Timestamp de criação (RFC 3339).
updatedAt	string	Timestamp da última atualização (RFC 3339).
updateTag	integer	Tag de atualização atual.
pass	objeto	O objeto de passe completo, para edição.
userId	string	User ID da Pushwoosh para o qual o passe foi emitido.