Descripción general: cómo funciona la sincronización de pases en vivo
A diferencia de las entradas en PDF estáticas o los códigos de barras como imagen, los pases de monedero digital gestionados por Passinstance permanecen conectados dinámicamente a la nube tras su instalación. Cada vez que cambia un atributo del pase, un saldo de mecánica (sellos, puntos de fidelidad, saldo prepago), un nivel o el diseño de una plantilla, Passinstance orquesta una Tubería asíncrona de propagación al monedero que actualiza la tarjeta en vivo en el iPhone, Apple Watch y dispositivo Android del cliente.
Ciclo de vida del estado de propagación al monedero (walletVoidStatus / WalletPropagationStatus)
Cada registro de pase supervisa su estado de anulación y propagación en las redes en la nube de Apple y Google mediante Pass.walletVoidStatus (WalletPropagationStatus):
| Enum de estado | Significado y estado operativo |
|---|---|
NONE | El pase se acaba de crear o no hay ninguna propagación visible para el monedero en cola. |
PENDING | Se ha confirmado una revisión de campo, saldo de mecánica, anulación o plantilla; a la espera de despacho a la cola background job queue. |
QUEUED | Despachado a la cola de workers in-memory cache/background job queue de propagación al monedero para ejecución por APNs y REST de Google. |
SUCCEEDED | La notificación push APNs fue aceptada por la pasarela HTTP/2 de Apple (200 OK) y/o el PATCH REST de Google Wallet finalizó correctamente. |
FAILED | La propagación encontró un error en destino (por ejemplo, certificado Apple Pass Type caducado, token APNs revocado 410 Gone o error de cuota en Google API). |
Importante: Publicar un borrador de plantilla mediante
POST /api/v1/templates/:id/publishconpropagateUpdates: truedistribuye trabajos de propagación entre los pases activos vinculados a esa plantilla (filtrable conactivePassesOnly: true). Ejecute siempre previamenteGET /api/v1/templates/:id/publish-risk-checkpara revisar cambios críticos y su impacto potencial.
Endpoints de API para actualizar pases
| Método | Ruta del endpoint | Descripción |
|---|---|---|
| PATCH | /api/v1/passes/:id | Actualiza atributos personalizados, estado, fecha de vencimiento o código de barras de un pase individual y lanza la propagación al monedero. |
| POST | /api/v1/passes/upsert-by-external-id | Crea o actualiza de manera idempotente un pase existente identificado por (customerId, externalId) (también compatible con PUT /api/v1/passes/by-external-id/:externalId). |
| POST | /api/v1/batch-pass-operations/update | Actualiza los passIds seleccionados en una única petición por lotes (request payload) y encola los trabajos de propagación. |
| POST | /api/v1/templates/:id/publish | Promueve un borrador de plantilla (request payload con propagateUpdates: true) y refresca los pases activos de esa plantilla. |
Ejemplo: actualización de un pase individual y disparo de propagación
PATCH /api/v1/passes/c41a8d20-6e11-4f3b-9a81-0029d81a4f10
{
"attributes": {
"points": 1450,
"tier": "Platinum",
"nextReward": "Free Espresso"
},
"expirationDate": "2027-12-31 23:59"
}
Respuesta (200 OK):
{
"id": "c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"externalId": "cust_884910",
"serialNumber": "PI-8849-2026-X9",
"status": "ACTIVE",
"lifecycleStatus": "ACTIVE",
"walletVoidStatus": "QUEUED",
"updatedAt": "2026-11-15T14:22:10.114Z"
}
Ejemplo: actualización por lotes con array (request payload)
POST /api/v1/batch-pass-operations/update
{
"operation": "update",
"passIds": [
"c41a8d20-6e11-4f3b-9a81-0029d81a4f10",
"9b2f1e44-8a10-4c92-a711-5530e91b2c01"
],
"updateData": {
"attributes": {
"seasonalOffer": "Winter Bonus Points"
}
}
}
Por qué el tiempo de sincronización puede variar entre dispositivos
-
Modo avión y Modo de bajo consumo de datos: Los dispositivos iOS en Modo avión o Ahorro de batería aplazan las consultas APNs en segundo plano hasta recuperar conectividad Wi-Fi o móvil.
-
Interruptor de actualización manual: Los clientes que desactivaron Actualizaciones automáticas en el reverso de su pase en Apple Wallet deben deslizar hacia abajo manualmente dentro de Apple Wallet para descargar la versión
.pkpassmás reciente. -
Supresión de pases anulados: Por defecto, los pases en estado
VOIDEDoEXPIREDomiten envíos promocionales rutinarios salvo que esté activadoupdateVoidedExpiredPasses: trueen la plantilla.
Consulte Notificaciones push, Ver y actualizar pases y Versiones de plantilla y publicación para ver flujos relacionados.
