Descripción general
Una vez que haya delimitado una cohorte objetivo de pases en el panel de control mediante los filtros rápidos o el panel de filtros avanzados AND/OR (StickySelectionToolbar), utilice el menú Acciones masivas de la barra de herramientas de Pases —o invoque Batch Operations API (/api/v1/batch-pass-operations/*) mediante la API REST— para ejecutar operaciones estructuradas en formato de matriz sobre hasta 1.000 pases por llamada. A diferencia de las cargas multipart de archivos CSV (/api/v1/batch-processing), /api/v1/batch-pass-operations/* procesa directamente cargas útiles JSON y devuelve errors y warnings por elemento en request payload.
Al actualizar miles o decenas de miles de pases emitidos simultáneamente, Passinstance desacopla las mutaciones en la base de datos de la entrega push a los monederos móviles. Los cambios se persisten de inmediato en la base de datos, mientras que las actualizaciones se difunden a los dispositivos con Apple Wallet a través de conexiones HTTP/2 APNs agrupadas con limitación de tasa, y a los dispositivos con Google Wallet mediante la propagación instantánea de la clase de emisor (Issuer Class) o mediante parches REST individuales del objeto de pase (Pass Object).
Arquitectura del sistema: operaciones masivas, limitación de colas y propagación a monederos
Filtrado de cohortes objetivo de pases
Antes de ejecutar operaciones masivas, los administradores aíslan exactamente la cohorte de audiencia que desean modificar:
Filtros rápidos y panel de filtros avanzados AND/OR
En el panel de control, en Pases (/passes):
-
Filtro de plantilla: Limita las acciones a una plantilla de pase o a un diseño de tarjeta de campaña específico.
-
Filtro de estado: Filtra por estado del ciclo de vida (
ACTIVE,INACTIVE,SUSPENDED,EXPIRED,VOIDED). -
Filtro de instalación: Distingue entre
active_only(instalado en al menos un dispositivo),inactive_only(desinstalado) ynot_registered(enlaces de descarga no reclamados). -
Panel de búsqueda avanzada (
Advanced Filter panel): Combina varios atributos mediante lógica AND/OR (por ejemplo,tier == "Gold"ANDpointsBalance < 500ANDexpirationDate < 2027-01-01). -
Barra de selección fija (
StickySelectionToolbar):
- Haga clic en la casilla principal para seleccionar la página actual (hasta 100 pases). - Haga clic en el aviso emergente para seleccionar todos los pases coincidentes en todas las páginas (por ejemplo, "Seleccionar los 4.850 pases que coinciden con este filtro").
Selección de cohortes mediante API
A través de la API REST, obtenga los UUID de los pases objetivo con POST /api/v1/passes/query-builder o POST /api/v1/passes/search y, a continuación, pase los identificadores resultantes a /batch-pass-operations/*.
Actualización de miles de pases emitidos
Actualizar grandes flotas de pases emitidos exige equilibrar el rendimiento de escritura en la base de datos con los estrictos límites de conexión de las pasarelas de notificaciones push de los monederos móviles.
Operaciones directas con matrices frente a la ingesta por lotes en CSV
Passinstance ofrece dos vías diferenciadas para las actualizaciones masivas según el volumen:
-
1
Operaciones directas con matrices JSON (
POST /api/v1/batch-pass-operations/update):
- Ideal para un máximo de 1.000 pases por solicitud HTTP. - Acepta una matriz passIds y un único diccionario updateData. - Respuesta HTTP síncrona que devuelve el estado, los errores y las advertencias individuales de cada pase.
-
2
Canalización asíncrona por lotes en CSV (
/api/v1/batch-processing):
- Ideal para entre 1.000 y más de 100.000 pases. - Cargue un archivo CSV que contenga identificadores únicos (externalId o serialNumber) y los atributos modificados. - Establezca la operación en UPDATE_PASSES o UPSERT. - Las colas de workers en segundo plano procesan las filas de forma asíncrona en transacciones acotadas de 50 filas en la base de datos, con seguimiento del progreso en tiempo real y registros descargables de resultados (result.csv).
Limitación HTTP/2 y agrupación de conexiones APNs en Apple Wallet
Al actualizar pases de Apple Wallet, Passinstance difunde notificaciones push que indican a los dispositivos iOS que se despierten en segundo plano y descarguen el paquete .pkpass actualizado desde la API de Passinstance:
-
Notificaciones push silenciosas: Las notificaciones de pases se envían con
content-available: 1. No muestran ventanas emergentes intrusivas en la pantalla de bloqueo salvo que se hayan configurado mensajes localizados de cambio de campo (por ejemplo, "Tu puerta cambió a B12"). -
Flujos persistentes HTTP/2: El servicio
@passinstance/apnsmantiene conexiones HTTP/2 persistentes y agrupadas con los servidores push de Apple (api.push.apple.com:443). En lugar de cerrar y recrear negociaciones TLS para cada destinatario, los flujos se multiplexan sobre las conexiones activas. -
Limitación de tasa adaptativa y regulación de colas:
- Las notificaciones salientes pasan por colas de trabajos en segundo plano (push-notifications, individual-push-notifications, silent-push-notifications). - Notification Rate Limiter y Notification Deduplication supervisan el flujo de respuestas de Apple. - Si APNs devuelve 429 TooManyRequests o contrapresión a nivel de conexión, los workers reducen la concurrencia y aplican un retroceso exponencial, evitando la invalidación de tokens y el bloqueo de IP.
Actualizaciones de clase frente a PATCH de objeto en Google Wallet
Google Wallet utiliza una arquitectura jerárquica que separa la Pass Class (la definición maestra de la plantilla) del Pass Object (la instancia individual de cada titular):
-
Actualizaciones visuales y de campos a nivel de plantilla (Issuer Class):
Cuando se publica un cambio global en una plantilla (por ejemplo, cambiar el logotipo de cabecera, el color de fondo o las condiciones del programa) dirigido a todas las tarjetas sin texto personalizado (!hasPersonalizedMessage), Passinstance invoca Google Wallet class sync en template.service.ts. Esto envía un único PATCH REST a la API de Google Wallet para actualizar la Issuer Class. Dado que todos los pases emitidos de Google Wallet hacen referencia a esta clase principal, los servidores en la nube de Google propagan inmediatamente la actualización a todos los pases Android activos de forma simultánea, sin generar miles de solicitudes API individuales.
-
Actualizaciones de atributos específicos por titular (Pass Object):
Cuando los atributos individuales varían en cada pase (como saldos de puntos individuales, ascensos de nivel o nombres personalizados), Passinstance ejecuta llamadas HTTP PATCH individuales sobre el Pass Object específico de Google Wallet (POST /batch-pass-operations/update).
Reglas de validación y seguridad de atributos
El servicio de actualización por lotes (batch-pass-operations.service.ts) aplica una integridad de datos estricta:
-
Aislamiento de inquilinos: Los campos protegidos (
customerId,tenantId,createdBy,templateId) se eliminan automáticamente de las cargas entrantes. Las actualizaciones no pueden modificar la titularidad del pase ni reasignar plantillas principales. -
Validación parcial de atributos (
preValidateAttributes): Al actualizar pases existentes (isUpdate = true), se omiten las comprobaciones de atributos obligatorios. Puede modificar una única propiedad personalizada (por ejemplo,pointsBalance) sin reenviar los campos existentes que no cambian. -
Normalización de atributos: Se recortan los espacios sobrantes en las cadenas de texto, los números se convierten a flotantes o enteros y las fechas se normalizan a ISO-8601 UTC.
Operaciones masivas compatibles en el panel y en la API
| Operación | Endpoint de la API | DTO y comportamiento |
|---|---|---|
| Creación por lotes | POST /api/v1/batch-pass-operations/create | request payload (passes[], máx. 1.000 elementos). Emite nuevos pases con externalId y bundleId opcionales. |
| Actualización por lotes | POST /api/v1/batch-pass-operations/update | request payload (operation: "update", passIds[], updateData, bundleOptions opcional). |
| Upsert por lotes | POST /api/v1/batch-pass-operations/upsert | request payload (operation: "upsert", passData[]) con clave de inquilino (customerId, externalId). |
| Activación por lotes | POST /api/v1/batch-pass-operations/activate | request payload (operation: "activate", passIds[]) que pasa los pases al estado ACTIVE. |
| Desactivación (anulación) por lotes | POST /api/v1/batch-pass-operations/deactivate | request payload (operation: "deactivate", passIds[]) que pasa los pases a SUSPENDED / INACTIVE e invalida los códigos de barras. |
| Eliminación por lotes | POST /api/v1/batch-pass-operations/delete | request payload (passIds[]) que transiciona los pases por DELETING -> borrado lógico (archivedAt: new Date()). |
| Agrupación por lotes | POST /api/v1/bundles/batch-create | Agrupa los ID de pases seleccionados en contenedores pass bundle compartidos (Pass.bundleId, hasta 10 pases por paquete). |
Importante: Revise siempre los campos
errorsywarningsenrequest payload. CuandovalidateBatchOperationdetecta filas no válidas, el controlador devuelvesuccess: falsecon diagnósticos detallados de error por elemento enerrors[].
Referencia de operaciones programáticas por lotes (request payload)
1. Upsert por lotes de pases (POST /api/v1/batch-pass-operations/upsert)
Ideal para sincronizaciones con CRM o recálculos de niveles de fidelización indexados por externalId:
Solicitud HTTP
POST /api/v1/batch-pass-operations/upsert Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "upsert",
"passData": [
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44910",
"attributes": {
"firstName": "Marcus",
"lastName": "Vance",
"pointsBalance": 1800,
"memberTier": "Platinum"
}
},
{
"templateId": "tmpl_01hxyz987654321",
"externalId": "crm_usr_44911",
"attributes": {
"firstName": "Hannah",
"lastName": "Abbott",
"pointsBalance": 250,
"memberTier": "Silver"
}
}
]
}
Respuesta HTTP (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"externalId": "crm_usr_44910",
"serialNumber": "PI-GOLD-2026-44910",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"externalId": "crm_usr_44911",
"serialNumber": "PI-GOLD-2026-44911",
"passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m9z8y7x6w5"
}
],
"message": "Successfully upserted 2 passes",
"errors": [],
"warnings": []
}
2. Actualización por lotes de pases (POST /api/v1/batch-pass-operations/update)
Aplica un parche a los passIds seleccionados con un objeto updateData compartido y bundleOptions opcionales:
POST /api/v1/batch-pass-operations/update Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json
{
"operation": "update",
"passIds": [
"pass_01j8k9m2n3p4q5r6",
"pass_01j8k9m9z8y7x6w5"
],
"updateData": {
"expirationDate": "2028-03-31T23:59:59Z",
"attributes": {
"seasonalOffer": "2x Winter Bonus Points"
}
}
}
Respuesta HTTP (200 OK)
{
"success": true,
"data": [
{
"id": "pass_01j8k9m2n3p4q5r6",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
},
{
"id": "pass_01j8k9m9z8y7x6w5",
"status": "ACTIVE",
"updatedAt": "2026-11-16T12:00:00.000Z"
}
],
"message": "Successfully updated 2 passes",
"errors": [],
"warnings": []
}
3. Activación, desactivación o eliminación por lotes de pases
-
Activar:
POST /api/v1/batch-pass-operations/activate({ "operation": "activate", "passIds": [...] }) -
Desactivar:
POST /api/v1/batch-pass-operations/deactivate({ "operation": "deactivate", "passIds": [...] }) -
Eliminar:
POST /api/v1/batch-pass-operations/delete({ "passIds": [...] }medianterequest payload)
Integración de entrega: ¿qué marcador inserta el enlace del pase? ({passDownloadUrl})
¿Qué marcador inserta el enlace del pase?
Cuando encadena operaciones masivas con notificaciones automatizadas por correo electrónico o SMS, Passinstance proporciona un motor flexible de sustitución de marcadores (pass-url-placeholder.util.ts). El token de marcador canónico es {passDownloadUrl}.
Marcador canónico y alias admitidos
El marcador oficial y canónico es {passDownloadUrl}. Passinstance también admite alias retrocompatibles:
| Token de marcador | Canónico / Alias | Ejemplo de salida resuelta |
|---|---|---|
{passDownloadUrl} | Canónico | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{smartLink} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{downloadUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{passUrl} | Alias | https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6 |
{walletDownloadUrl} | Alias dinámico | Enlace contextual que redirige según el sistema operativo del cliente |
Flexibilidad de formato: Passinstance normaliza automáticamente la sintaxis de dobles llaves
{{passDownloadUrl}}, el formato snake_case{pass_download_url}y PascalCase{PassDownloadUrl}al token canónico.
Botones directos de acción de monedero e indicadores condicionales
En plantillas HTML adaptables de correo electrónico, puede construir botones directos de monedero de un solo toque en lugar de depender exclusivamente de la página intermedia de PassFlow:
| Variable | Descripción |
|---|---|
{appleWalletUrl} | Flujo directo de descarga binaria .pkpass que inicia la instalación nativa en Apple Wallet en Safari de iOS. |
{googleWalletUrl} | Enlace profundo directo de guardado en Google Wallet (https://pay.google.com/gp/v/save/...). |
{samsungWalletUrl} | Enlace profundo directo de guardado en Samsung Wallet. |
{walletButtonText} | Etiqueta de botón contextual ("Add to Apple Wallet", "Save to Google Wallet" o "Download my pass"). |
{showAppleWalletButton} | Indicador booleano (true/false) que señala si los activos de Apple Wallet están configurados. |
{showGoogleWalletButton} | Indicador booleano que señala si la integración con Google Wallet está activa. |
Fallos parciales, gestión de errores y registro de auditoría
Al invocar operaciones por lotes, las solicitudes no fallan por completo si un subconjunto de elementos contiene errores:
-
1
Aislamiento de fallos por elemento: En
updateBatchPasses, cada pase se procesa dentro de un bloque try-catch aislado. Un fallo en la fila 42 (por ejemplo, un formato de fecha no válido) no impide que las filas 1–41 ni 43–100 se completen correctamente. -
2
Estructura estándar de errores: Los elementos fallidos se comunican en
errors[]conpassId, el mensajeerroryerrorCode:
{
"passId": "pass_01j8k9m2n3p4q5r6",
"error": "Attribute 'pointsBalance' must be a valid number",
"errorCode": "ATTR_VALIDATION"
}
-
3
Registro de auditoría del espacio de trabajo: Cada operación masiva genera una entrada en
pass audit logy en el registro de auditoría del espacio de trabajo (GET /api/v1/audit-log/export.csv), registrando el ID del actor, la dirección IP, el tipo de operación, el recuento de pases afectados y la marca temporal.
Para importaciones por lotes basadas en archivos CSV, consulte Creación masiva de pases. Para anulaciones masivas en toda una plantilla, consulte Ciclo de vida y estados de los pases.
