Skip to content
Guía del Centro de ayuda · Actualizaciones y notificaciones
4 min de lecturaVerificado 2026-11-16

Notificaciones push

Envía avisos en pantalla bloqueada en iOS (mediante changeMessage) y Android sin coste por SMS.

En esta guía

Descripción general: cómo funcionan las notificaciones push en pantalla de bloqueo del monedero

Apple Wallet y Google Wallet no permiten avisos push arbitrarios sin vínculo como las aplicaciones nativas independientes; en su lugar, las notificaciones en pantalla de bloqueo están regidas por estrictos protocolos criptográficos del monedero ligados directamente a modificaciones de valor en campos de un pase ya instalado. Cuando cambia un campo de un pase, ambas plataformas muestran una alerta nativa en la pantalla de bloqueo sin costes por mensaje de pasarela SMS.

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
PROTOCOLO PUSH APPLE APNs Y GOOGLE WALLET
ETAPA 01 FASE 1: REGISTRO INICIAL DEL DISPOSITIVO (iOS)
El iPhone instala .pkpassLlama al Apple Web Service de Passinstance:POST/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeId/:serial
Cabecera: Authorization: ApplePass <authenticationToken>
Cuerpo: { "pushToken": "<apns_device_hex_token>" }
ETAPA 02 FASE 2: DISPARADOR DE ENVÍO DE NOTIFICACIÓN PUSH
POST/api/v1/push-notifications/passes/:id | /templates/:id/send | /segmentation
Protocolo Apple APNs HTTP/2
ETAPA 03A
1
Apple Push Delivery abre flujo TLS H a api.push.apple.com:443 firmado con Certificado Pass Type (topic)
2
Envía payload vacío {} (<4096 B)
3
iPhone despierta y consulta lista:GET/v1/devices/...?passesUpdated
4
iPhone descarga .pkpass vía:GET/v1/passes/:passTypeId/:serial
5
iOS compara pass.json antiguo/nuevo y dispara changeMessage: "... %@"
Protocolo API REST Google Wallet
ETAPA 03B /2 | | 1. Google Wallet Sync ejecu
PATCH o addMessage en walletobjects/v1/...
2
Establece notifyPreference: NOTIFY_ON_UPDATE
3
Google Play Services renderiza notificación nativa de monedero en la pantalla bloqueo Android

Especificación de Apple Wallet Web Service (/v1) y changeMessage

Passinstance implementa la especificación completa de Apple Wallet Web Service bajo el prefijo global de rutas /v1:

  1. 1
    Registro del dispositivo: POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber almacena el pushToken del dispositivo y lo vincula al serialNumber del pase tras verificar la cabecera ApplePass <authenticationToken>.
  2. 2
    Push silencioso de activación: Cuando se dispara una notificación o actualización de saldo, Apple Push Delivery envía un payload JSON vacío {} por HTTP/2 a la pasarela APNs de Apple.
  3. 3
    Consulta de números de serie: El dispositivo iOS se despierta en segundo plano y llama a GET /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier?passesUpdatedSince=<tag>, recibiendo una lista de serialNumbers actualizados y una nueva etiqueta lastUpdated.
  4. 4
    Descarga del paquete y alerta en pantalla de bloqueo: Para cada número de serie actualizado, iOS solicita GET /v1/passes/:passTypeIdentifier/:serialNumber (enviando If-Modified-Since). iOS compara el nuevo pass.json descargado con la versión almacenada anteriormente. Cualquier campo cuyo value haya cambiado y defina un texto changeMessage con el marcador %@ dispara un aviso en la pantalla de bloqueo:
JSON
{
  "key": "points_balance",
  "label": "REWARD POINTS",
  "value": "1,450 pts",
  "changeMessage": "Your reward balance was updated to %@!"
}
  1. 5
    Baja del dispositivo y registro de errores: Cuando un usuario elimina un pase de Apple Wallet, iOS llama a DELETE /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber. Cualquier error de análisis en el cliente iOS es notificado por iOS a POST /v1/log.

Importante: En Apple Wallet, changeMessage debe incluir el especificador de formato %@ (que iOS sustituye por el nuevo value del campo), y el value del campo debe ser distinto de su valor anterior en el dispositivo. Enviar exactamente el mismo texto dos veces seguidas no activará una segunda alerta en la pantalla de bloqueo de iOS.

Actualizaciones REST de Google Wallet y cuotas de notificación

En Android, Passinstance actualiza el objeto de pase en la nube (LoyaltyObject, EventTicketObject, GenericObject, OfferObject o GiftCardObject) mediante la API REST walletobjects de Google:

  • Actualizaciones de campos (PATCH): Actualizar puntos, etiquetas de nivel o módulos de texto con notifyPreference: "NOTIFY_ON_UPDATE" indica a Google Wallet que notifique al usuario.
  • Objetos de mensaje personalizados (addMessage): Los mensajes de difusión añaden un objeto Message (messageType: "TEXT_AND_NOTIFY") al pase de Google Wallet, sujeto al límite antispam de Google de un máximo de 3 mensajes con notificación push por pase en una ventana de 24 horas.

Endpoints de API de notificaciones push (Push Notifications API)

Todos los endpoints push están montados bajo /api/v1/push-notifications (Push Notifications API; Passes API también expone POST /api/v1/passes/:id/notifications y POST /api/v1/passes/sendpushnotifications):

MétodoRuta del endpointReglas de DTO / PayloadDescripción
POST/api/v1/push-notifications/passes/:idrequest payload (pushNotificationText, <=85 caracteres; acepta id o externalId del pase)Envía una actualización inmediata o futura opcional a todos los dispositivos registrados de un pase individual.
POST/api/v1/push-notifications/passes/:id/schedulerequest payload (pushNotificationText, publicationDate Y-m-d H:i, publicationTimezone?)Programa una notificación futura para un pase individual (id o externalId).
POST/api/v1/push-notifications/templates/:id/sendrequest payload (pushNotificationText)Difunde una actualización inmediata por notificación push a los pases activos de una plantilla (204 No Content).
POST/api/v1/push-notifications/templates/:idrequest payloadPrograma una notificación push para todos los pases de una plantilla (segmentIds?, savedSearchIds?).
POST/api/v1/push-notifications/segmentationrequest payload (searchId, message <=85 caracteres, priority?)Envía una notificación push dirigida a los pases que coinciden con el UUID de una búsqueda guardada.
POST/api/v1/push-notifications/batchrequest payload (passIds[] máx. 500, message, priority?)Envía una notificación push inmediata a un máximo de 500 identificadores explícitos de pases.

Ejemplo: notificación push segmentada por búsqueda guardada (request payload)

JSON
POST /api/v1/push-notifications/segmentation
{
  "searchId": "7b9e4c12-3f81-4a90-b8d2-19c48a70e112",
  "message": "Double points weekend starts tonight at 6 PM!",
  "priority": "HIGH"
}

Ejemplo: notificación de un pase individual (externalId o UUID)

JSON
POST /api/v1/push-notifications/passes/crm_usr_44910
{
  "pushNotificationText": "Hi Marcus, you unlocked Gold Tier status!",
  "pushNotificationHeaderText": "Artisan Roasters VIP"
}

Geocercas, iBeacons y disparadores por fecha relevante

Además de las actualizaciones enviadas desde el servidor, los pases admiten aparición pasiva en la pantalla de bloqueo configurada en el Editor de plantillas:

  • Ubicaciones GPS (locations): Hasta 10 coordenadas GPS (latitude, longitude, relevantText, maxDistance) por .pkpass (y arrays de ubicación en Google Wallet).
  • Bluetooth Low Energy (beacons): Hasta 10 UUID de proximidad iBeacon (proximityUUID, major, minor, relevantText) para avisos en interior en comercios sobre iOS.
  • Fechas relevantes (relevantDate): Marca de tiempo ISO 8601 del evento que muestra automáticamente una entrada o tarjeta de embarque en la pantalla de bloqueo al aproximarse el evento.

Explore todos los detalles de entrega en Notificaciones de pases Wallet, Capacidades de geocercas y Actualizaciones programadas y mensajería.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.