# API do Google Wallet

A API do Google Wallet permite criar, atualizar, listar e gerenciar [passes do Google Wallet](/pt/product/messaging-channels/google-wallet-passes/) programaticamente. Ela suporta as mesmas operações que o [construtor de passes](/pt/product/messaging-channels/google-wallet-passes/pass-builder/) no Painel de Controle realiza.

Use-a para emitir cartões de fidelidade, ofertas, vales-presente, ingressos para eventos, cartões de embarque de voos, bilhetes de trânsito e passes genéricos, e para enviar atualizações ao vivo para passes já salvos nos dispositivos de seus usuários.

<Aside type="note" title="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 passe do Google Wallet para Android](/pt/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/).
</Aside>


## 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

Toda solicitação deve incluir um cabeçalho `Authorization` com seu [token de acesso à API da Pushwoosh](/pt/developer/api-reference/api-access-token/):

```
Authorization: Token <api-token>
```

A conta proprietária do token deve ser 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 enviados.
*   **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 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/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 "Adicionar ao Google Wallet" para salvar |
| `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 passe 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 "Adicionar ao Google Wallet" para salvar.

`POST` `/api/google/pass/create`

### Corpo da solicitação

| Parâmetro | Tipo | Obrigatório | Descrição |
| :---- | :---- | :---- | :---- |
| `pass` | object | Sim | O [objeto de passe](#pass-object) que descreve o passe. Exatamente um estilo deve ser definido. |
| `userId` | string | Sim | O [ID de Usuário da Pushwoosh](/pt/developer/api-reference/api-identifiers/#user-id) para quem o passe é emitido. |
| `applicationCode` | string | Sim | O [código de aplicativo da Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code). |

##### Exemplo de solicitação

```json
{
  "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 atribuída pelo servidor ao passe criado. |
| `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

```json
{
  "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` | object | Sim | O [objeto de passe](#pass-object) a ser validado. |

### Resposta

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

## Atualizar um passe

Aplica patches 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 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` | object | Sim | O [objeto de passe](#pass-object) com o novo conteúdo. O estilo não pode ser alterado. |
| `applicationCode` | string | Sim | O [código de aplicativo da Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code). |
| `notifyMessage` | string | Não | Quando não estiver vazio, envia uma notificação 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 de `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. |

<Aside type="note" title="Duas maneiras de notificar na atualização">
`notifyMessage` envia uma notificação Android personalizada 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 é disparada apenas para passes de `loyalty`, `eventTicket` e `flight`.
</Aside>

### 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 salvar um passe já criado. O objeto do passe já deve existir (criado via [Criar um passe](#create-a-pass)).

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

### Resposta

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

<Aside type="tip" title="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.
</Aside>

## 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 [registro de passe](#pass-record-object).

## 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 de aplicativo da Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code). |
| `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 recente 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 of objects | A página atual de [registros de passe](#pass-record-object). |
| `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 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}`

<Aside type="caution" title="Um passe salvo não pode ser removido à força">
O Google não permite remover 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.
</Aside>

### 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](/pt/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-issuer-account) configurado. |
| `serviceAccountEmail` | string | O `client_email` da [conta de serviço](/pt/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-service-account-key) configurada. |

## Modelos

Liste os modelos de passe de exemplo disponíveis ou busque um como um [objeto de passe](#pass-object) 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` | object | 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 trânsito. |
| `heroImageUrl` | string | URL HTTPS pública de uma imagem de banner larga. |
| `barcode` | object | [Código de barras](#barcode-object) exibido no passe. |
| `textModules` | array | [Módulos de texto](#text-module-object) exibidos na visualização de detalhes. |
| `links` | array | [Módulos de link](#link-module-object) exibidos na visualização de detalhes. |
| `expirationTime` | string | Horário ISO 8601 em que o Google expira automaticamente o passe. Vazio significa sem expiração. |
| `appLink` | object | [Link de aplicativo](#app-link-object): um botão de CTA na frente do passe. |
| `locations` | array | [Localizações](#location-object) 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](#text-module-object) 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 | Exibido nas superfícies "emitido por" do Google; o padrão é o `provider`. |

### Objeto de fidelidade

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `programName` | string | Obrigatório. Requer `logoUrl` no passe. |
| `accountName` | string | Nome do membro exibido no cartão. |
| `accountId` | string | ID do membro exibido no cartão. |
| `pointsLabel` | string | Por exemplo, `Pontos`. Exibido 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 vale-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. Horário **local** do aeroporto de origem, ISO 8601 **sem** deslocamento (por exemplo, `2026-09-01T06:30:00`). |
| `boardingTime` / `arrivalDateTime` | string | Mesmo formato local. `arrivalDateTime` é o horário local de 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 trânsito

| 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 trânsito](#transit-leg-object) na ordem da viagem. |
| `issuerName` | string | O padrão é `transitOperatorName`. |

### Objeto de trecho de trânsito

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `originName` / `destinationName` | string | Obrigatório. |
| `departureDateTime` / `arrivalDateTime` | string | ISO 8601; deslocamento opcional (horário 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 exibido abaixo do código de barras. |

### Objeto de módulo de texto

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `id` | string | Identificador do módulo. |
| `header` | string | Cabeçalho 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 exibido na visualização de detalhes. |

### Objeto de link de aplicativo

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `uri` | string | URL da web ou URI de destino do deep-link. |
| `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](/pt/developer/api-reference/api-identifiers/#user-id) 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` | object | O [objeto de passe](#pass-object) completo, para edição. |