# REQUERIMIENTOS.md - MAI-010: Liquidaciones a Operadores **Version:** 1.0.0 **Fecha:** 2026-01-27 **Fuente:** REQ-GIRO-TRANSPORTISTA.md - Sección 4.9 --- ## Requerimientos Funcionales ### RF-4.9.1: Esquemas de Pago **Descripción:** El sistema debe permitir configurar diferentes esquemas de pago para operadores: por km, por viaje, por porcentaje del flete, por bono SLA. **Criterios de Aceptación:** 1. Configurar esquema por operador individual 2. Esquemas predefinidos reutilizables 3. Pago por km con tarifa configurable 4. Pago fijo por viaje 5. Pago como % del flete cobrado al cliente 6. Bonos por cumplimiento de SLA (on-time delivery) 7. Combinación de esquemas (base + variable) **Mapeo a DDL:** - Tabla: `settlements.esquemas_pago` - Tabla: `settlements.esquema_operador` **Endpoints Requeridos:** - `GET /api/v1/esquemas-pago` - Listar esquemas - `POST /api/v1/esquemas-pago` - Crear esquema - `PUT /api/v1/operadores/:id/esquema-pago` - Asignar a operador **Prioridad:** Alta --- ### RF-4.9.2: Viáticos **Descripción:** El sistema debe gestionar anticipos de viáticos, comprobación de gastos y control de sobrantes. **Criterios de Aceptación:** 1. Registrar anticipo de viático por viaje 2. Comprobación de gastos con recibos/tickets 3. Clasificación de gastos: combustible, casetas, comidas, hospedaje 4. Cálculo de sobrante (anticipo - comprobado) 5. Sobrante se descuenta en liquidación 6. Alertas por viáticos sin comprobar **Mapeo a DDL:** - Tabla: `settlements.viaticos` - Tabla: `settlements.comprobantes_viatico` **Endpoints Requeridos:** - `POST /api/v1/viajes/:id/viatico` - Registrar anticipo - `POST /api/v1/viaticos/:id/comprobantes` - Agregar comprobante - `GET /api/v1/operadores/:id/viaticos-pendientes` - Viáticos sin comprobar **Prioridad:** Alta --- ### RF-4.9.3: Deducciones **Descripción:** El sistema debe permitir registrar deducciones por multas, daños, faltantes según política, con aprobación. **Criterios de Aceptación:** 1. Catálogo de tipos de deducción 2. Registrar deducción vinculada a viaje/incidencia 3. Monto puede ser fijo o % del daño 4. Requiere aprobación de supervisor 5. Plan de pagos para montos grandes (descuento parcial) 6. Historial de deducciones por operador 7. Límite máximo de deducción por periodo (política) **Mapeo a DDL:** - Tabla: `settlements.deducciones` - Tabla: `settlements.tipos_deduccion` **Endpoints Requeridos:** - `POST /api/v1/deducciones` - Registrar deducción - `POST /api/v1/deducciones/:id/aprobar` - Aprobar deducción - `GET /api/v1/operadores/:id/deducciones` - Historial **Prioridad:** Media --- ### RF-4.9.4: Corte y Autorización **Descripción:** El sistema debe generar liquidaciones con corte semanal/quincenal, autorización de supervisor y exportación a nómina/contabilidad. **Criterios de Aceptación:** 1. Configurar periodo de corte (semanal, quincenal) 2. Generar liquidación con todos los conceptos 3. Desglose: viajes, viáticos, deducciones, bonos 4. Revisión y autorización de supervisor 5. Firma digital o aceptación del operador 6. Exportación a formato de nómina 7. Integración con contabilidad para pólizas **Mapeo a DDL:** - Tabla: `settlements.liquidaciones` - Tabla: `settlements.conceptos_liquidacion` **Endpoints Requeridos:** - `POST /api/v1/liquidaciones/generar` - Generar corte - `POST /api/v1/liquidaciones/:id/autorizar` - Autorizar - `GET /api/v1/liquidaciones/:id/exportar` - Exportar a nómina **Prioridad:** Alta --- ### RF-4.9.5: Cálculo Automático de Pago por Viaje **Descripción:** El sistema debe calcular automáticamente el monto a pagar por cada viaje según el esquema del operador. **Criterios de Aceptación:** 1. Calcular al cerrar viaje (POD completado) 2. Aplicar esquema del operador asignado 3. Considerar km reales si aplica (desde tracking) 4. Considerar flete real si es % del flete 5. Aplicar bono si cumplió SLA 6. Registrar desglose del cálculo 7. Ajuste manual con justificación **Mapeo a DDL:** - Tabla: `settlements.pagos_viaje` - Vista: `v_viajes_por_liquidar` **Endpoints Requeridos:** - `POST /api/v1/viajes/:id/calcular-pago` - Calcular pago - `PUT /api/v1/pagos-viaje/:id` - Ajustar pago - `GET /api/v1/operadores/:id/viajes-pendientes` - Por liquidar **Prioridad:** Alta --- ### RF-4.9.6: Bonos por Desempeño **Descripción:** El sistema debe calcular y aplicar bonos por cumplimiento de indicadores. **Criterios de Aceptación:** 1. Configurar bonos: on-time delivery, sin incidencias, combustible eficiente 2. Calcular automáticamente si cumple condiciones 3. Bono por viaje o por periodo 4. Desglose de bonos en liquidación 5. Histórico de bonos ganados **Mapeo a DDL:** - Tabla: `settlements.bonos` - Tabla: `settlements.tipos_bono` **Endpoints Requeridos:** - `GET /api/v1/operadores/:id/bonos` - Bonos ganados - `POST /api/v1/bonos` - Registrar bono manual **Prioridad:** Media --- ## Requerimientos No Funcionales ### RNF-001: Precisión de Cálculo Los cálculos de liquidación deben tener precisión de 2 decimales sin errores de redondeo. ### RNF-002: Auditoría Todos los ajustes manuales deben registrarse con usuario, fecha y justificación. ### RNF-003: Confidencialidad Las liquidaciones solo deben ser visibles para el operador correspondiente y personal autorizado. ### RNF-004: Exportación La exportación a nómina debe completarse en menos de 30 segundos para 100 operadores. --- ## Validaciones de Negocio | Validación | Descripción | Acción si falla | |------------|-------------|-----------------| | LIQ_001 | Viaje con POD para calcular pago | Bloquear cálculo | | LIQ_002 | Deducción requiere aprobación | Pendiente hasta aprobar | | LIQ_003 | Deducción no excede límite periodo | Alertar, requiere override | | LIQ_004 | Viático comprobado antes de liquidar | Alertar, permitir continuar | | LIQ_005 | Operador sin bloqueo | Alertar si operador bloqueado | --- ## Matriz de Trazabilidad | RF | Tabla DDL | Entity | Endpoint | US | |----|-----------|--------|----------|---| | RF-4.9.1 | esquemas_pago | EsquemaPago | /esquemas-pago | US-MAI010-001 | | RF-4.9.2 | viaticos | Viatico | /viaticos | US-MAI010-003 | | RF-4.9.3 | deducciones | Deduccion | /deducciones | US-MAI010-004 | | RF-4.9.4 | liquidaciones | Liquidacion | /liquidaciones | US-MAI010-005 | | RF-4.9.5 | pagos_viaje | PagoViaje | /viajes/:id/pago | US-MAI010-002 | | RF-4.9.6 | bonos | Bono | /bonos | US-MAI010-002 | --- *MAI-010 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0*