API de Google Wallet

La API de Google Wallet te permite crear, actualizar, listar y gestionar pases de Google Wallet de forma programática. Admite las mismas operaciones que realiza el creador de pases en el Panel de Control.

Utilízala 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 tus usuarios.

Requisito previo: configuración de Google Wallet

Antes de que puedas 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. Consulta la configuración de pases de Google Wallet para Android.

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 tu token de acceso a la API de Pushwoosh:

Authorization: Token <api-token>

La cuenta propietaria del token debe ser 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 poblados: las respuestas incluyen todos los campos, incluso cuando están vacíos o con valor cero.
• Identidad: el serialNumber siempre es asignado por el servidor cuando se crea un pase. Cualquier valor que envíes al crearlo se ignora. El ID de objeto completo 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 faltante 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 guardarlo
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 pase 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	objeto	Sí	El objeto de pase que describe el pase. Se debe establecer exactamente un estilo.
userId	string	Sí	El ID de Usuario de Pushwoosh al que se emite el pase.
applicationCode	string	Sí	El código de aplicación de Pushwoosh.

Ejemplo de solicitud

{
  "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 de objeto completo 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

{
  "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 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	objeto	Sí	El objeto de pase a validar.

Respuesta

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

Actualizar un pase

Aplica un parche al objeto del pase con nuevo contenido. Google luego 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	objeto	Sí	El objeto de pase con el nuevo contenido. El estilo no se puede cambiar.
applicationCode	string	Sí	El código de aplicación de Pushwoosh.
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	Solicita una notificación de actualización de campo. Solo los pases loyalty, eventTicket y flight realmente notifican; 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.

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.

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).

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

Respuesta

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

Comparte el enlace o reprodúcelo como un código QR

Coloca el saveLink detrás de un botón “Añadir a Google Wallet”, o reprodúcelo 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.

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.

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.
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 de objetos	La página actual de registros de pase.
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}

Un pase guardado no se puede eliminar a la fuerza

Google no permite eliminar un pase que ya está guardado en el dispositivo de un usuario. Eliminar invalida el pase (se mueve a Pases caducados) y elimina el registro de Pushwoosh.

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 configurado.
serviceAccountEmail	string	El client_email de la cuenta de servicio configurada.

Plantillas

Lista las plantillas de pase de ejemplo disponibles, o busca una como un objeto de pase que puedas 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	objeto	El estilo del pase. Se debe establecer exactamente uno. Consulta 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	objeto	Código de barras que se muestra en el pase.
textModules	array	Módulos de texto que se muestran en la vista de detalles.
links	array	Módulos de enlace que se muestran 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	objeto	Enlace de aplicación: un botón de llamada a la acción en la parte frontal del pase.
locations	array	Ubicaciones 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 fijados en el frente (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	Cantidad 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 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 Cualquier Hora.

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 de la URI de destino (no es una etiqueta de botón visible); el valor predeterminado es la 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 listar/obtener.

Campo	Tipo	Descripción
serialNumber	string	Número de serie del pase.
objectId	string	ID de objeto completo 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 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	objeto	El objeto de pase completo, para editar.