Descripción general
Passinstance gobierna cada pase emitido mediante tres máquinas de estados ortogonales registradas en el modelo Pass:
-
1
pass status (11 valores): Estado funcional de validez comercial que determina si un pase puede instalarse, escanearse o canjearse.
-
2
PassLifecycleStatus(5 etapas): Progresión administrativa de retención y revocación desdeACTIVEhastaDELETED. -
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
1. Los 11 estados comerciales de pass status
| Valor pass status | Resultado de validación en escáner | Renderizado visual y comportamiento en Wallet |
|---|---|---|
DRAFT | Rechazado (INVALID) | El registro existe en la BD antes de firmarse; el enlace de descarga aún no está activo. |
AWAITING_OPT_IN | Rechazado (PENDING) | Creado desde PassFlow o campaña; a la espera de OTP por correo/SMS o confirmación de consentimiento RGPD. |
PENDING_ACTIVATION | Rechazado (PENDING) | Pase emitido en espera de confirmación de pago externa o escaneo de activación en POS. |
GENERATING | Rechazado (PENDING) | El paquete criptográfico .pkpass o el objeto de Google Wallet está siendo compilado por un worker. |
ACTIVE | Aceptado (SUCCESS) | Pase válido y activo apto para escaneo, acumulación de puntos, lectura NFC y notificaciones push. |
INACTIVE | Rechazado (INVALID) | Desactivado temporalmente por un operador (POST /api/v1/batch-pass-operations/deactivate). |
SUSPENDED | Rechazado (INVALID) | Congelado por sospecha de fraude, impago o retención de seguridad; reversible a ACTIVE. |
REDEEMED | Rechazado (ALREADY_USED) | Cupón o entrada de un solo uso ya escaneado y consumido (VOIDED_AFTER_SCAN scan mode). |
EXPIRED | Rechazado (EXPIRED) | La hora actual superó Pass.expirationDate; el código de barras se atenúa en el dispositivo del cliente. |
CANCELLED | Rechazado (ALREADY_VOIDED) | La inscripción o el pedido fue cancelado (p. ej., entrada reembolsada) antes del canje. |
VOIDED | Rechazado (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:
| Etapa | Descripción |
|---|---|
ACTIVE | Estado operativo normal entre pases activos, inactivos o caducados. |
VOIDING | Bloqueo transicional adquirido al solicitar una anulación; encola notificaciones push prioritarias hacia Apple y Google Wallet. |
VOIDED | Revocación finalizada; voidedAt y voidReason quedan registrados de forma permanente en el libro mayor del pase. |
DELETING | Bloqueo transicional adquirido cuando un operador solicita el borrado definitivo del registro; revoca tokens de descarga y desvincula archivos almacenados. |
DELETED | Estado 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 |
|---|---|
NONE | El pase acaba de crearse o no se ha encolado ningún estado de anulación o propagación. |
PENDING | Se 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. |
QUEUED | Existe 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. |
SUCCEEDED | Todos 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/...). |
FAILED | La 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/:idrealiza una eliminación lógica (SOFT, establecearchivedAty libera la unicidad(customerId, externalId)para reemisión conservando los registros de auditoría), mientras queDELETE /api/v1/passes/:id/hardejecuta una purga definitiva (HARD). -
ArtifactStatus(appleArtifactStatus,googleArtifactStatus):NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATEDindica 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: trueen 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 | Ámbito | Descripción |
|---|---|---|
POST /api/v1/passes/:id/deactivate | Pase individual | Cambia temporalmente el estado del pase de ACTIVE a INACTIVE. |
POST /api/v1/passes/voiding/:id/void | Pase individual | Anula (voided: true) o reactiva (voided: false) un pase individual (204 No Content). |
POST /api/v1/passes/voiding/batch-void | Array de pases | Anula o activa varios passIds en una sola petición (request payload). |
POST /api/v1/passes/voiding/template-void | Plantilla completa | Anula masivamente todos los pases activos emitidos bajo un templateId (request payload). |
GET /api/v1/passes/voiding/:id/voiding-history | Pista de auditoría | Devuelve 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
{
"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 Contenten caso de éxito, estableciendo de inmediatostatus = "VOIDED",lifecycleStatus = "VOIDED", y actualizandowalletVoidStatus(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
{
"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
{
"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.
