Documentação

Español

Português
English

Español

Português
English

Appearance

Registro de cobros para usuarios ​

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 pantalla crea cobros recurrentes mensuales que debitan al usuario dentro de una ventana de fechas (inicio y fin). Es la herramienta para cuotas mensuales, suscripciones, tarifas administrativas y cualquier débito que necesite repetirse durante varios meses contra el saldo de un cliente.

A diferencia de la Nómina (que paga al usuario en nombre de la empresa) y de los Cobros automáticos (perpetuos, por día del mes), este cobro tiene un período definido: al guardar, el backend calcula cuántos meses caben entre la fecha de inicio y la fecha de fin y programa una cuota por mes. Un job en el FinanceManagementService (FMS) recorre esas cuotas pendientes y las aplica 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 botón no aparece, aunque el enum sea correcto).
  • Licencia/Feature: Ninguna específica.
  • Dependencias de otras pantallas: el usuario destino debe existir y estar APPROVED — el cobro debita su saldo (billetera cripto o cuenta digital BRL). El ID ingresado en el modal es el userIdTo (identificador interno del usuario), no el correo electrónico.

Paso a paso ​

  1. Acceda a Cobros → Registro de cobros para usuarios (ruta /manage-recurrences).
  2. El listado muestra todos los cobros ya registrados, en orden descendente de creación, con el correo electrónico del usuario resuelto a partir del userIdTo.
  3. Haga clic en Crear nuevo cobro para abrir el modal de registro.
  4. Complete ID del usuario, Descripción, Moneda, Valor, Fecha de inicio y Fecha fin (formato dd/mm/aaaa).
  5. Confirme con Guardar. El backend graba el cobro y genera las cuotas mensuales entre las dos fechas.
  6. Para eliminar un cobro, use el ícono de papelera en la fila; para abrir el usuario, use el ícono de ojo (visibilidad), que navega a los detalles del usuario.

Campos (modal de registro) ​

CampoQué es¿Obligatorio?Efecto en el sistema/backend
ID del usuarioIdentificador interno (userIdTo) del cliente que será debitadoSíGraba user_id_to en recurrently_charges (FMS). Es el ID interno, no el correo electrónico. Define de quién sale el valor cada mes.
DescripciónTexto libre que aparece en el extracto/transacciónSíSe convierte en el transactionDescription de la transacción de billetera o el descriptivo del crédito BMS. Máx. 250 caracteres en el formulario / 140 en la base de datos.
MonedaSímbolo de la moneda del cobro (ej.: BRL, tBRL, símbolo de token)SíGraba unit_of_money_requested. Determina el canal de pago: si es BRL, el débito se realiza mediante cuenta digital (BMS giveUserBalance contra la cuenta principal); cualquier otro valor se trata como transacción de billetera cripto a la walletForBonus.
ValorMonto a debitar por cuotaSí (> 0)Graba amount_requested. Tratado como BigNumber en el procesamiento (sin redondeo). El mismo valor se replica en cada cuota mensual.
Fecha de inicioPrimera competencia del cobro (dd/mm/aaaa)SíGraba creation_date. Es la fecha de la primera cuota.
Fecha finÚltima competencia (dd/mm/aaaa)Sí (≥ inicio)Graba expiration_date. El backend calcula el número de meses entre inicio y fin y crea una cuota (recurrently_charges_payments) por mes. Si el intervalo es menor a ~1 mes, no se genera ninguna cuota mensual adicional.
Cómo se generan las cuotas

Al guardar, el FMS calcula la diferencia en días entre inicio y fin y la convierte en meses (días / 30). Para cada mes, crea un registro de cuota con applied = false y la fecha de ese mes. El scheduler de recurrencias recorre las cuotas pendientes y aplica cada una en su fecha, marcando applied = true al concluir.

Acciones y modales ​

  • Crear nuevo cobro: abre el modal RecurrencyModalComponent. Valida que todos los campos estén completos, valor > 0 y fecha fin ≥ fecha de inicio antes de habilitar Guardar.
  • Guardar: envía a POST /v1/recurrently/create. Si tiene éxito, cierra el modal y recarga el listado.
  • Eliminar (papelera): llama a POST /v1/recurrently/delete con el recurrencyId. Elimina el cobro y las cuotas mensuales aún no aplicadas. Tras la confirmación, la página se recarga.
  • Ver usuario (ojo): navega a los Detalles del usuario destinatario.

Reglas de negocio / precauciones ​

Atención

  • El campo ID del usuario es el identificador interno (userIdTo), no el correo electrónico. Obténgalo en los Detalles del usuario.
  • La Moneda determina el canal: BRL debita mediante la cuenta digital; cualquier otro símbolo debita mediante la billetera cripto. Ingresar la moneda incorrecta hace que el débito salga del lugar equivocado (o falle por saldo/ruta inexistente).
  • El número de cuotas depende exclusivamente del intervalo inicio → fin. Fechas muy próximas pueden no generar ninguna cuota mensual.
  • Eliminar un cobro borra las cuotas pendientes, pero no revierte las cuotas ya aplicadas.
  • Valores financieros: tratados como BigNumber en el scheduler — sin redondeo; verifique los decimales de la moneda/token.
  • Idempotencia: cada cuota se aplica con un externalId igual al id de la cuota. Si el servicio reprocesa tras un crash, FinLib retorna E00021 ("already processed") — esto es éxito, no error: el valor ya fue debitado y la cuota se marca como aplicada.
  • Estado APPROVED: el usuario destino debe estar aprobado para que el débito (billetera o cuenta digital) sea efectivo.

Ejemplos ​

Escenario 1 — Suscripción mensual de 6 meses en BRL

El operador crea un cobro para el usuario u-1234, descripción "Cuota mensual Plan Pro", moneda BRL, valor 49,90, inicio 01/06/2026 y fin 01/12/2026. Al guardar, el FMS genera 6 cuotas mensuales (junio a diciembre). Cada mes el scheduler debita R$ 49,90 de la cuenta digital del usuario a la cuenta principal mediante BMS, y marca la cuota como aplicada. En diciembre, cerrada la ventana, no quedan cuotas pendientes.

Escenario 2 — Tarifa administrativa en token utilitario

Cobro en moneda UTK (token utilitario), valor 10, inicio 01/06/2026, fin 01/09/2026. Como la moneda no es BRL, cada cuota se convierte en una transacción de billetera que mueve 10 UTK de la billetera del usuario a la walletForBonus configurada. Son 3 cuotas (junio, julio, agosto). Útil para descontar tarifas en token sin tocar la cuenta bancaria.

Escenario 3 — Corrección por eliminación antes del primer débito

El operador nota que ingresó el valor incorrecto justo después de registrar. Como ninguna cuota fue aplicada aún, hace clic en la papelera: el cobro y todas las cuotas pendientes son eliminados. Luego crea el cobro nuevamente con el valor correcto. No se realizó ningún débito en el intervalo.

Pantallas relacionadas ​