Recurrencias (Gestionar cobros recurrentes)

Requisitos previos de acceso

• Permiso (módulo): processPaymentQueue
• Licencia/Feature: Ninguna específica.
• Contenedor del menú: GENERAL → grupo Cobros (ruta /manage-recurrences)

Qué es / cuándo usar

Esta es la pantalla de listado y gestión de cobros recurrentes mensuales que debitan a los usuarios durante un período definido (fecha de inicio → fecha de fin). Es el punto de entrada del grupo Cobros (la ruta raíz /manage-recurrences del menú): aquí el operador visualiza todos los cobros recurrentes registrados, crea nuevos y elimina los existentes.

El registro en sí (campos del formulario, generación de cuotas, carril BRL × token) está documentado en detalle en Registro de cobros para usuarios — esta página se enfoca en el listado, columnas y acciones de la pantalla.

A diferencia de los Cobros automáticos (perpetuos, ejecutados por día del mes) y la Nómina (que paga al usuario en nombre de la empresa), los cobros recurrentes tienen una ventana cerrada: al guardar, el backend genera una cuota por mes entre las dos fechas y un job del FinanceManagementService (FMS) aplica cada cuota en la fecha correspondiente.

Requisitos previos

• Permiso: processPaymentQueue registrado para el rol del operador (permiso doble — enum CPM en el backend + módulo dinámico en la BD; sin el módulo en la BD el ítem de menú/botón no aparece, aunque el enum sea correcto).
• Licencia/Feature: Ninguna específica.
• Dependencias con otras pantallas: el usuario destino de cada cobro debe existir y estar APPROVED — el cobro debita su saldo (billetera cripto o cuenta digital BRL). El listado resuelve el email de cada cobro cruzando el userIdTo con la lista de usuarios (CPM).

Paso a paso

1. Acceda a Cobros → Recurrencias (ruta /manage-recurrences).
2. La página carga en paralelo los cobros recurrentes (GET /v1/recurrently) y la lista de usuarios, y muestra la tabla en orden decreciente de creación (proveniente del backend).
3. Para crear, haga clic en Crear nuevo cobro — abre el modal de registro (RecurrencyModalComponent). Los campos y reglas están en Registro de cobros para usuarios.
4. Para inspeccionar el cliente de una fila, haga clic en el ícono de ojo (visibilidad): navega a los Detalles del usuario.
5. Para eliminar un cobro, haga clic en el ícono de papelera.

Filtros y columnas

La pantalla es un listado (sin filtros de búsqueda): muestra todos los cobros recurrentes registrados, paginados (5/10/25/100 por página, predeterminado 25).

Columna	Qué muestra	Origen del dato
Fecha de inicio	Primer período de facturación del cobro	creationDate (creation_date)
Fecha de fin	Último período de facturación	expirationDate (expiration_date)
Descripción	Texto que va al extracto/transacción	description
Monto	Importe debitado por cuota	amountRequested (amount_requested) — tratado como BigNumber en el procesamiento
Moneda	Símbolo de la moneda del cobro	unitOfMoneyRequested (unit_of_money_requested) — define el carril (BRL vía cuenta digital × token vía billetera)
Usuario	Email del cliente debitado	resuelto a partir del userIdTo cruzando con la lista de usuarios (CPM); no se almacena en el propio cobro
Acciones	Íconos de papelera (eliminar) y ojo (abrir usuario)	—

La columna Usuario muestra el email, pero lo que el cobro registra es el userIdTo (ID interno). Si el usuario no se encuentra en la lista, el email aparece vacío — el cobro sigue siendo válido.

Acciones y modales

• Crear nuevo cobro: abre el RecurrencyModalComponent. Al guardar, envía POST /v1/recurrently/create; en caso de éxito, la lista se recarga. Ver campos y validaciones en Registro de cobros para usuarios.
• Eliminar (papelera): llama a POST /v1/recurrently/delete con el recurrencyId. Elimina el cobro y las cuotas mensuales aún no aplicadas; la página se recarga tras el éxito. No hay modal de confirmación — el clic ya dispara la eliminación.
• Ver usuario (ojo): navega a /users/informations/details del destinatario (Detalles del usuario).

Reglas de negocio / consideraciones

Atención

• Eliminar no tiene confirmación: un clic en la papelera ya elimina el cobro recurrente y las cuotas pendientes. Verifique la fila (usuario, descripción, monto) antes de proceder.
• Eliminar borra las cuotas pendientes, pero no revierte las cuotas ya aplicadas (débitos ya realizados).
• La Moneda define el carril de débito: BRL debita por la cuenta digital; cualquier otro símbolo debita por la billetera cripto. Es un dato elegido en el registro — verifíquelo en la columna Moneda al revisar un cobro existente.
• El listado no filtra/busca: en bases de datos grandes, use la paginación para localizar el cobro recurrente.

• Valores financieros: el Monto es tratado como BigNumber en el scheduler del FMS — sin redondeo; verifique los decimales de la moneda/token.
• Idempotencia: cada cuota se aplica con un externalId igual al id de la cuota. En reprocesamiento tras un fallo, FinLib devuelve E00021 ("already processed") — esto es éxito, no un error: el monto ya fue debitado y la cuota permanece marcada como aplicada.
• Estado APPROVED: el usuario destino debe estar aprobado para que el débito (billetera o cuenta digital) sea efectuado.

Pantallas relacionadas

• Registro de cobros para usuarios (modal de creación y generación de cuotas)
• Cobros automáticos
• Nómina
• Colas de Pago
• Volver al índice Financiero