--- audiencia: usuario screen_key: comisiones titulo: Comisiones y Liquidaciones (Vendedores, Cobradores y Supervisores) aliases: - comisiones - comision vendedor - comision cobrador - comision supervisor - liquidacion comisiones - liquidaciones vendedores - liquidacion supervisor - eliminar comision - equipo supervisor - asignar vendedor cobrador - generar comisiones historicas - recalcular comision supervisor --- # Comisiones y Liquidaciones Cubre cómo la empresa paga comisiones a sus **vendedores**, **cobradores** y **supervisores**: dónde se configura cada uno, cómo se generan las comisiones, cómo se arman los equipos, cómo se liquidan y qué auditoría queda. ## Dónde está esto en el menú > Ojo: "Vendedores y Cobradores" **no es un módulo propio del sidebar** — es una pestaña dentro de **Contactos**. Y las pantallas de Comisiones/Liquidaciones no viven ahí: quedaron en el sidebar **Finanzas** (ítem que abre `/finanzas`) porque comparten administración con Tesorería/Rendiciones. Ver `guia-contactos.md`. - `Contactos → Vendedores y Cobradores` → sub-pestaña **Equipo** — alta y mantenimiento de vendedores/cobradores. Define el % o monto fijo de comisión. - `Contactos → Vendedores y Cobradores` → sub-pestaña **Supervisores** — alta de supervisores y asignación de su equipo. - **Zonas de Cobranza**: existe un componente (`ZonasCobranzaList`) pero **no está enlazado a ningún tab ni ruta del menú actual** — no es accesible hoy desde la UI. - `Finanzas → Comisiones` → tab **Vendedores / Cobradores** — resumen, detalle, generación histórica y eliminación de comisiones. - `Finanzas → Comisiones` → tab **Supervisores** — generar por período, recalcular, liquidar y eliminar comisiones de supervisor. - `Finanzas → Liquidaciones` — panel unificado con liquidaciones de vendedores/cobradores y supervisores, anulación y comprobante PDF. Permisos reales (submódulos `COBRANZAS`): `COB_COM_COMISION_VER` (ver comisiones), `COB_COM_COMISION_GENERAR` (generar históricas / por período), `COB_COM_LIQUIDACION_VER`, `COB_COM_LIQUIDACION_PAGAR`, `COB_COM_LIQUIDACION_ANULAR`, `COB_ASG_ASIGNACION_VER` / `COB_ASG_ASIGNACION_CREAR` (asignación de cartera). El alta/edición de % y equipos en Contactos usa `COB_CBR_COBRADOR_VER` / `_CREAR` / `_EDITAR`. --- ## 1. Conceptos generales - **Vendedor**: persona que registra ventas (facturas). Cobra comisión por **venta**. - **Cobrador**: persona que cobra recibos. Cobra comisión por **cobranza**. - **Vendedor/Cobrador "ambos"**: una misma persona puede tener rol de vendedor y de cobrador, con porcentajes independientes para cada concepto. - **Supervisor**: persona que tiene a cargo un **equipo** de vendedores y/o cobradores. Cobra un porcentaje sobre las ventas y cobros del equipo, calculado **por período**. - **Equipo de un supervisor**: lista de vendedores/cobradores asignados al supervisor (tabla `supervisor_vendedores_cobradores`). - **Cliente con dirección supervisada**: una `cliente_direccion` puede tener un `supervisor_id` propio. Tiene **prioridad** sobre el equipo del vendedor para decidir a qué supervisor le suma la venta. ### Tipos de comisión | `tipo` | Cuándo se devenga | Quién la cobra | |---|---|---| | `venta` | Al confirmar una factura con vendedor asignado | Vendedor | | `cobranza` | Al confirmar un recibo con cobrador asignado | Cobrador | | (supervisor) | Manual por período | Supervisor (ver §4) | ### Estados de la comisión (vendedor/cobrador y supervisor) | Estado | Significado | |---|---| | `pendiente` | Recién generada, todavía no liquidada. Puede eliminarse. | | `aprobada` | Estado intermedio reservado. Hoy el flujo va directo `pendiente → liquidada`. | | `liquidada` | Ya forma parte de una liquidación pagada. No puede eliminarse. | | `cancelada` | Descartada sin pago. | ### Estados de la liquidación | Estado | Significado | |---|---| | `pendiente` | Liquidación creada pero aún no pagada. | | `pagada` | Pagada al colaborador. Genera asiento contable. | | `anulada` | Revertida. Las comisiones incluidas vuelven a `pendiente`. | > Todos los estados y tipos viven en el enum central `src/components/_standards/enums/estados.js` (`ESTADO_COMISION`, `ESTADO_LIQUIDACION`, `TIPO_COMISION`, `TIPO_BENEFICIARIO`). La UI nunca usa strings sueltos para estados. --- ## 2. Configuración de Vendedores y Cobradores `Contactos → Vendedores y Cobradores → Equipo → Nuevo`. Campos relevantes para comisiones: | Campo | Para qué sirve | |---|---| | Tipo (`vendedor`, `cobrador`, `ambos`) | Determina qué comisiones se le generan. | | `comision_venta` (%) | % aplicado al monto neto de la factura. | | `comision_cobranza` (%) | % aplicado al monto del recibo. | | `comision_porcentaje` (%) | % por defecto, usado si los dos anteriores están en blanco. | | `comision_fija` (₲) | Monto fijo que se suma por cada operación (no reemplaza al %). | | Activo | Si está OFF, no se le generan más comisiones. | > Si tanto el % como el monto fijo están en 0, no se genera comisión y la operación queda registrada como "sin comisión configurada" en el log de generación. --- ## 3. Configuración de Supervisores `Contactos → Vendedores y Cobradores → Supervisores → Nuevo`. Campos relevantes: | Campo | Para qué sirve | |---|---| | Nombre, apellido, código | Identificación. | | `comision_ventas` (%) | % sobre el total de ventas del equipo en el período. | | `comision_cobros` (%) | % sobre el total de cobros del equipo en el período. | | Activo | Si está OFF, no aparece en la generación de comisiones. | ### Asignar equipo Dentro de la ficha del supervisor, sección **Equipo**: - Botón **Asignar** abre un selector multiselección de vendedores/cobradores activos. - Cada asignación crea una fila en `supervisor_vendedores_cobradores`. - Botón ❌ por fila para **desasignar**. - Un mismo vendedor/cobrador puede pertenecer a **un solo supervisor a la vez** (la asignación a un nuevo supervisor reemplaza la anterior — verificar antes de mover). ### Supervisor de la dirección del cliente En `Clientes → ficha → Direcciones`, cada dirección puede tener un `supervisor_id`. Si se carga, esa dirección queda **clavada** a ese supervisor: cualquier venta a esa dirección le sumará a él **independientemente** del equipo del vendedor. --- ## 4. Cómo se generan las comisiones ### 4.1 Comisión de venta (vendedor) Se crea automáticamente al confirmar una factura que: - Tiene `vendedor_id` asignado. - El vendedor está activo. - El vendedor tiene `%` o monto fijo configurado. Cálculo: ``` monto_base = total neto de la factura (sin IVA si configuración lo separa) monto_comision = (monto_base × % aplicado) / 100 + monto_fijo estado = "pendiente" ``` ### 4.2 Comisión de cobranza (cobrador) Se crea automáticamente al confirmar un recibo que: - Tiene `cobrador_id` asignado. - El cobrador está activo y con comisión configurada. ``` monto_base = monto total del recibo monto_comision = (monto_base × % cobranza) / 100 + monto_fijo estado = "pendiente" ``` ### 4.3 Generación histórica de comisiones de venta Botón **Generar comisiones históricas** (`Finanzas → Comisiones → tab Vendedores / Cobradores`): - Recorre `asignacion_facturas` con vendedor asignado. - Para cada factura **que no tiene comisión** (`comisiones` no existe para esa combinación `factura_id + vendedor_cobrador_id + tipo='venta'`), la crea. - Es **idempotente**: nunca duplica. - Sirve para reprocesar facturas confirmadas antes de configurar el % del vendedor, o para arreglar huecos. > **No regenera comisiones de cobranza**. Las de cobranza nacen únicamente al confirmar el recibo. Si borrás una de cobranza no hay forma de recrearla sin tocar el recibo original. ### 4.4 Comisión de supervisor (por período) `Finanzas → Comisiones → tab Supervisores → Generar comisión`: 1. Elegir supervisor. 2. Definir `periodo_desde` y `periodo_hasta`. 3. (Opcional) cargar observaciones. 4. **Vista previa**: muestra el cálculo sin persistir. Útil para verificar antes de generar. 5. **Generar**: crea la comisión en `comisiones_supervisores` con `estado=pendiente`. #### Cálculo del total del equipo El sistema recorre las facturas y recibos del período aplicando este orden de precedencia para decidir si "es del supervisor": 1. **Por dirección del cliente** (`cliente_direccion.supervisor_id = supervisor_id`) — caso prioritario. 2. **Por equipo del vendedor**: si la dirección del cliente no tiene supervisor pero `factura_cab.vendedor_id` pertenece al equipo del supervisor → suma como fallback. Cálculo final: ``` total_ventas = suma de facturas elegibles del período total_cobros = suma de recibos elegibles del período comision_ventas = total_ventas × comision_ventas% / 100 comision_cobros = total_cobros × comision_cobros% / 100 total_comision = comision_ventas + comision_cobros ``` El detalle por factura/recibo queda guardado en el snapshot de la comisión y se ve con el botón 👁. --- ## 5. Trabajar con comisiones de vendedor/cobrador `Finanzas → Comisiones → tab Vendedores / Cobradores`. ### Filtros - Período (Mes actual / Mes anterior / Trimestre / Año). - Vendedor/Cobrador (autocomplete, "Todos" para no filtrar). - Moneda. ### KPIs - Total Ventas del período. - Total Cobranzas del período. - Comisiones generadas (suma de `monto_comision` en el período y moneda). ### Tabla resumen Una fila por vendedor/cobrador con: tipo (chip), ventas, cobranzas, % comisión, comisión generada, estado consolidado. Click en una fila → abre el **diálogo de detalle**. ### Diálogo de detalle por persona Columnas: | Columna | Detalle | |---|---| | Fecha | Fecha del documento (factura o recibo). | | Tipo | Chip "Venta" (azul) / "Cobranza" (violeta). | | Documento | Número de factura (`est-pun-numero`) o de recibo. | | Cliente | Razón social / nombre fantasía. | | **Supervisor (dirección)** | A quién le sumó esa venta. Ver §5.1. | | Monto base | Base del cálculo. | | % | Porcentaje aplicado (si aplica). | | Fijo | Monto fijo aplicado (si aplica). | | Comisión | Monto generado. | | Estado | Chip de estado por enum. | | Acciones | Papelera roja si está pendiente — ver §5.2. | #### 5.1 Columna "Supervisor (dirección)" Sirve para rastrear por qué una venta sumó (o no) a un supervisor: - Chip **azul** ("info") con ícono `user-check` → el supervisor está clavado en la dirección del cliente. - Chip **gris** con ícono `users` → el supervisor viene del equipo del vendedor (fallback). - "—" → ni la dirección ni el vendedor tienen supervisor asociado. #### 5.2 Eliminar una comisión individual - Solo visible si el estado de la comisión es `pendiente` **y** no tiene `liquidacion_id`. - Pide confirmación. - Queda auditada (ver §8). - Si está liquidada: *"No se puede eliminar una comisión liquidada. Anulá la liquidación primero."* > **No existe** borrado masivo por período. Se decidió no incluirlo porque las comisiones de cobranza no son regenerables; un borrado masivo dejaría huecos imposibles de reconstruir sin tocar el recibo original. --- ## 6. Trabajar con comisiones de supervisor `Finanzas → Comisiones → tab Supervisores`. ### Filtros - Supervisor (autocomplete). - Período desde / hasta. ### Tabla Una fila por **comisión generada** con: supervisor, período, ventas equipo, cobros equipo, comisión ventas, comisión cobros, total comisión, estado. ### Acciones por fila | Acción | Cuándo se muestra | Qué hace | |---|---|---| | 👁 Ver detalle | Siempre | Abre desglose de facturas y cobros del período. Muestra el supervisor que recibió cada venta. | | 🔄 Recalcular | Estado ≠ `liquidada` | Recalcula el snapshot con los datos actuales. Útil si después de generar cambiaron asignaciones, % o se anularon documentos. | | ✔ Marcar como liquidada | Estado ≠ `liquidada` | Cambia a `liquidada` **y crea una fila en el panel unificado de Liquidaciones** (`tipo=supervisor`, `estado=pagada`). | | 🗑 Eliminar | Estado ≠ `liquidada` | Borra la comisión pendiente con confirmación y auditoría. | Una vez **liquidada**, sólo queda el botón 👁. Para deshacer hay que anular desde el panel de Liquidaciones (§7). --- ## 7. Panel de Liquidaciones (unificado) `Finanzas → Liquidaciones`. Una **única tabla** lista las liquidaciones de vendedores/cobradores y de supervisores. La columna **Origen** las diferencia: | Origen | Cómo se crea | Estado al crearse | |---|---|---| | Vendedor / Cobrador (chip azul) | Botón **Nueva liquidación** → elegir persona y período → agrupa pendientes | `pendiente` | | Supervisor (chip púrpura) | Automático al marcar la comisión del supervisor como liquidada | `pagada` | ### KPIs por colaborador Cards superiores con: Pendientes (cantidad + monto) y Liquidadas (cantidad + monto) por vendedor/cobrador, en la moneda elegida. ### Filtros - Vendedor (autocomplete). - Tipo (vendedor / supervisor) vía query. - Moneda. ### Acciones por fila | Acción | Vendedor/Cobrador | Supervisor | |---|---|---| | Ver detalle | ✔ | ✔ | | Comprobante PDF | ✔ | ✔ | | Marcar como pagada | Sólo si `pendiente` | No aplica (nace pagada) | | Anular | Sólo si **no** está `anulada` y **no** está `pagada` (excepto supervisor) | Permitido incluso en `pagada` | #### Qué hace "Anular" - **Vendedor/Cobrador**: las comisiones incluidas vuelven a `pendiente` (recuperan `liquidacion_id = null`). - **Supervisor**: la comisión del supervisor vuelve a `pendiente` y se **revierte el asiento contable** con `revertirDocumento('comision_supervisor', ...)`. --- ## 8. Auditoría — qué queda registrado Todas las acciones destructivas o de cambio de estado quedan en `audit_logs`. Consulta desde `Reportes → Auditoría y Seguridad → Logs de Auditoría`. | Acción | `entity_type` | `action` | Disparador | |---|---|---|---| | Eliminar comisión vendedor/cobrador | `comision` | `DELETE` | Papelera roja en el detalle | | Eliminar comisión supervisor | `comision_supervisor` | `DELETE` | Papelera roja en el tab Supervisores | Cada registro incluye: - `user_id` del usuario que ejecutó la acción. - `ip_address` y `user_agent` del request. - `old_value` con el snapshot completo del registro antes del borrado (vendedor, documento, montos, estado, período). - `descripcion` legible (ej. *"Comisión venta eliminada (estado: pendiente)"*). > Las acciones de liquidar, marcar como pagada y anular también dejan rastro a través del propio cambio de estado en `liquidaciones_comisiones` y de los asientos contables generados/revertidos. --- ## 9. Integración con contabilidad - Al **pagar una liquidación** (vendedor/cobrador) o al **liquidar una comisión de supervisor**, se genera un asiento contable usando el mapeo de cuentas configurado en `Contabilidad → Mapeo de Cuentas`. - Cuentas típicas: - Gasto: `6.x Comisiones a Personal` o similar — se confirma con el contador. - Contracuenta: caja/banco desde donde se paga. - Al **anular** una liquidación, el asiento se **revierte** automáticamente. - El detalle del asiento se ve desde la liquidación o desde el libro contable. --- ## 10. Validaciones (texto que ve el usuario) - *"No se puede eliminar una comisión liquidada. Anulá la liquidación primero."* — comisión vendedor con `estado=liquidada` o con `liquidacion_id`. - *"No se puede eliminar una comisión liquidada. Anulá desde Liquidaciones."* — comisión supervisor con `estado=liquidada`. - *"Comisión no encontrada"* — el ID no pertenece a la empresa o ya fue eliminada. - *"Definí el período (fecha_desde y fecha_hasta)."* — falta rango en la generación de supervisor. - *"Seleccioná un supervisor"* / *"Definí el período"* — validaciones del diálogo de generar. - *"Debe seleccionar al menos una comisión para liquidar"* — al crear liquidación sin items. --- ## 11. Lo que NO se puede hacer - **No se puede eliminar una comisión liquidada o que tiene `liquidacion_id`.** Hay que anular primero la liquidación. - **No hay borrado masivo por período** ni para vendedores ni para supervisores. - **No se regeneran comisiones de cobranza** con "Generar comisiones históricas" — solo las de venta. - **No se puede crear manualmente** una liquidación de supervisor desde el panel: sólo nace al marcar la comisión del supervisor como liquidada. - **No se puede marcar como pagada** una liquidación de supervisor — ya nace `pagada`. - **No se puede editar** el monto, % o moneda de una comisión ya generada — sólo eliminar y regenerar (para vendedores) o recalcular (para supervisores). - **No se puede asignar un mismo vendedor/cobrador a dos supervisores** en simultáneo: una nueva asignación reemplaza la anterior. - **No hay aprobación intermedia**: el estado `aprobada` existe en el esquema pero no se usa hoy. - **El % del vendedor no se "congela"** en la comisión generada: si cambiás el % en la ficha del vendedor, las comisiones que ya están en `pendiente` no se actualizan solas (eliminar y regenerar, o recalcular). --- ## 12. Problemas frecuentes - **"El supervisor no me totaliza una venta que sí es de su equipo"** → abrir el detalle del vendedor de esa factura: la columna **Supervisor (dirección)** muestra a qué supervisor sumó. Si no es el esperado, revisar (1) `cliente_direccion.supervisor_id` de esa dirección y (2) a qué supervisor pertenece el vendedor. - **"Generé la comisión del supervisor antes de cargar las últimas facturas del mes"** → botón **Recalcular** en la fila del supervisor. No hace falta borrar. - **"Borré una comisión por error"** → revisar `audit_logs` por `entity_type=comision` (o `comision_supervisor`) y `entity_id=`. El `old_value` tiene el snapshot completo para regenerarla. Si era de venta, también funciona correr **Generar comisiones históricas** porque es idempotente. - **"No me deja borrar una comisión que está en `pendiente`"** → tiene `liquidacion_id` (ya forma parte de una liquidación abierta). Anular la liquidación primero. - **"Quiero deshacer una liquidación de supervisor ya pagada"** → Liquidaciones → fila del supervisor → **Anular**. Está habilitado incluso en `pagada` para supervisores. Revierte el asiento. - **"El monto base no coincide con el total de la factura"** → revisar si la configuración de la empresa separa IVA o no, y si la factura tiene descuentos/recargos que excluyen. - **"Cambié el % del vendedor y las comisiones viejas no se actualizaron"** → es el comportamiento esperado: el % se aplica al momento de generar. Para actualizar, eliminar las pendientes y regenerar. - **"Un vendedor cambió de supervisor a mitad de mes"** → desasignar del supervisor viejo y asignar al nuevo. Las facturas anteriores siguen vinculadas al supervisor anterior **si** la comisión del supervisor ya se generó con los datos viejos; el botón **Recalcular** sobre la comisión actualiza el snapshot a la asignación vigente. --- ## 13. Limitaciones actuales - **No hay flujo de aprobación** (estado `aprobada`). Se va directo de `pendiente` a `liquidada`. - **No hay generación masiva** de comisiones de supervisor. Una por una. - **No hay edición** de comisiones generadas, solo eliminar / recalcular. - **No hay borrado masivo por período** (decisión de diseño por irreversibilidad de las de cobranza). - **No hay alerta automática** de "comisiones pendientes desde hace más de X días". - **No hay portal de autoconsulta** para el vendedor/cobrador/supervisor: la información la consulta el área administrativa. - **No hay configuración por producto/categoría**: el % aplica a toda la factura por igual. - **No hay retenciones automáticas** sobre comisiones: si hay que retener, se calcula manualmente al cargar el pago. --- ## Documentos relacionados - `guia-vendedores-cobradores.md` — alta y mantenimiento de vendedores y cobradores. - `guia-supervisores.md` — alta de supervisores y equipos (si existe). - `guia-clientes.md` — direcciones del cliente y supervisor por dirección. - `guia-facturacion.md` — confirmación de facturas (dispara la comisión de venta). - `guia-cobros-finanzas.md` — confirmación de recibos (dispara la comisión de cobranza). - `guia-contabilidad.md` — mapeo de cuentas y asientos al liquidar/anular. - `guia-auditoria.md` — consulta de audit logs.