Skip to content
Guía del Centro de ayuda · Gestión de pasesFase de incorporación 4
6 min de lecturaVerificado 2026-11-16

Ciclo de vida y estados del pase

Comprende Creado, No instalado, Instalado, Caducado y Anulado junto con su impacto en facturación y escaneo.

En esta guía

Recorridos visuales interactivos

Abrir en la guía de 6 fases

Inspecciona las pantallas reales del panel y las anotaciones ampliadas de esta guía.

Enfoque de interfaz ampliado
Elementos clave de la interfaz

Detalle de estado de registro en Wallet en vivo (Zoom)

Haz clic en el icono de Apple Wallet o Google Wallet de cualquier fila para verificar registros activos, eliminaciones e historial de instalación.

Descripción general

Passinstance gobierna cada pase emitido mediante tres máquinas de estados ortogonales registradas en el modelo Pass:

  1. 1
    pass status (11 valores): Estado funcional de validez comercial que determina si un pase puede instalarse, escanearse o canjearse.
  2. 2
    PassLifecycleStatus (5 etapas): Progresión administrativa de retención y revocación desde ACTIVE hasta DELETED.
  3. 3
    WalletPropagationStatus (5 etapas): Estado de sincronización asíncrona en la nube que supervisa la entrega push hacia APNs y Google Wallet.

Arquitectura del sistema: máquinas de estados de ciclo de vida y propagación al monedero

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
MÁQUINA DE ESTADOS DEL PASE Y PROPAGACIÓN AL WALLET
ETAPA 01
1
ESTADO COMERCIAL (pass status) [DRAFT] / [AWAITING_OPT_IN] / [PENDING_ACTIVATION]
[GENERATING][ACTIVE] <[INACTIVE] / [SUSPENDED] [REDEEMED] [EXPIRED] [CANCELLED] / [VOIDED]
ETAPA 02
2
PROGRESIÓN DE CICLO DE VIDA (PassLifecycleStatus) [ACTIVE][VOIDING][VOIDED][DELETING][DELETED]
ETAPA 03
3
TUBERÍA DE SINCRONIZACIÓN EN LA NUBE (WalletPropagationStatus) [NONE][PENDING][QUEUED][SUCCEEDED] (o [FAILED] + Reintento)

1. Los 11 estados comerciales de pass status

Valor pass statusResultado de validación en escánerRenderizado visual y comportamiento en Wallet
DRAFTRechazado (INVALID)El registro existe en la BD antes de firmarse; el enlace de descarga aún no está activo.
AWAITING_OPT_INRechazado (PENDING)Creado desde PassFlow o campaña; a la espera de OTP por correo/SMS o confirmación de consentimiento RGPD.
PENDING_ACTIVATIONRechazado (PENDING)Pase emitido en espera de confirmación de pago externa o escaneo de activación en POS.
GENERATINGRechazado (PENDING)El paquete criptográfico .pkpass o el objeto de Google Wallet está siendo compilado por un worker.
ACTIVEAceptado (SUCCESS)Pase válido y activo apto para escaneo, acumulación de puntos, lectura NFC y notificaciones push.
INACTIVERechazado (INVALID)Desactivado temporalmente por un operador (POST /api/v1/batch-pass-operations/deactivate).
SUSPENDEDRechazado (INVALID)Congelado por sospecha de fraude, impago o retención de seguridad; reversible a ACTIVE.
REDEEMEDRechazado (ALREADY_USED)Cupón o entrada de un solo uso ya escaneado y consumido (VOIDED_AFTER_SCAN scan mode).
EXPIREDRechazado (EXPIRED)La hora actual superó Pass.expirationDate; el código de barras se atenúa en el dispositivo del cliente.
CANCELLEDRechazado (ALREADY_VOIDED)La inscripción o el pedido fue cancelado (p. ej., entrada reembolsada) antes del canje.
VOIDEDRechazado (ALREADY_VOIDED)Invalidado permanentemente vía Pass Voiding API; establece "voided": true en pass.json de Apple y STATE_EXPIRED/INACTIVE en Google Wallet.

2. Las 5 etapas de PassLifecycleStatus

La columna lifecycleStatus coordina la revocación segura multipaso y la limpieza en base de datos sin dejar objetos huérfanos en los monederos de los usuarios:

EtapaDescripción
ACTIVEEstado operativo normal entre pases activos, inactivos o caducados.
VOIDINGBloqueo transicional adquirido al solicitar una anulación; encola notificaciones push prioritarias hacia Apple y Google Wallet.
VOIDEDRevocación finalizada; voidedAt y voidReason quedan registrados de forma permanente en el libro mayor del pase.
DELETINGBloqueo transicional adquirido cuando un operador solicita el borrado definitivo del registro; revoca tokens de descarga y desvincula archivos almacenados.
DELETEDEstado lógico de eliminación o purga finalizada previa al borrado por RGPD.

3. walletVoidStatus (WalletPropagationStatus), modos de eliminación y artefactos

Passinstance realiza el seguimiento de la entrega asíncrona de push en la nube, la semántica de eliminación y la compilación de artefactos mediante columnas y enums dedicados de Passinstance database en Pass:

walletVoidStatus (WalletPropagationStatus)

Cada vez que se envía una transición de anulación o estado hacia Apple APNs o Google Wallet, Pass.walletVoidStatus supervisa el progreso de entrega:

Etapa (WalletPropagationStatus)Descripción
NONEEl pase acaba de crearse o no se ha encolado ningún estado de anulación o propagación.
PENDINGSe ha confirmado una actualización de campo o transición de ciclo de vida en database y espera ser recogida por el despachador de propagación.
QUEUEDExiste un trabajo activo en background job queue en cola para transmitir la notificación APNs HTTP/2 o la petición PATCH de Google Wallet.
SUCCEEDEDTodos los dispositivos registrados u objetos en la nube confirmaron la actualización (en Apple Wallet, el dispositivo descargó la versión .pkpass más reciente mediante GET /v1/passes/...).
FAILEDLa entrega encontró un error en destino (p. ej., token APNs anulado o límite de cuota en Google API); apto para reintento.

PassDeletionMode y ArtifactStatus

  • PassDeletionMode (SOFT | HARD): DELETE /api/v1/passes/:id realiza una eliminación lógica (SOFT, establece archivedAt y libera la unicidad (customerId, externalId) para reemisión conservando los registros de auditoría), mientras que DELETE /api/v1/passes/:id/hard ejecuta una purga definitiva (HARD).
  • ArtifactStatus (appleArtifactStatus, googleArtifactStatus): NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATED indica si el paquete criptográfico u objeto en la nube de cada plataforma está compilado y al día.

Invariante importante de facturación y ciclo de vida en Wallet

Importante: Anular o caducar un pase rechaza futuras validaciones de escáner y marca visualmente la tarjeta como inválida o atenuada en el monedero del usuario, pero Apple iOS y Google Android no permiten que servidores de terceros eliminen por la fuerza un pase del dispositivo del cliente sin acción del usuario. En Apple Wallet, los pases anulados suprimen actualizaciones en pantalla de bloqueo salvo que se active updateVoidedExpiredPasses: true en la plantilla. Un pase instalado sigue contando como registro activo de dispositivo hasta que el cliente lo elimine de su monedero o finalice la baja del dispositivo.

API de desactivación y anulación de pases (Passes API / Pass Voiding API)

Passinstance expone desactivación reversible (POST /api/v1/passes/:id/deactivate) y endpoints formales de anulación bajo /api/v1/passes/voiding (aceptando VoidingReason: EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER):

EndpointÁmbitoDescripción
POST /api/v1/passes/:id/deactivatePase individualCambia temporalmente el estado del pase de ACTIVE a INACTIVE.
POST /api/v1/passes/voiding/:id/voidPase individualAnula (voided: true) o reactiva (voided: false) un pase individual (204 No Content).
POST /api/v1/passes/voiding/batch-voidArray de pasesAnula o activa varios passIds en una sola petición (request payload).
POST /api/v1/passes/voiding/template-voidPlantilla completaAnula masivamente todos los pases activos emitidos bajo un templateId (request payload).
GET /api/v1/passes/voiding/:id/voiding-historyPista de auditoríaDevuelve los eventos cronológicos de anulación y reactivación del pase.

Ejemplo: anular un pase individual (request payload)

POST /api/v1/passes/voiding/pass_01j8k9m2n3p4q5r6/void Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Order refunded via Shopify webhook #SH-99412",
    "sendPushNotification": true,
    "pushNotificationMessage": "This pass has been voided following your order refund.",
    "updateGoogleWallet": true
  }
}

Estado HTTP: Devuelve 204 No Content en caso de éxito, estableciendo de inmediato status = "VOIDED", lifecycleStatus = "VOIDED", y actualizando walletVoidStatus (WalletPropagationStatus: NONE -> PENDING -> QUEUED -> SUCCEEDED) conforme se ejecutan las notificaciones push en segundo plano.

Ejemplo: anulación por lotes de varios pases (request payload)

POST /api/v1/passes/voiding/batch-void Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "passIds": [
    "pass_01j8k9m2n3p4q5r6",
    "pass_01j8k9m2n3p4q5r7"
  ],
  "voided": true,
  "options": {
    "reason": "EXPIRED",
    "customReason": "Expired seasonal VIP cohort",
    "sendPushNotification": true
  }
}

Ejemplo: anular todos los pases de una plantilla (request payload)

POST /api/v1/passes/voiding/template-void Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Summer 2026 promotional campaign concluded",
    "sendPushNotification": true
  }
}

Consulte Operaciones por lotes para flujos de activación, desactivación y eliminación basados en arrays, o Pases activos y límites de uso para las reglas de medición de capacidad.

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