Gestión de recurrencia por Lotes (Batch)

definición el módulo de gestión de recurrencia por lotes (batch) permite ejecutar cobros masivos sobre suscriptores de tipo manual mediante la carga de un archivo csv en la plataforma en lugar de ejecutar cada cobro de forma individual a través de la api, el operador prepara un archivo estructurado con el detalle de los cobros a procesar y lo sube a la consola la plataforma toma el control de la ejecución, procesa cada registro en background y devuelve un reporte con el resultado de cada operación resuelve la necesidad operativa de ejecutar cobros recurrentes sobre carteras grandes de suscriptores sin requerir integración api por cada cobro ni procesar registro a registro desde sistemas externos es el canal de ingreso batch del módulo de suscripciones manuales la contraparte por archivo del endpoint de ejecución masiva vía api este módulo es especialmente relevante para operadores que gestionan carteras de suscriptores con ciclos de cobro propios —como servicios financieros, seguros, clubes o cualquier modelo de débito periódico— donde la ejecución de cobros se dispara desde un proceso administrativo centralizado y no desde un sistema integrado en tiempo real concepto central del batch de suscripciones canal de ingreso → archivo csv cargado desde la consola de operación ejecución → la plataforma procesa cada registro en background de forma asíncrona resultado → reporte csv descargable con el estado de cada cobro (paid / fail) límite por lote → hasta 5 000 registros por archivo aplicación → exclusivo para suscripciones de tipo manual el módulo de gestión por lotes abstrae la complejidad de coordinar y ejecutar cobros masivos sobre carteras grandes de suscriptores sin requerir integración técnica por cada cobro ni procesamiento secuencial desde sistemas externos la plataforma suga encapsula todo esto en un único archivo csv archivo csv con n registros → carga en consola → procesamiento asíncrono en background cada registro → misma lógica de autorización que una ejecución individual por api cada ejecución → transacción trazable + webhook emitido lote completo → reporte csv con resultado de cada registro descargable desde consola rol dentro de la plataforma dentro de la arquitectura suga, el módulo de gestión por lotes representa el canal de operación batch del ecosistema de suscripciones complementa los canales de ejecución disponibles en el módulo de suscripciones —la ejecución individual por api y la ejecución masiva por api— con un tercer canal orientado a comercioa que trabajan con procesos administrativos basados en archivos ejemplo aseguradoras el módulo no altera la lógica de autorización ni el ciclo de vida de los suscriptores cada registro del lote transita exactamente el mismo flujo que una ejecución manual iniciada por api la diferencia está en el canal de ingreso y en la gestión asíncrona del procesamiento el resultado final —una ejecución registrada, un webhook emitido, un impacto en liquidaciones— es idéntico módulo relacionado relación con gestión por lotes módulo de suscripciones provee las suscripciones de tipo manual y los suscriptores sobre los que opera el lote smart acquiring core procesa cada autorización de cobro del lote contra el procesador o red correspondiente gestión de transacciones registra cada ejecución del lote como una transacción trazable con su propio smartcupón módulo de liquidaciones las ejecuciones aprobadas del lote se incluyen en el ciclo de liquidación al comercio webhooks / notificaciones emite un evento por cada ejecución procesada del lote, aprobada o rechazada consola de operación canal de carga del archivo csv y descarga del reporte de resultados funcionamiento del módulo preparación del archivo el comercio prepara un archivo csv con los cobros a ejecutar cada fila representa un cobro individual sobre un suscriptor específico dentro de una suscripción específica el archivo debe respetar el formato definido por la plataforma, incluyendo las columnas obligatorias y, opcionalmente, las columnas adicionales que enriquecen la descripción y trazabilidad del cobro el archivo no debe superar los 5 000 registros por lote si la cartera a cobrar supera ese límite, el operador debe dividir la ejecución en múltiples archivos no existe una restricción en cuanto al número de lotes que pueden cargarse, pero el sistema procesa cada lote de forma independiente condición previa crítica antes de subir el archivo, el operador debe verificar que los suscriptores incluidos cuenten con un medio de pago activo si un suscriptor no tiene medio de pago asociado al momento de la ejecución, el cobro resultará en fail y quedará registrado como tal en el reporte de respuesta estructura del archivo csv el archivo csv debe contener las siguientes columnas columna tipo descripción subscription requerido uid de la suscripción a la que pertenece el suscriptor subscriber requerido uid del suscriptor al que se le ejecutará el cobro total requerido monto a cobrar en formato xxx xx (punto como separador decimal) reference opcional referencia única del cobro no puede repetirse dentro del lote ni en lotes anteriores description opcional título o descripción de la operación que se mostrará en el comprobante softdescriptor opcional texto que aparecerá en el resumen de cuenta del tarjetahabiente ejemplo de estructura del archivo a subir carga y procesamiento el operador accede a la consola de operación, navega al menú suscripciones y selecciona la opción gestionar lotes desde allí puede ver el historial de lotes cargados (procesando y procesados) y cargar nuevos archivos al subir un nuevo archivo, el operador asigna una descripción al lote para facilitar su identificación posterior la plataforma asigna un id único al lote y comienza el procesamiento en background de forma inmediata el lote queda visible en la lista con el estado procesando consideración operativa crítica el archivo debe subirse el mismo día en que se desea que los cobros sean ejecutados la plataforma inicia la ejecución en el momento de la carga del archivo, no en una fecha programada no existe un mecanismo de programación diferida dentro del módulo de gestión por lotes estados del lote estado descripción procesando el archivo fue recibido y la plataforma está ejecutando los cobros en background no se puede descargar el reporte aún procesado todos los registros del lote fueron procesados el reporte de resultados está disponible para descarga reporte de respuesta una vez que el lote pasa al estado procesado, el operador puede descargar el reporte de respuesta desde la opción descargar reporte el nombre del archivo de reporte incluye el id del lote para facilitar su identificación y archivo el reporte extiende el archivo original con columnas adicionales que informan el resultado de cada cobro columna del reporte descripción couponstatus estado del cobro paid para operaciones aprobadas, fail para intentos rechazados código de estado código numérico del resultado de la operación según la tabla de códigos de estado de la plataforma ejemplo de estructura del reporte de respuesta componentes y funcionalidades principales carga de lotes • carga de archivos csv desde la consola de operación • capacidad de hasta 5 000 registros por archivo • asignación de descripción al lote para identificación operativa • asignación automática de id único por lote • visualización del listado de lotes con estado y fecha procesamiento asíncrono • ejecución en background de cada cobro al momento de la carga del archivo • cada registro del lote transita el mismo flujo de autorización que una ejecución manual por api • emisión de webhook por cada cobro procesado (aprobado o rechazado) • registro de cada ejecución como transacción trazable en el módulo de gestión de transacciones reporte de resultados • reporte csv descargable una vez completado el procesamiento del lote • nombre del reporte incluye el id del lote para trazabilidad • estado por registro paid (aprobado) o fail (rechazado) • código de estado numérico por registro según tabla de códigos de la plataforma validaciones y restricciones • formato de archivo csv con extensión csv • límite de registros 5 000 por archivo • el campo reference debe ser único dentro del lote y no puede repetirse en lotes anteriores • el campo total debe respetar el formato xxx xx con punto como separador decimal • los suscriptores incluidos deben tener medio de pago activo al momento de la ejecución • aplica exclusivamente a suscripciones de tipo manual dimensiones y entidades del módulo entidad descripción lote (batch) unidad de procesamiento masivo conjunto de hasta 5 000 cobros agrupados en un archivo csv con id único asignado por la plataforma archivo de entrada archivo csv preparado por el operador con las columnas subscription, subscriber, total y opcionales registro cada fila del archivo csv representa un cobro individual sobre un suscriptor dentro de una suscripción reporte de respuesta archivo csv generado por la plataforma con el resultado de cada registro del lote (paid / fail + código de estado) suscripción manual tipo de suscripción sobre el que opera el módulo el ciclo de cobro es controlado por el operador, no por el motor automático de la plataforma suscriptor instancia de cliente dentro de una suscripción debe tener medio de pago activo para que el cobro del lote sea ejecutable ejecución resultado del procesamiento de cada registro del lote genera una transacción trazable y un evento webhook integración técnica el módulo de gestión por lotes opera a través de la consola de operación de suga mediante carga manual de archivos no expone un endpoint de api dedicado para la carga del archivo sin embargo, todos los eventos derivados del procesamiento del lote —ejecuciones, resultados, estados— son accesibles a través de los canales estándar de integración de la plataforma canal de carga • acceso consola de operación → menú suscripciones → gestionar lotes • formato archivo csv con extensión csv • límite 5 000 registros por archivo • ejecución inmediata al subir el archivo no existe programación diferida formato del archivo de entrada columnas obligatorias subscription → uid de la suscripción subscriber → uid del suscriptor total → monto en formato xxx xx columnas opcionales reference → referencia única del cobro (no repetible en el lote ni en lotes anteriores) description → descripción de la operación softdescriptor → texto en resumen de cuenta del tarjetahabiente seguimiento de resultados una vez procesado el lote, los resultados son accesibles por dos vías • reporte csv descargable desde la consola con el estado de cada registro (paid / fail + código) • webhooks estándar emitidos por la plataforma para cada ejecución procesada, aprobada o rechazada, integrables con sistemas propios del operador los códigos de estado incluidos en el reporte de respuesta siguen la misma tabla de códigos estándar de la plataforma, consultable en la documentación de referencia de códigos de estado consideraciones operativas condiciones críticas previas a la carga del lote verificar que todos los suscriptores del lote tengan medio de pago activo cargar el archivo el mismo día en que se desea ejecutar los cobros garantizar unicidad del campo reference dentro del lote y respecto a lotes anteriores respetar el formato xxx xx en el campo total (punto como separador decimal) aplicable únicamente a suscripciones de tipo manual flujo operativo flujo — gestión de cobros por lotes 1 operador prepara archivo csv con los cobros del período → columnas obligatorias y opcionales 2 verifica que todos los suscriptores tengan medio de pago activo 3 accede a la consola suscripciones → gestionar lotes → carga el archivo el día de ejecución 4 plataforma asigna id al lote y comienza el procesamiento en background → estado procesando 5 por cada registro smart acquiring core ejecuta la autorización contra el procesador 6 resultado aprobado → ejecución registrada como transacción + webhook emitido (paid) 7 resultado rechazado → ejecución registrada + webhook emitido (fail) 8 lote completo → estado pasa a procesado → reporte csv disponible para descarga 9 operador descarga el reporte y analiza resultados por suscriptor 10 ejecuciones aprobadas se incluyen en el ciclo de liquidación al comercio beneficios y valor operativo dimensión valor que aporta el módulo operación sin integración api permite ejecutar cobros masivos desde la consola sin requerir desarrollo técnico ni integración por cobro procesamiento asíncrono la plataforma gestiona el procesamiento en background sin bloquear la operación del equipo trazabilidad completa cada cobro del lote genera una transacción registrada, un webhook emitido y un registro en el reporte de respuesta simplicidad del formato el archivo csv con seis columnas como máximo es preparable desde cualquier herramienta de gestión de datos control operativo el reporte de respuesta permite identificar rápidamente qué cobros fallaron y tomar acciones sobre esos suscriptores escalabilidad hasta 5 000 cobros por lote con soporte para múltiples lotes simultáneos integración en liquidaciones las ejecuciones aprobadas del lote se integran automáticamente en el ciclo de liquidación de la plataforma qué transmite este módulo el módulo de gestión de cobros por lotes demuestra que la plataforma suga comprende que no todos los comercios que gestionan cobros recurrentes tienen sistemas integrados en tiempo real existen modelos de operación —servicios financieros, gestoras de carteras, operadores sin equipo técnico propio— donde el cobro masivo se gestiona a través de procesos administrativos basados en archivos suga habilita ese modelo sin forzar una integración api que no corresponde a la realidad operativa de esos actores ✔ canal batch nativo para ejecución masiva de cobros sobre suscripciones manuales ✔ operación desde consola sin requerir integración api por cobro ✔ procesamiento asíncrono en background con trazabilidad completa por registro ✔ reporte de resultados descargable con estado y código por cada cobro ejecutado ✔ integración automática de ejecuciones aprobadas en el ciclo de liquidación de la plataforma ✔ formato csv simple y preparable desde cualquier herramienta de gestión de datos