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

Creación masiva de pases

Sube archivos CSV en Operaciones masivas o por FTP/SFTP, asigna columnas y supervisa el progreso del lote.

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

Panel de trabajos de importación por lotes (Zoom)

Inicia un «New import job» desde el resumen de la plantilla y supervisa las ejecuciones CSV en curso, fallidas y completadas.

Descripción general

Cuando necesite dar de alta a cientos o cientos de miles de titulares de forma simultánea, Passinstance proporciona una canalización asíncrona y tolerante a fallos de ingesta por lotes en CSV impulsada por Batch Jobs API (/api/v1/batch-processing) y colas de workers en segundo plano respaldadas por caché en memoria (background job queue). Los operadores pueden cargar hojas de cálculo UTF-8 desde el panel de control (Operaciones masivas -> Importar pases), activar importaciones FTP/SFTP automatizadas u orquestar programáticamente la canalización CSV de 6 etapas a través de la API REST.

Contadores de trabajos de importación por lotes y botón de nueva importación
Contadores de trabajos de importación por lotes y botón de nueva importación

Arquitectura del sistema: emisión por lotes CSV y canalización de workers en segundo plano

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
EMISIÓN POR LOTES CSV Y CANALIZACIÓN ASÍNCRONA DE WORKERS
ETAPA 01 CARGA CSV EN EL PANEL / API (Batch Jobs API)
1
GET/api/v1/batch-processing/templates/:templateId/sample-csv
2
POST/api/v1/batch-processing (Carga multipart de archivo CSV en UTF-8)
3
POST/api/v1/batch-processing/templates/:templateId/field-mapping-recommendations
ETAPA 02 ASIGNACIÓN DE ESQUEMA Y VALIDACIÓN PREVIA EN SECO (DRY-RUN)
4
PUT/api/v1/batch-processing/:id/field-mapping (Enlazar cabecerasclaves)
5
POST/api/v1/batch-processing/:id/validate
Verifica propiedades personalizadas obligatorias, fechas ISO, tipos numéricos y externalIds
Informa errores de sintaxis o esquema fila por fila antes de persistir
ETAPA 03 CANALIZACIÓN ASÍNCRONA DE WORKERS (caché en memoria)
Procesa en streaming fragmentos CSV validados en transacciones acotadas
Genera registros Pass, serialNumber, authenticationToken y smart links
Compila un informe descargable: GET/api/v1/batch-processing/:id/result.csv

Lista de requisitos previos

Requisitos previos: Antes de iniciar un trabajo de importación masiva por CSV, verifique los siguientes requisitos:

1. La plantilla objetivo (Template) debe estar en estado PUBLISHED.

2. El archivo CSV debe estar codificado en UTF-8, sin delimitadores mal formados ni comillas sin escapar.

3. Incluya las columnas email y/o phone si planea enviar enlaces de descarga de pases automáticamente mediante campañas de Delivery Center tras la generación.

4. Configure el origen de ID externo en la configuración de la plantilla (externalId) si desea una deduplicación idempotente en importaciones repetidas.

Flujo paso a paso de importación CSV (Bulk Pass Wizard)

En el panel de control, en Lotes -> Procesamiento por lotes (/batch-processing), el asistente guía a los operadores a través de cinco etapas (Plantilla -> Cargar CSV -> Asignar campos -> Opciones de envío (opcional) -> Procesar):

  1. 1
    Plantilla: Seleccione la plantilla objetivo PUBLISHED / PRODUCTION (o abra Pases -> Importar directamente desde una plantilla).
  2. 2
    Cargar CSV: Arrastre un archivo CSV en UTF-8 o descargue el CSV de ejemplo dinámico (GET /api/v1/batch-processing/templates/:templateId/sample-csv), precargado con las cabeceras correspondientes a las propiedades personalizadas y campos del sistema de su plantilla (externalId, expirationDate, etc.).
  3. 3
    Asignar campos: Revise las recomendaciones automáticas de asignación de columnas con puntuación de confianza (POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations) que vinculan cabeceras (por ejemplo, Customer_ID, First_Name) a externalId o claves attributes.*.
  4. 4
    Opciones de envío (cuando está habilitado): Elija una plantilla de entrega por correo electrónico o SMS si desea enviar automáticamente los nuevos pases al finalizar.
  5. 5
    Procesar: Valide e inicie el trabajo en la cola en segundo plano (estados de trabajo por lotes: NEW, READY_TO_RUN, INTEGRATION_MAPPING_COMPLETE, SENDOUT_PENDING, RUNNING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELLED, PAUSED) y, a continuación, descargue /result.csv con cada serialNumber, externalId, bundleId y enlace de descarga generados.

Referencia de la API REST de procesamiento por lotes (Batch Jobs API)

Todos los endpoints de trabajos por lotes en CSV están montados bajo /api/v1/batch-processing (admiten tipos de trabajo por lotes CREATE_PASSES, UPDATE_PASSES, DELETE_PASSES, IMPORT_DATA, EXPORT_DATA, MIGRATION y orígenes de datos CSV_UPLOAD, API, SEGMENT, QUERY, MANUAL):

PasoMétodo HTTP y endpointPropósito
1. CSV de ejemploGET /api/v1/batch-processing/templates/:templateId/sample-csvDescarga una plantilla dinámica de cabeceras CSV en UTF-8 adaptada a las propiedades personalizadas de la plantilla.
2. Cargar CSVPOST /api/v1/batch-processingCarga un archivo CSV multipart o una definición de trabajo por lotes en JSON (status: NEW / READY_TO_RUN).
3. Asignación automática de columnasPOST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendationsAnaliza las columnas de cabecera del CSV y devuelve sugerencias de asignación de atributos con puntuación de confianza.
4. Guardar asignaciónPUT /api/v1/batch-processing/:id/field-mappingPersiste en el trabajo el diccionario confirmado de asignación de columnas CSV a atributos.
5. Validación en secoPOST /api/v1/batch-processing/:id/validateEjecuta una validación no destructiva sobre las filas del CSV y devuelve advertencias/errores por fila.
6. Iniciar workerPOST /api/v1/batch-processing/:id/startEncola el trabajo en segundo plano (status: RUNNING) para emitir los pases de forma asíncrona.
7. Exportar resultadosGET /api/v1/batch-processing/:id/result.csvTransmite un informe CSV que añade el passId, el serialNumber, los enlaces de descarga y el estado de cada fila.

Ejemplo: solicitar recomendaciones de asignación de campos

POST /api/v1/batch-processing/templates/tmpl_01hxyz987654321/field-mapping-recommendations Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "csvHeaders": [
    "Customer_ID",
    "First_Name",
    "Last_Name",
    "Loyalty_Points",
    "Card_Expiry"
  ]
}

Respuesta HTTP (200 OK)

JSON
{
  "success": true,
  "data": {
    "recommendations": [
      { "csvColumn": "Customer_ID", "targetField": "externalId", "confidence": 0.98, "matchType": "SYSTEM" },
      { "csvColumn": "First_Name", "targetField": "attributes.firstName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Last_Name", "targetField": "attributes.lastName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Loyalty_Points", "targetField": "attributes.pointsBalance", "confidence": 0.89, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Card_Expiry", "targetField": "expirationDate", "confidence": 0.94, "matchType": "SYSTEM" }
    ]
  },
  "statusCode": 200
}

Ejemplo: confirmar la asignación de campos y validar el trabajo

PUT /api/v1/batch-processing/job_batch_77123/field-mapping Cabeceras: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "duplicateStrategy": "UPSERT_BY_EXTERNAL_ID",
  "mappings": {
    "Customer_ID": "externalId",
    "First_Name": "attributes.firstName",
    "Last_Name": "attributes.lastName",
    "Loyalty_Points": "attributes.pointsBalance",
    "Card_Expiry": "expirationDate"
  }
}

A continuación, valide e inicie el worker de la cola de trabajos en segundo plano:

POST /api/v1/batch-processing/job_batch_77123/validate POST /api/v1/batch-processing/job_batch_77123/start

JSON
{
  "success": true,
  "data": {
    "id": "job_batch_77123",
    "status": "RUNNING",
    "jobType": "CREATE_PASSES",
    "dataSource": "CSV_UPLOAD",
    "totalRows": 5000,
    "processedRows": 0
  },
  "statusCode": 200
}

Resolución de problemas y preguntas frecuentes

¿Cómo compruebo cuándo falla un trabajo de procesamiento masivo?

Cuando una importación asíncrona por lotes en CSV encuentra un problema, inspeccione el estado y los registros del trabajo desde el panel de control o la API REST:

  1. 1
    Panel de trabajos del dashboard: Vaya a Lotes -> Procesamiento por lotes (/batch-processing). Los trabajos finalizados con errores muestran una etiqueta Completado con errores (COMPLETED_WITH_ERRORS), mientras que los trabajos detenidos muestran Fallido (FAILED).
  2. 2
    Descargar registro de errores: Haga clic en la tarjeta del trabajo y seleccione Descargar CSV de errores o consulte GET /api/v1/batch-processing/:id/result.csv. La hoja de cálculo resultante incluye cada fila del CSV original junto con una columna status (SUCCESS, SKIPPED o FAILED) y una columna errorMessage que detalla el fallo (por ejemplo: "Missing required custom property: firstName", "Invalid ISO 8601 date format" o "Duplicate externalId").
  3. 3
    Inspeccionar detalles del trabajo vía API: Llame a GET /api/v1/batch-processing/:id con su clave de API (X-API-Key). La respuesta JSON devuelve el request payload con totalRows, processedRows, successfulRows, failedRows y la matriz errorDetails[] con los índices exactos de fila y códigos de error de validación.
  4. 4
    Comprobación previa al envío: Antes de encolar un trabajo de 100.000 filas, llame siempre a POST /api/v1/batch-processing/:id/validate. Este paso de validación en seco comprueba las asignaciones de cabeceras y los esquemas de atributos sin crear registros en la base de datos, informando errores de sintaxis antes de que arranquen los workers.

¿Por qué mi procesamiento masivo creó menos pases que filas tenía el archivo?

Si el CSV de entrada contenía 5.000 filas pero el trabajo informa que solo se crearon 4.820 pases, revise estos comportamientos verificados de la plataforma:

  1. 1
    Deduplicación por ID externo (duplicateStrategy): Si su plantilla exige unicidad de ID externo y configuró duplicateStrategy en SKIP, las filas que compartan un externalId con un pase activo existente en el espacio de trabajo (o repetido anteriormente en el mismo CSV) se omiten para evitar emisiones duplicadas. Para sobrescribir los pases existentes en su lugar, seleccione duplicateStrategy: "UPSERT_BY_EXTERNAL_ID".
  2. 2
    Filas vacías o en blanco al final del archivo: Los editores de hojas de cálculo (Excel, Google Sheets) suelen exportar filas en blanco finales con comas sobrantes. El analizador CSV de Passinstance descarta automáticamente las filas vacías sin incrementar el contador de pases generados.
  3. 3
    Rechazos de atributos en la validación previa: Las filas con tipos de datos no válidos (como texto no numérico en un atributo numérico, sintaxis de correo electrónico incorrecta o cadenas de fecha ilegibles) fallan la validación individual y se registran en el listado de fallos sin detener todo el trabajo.
  4. 4
    Agotamiento de la cuota de pases activos (PASS_LIMIT_REACHED): Si su espacio de trabajo alcanza el 100 % del límite de pases activos de su plan de suscripción durante el procesamiento, las filas posteriores fallarán con PASS_LIMIT_REACHED. Consulte Configuración de la empresa -> Uso y facturación para comprobar la cuota disponible.

¿Es normal una espera de varias horas en el procesamiento masivo?

  • Velocidades estándar de procesamiento: Las colas de workers en segundo plano de Passinstance suelen generar entre 500 y 2.000 pases por minuto, según si las firmas criptográficas dinámicas .pkpass de Apple Wallet y las imágenes de códigos de barras se generan de forma síncrona o se difieren al momento de la descarga. Un lote de 10.000 pases suele completarse en 5 a 15 minutos.
  • Cuándo es normal que tarde varias horas:

- Volúmenes de ingesta masivos: Las importaciones muy grandes (de 100.000 a más de 500.000 pases) tardan varias horas para mantener estables los pools de conexiones a la base de datos y las colas de caché en memoria sin saturar su espacio de trabajo. - Envíos salientes inmediatos: Si adjuntó una campaña de entrega por correo electrónico o SMS al trabajo por lotes, los correos salientes se regulan conforme a las cuotas de velocidad de la entrega gestionada de correo (por ejemplo, de 14 a 50 correos/segundo) y a los límites de conexión de su servidor SMTP personalizado para proteger la reputación de su dominio.

  • Cuándo un trabajo está detenido o requiere intervención:

- Si un trabajo permanece en NEW o READY_TO_RUN durante horas, el worker nunca se inició. Haga clic en Iniciar trabajo en el panel de control o invoque POST /api/v1/batch-processing/:id/start. - Si el estado del trabajo es PAUSED, reanude la ejecución mediante POST /api/v1/batch-processing/:id/resume.

¿Puede un pase caducar un número fijo de días después de su emisión?

Sí. Passinstance admite tanto fechas fijas de caducidad en el calendario como periodos dinámicos de validez relativa:

  1. 1
    Duración dinámica relativa (validityInDays): En el editor visual, dentro de Validez y caducidad, establezca la estrategia de caducidad en Duración dinámica y especifique el número de días (por ejemplo, 30, 90 o 365). Cuando cada pase se crea mediante importación CSV, API o formulario PassFlow, Passinstance calcula automáticamente:

expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).

  1. 2
    Anulación de caducidad por fila: Si distintos clientes tienen fechas únicas de finalización de contrato, asigne una columna CSV con marcas temporales ISO 8601 (por ejemplo, 2027-06-30T23:59:59Z) directamente al campo del sistema expirationDate durante la etapa Asignar campos.
  2. 3
    Ampliación posterior a la emisión: Puede ampliar o modificar las fechas de caducidad en miles de pases activos en cualquier momento mediante Operaciones masivas.

¿Cómo migro los datos de clientes existentes desde otro proveedor de monederos o un CRM?

Migrar desde sistemas heredados (como Airship, PassKit, Braze o una base de datos interna) a Passinstance es sencillo:

  1. 1
    Exporte los registros heredados: Exporte su base de datos actual de clientes a un archivo CSV en UTF-8 que incluya nombres de socios, datos de contacto, saldos de puntos, nivel y números históricos de tarjeta.
  2. 2
    Configure la plantilla de destino: En Passinstance, cree una plantilla equivalente. Configure las propiedades personalizadas (por ejemplo, memberId, pointsBalance, tier) y la simbología del código de barras (QR, Aztec, Code 128 o PDF417).
  3. 3
    Asigne identificadores históricos a externalId: Asigne su número de tarjeta heredado o UUID de cliente al campo externalId de Passinstance. Esto garantiza continuidad 1:1 y evita registros duplicados.
  4. 4
    Ejecute la ingesta por lotes CSV: Cargue el archivo CSV mediante el asistente de 5 pasos. Configure la estrategia de importación en UPSERT_BY_EXTERNAL_ID para que cualquier registro preexistente se actualice de forma controlada.
  5. 5
    Transición fluida para los titulares: Si su organización mantiene el mismo Apple Pass Type Identifier y certificado de firma, los clientes recibirán pases actualizados sin tener que eliminar sus tarjetas actuales del monedero. Como alternativa, envíe nuevos enlaces inteligentes de descarga mediante Delivery Center usando el marcador {passDownloadUrl}.

¿Cómo limpio los pases cuando finaliza un evento?

Una vez concluido un concierto, partido deportivo o campaña estacional, mantenga la higiene de su espacio de trabajo y libere cuota activa:

  1. 1
    Localice la cohorte del evento: En el panel de control, en Pases (/passes), filtre por la plantilla del evento o use el panel de búsqueda avanzada para filtrar por expirationDate < today.
  2. 2
    Seleccione todos los pases coincidentes: Utilice la casilla de StickySelectionToolbar para seleccionar la vista actual y haga clic en el aviso para seleccionar todos los pases que coinciden con el filtro en todas las páginas.
  3. 3
    Ejecute la anulación / desactivación masiva: Haga clic en Acciones masivas -> Desactivar / Anular (POST /api/v1/batch-pass-operations/deactivate). Esto cambia el estado del pase a VOIDED, muestra un aviso de código de barras invalidado en la pantalla de bloqueo e impide el canje en escáneres, preservando al mismo tiempo el historial de escaneos y los datos de asistencia para informes de cumplimiento.
  4. 4
    Borrado lógico (DELETING -> SOFT): Si desea retirar los pases caducados del evento de la vista activa del panel, seleccione Acciones masivas -> Eliminar. Los pases con borrado lógico no computan contra los límites de pases activos de su suscripción y liberan su externalId para futuros usos, al tiempo que siguen disponibles en las exportaciones históricas de auditoría.

Para operaciones directas por lotes con matrices JSON sin archivos CSV, consulte Operaciones masivas. Para distribuir por correo electrónico los pases recién importados, consulte Entrega por correo electrónico y SMS.

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