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.

Arquitectura del sistema: emisión por lotes CSV y canalización de workers en segundo plano
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 estadoPUBLISHED.2. El archivo CSV debe estar codificado en UTF-8, sin delimitadores mal formados ni comillas sin escapar.
3. Incluya las columnas
phonesi 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
Plantilla: Seleccione la plantilla objetivo
PUBLISHED/PRODUCTION(o abra Pases -> Importar directamente desde una plantilla). -
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
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) aexternalIdo clavesattributes.*. -
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
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.csvcon cadaserialNumber,externalId,bundleIdy 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):
| Paso | Método HTTP y endpoint | Propósito |
|---|---|---|
| 1. CSV de ejemplo | GET /api/v1/batch-processing/templates/:templateId/sample-csv | Descarga una plantilla dinámica de cabeceras CSV en UTF-8 adaptada a las propiedades personalizadas de la plantilla. |
| 2. Cargar CSV | POST /api/v1/batch-processing | Carga 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 columnas | POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations | Analiza las columnas de cabecera del CSV y devuelve sugerencias de asignación de atributos con puntuación de confianza. |
| 4. Guardar asignación | PUT /api/v1/batch-processing/:id/field-mapping | Persiste en el trabajo el diccionario confirmado de asignación de columnas CSV a atributos. |
| 5. Validación en seco | POST /api/v1/batch-processing/:id/validate | Ejecuta una validación no destructiva sobre las filas del CSV y devuelve advertencias/errores por fila. |
| 6. Iniciar worker | POST /api/v1/batch-processing/:id/start | Encola el trabajo en segundo plano (status: RUNNING) para emitir los pases de forma asíncrona. |
| 7. Exportar resultados | GET /api/v1/batch-processing/:id/result.csv | Transmite 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
{
"csvHeaders": [
"Customer_ID",
"First_Name",
"Last_Name",
"Loyalty_Points",
"Card_Expiry"
]
}
Respuesta HTTP (200 OK)
{
"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
{
"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
{
"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
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
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 columnastatus(SUCCESS,SKIPPEDoFAILED) y una columnaerrorMessageque detalla el fallo (por ejemplo: "Missing required custom property: firstName", "Invalid ISO 8601 date format" o "Duplicate externalId"). -
3
Inspeccionar detalles del trabajo vía API: Llame a
GET /api/v1/batch-processing/:idcon su clave de API (X-API-Key). La respuesta JSON devuelve elrequest payloadcontotalRows,processedRows,successfulRows,failedRowsy la matrizerrorDetails[]con los índices exactos de fila y códigos de error de validación. -
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
Deduplicación por ID externo (
duplicateStrategy): Si su plantilla exige unicidad de ID externo y configuróduplicateStrategyenSKIP, las filas que compartan unexternalIdcon 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, seleccioneduplicateStrategy: "UPSERT_BY_EXTERNAL_ID". -
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
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
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 conPASS_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
.pkpassde 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
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,90o365). Cuando cada pase se crea mediante importación CSV, API o formulario PassFlow, Passinstance calcula automáticamente:
expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).
-
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 sistemaexpirationDatedurante la etapa Asignar campos. -
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
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
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
Asigne identificadores históricos a
externalId: Asigne su número de tarjeta heredado o UUID de cliente al campoexternalIdde Passinstance. Esto garantiza continuidad 1:1 y evita registros duplicados. -
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_IDpara que cualquier registro preexistente se actualice de forma controlada. -
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
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 porexpirationDate < today. -
2
Seleccione todos los pases coincidentes: Utilice la casilla de
StickySelectionToolbarpara 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
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 aVOIDED, 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
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 suexternalIdpara 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.
