erp-transportistas-v2/docs/02-definicion-modulos/MAI-010-liquidaciones/REQUERIMIENTOS.md

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