API do Google Wallet

A API do Google Wallet permite criar, atualizar, listar e gerenciar passes do Google 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, ofertas, cartões-presente, ingressos para eventos, cartões de embarque de voos, bilhetes de transporte e passes genéricos, e para enviar atualizações em tempo real para passes já salvos nos dispositivos dos seus usuários.

Pré-requisito: configuração do Google Wallet

Antes de poder criar passes para um aplicativo, um ID de Emissor do Google Wallet e uma chave de conta de serviço devem ser configurados para esse aplicativo no Painel de Controle da Pushwoosh. Sem eles, as solicitações de create e update falham. Consulte Configuração de passes do Google Wallet para Android.

URL Base

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

Todos os endpoints são servidos via 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 da API 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, serialNumber, hexBackgroundColor, logoUrl).
• Campos não preenchidos: as respostas incluem todos os campos, mesmo quando vazios ou com valor zero.
• Identidade: o serialNumber é sempre atribuído pelo servidor quando um passe é criado. Qualquer valor que você enviar na criação é ignorado. O ID completo do objeto do Google Wallet é {issuerId}.{serialNumber}.
• Imagens: logoUrl e heroImageUrl são URLs HTTPS públicas para imagens que o Google busca — não são arquivos carregados.
• Estilo do passe: exatamente um objeto de estilo (generic, offer, loyalty, eventTicket, giftCard, flight ou transit) deve ser definido em um passe. O estilo não pode ser alterado após a criação.

Respostas de erro

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 solicitante.
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/google/pass/validate	Validar uma configuração de passe
POST	/api/google/pass/create	Criar um novo objeto de passe e obter um link para salvar
POST	/api/google/pass/update/{serialNumber}	Atualizar um passe existente; o Google entrega a alteração
GET	/api/google/pass/{applicationCode}/{serialNumber}/save-link	Obter um link para salvar “Adicionar ao Google Wallet”
GET	/api/google/pass/{applicationCode}/{serialNumber}	Obter um único passe
GET	/api/google/passes	Listar todos os passes de um aplicativo
POST	/api/google/pass/{applicationCode}/{serialNumber}/state	Ativar ou invalidar um passe
DELETE	/api/google/pass/{applicationCode}/{serialNumber}	Excluir um passe
GET	/api/google/config	Obter a configuração do Google Wallet do aplicativo
GET	/api/google/templates	Listar modelos de passes disponíveis
GET	/api/google/templates/{filename}	Obter um único modelo

Criar um passe

Cria a classe e o objeto do passe no Google Wallet, e então retorna o número de série atribuído pelo servidor, o ID completo do objeto e um link para salvar “Adicionar ao Google Wallet”.

POST /api/google/pass/create

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
pass	objeto	Sim	O objeto de passe que descreve o passe. Exatamente um estilo deve ser definido.
userId	string	Sim	O ID de Usuário da Pushwoosh para quem o passe é emitido.
applicationCode	string	Sim	O código do aplicativo Pushwoosh.

Exemplo de solicitação

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

Resposta

Campo	Tipo	Descrição
serialNumber	string	Identidade única do passe criado, atribuída pelo servidor.
objectId	string	ID completo do objeto do Google Wallet: {issuerId}.{serialNumber}.
saveLink	string	Link “Adicionar ao Google Wallet”: https://pay.google.com/gp/v/save/{jwt}.
message	string	Mensagem de resultado.

Exemplo de resposta

{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}

Validar um passe

Verifica uma configuração de passe em relação aos requisitos do Google sem criá-lo. Útil antes de chamar a criação.

POST /api/google/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

Aplica um patch no objeto do passe com novo conteúdo. O Google então entrega a versão atualizada para cada dispositivo que salvou o passe. Opcionalmente, envia uma notificação do Android com a atualização.

POST /api/google/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 com o novo conteúdo. O estilo não pode ser alterado.
applicationCode	string	Sim	O código do aplicativo Pushwoosh.
notifyMessage	string	Não	Quando não estiver vazio, envia uma notificação push do Android com este texto para todos que salvaram o passe. Vazio significa uma atualização silenciosa.
notifyOnUpdate	boolean	Não	Solicita uma notificação de atualização de campo. Apenas passes do tipo loyalty, eventTicket e flight realmente notificam; outros estilos aceitam a flag, mas nunca enviam uma. As notificações são disparadas apenas dentro de 3 horas de um horário de início relevante, e o Google as limita a 3 notificações por passe a cada 24 horas.

Duas maneiras de notificar na atualização

notifyMessage envia uma notificação personalizada do Android para todos que salvaram o passe e funciona para qualquer estilo de passe. notifyOnUpdate solicita ao Google que envie sua própria notificação de atualização de campo, que só é disparada para passes do tipo loyalty, eventTicket e flight.

Resposta

Campo	Tipo	Descrição
success	boolean	Se a atualização foi bem-sucedida.
message	string	Mensagem de resultado.

Obter um link para salvar

Retorna um link “Adicionar ao Google Wallet” para um passe já criado. O objeto do passe já deve existir (criado via Criar um passe).

GET /api/google/pass/{applicationCode}/{serialNumber}/save-link

Resposta

Campo	Tipo	Descrição
saveLink	string	https://pay.google.com/gp/v/save/{jwt}.

Compartilhe o link ou renderize-o como um código QR

Coloque o saveLink atrás de um botão “Adicionar ao Google Wallet” ou renderize-o como um código QR com qualquer biblioteca de QR. Quando um usuário o abre, o Google solicita que ele salve o passe e registra seu dispositivo para atualizações.

Obter um passe

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

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

Resposta

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

Listar passes

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

GET /api/google/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.

Definir o estado do passe

Ativa ou invalida um passe. Um passe invalidado (inativo) é movido para a seção Passes expirados do usuário no Google Wallet; o registro é mantido para que possa ser reativado.

POST /api/google/pass/{applicationCode}/{serialNumber}/state

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
active	boolean	Sim	true define o passe como ACTIVE; false o invalida (INACTIVE).

Resposta

Retorna um objeto vazio {} em caso de sucesso.

Excluir um passe

Invalida o passe no Google e remove seu registro armazenado na Pushwoosh.

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

Um passe salvo não pode ser removido à força

O Google não permite a remoção de um passe já salvo no dispositivo de um usuário. A exclusão invalida o passe (ele é movido para Passes expirados) e remove o registro da Pushwoosh.

Resposta

Retorna um objeto vazio {} em caso de sucesso.

Obter configuração

Retorna o estado da configuração do Google Wallet para um aplicativo.

GET /api/google/config?applicationCode=XXXXX-XXXXX

Resposta

Campo	Tipo	Descrição
hasServiceAccount	boolean	Se uma chave de conta de serviço está configurada.
issuerId	string	O ID de Emissor do Google Pay & Wallet Console configurado.
serviceAccountEmail	string	O client_email da conta de serviço configurada.

Modelos

Lista os modelos de passe de exemplo disponíveis ou busca um como um objeto de passe que você pode usar como ponto de partida.

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

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

Referência de objeto

Objeto de passe

Campo	Tipo	Descrição
serialNumber	string	Atribuído pelo servidor na criação; identifica o passe.
generic / offer / loyalty / eventTicket / giftCard / flight / transit	objeto	O estilo do passe. Exatamente um deve ser definido. Veja os objetos de estilo abaixo.
hexBackgroundColor	string	Cor de fundo do cartão, #rrggbb.
logoUrl	string	URL HTTPS pública da imagem do logotipo. Obrigatório para fidelidade e transporte.
heroImageUrl	string	URL HTTPS pública de uma imagem de banner larga.
barcode	objeto	Código de barras mostrado no passe.
textModules	array	Módulos de texto mostrados na visualização de detalhes.
links	array	Módulos de link mostrados na visualização de detalhes.
expirationTime	string	Hora ISO 8601 em que o Google expira automaticamente o passe. Vazio significa sem expiração.
appLink	objeto	Link de aplicativo: um botão de CTA na frente do passe.
locations	array	Localizações que acionam uma notificação geocercada (máximo de 10).
holdersPolicy	string	Quem pode salvar o passe: ONE_USER_ALL_DEVICES (padrão), ONE_USER_ONE_DEVICE ou MULTIPLE_HOLDERS.

Objeto genérico

Campo	Tipo	Descrição
cardTitle	string	Obrigatório. O nome do emissor/programa no topo do cartão.
header	string	Obrigatório. O título principal do cartão.
subheader	string	Título secundário.
cardFields	array	Até 6 módulos de texto fixados na frente (até 3 linhas de 2).

Objeto de oferta

Campo	Tipo	Descrição
title	string	Obrigatório. Por exemplo, 20% de desconto em tudo.
provider	string	Obrigatório. O nome do comerciante.
details	string	Detalhes da oferta.
finePrint	string	Termos e condições.
redemptionChannel	string	ONLINE, INSTORE, BOTH (padrão), ou TEMPORARY_PRICE_REDUCTION.
issuerName	string	Mostrado nas superfícies “emitido por” do Google; o padrão é provider.

Objeto de fidelidade

Campo	Tipo	Descrição
programName	string	Obrigatório. Requer logoUrl no passe.
accountName	string	Nome do membro mostrado no cartão.
accountId	string	ID do membro mostrado no cartão.
pointsLabel	string	Por exemplo, Pontos. Mostrado apenas com um saldo.
pointsBalance	string	O saldo de pontos.
rewardsTier	string	Por exemplo, Ouro.
rewardsTierLabel	string	Rótulo ao lado do nível; o padrão é Nível.
issuerName	string	O padrão é programName.

Objeto de ingresso para evento

Campo	Tipo	Descrição
eventName	string	Obrigatório.
venueName / venueAddress	string	Detalhes do local.
startDateTime / endDateTime	string	ISO 8601 com deslocamento (por exemplo, 2026-07-01T19:30:00+02:00).
ticketHolderName / ticketNumber / ticketType	string	Detalhes do portador e do ingresso.
section / row / seat / gate	string	Detalhes do assento.
issuerName	string	O padrão é eventName.

Objeto de cartão-presente

Campo	Tipo	Descrição
merchantName	string	Obrigatório.
cardNumber	string	Obrigatório.
pin	string	PIN do cartão.
balance	string	Valor decimal, por exemplo 25.00. Requer balanceCurrency.
balanceCurrency	string	Código de moeda ISO 4217, por exemplo USD.
issuerName	string	O padrão é merchantName.

Objeto de voo

Campo	Tipo	Descrição
carrierIataCode	string	Obrigatório. Código IATA de 2 letras, por exemplo LX.
airlineName	string	Nome de exibição da companhia aérea.
flightNumber	string	Obrigatório. Apenas dígitos, por exemplo 113.
originAirportCode / destinationAirportCode	string	Obrigatório. Códigos IATA de 3 letras.
originTerminal / originGate / destinationTerminal	string	Detalhes do terminal e portão.
departureDateTime	string	Obrigatório. Hora local do aeroporto de origem, ISO 8601 sem deslocamento (por exemplo, 2026-09-01T06:30:00).
boardingTime / arrivalDateTime	string	Mesmo formato local. arrivalDateTime é a hora local do destino.
passengerName	string	Obrigatório.
confirmationCode / seatNumber / seatClass / boardingGroup	string	Detalhes do passageiro.
issuerName	string	O padrão é airlineName, depois o código da transportadora.

Objeto de transporte

Campo	Tipo	Descrição
transitType	string	Obrigatório. BUS, RAIL, TRAM, FERRY ou OTHER.
transitOperatorName	string	Obrigatório. Requer logoUrl no passe.
passengerName	string	Obrigatório.
ticketNumber	string	Número do bilhete.
tripType	string	ONE_WAY (padrão) ou ROUND_TRIP.
legs	array	Um ou mais trechos de transporte na ordem da viagem.
issuerName	string	O padrão é transitOperatorName.

Objeto de trecho de transporte

Campo	Tipo	Descrição
originName / destinationName	string	Obrigatório.
departureDateTime / arrivalDateTime	string	ISO 8601; deslocamento opcional (hora local quando omitido).
platform / coach / seat	string	Detalhes do embarque.
fareName	string	Por exemplo, Anytime Single.

Objeto de código de barras

Campo	Tipo	Descrição
format	string	QR_CODE, PDF_417, AZTEC, CODE_128, EAN_13 e outros tipos de código de barras do Google Wallet.
value	string	Dados codificados no código de barras.
altText	string	Texto mostrado abaixo do código de barras.

Objeto de módulo de texto

Campo	Tipo	Descrição
id	string	Identificador do módulo.
header	string	Título do módulo.
body	string	Texto do módulo.

Objeto de módulo de link

Campo	Tipo	Descrição
uri	string	URL do link externo.
description	string	Rótulo do link mostrado na visualização de detalhes.

Objeto de link de aplicativo

Campo	Tipo	Descrição
uri	string	URL da web ou URI de destino de link direto.
androidPackageName	string	Opcional. Quando definido, abre o aplicativo Android.
description	string	Descrição interna do URI de destino (não é um rótulo de botão visível); o padrão é o URI.

Objeto de localização

Campo	Tipo	Descrição
latitude	number	-90.0 a +90.0.
longitude	number	-180.0 a +180.0.

Objeto de registro de passe

Retornado pelos endpoints de listagem/obtenção.

Campo	Tipo	Descrição
serialNumber	string	Número de série do passe.
objectId	string	ID completo do objeto do Google Wallet {issuerId}.{serialNumber}.
cardTitle	string	Título/cabeçalho de exibição para o passe.
header	string	Título de exibição secundário.
userId	string	ID de Usuário da Pushwoosh para quem o passe foi emitido.
createdAt / updatedAt	string	Carimbos de data/hora de criação e última atualização.
state	string	ACTIVE ou INACTIVE.
style	string	generic, offer, loyalty, eventTicket, giftCard, flight ou transit.
pass	objeto	O objeto de passe completo, para edição.