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.







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.





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.



El archivo CSV debe contener las siguientes columnas:





Ejemplo de estructura del archivo a subir:

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.







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:





Ejemplo de estructura del reporte de respuesta:

•       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



•       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 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



•       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





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.



•       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



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



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.











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.