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

Operaciones en lote

Ejecuta acciones masivas sobre cohortes filtradas: actualización múltiple, anulación, borrado y exportación.

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

Pestaña Passes y Acciones masivas (Ampliado)

Tras importar en bloque, usa Passes, filtros y Bulk actions para inspeccionar o actualizar las tarjetas generadas.

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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
OPERACIONES MASIVAS DE PASES Y PROPAGACIÓN A MONEDEROS
ETAPA 01 BARRA MASIVA DEL PANEL / API (Batch Operations API)
Selección de cohortes (StickySelectionToolbar / Panel de filtros / Pass IDs)
POST/api/v1/batch-pass-operations/update (operation: "update")
POST/api/v1/batch-pass-operations/upsert (Clave en externalId)
POST/api/v1/batch-pass-operations/activate (operation: "activate")
POST/api/v1/batch-pass-operations/deactivate (operation: "deactivate")
POST/api/v1/batch-pass-operations/delete (request payload)
POST/api/v1/batch-pass-operations/validate (Validación previa al envío)
ETAPA 02 MOTOR AISLADO DE VALIDACIÓN Y EJECUCIÓN POR ELEMENTO
Elimina claves protegidas del inquilino (customerId, tenantId, createdBy)
Prevalida atributos vía preValidateAttributes (omite obligatorios al editar)
Normaliza atributos vía normalizeAttributes
Devuelve request payload: { success, data, message, errors, warnings }
ETAPA 03A COLA DE WORKERS APNs HTTP/2 REGULADA
Cola en segundo plano: push-notifications
Pool de conexiones HTTP/2 persistentes
El rate-limiting evita errores 429
Push silencioso despierta al iPhone para descargar el pase actualizado
ETAPA 03B PROPAGACIÓN DE CLASES GOOGLE WALLET
Cambio de plantilla: PATCH a la
Issuer Class
Sincronización instantánea a TODOS los pases Android
PATCH individual al Pass Object para atributos dinámicos por pase

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) y not_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" AND pointsBalance < 500 AND expirationDate < 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. 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.

  1. 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/apns mantiene 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ónEndpoint de la APIDTO y comportamiento
Creación por lotesPOST /api/v1/batch-pass-operations/createrequest payload (passes[], máx. 1.000 elementos). Emite nuevos pases con externalId y bundleId opcionales.
Actualización por lotesPOST /api/v1/batch-pass-operations/updaterequest payload (operation: "update", passIds[], updateData, bundleOptions opcional).
Upsert por lotesPOST /api/v1/batch-pass-operations/upsertrequest payload (operation: "upsert", passData[]) con clave de inquilino (customerId, externalId).
Activación por lotesPOST /api/v1/batch-pass-operations/activaterequest payload (operation: "activate", passIds[]) que pasa los pases al estado ACTIVE.
Desactivación (anulación) por lotesPOST /api/v1/batch-pass-operations/deactivaterequest payload (operation: "deactivate", passIds[]) que pasa los pases a SUSPENDED / INACTIVE e invalida los códigos de barras.
Eliminación por lotesPOST /api/v1/batch-pass-operations/deleterequest payload (passIds[]) que transiciona los pases por DELETING -> borrado lógico (archivedAt: new Date()).
Agrupación por lotesPOST /api/v1/bundles/batch-createAgrupa los ID de pases seleccionados en contenedores pass bundle compartidos (Pass.bundleId, hasta 10 pases por paquete).

Importante: Revise siempre los campos errors y warnings en request payload. Cuando validateBatchOperation detecta filas no válidas, el controlador devuelve success: false con diagnósticos detallados de error por elemento en errors[].


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

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)

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

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)

JSON
{
  "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": [...] } mediante request 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 marcadorCanónico / AliasEjemplo de salida resuelta
{passDownloadUrl}Canónicohttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{smartLink}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{downloadUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{passUrl}Aliashttps://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6
{walletDownloadUrl}Alias dinámicoEnlace 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:

VariableDescripció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. 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. 2
    Estructura estándar de errores: Los elementos fallidos se comunican en errors[] con passId, el mensaje error y errorCode:
JSON
{
     "passId": "pass_01j8k9m2n3p4q5r6",
     "error": "Attribute 'pointsBalance' must be a valid number",
     "errorCode": "ATTR_VALIDATION"
   }
  1. 3
    Registro de auditoría del espacio de trabajo: Cada operación masiva genera una entrada en pass audit log y 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.

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