Documentação

Español

Português
English

Español

Português
English

Appearance

Nómina ​

Requisitos previos de acceso

  • Permiso (módulo): processPayroll (controla los botones en la UI) + manageCompanyCharges (crear/editar/eliminar) o viewCompanyCharges (solo listar) — exigidos por el backend
  • Licencia/Feature: Ninguna específica.
  • Contenedor del menú: GENERAL → grupo Cobros (ruta /manage-payroll)

Qué es / cuándo usar ​

La Nómina agenda pagos mensuales recurrentes de la empresa a un usuario/empleado — es la operación inversa de los cobros al usuario: aquí el dinero sale de la cuenta del propietario de la empresa (userIdFrom) y entra en la del empleado (userIdTo), cada mes, en el día configurado, hasta la competencia final.

Úsela para salarios, pro-labore, becas, traspasos fijos y cualquier pago periódico a colaboradores. Cada entrada genera un agendamiento mensual; un scheduler en el CustomerProfileService (CPM) se ejecuta periódicamente y procesa cada cuota pendiente — vía cuenta digital (cuando la moneda es BRL y el recurso DIGITAL_BANKING_CHARGES está habilitado) o vía transacción de billetera (token, o BRL sin el recurso de banking).

Requisitos previos ​

  • Permiso: processPayroll registrado para el rol (habilita los botones Agregar pago, editar y eliminar en la UI). El backend valida manageCompanyCharges para mutaciones y viewCompanyCharges/manageCompanyCharges para listar. Permiso doble — enum CPM + módulo dinámico en la BD.
  • Licencia/Feature: Ninguna específica. El comportamiento de pago en BRL depende de que el recurso DIGITAL_BANKING_CHARGES esté activado en el tenant.
  • Dependencias de otras pantallas: el empleado debe existir y tener billetera/cuenta válidas; el propietario de la empresa (owner) es resuelto automáticamente por el backend como pagador. El usuario destino debe estar APPROVED.

Paso a paso ​

  1. Acceda a Cobros → Nómina (ruta /manage-payroll).
  2. Use la búsqueda para filtrar la lista por nombre o correo electrónico (filtro local).
  3. Haga clic en Agregar pago para abrir el modal.
  4. Ingrese el Correo electrónico del empleado, Descripción, Día (1–31), Mes y año del último pago y Monto.
  5. Confirme. El sistema valida el correo (busca al usuario por la billetera), calcula la fecha del primer pago y la fecha de vencimiento, y guarda el agendamiento.
  6. Para modificar, use el ícono de lápiz; para eliminar, el de papelera (abre una confirmación en bottom-sheet).

Campos (modal de agendamiento) ​

CampoQué es¿Obligatorio?Efecto en el sistema/backend
Correo electrónicoCorreo del empleado a pagarSí (correo válido)La pantalla busca al usuario mediante getUserByEmailWallet. Si no existe, muestra error y no guarda. El id retornado se convierte en el userIdTo del agendamiento.
DescripciónIdentificación del pago (ej.: "Salario Junio")Sí (alfanumérico)Guarda description; aparece en el extracto/transacción.
DíaDía del mes en que ocurre el pagoSí (1–31)Define el día de recurrencia. Regla: si el día elegido ya pasó en el mes actual, el primer pago se agenda para el mes siguiente; días inexistentes (ej.: 31 en mes corto) se ajustan al último día del mes.
Mes / Año del último pagoCompetencia final de la nóminaSíCompone la expirationDate. El sistema impide fechas en el pasado (validación errorInLastDate).
MontoCantidad pagada por mesSíGuarda amountRequested. Tratado como BigNumber en el procesamiento. Mostrado en el listado con la moneda fiduciaria del tenant.

La moneda predeterminada de las llamadas de nómina es BRL. El agendamiento hereda los campos de inicio (creationDate, calculada a partir del Día) y fin (expirationDate, a partir de Mes/Año).

Acciones y modales ​

  • Agregar pago: abre el UserPaymentScheduleModalComponent. Solo habilita confirmar con formulario válido, correo existente y fecha final no pasada → POST /v1/company-charges/createAdmin. El backend define el pagador (userIdFrom) como el owner de la empresa.
  • Editar (lápiz): abre el mismo modal prellenado → POST /v1/company-charges/updateAdmin.
  • Eliminar (papelera): abre un bottom-sheet de confirmación; al confirmar, llama a POST /v1/company-charges/deleteAdmin y recarga la página.

Step-up / MFA

Las operaciones de nómina son movimientos financieros sensibles. Según la configuración del tenant, las acciones de pago pueden exigir step-up (re-autenticación contraseña + MFA, header X-Step-Up-Token, ventana de 5 min). Si se solicita, complete el re-login antes de que la operación sea enviada.

Reglas de negocio / consideraciones ​

Atención

  • El correo electrónico debe corresponder a un usuario existente — de lo contrario la pantalla bloquea el guardado.
  • La fecha final no puede estar en el pasado; la pantalla valida e impide confirmar.
  • El Día define la primera competencia: días ya vencidos en el mes mueven el primer pago al mes siguiente; 29/30/31 en meses cortos se ajustan al último día.
  • La nómina paga al empleado (sale del owner). No la confunda con cobros que debitan al usuario.

Movimiento financiero recurrente

Cada cuota de la nómina transfiere dinero real del owner al empleado. Revise el monto, el día y la competencia final antes de guardar — las cuotas ya pagadas no son revertidas por la eliminación.

  • Valores financieros: tratados como BigNumber en el scheduler — sin redondeo; verifique los decimales de la moneda/token.
  • Idempotencia: cada cuota usa externalId igual al id del agendamiento de pago. En reprocesamiento tras un crash, FinLib retorna E00021 ("already processed") — éxito, no error: el monto ya fue pagado y la cuota se marca como aplicada.
  • Estado APPROVED: el empleado debe estar aprobado para recibir (billetera o cuenta digital).

Ejemplos ​

Escenario 1 — Salario mensual en BRL vía cuenta digital

Empresa con DIGITAL_BANKING_CHARGES habilitado registra al empleado joao@empresa.com, descripción "Salario", día 5, último pago Diciembre/2026, monto R$ 4.500,00. Si hoy es día 10, el primer pago cae en julio (el día 5 ya pasó). Cada mes hasta diciembre, el scheduler (CPM) acredita R$ 4.500,00 de la cuenta del owner a la cuenta digital de João vía BMS giveUserBalance.

Escenario 2 — Pro-labore en token

El empleado recibe en token (moneda distinta de BRL, o con DIGITAL_BANKING_CHARGES desactivado). Cada cuota se convierte en una transacción de billetera del owner a la billetera del colaborador, por el monto y descripción definidos. Útil cuando el pago se realiza en activo digital y no por cuenta bancaria.

Escenario 3 — Ajuste del monto de un colaborador

RR.HH. aumentó el salario. El operador abre la entrada mediante el lápiz, ajusta el Monto y confirma. El agendamiento se actualiza (updateAdmin) y las próximas cuotas usan el nuevo monto; las cuotas ya pagadas permanecen tal como estaban.

Pantallas relacionadas ​