# API de Google Wallet

La API de Google Wallet le permite crear, actualizar, listar y gestionar [pases de Google Wallet](/es/product/messaging-channels/google-wallet-passes/) de forma programática. Admite las mismas operaciones que realiza el [constructor de pases](/es/product/messaging-channels/google-wallet-passes/pass-builder/) en el Panel de Control.

Utilícela para emitir tarjetas de fidelización, ofertas, tarjetas de regalo, entradas para eventos, tarjetas de embarque de vuelos, billetes de transporte y pases genéricos, y para enviar actualizaciones en tiempo real a los pases ya guardados en los dispositivos de sus usuarios.

<Aside type="note" title="Requisito previo: configuración de Google Wallet">
Antes de poder crear pases para una aplicación, se debe configurar un **ID de emisor** de Google Wallet y una **clave de cuenta de servicio** para esa aplicación en el Panel de Control de Pushwoosh. Sin ellos, las solicitudes de `create` y `update` fallan. Consulte [Configuración de pases de Google Wallet para Android](/es/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/).
</Aside>


## URL base

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

Todos los endpoints se sirven a través de HTTPS. Las solicitudes y respuestas utilizan `application/json` a menos que se indique lo contrario.

## Autenticación

Cada solicitud debe incluir un encabezado `Authorization` con su [token de acceso a la API de Pushwoosh](/es/developer/api-reference/api-access-token/):

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

La cuenta propietaria del token debe ser la propietaria de la aplicación a la que hace referencia `applicationCode`. Una solicitud para una aplicación que pertenece a otra cuenta devuelve `403 Forbidden`.

## Convenciones

*   **Nomenclatura de campos:** Los campos JSON utilizan `lowerCamelCase` (por ejemplo, `serialNumber`, `hexBackgroundColor`, `logoUrl`).
*   **Campos no rellenados:** las respuestas incluyen todos los campos, incluso cuando están vacíos o tienen valor cero.
*   **Identidad:** el `serialNumber` siempre es asignado por el servidor cuando se crea un pase. Cualquier valor que envíe al crear será ignorado. El ID completo del objeto de Google Wallet es `{issuerId}.{serialNumber}`.
*   **Imágenes:** `logoUrl` y `heroImageUrl` son URL HTTPS públicas de imágenes que Google obtiene, no archivos subidos.
*   **Estilo de pase:** se debe establecer exactamente un objeto de estilo (`generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight`, o `transit`) en un pase. El estilo no se puede cambiar después de la creación.

### Respuestas de error

| Estado HTTP | Significado |
| :---- | :---- |
| `400 Bad Request` | Argumento no válido: falta un campo obligatorio o está mal formado. |
| `401 Unauthorized` | Encabezado `Authorization` ausente o no válido. |
| `403 Forbidden` | La aplicación no pertenece a la cuenta del solicitante. |
| `404 Not Found` | No se encontró el pase, la plantilla o la aplicación. |
| `503 Service Unavailable` | El servicio está al máximo de su capacidad o no está disponible temporalmente. |

## Endpoints

| Método | Ruta | Descripción |
| :---- | :---- | :---- |
| `POST` | `/api/google/pass/validate` | Validar una configuración de pase |
| `POST` | `/api/google/pass/create` | Crear un nuevo objeto de pase y obtener un enlace para guardar |
| `POST` | `/api/google/pass/update/{serialNumber}` | Actualizar un pase existente; Google entrega el cambio |
| `GET` | `/api/google/pass/{applicationCode}/{serialNumber}/save-link` | Obtener un enlace para guardar "Añadir a Google Wallet" |
| `GET` | `/api/google/pass/{applicationCode}/{serialNumber}` | Obtener un único pase |
| `GET` | `/api/google/passes` | Listar todos los pases de una aplicación |
| `POST` | `/api/google/pass/{applicationCode}/{serialNumber}/state` | Activar o invalidar un pase |
| `DELETE` | `/api/google/pass/{applicationCode}/{serialNumber}` | Eliminar un pase |
| `GET` | `/api/google/config` | Obtener la configuración de Google Wallet de la aplicación |
| `GET` | `/api/google/templates` | Listar las plantillas de pases disponibles |
| `GET` | `/api/google/templates/{filename}` | Obtener una única plantilla |

## Crear un pase

Crea la clase y el objeto del pase en Google Wallet, y luego devuelve el número de serie asignado por el servidor, el ID completo del objeto y un enlace para guardar "Añadir a Google Wallet".

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

### Cuerpo de la solicitud

| Parámetro | Tipo | Requerido | Descripción |
| :---- | :---- | :---- | :---- |
| `pass` | object | Sí | El [objeto de pase](#pass-object) que describe el pase. Se debe establecer exactamente un estilo. |
| `userId` | string | Sí | El [ID de usuario de Pushwoosh](/es/developer/api-reference/api-identifiers/#user-id) al que se emite el pase. |
| `applicationCode` | string | Sí | El [código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code). |

##### Ejemplo de solicitud

```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"
    }
  }
}
```

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `serialNumber` | string | Identidad única asignada por el servidor del pase creado. |
| `objectId` | string | ID completo del objeto de Google Wallet: `{issuerId}.{serialNumber}`. |
| `saveLink` | string | Enlace "Añadir a Google Wallet": `https://pay.google.com/gp/v/save/{jwt}`. |
| `message` | string | Mensaje de resultado. |

##### Ejemplo de respuesta

```json
{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pase creado con éxito"
}
```

## Validar un pase

Comprueba la configuración de un pase con los requisitos de Google sin crearlo. Útil antes de llamar a crear.

`POST` `/api/google/pass/validate`

### Cuerpo de la solicitud

| Parámetro | Tipo | Requerido | Descripción |
| :---- | :---- | :---- | :---- |
| `pass` | object | Sí | El [objeto de pase](#pass-object) a validar. |

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `valid` | boolean | Indica si el pase supera la validación. |
| `errors` | array of strings | Problemas de bloqueo que deben ser solucionados. |
| `warnings` | array of strings | Advertencias no bloqueantes. |

## Actualizar un pase

Aplica un parche al objeto del pase con nuevo contenido. Google entrega la versión actualizada a cada dispositivo que guardó el pase. Opcionalmente, envía una notificación de Android con la actualización.

`POST` `/api/google/pass/update/{serialNumber}`

### Parámetros de ruta

| Parámetro | Tipo | Descripción |
| :---- | :---- | :---- |
| `serialNumber` | string | El número de serie devuelto cuando se creó el pase. |

### Cuerpo de la solicitud

| Parámetro | Tipo | Requerido | Descripción |
| :---- | :---- | :---- | :---- |
| `updates` | object | Sí | El [objeto de pase](#pass-object) con el nuevo contenido. El estilo no se puede cambiar. |
| `applicationCode` | string | Sí | El [código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code). |
| `notifyMessage` | string | No | Cuando no está vacío, envía una notificación push de Android con este texto a todos los que guardaron el pase. Vacío significa una actualización silenciosa. |
| `notifyOnUpdate` | boolean | No | Solicitar una notificación de actualización de campo. Solo los pases `loyalty`, `eventTicket` y `flight` notifican realmente; otros estilos aceptan la bandera pero nunca envían una. Las notificaciones se activan solo dentro de las 3 horas de una hora de inicio relevante, y Google las limita a 3 notificaciones por pase cada 24 horas. |

<Aside type="note" title="Dos formas de notificar en la actualización">
`notifyMessage` envía una notificación de Android personalizada a todos los que guardaron el pase y funciona para cualquier estilo de pase. `notifyOnUpdate` le pide a Google que envíe su propia notificación de actualización de campo, que solo se activa para los pases `loyalty`, `eventTicket` y `flight`.
</Aside>

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `success` | boolean | Indica si la actualización tuvo éxito. |
| `message` | string | Mensaje de resultado. |

## Obtener un enlace para guardar

Devuelve un enlace para guardar "Añadir a Google Wallet" para un pase ya creado. El objeto del pase ya debe existir (creado a través de [Crear un pase](#create-a-pass)).

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

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `saveLink` | string | `https://pay.google.com/gp/v/save/{jwt}`. |

<Aside type="tip" title="Comparta el enlace o reprodúzcalo como un código QR">
Coloque el `saveLink` detrás de un botón "Añadir a Google Wallet", o reprodúzcalo como un código QR con cualquier biblioteca de QR. Cuando un usuario lo abre, Google le pide que guarde el pase y registra su dispositivo para recibir actualizaciones.
</Aside>

## Obtener un pase

Devuelve un único pase almacenado, incluyendo su objeto de pase completo.

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

### Respuesta

Devuelve `{ "pass": { ... } }`, un único [registro de pase](#pass-record-object).

## Listar pases

Devuelve una lista paginada y ordenada de los pases almacenados para una aplicación.

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

### Parámetros de consulta

| Parámetro | Tipo | Requerido | Descripción |
| :---- | :---- | :---- | :---- |
| `applicationCode` | string | Sí | El [código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code). |
| `orderBy` | string | No | Campo de ordenación: `UPDATED` (predeterminado) o `CREATED`. |
| `orderDirection` | string | No | Dirección de ordenación: `DESC` (predeterminado, los más nuevos primero) o `ASC`. |
| `page` | integer | No | Índice de página basado en cero. El valor predeterminado es `0`. |
| `perPage` | integer | No | Tamaño de la página. `0` u omitido utiliza el valor predeterminado del servidor. |

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `passes` | array of objects | La página actual de [registros de pase](#pass-record-object). |
| `page` | integer | El índice de la página devuelta. |
| `perPage` | integer | El tamaño de página utilizado para esta respuesta. |
| `total` | integer | Número total de pases para la aplicación en todas las páginas. |

## Establecer el estado del pase

Activa o invalida un pase. Un pase invalidado (inactivo) se mueve a la sección **Pases caducados** del usuario en Google Wallet; el registro se mantiene para que pueda ser reactivado.

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

### Cuerpo de la solicitud

| Parámetro | Tipo | Requerido | Descripción |
| :---- | :---- | :---- | :---- |
| `active` | boolean | Sí | `true` establece el pase en `ACTIVE`; `false` lo invalida (`INACTIVE`). |

### Respuesta

Devuelve un objeto vacío `{}` si tiene éxito.

## Eliminar un pase

Invalida el pase en Google y elimina su registro almacenado en Pushwoosh.

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

<Aside type="caution" title="Un pase guardado no se puede eliminar a la fuerza">
Google no permite eliminar un pase ya guardado en el dispositivo de un usuario. La eliminación invalida el pase (se mueve a **Pases caducados**) y elimina el registro de Pushwoosh.
</Aside>

### Respuesta

Devuelve un objeto vacío `{}` si tiene éxito.

## Obtener configuración

Devuelve el estado de la configuración de Google Wallet para una aplicación.

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

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `hasServiceAccount` | boolean | Indica si una clave de cuenta de servicio está configurada. |
| `issuerId` | string | El [ID de emisor de la Consola de Google Pay y Wallet](/es/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-issuer-account) configurado. |
| `serviceAccountEmail` | string | El `client_email` de la [cuenta de servicio](/es/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/#create-the-service-account-key) configurada. |

## Plantillas

Liste las plantillas de pases de ejemplo disponibles, o recupere una como un [objeto de pase](#pass-object) que puede usar como punto de partida.

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

`GET` `/api/google/templates/{filename}` — devuelve `{ "template": { ...objeto de pase... } }`.

## Referencia de objetos

### Objeto de pase

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `serialNumber` | string | Asignado por el servidor en la creación; identifica el pase. |
| `generic` / `offer` / `loyalty` / `eventTicket` / `giftCard` / `flight` / `transit` | object | El estilo del pase. Se debe establecer **exactamente uno**. Vea los objetos de estilo a continuación. |
| `hexBackgroundColor` | string | Color de fondo de la tarjeta, `#rrggbb`. |
| `logoUrl` | string | URL HTTPS pública de la imagen del logotipo. Requerido para fidelización y transporte. |
| `heroImageUrl` | string | URL HTTPS pública de una imagen de banner ancha. |
| `barcode` | object | [Código de barras](#barcode-object) mostrado en el pase. |
| `textModules` | array | [Módulos de texto](#text-module-object) mostrados en la vista de detalles. |
| `links` | array | [Módulos de enlace](#link-module-object) mostrados en la vista de detalles. |
| `expirationTime` | string | Hora ISO 8601 en la que Google hace caducar automáticamente el pase. Vacío significa que no caduca. |
| `appLink` | object | [Enlace de aplicación](#app-link-object): un botón de llamada a la acción en el anverso del pase. |
| `locations` | array | [Ubicaciones](#location-object) que activan una notificación geocercada (máximo 10). |
| `holdersPolicy` | string | Quién puede guardar el pase: `ONE_USER_ALL_DEVICES` (predeterminado), `ONE_USER_ONE_DEVICE`, o `MULTIPLE_HOLDERS`. |

### Objeto genérico

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `cardTitle` | string | Requerido. El nombre del emisor/programa en la parte superior de la tarjeta. |
| `header` | string | Requerido. El título principal de la tarjeta. |
| `subheader` | string | Título secundario. |
| `cardFields` | array | Hasta 6 [módulos de texto](#text-module-object) fijados en el anverso (hasta 3 filas de 2). |

### Objeto de oferta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `title` | string | Requerido. Por ejemplo, `20% de descuento en todo`. |
| `provider` | string | Requerido. El nombre del comerciante. |
| `details` | string | Detalles de la oferta. |
| `finePrint` | string | Términos y condiciones. |
| `redemptionChannel` | string | `ONLINE`, `INSTORE`, `BOTH` (predeterminado), o `TEMPORARY_PRICE_REDUCTION`. |
| `issuerName` | string | Se muestra en las superficies de "emitido por" de Google; el valor predeterminado es `provider`. |

### Objeto de fidelización

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `programName` | string | Requerido. Requiere `logoUrl` en el pase. |
| `accountName` | string | Nombre del miembro que se muestra en la tarjeta. |
| `accountId` | string | ID del miembro que se muestra en la tarjeta. |
| `pointsLabel` | string | Por ejemplo, `Puntos`. Se muestra solo con un saldo. |
| `pointsBalance` | string | El saldo de puntos. |
| `rewardsTier` | string | Por ejemplo, `Oro`. |
| `rewardsTierLabel` | string | Etiqueta junto al nivel; el valor predeterminado es `Nivel`. |
| `issuerName` | string | El valor predeterminado es `programName`. |

### Objeto de entrada de evento

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `eventName` | string | Requerido. |
| `venueName` / `venueAddress` | string | Detalles del lugar. |
| `startDateTime` / `endDateTime` | string | ISO 8601 con desplazamiento (por ejemplo, `2026-07-01T19:30:00+02:00`). |
| `ticketHolderName` / `ticketNumber` / `ticketType` | string | Detalles del titular y de la entrada. |
| `section` / `row` / `seat` / `gate` | string | Detalles del asiento. |
| `issuerName` | string | El valor predeterminado es `eventName`. |

### Objeto de tarjeta de regalo

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `merchantName` | string | Requerido. |
| `cardNumber` | string | Requerido. |
| `pin` | string | PIN de la tarjeta. |
| `balance` | string | Importe decimal, por ejemplo `25.00`. Requiere `balanceCurrency`. |
| `balanceCurrency` | string | Código de moneda ISO 4217, por ejemplo `USD`. |
| `issuerName` | string | El valor predeterminado es `merchantName`. |

### Objeto de vuelo

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `carrierIataCode` | string | Requerido. Código IATA de 2 letras, por ejemplo `LX`. |
| `airlineName` | string | Nombre de visualización de la aerolínea. |
| `flightNumber` | string | Requerido. Solo dígitos, por ejemplo `113`. |
| `originAirportCode` / `destinationAirportCode` | string | Requerido. Códigos IATA de 3 letras. |
| `originTerminal` / `originGate` / `destinationTerminal` | string | Detalles de la terminal y la puerta de embarque. |
| `departureDateTime` | string | Requerido. Hora **local** del aeropuerto de origen, ISO 8601 **sin** desplazamiento (por ejemplo, `2026-09-01T06:30:00`). |
| `boardingTime` / `arrivalDateTime` | string | Mismo formato local. `arrivalDateTime` es la hora local de destino. |
| `passengerName` | string | Requerido. |
| `confirmationCode` / `seatNumber` / `seatClass` / `boardingGroup` | string | Detalles del pasajero. |
| `issuerName` | string | El valor predeterminado es `airlineName`, luego el código de la aerolínea. |

### Objeto de transporte

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `transitType` | string | Requerido. `BUS`, `RAIL`, `TRAM`, `FERRY`, o `OTHER`. |
| `transitOperatorName` | string | Requerido. Requiere `logoUrl` en el pase. |
| `passengerName` | string | Requerido. |
| `ticketNumber` | string | Número de billete. |
| `tripType` | string | `ONE_WAY` (predeterminado) o `ROUND_TRIP`. |
| `legs` | array | Uno o más [tramos de transporte](#transit-leg-object) en orden de viaje. |
| `issuerName` | string | El valor predeterminado es `transitOperatorName`. |

### Objeto de tramo de transporte

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `originName` / `destinationName` | string | Requerido. |
| `departureDateTime` / `arrivalDateTime` | string | ISO 8601; desplazamiento opcional (hora local cuando se omite). |
| `platform` / `coach` / `seat` | string | Detalles de embarque. |
| `fareName` | string | Por ejemplo, `Sencillo en cualquier momento`. |

### Objeto de código de barras

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `format` | string | `QR_CODE`, `PDF_417`, `AZTEC`, `CODE_128`, `EAN_13`, y otros tipos de códigos de barras de Google Wallet. |
| `value` | string | Datos codificados en el código de barras. |
| `altText` | string | Texto que se muestra debajo del código de barras. |

### Objeto de módulo de texto

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `id` | string | Identificador del módulo. |
| `header` | string | Encabezado del módulo. |
| `body` | string | Texto del módulo. |

### Objeto de módulo de enlace

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `uri` | string | URL del enlace externo. |
| `description` | string | Etiqueta del enlace que se muestra en la vista de detalles. |

### Objeto de enlace de aplicación

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `uri` | string | URL web o URI de destino de enlace profundo. |
| `androidPackageName` | string | Opcional. Cuando se establece, abre la aplicación de Android. |
| `description` | string | Descripción interna del URI de destino (no es una etiqueta de botón visible); el valor predeterminado es el URI. |

### Objeto de ubicación

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `latitude` | number | `-90.0` a `+90.0`. |
| `longitude` | number | `-180.0` a `+180.0`. |

### Objeto de registro de pase

Devuelto por los endpoints de lista/obtención.

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `serialNumber` | string | Número de serie del pase. |
| `objectId` | string | ID completo del objeto de Google Wallet `{issuerId}.{serialNumber}`. |
| `cardTitle` | string | Título/encabezado de visualización para el pase. |
| `header` | string | Título de visualización secundario. |
| `userId` | string | [ID de usuario de Pushwoosh](/es/developer/api-reference/api-identifiers/#user-id) al que se emitió el pase. |
| `createdAt` / `updatedAt` | string | Marcas de tiempo de creación y última actualización. |
| `state` | string | `ACTIVE` o `INACTIVE`. |
| `style` | string | `generic`, `offer`, `loyalty`, `eventTicket`, `giftCard`, `flight`, o `transit`. |
| `pass` | object | El [objeto de pase](#pass-object) completo, para editar. |