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

Actualizar pases existentes

Descubre cómo los cambios de servidor envían alertas silenciosas APNs en Apple y parches REST en Google Wallet.

En esta guía

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.

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
TUBERÍA DE ACTUALIZACIÓN Y PROPAGACIÓN AL WALLET
ETAPA 01 FUENTES QUE DISPARAN LA MUTACIÓN
Individual: PATCH/api/v1/passes/:id o POST/api/v1/passes/upsert-by-external-id
Lote JSON: POST/api/v1/batch-pass-operations/update
Publicar plantilla: POST/api/v1/templates/:id/publish (propagateUpdates)
Escáner / POS: POST/api/v1/scans / POST/v1/pos/redeem / /api/v1/reader/redeem
ETAPA 02 CONFIRMACIÓN EN BASE DE DATOS Y TRANSICIÓN DE PROPAGACIÓN
1
Incrementa revisión del pase y registra historial en pass audit log
2
Fija walletVoidStatus (WalletPropagationStatus): NONEPENDINGQUEUED
3
Encola trabajo de propagación en background job queue (cola wallet-propagation)
Registros dispositivo Apple Wallet
ETAPA 03A
1
Apple Push Delivery envía push HTTP/ {} a cada dispositivo registrado
2
iOS despierta y consulta:GET/v1/devices/.../registrations
3
iOS descarga nuevo .pkpass firmadoGET/v1/passes/:typeId/:serial
Objeto en nube Google Wallet
ETAPA 03B acío| | 1. Google Wallet Sync ejecu
PATCH REST autenticado en walletobjects/v1/...
2
Google Cloud envía el estado actualizado directo a Android mediante Google Play Services
ETAPA 04 TELEMETRÍA FINAL Y ACTUALIZACIÓN DE ESTADO DE PROPAGACIÓN
walletVoidStatus (WalletPropagationStatus): SUCCEEDED o FAILED

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 estadoSignificado y estado operativo
NONEEl pase se acaba de crear o no hay ninguna propagación visible para el monedero en cola.
PENDINGSe 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.
QUEUEDDespachado 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.
SUCCEEDEDLa 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.
FAILEDLa 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/publish con propagateUpdates: true distribuye trabajos de propagación entre los pases activos vinculados a esa plantilla (filtrable con activePassesOnly: true). Ejecute siempre previamente GET /api/v1/templates/:id/publish-risk-check para revisar cambios críticos y su impacto potencial.

Endpoints de API para actualizar pases

MétodoRuta del endpointDescripción
PATCH/api/v1/passes/:idActualiza 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-idCrea 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/updateActualiza los passIds seleccionados en una única petición por lotes (request payload) y encola los trabajos de propagación.
POST/api/v1/templates/:id/publishPromueve 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

JSON
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):

JSON
{
  "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)

JSON
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 .pkpass más reciente.
  • Supresión de pases anulados: Por defecto, los pases en estado VOIDED o EXPIRED omiten envíos promocionales rutinarios salvo que esté activado updateVoidedExpiredPasses: true en la plantilla.

Consulte Notificaciones push, Ver y actualizar pases y Versiones de plantilla y publicación para ver flujos relacionados.

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.