erp-transportistas-v2/docs/02-definicion-modulos/MAI-009-facturacion-transporte

MAI-009: Facturación de Transporte

Version: 1.0.0 Fecha: 2026-01-27 Estado: Diseño Prioridad: P1 (Crítico - Monetización)

---

Descripción General

El módulo de Facturación de Transporte es responsable de generar facturas CFDI por los servicios de transporte, aplicando tarifas, recargos y conectando con evidencias de entrega (POD).

Problema que resuelve:

• Facturación manual lenta y propensa a errores
• Recargos (demoras, fuel surcharge) no capturados
• Falta de trazabilidad factura → viaje → POD
• Conciliación difícil entre cotizado vs facturado vs cobrado
• Aging de cartera sin visibilidad

---

Objetivos del Módulo

1. Factura automatizada: Generar facturas desde viajes cerrados con POD
2. Recargos automáticos: Aplicar fuel surcharge, detention, maniobras
3. Trazabilidad completa: Vincular factura con viajes, POD y evidencias
4. CFDI timbrado: Integración con PAC para factura electrónica
5. Gestión de cobranza: Estados de cuenta, aging, pagos

---

Alcance Funcional

Incluido

• Facturación por viaje, por embarque o por OT
• Cálculo automático de recargos (fuel, detention, etc.)
• Integración con POD para adjuntar evidencias
• Timbrado CFDI via PAC
• Complemento Carta Porte (MAE-016)
• Estados de cuenta por cliente
• Registro de pagos y aging de cartera

Excluido

• Cobranza judicial (CRM/Legal)
• Contabilidad detallada (módulo financiero erp-core)
• Carta Porte como documento independiente (MAE-016)

---

Actores

Actor	Rol en el módulo
Facturador	Crea y emite facturas
Contador	Revisa, aprueba, concilia
Cobranza	Seguimiento de pagos, aging
Cliente	Recibe factura, realiza pagos
Sistema PAC	Timbra CFDI

---

Flujo Principal

VIAJES CERRADOS (con POD)
      │
      ▼
┌─────────────────────────────────────────┐
│ 1. SELECCIONAR VIAJES A FACTURAR        │
│    - Filtrar por cliente/periodo        │
│    - Viajes con POD pendientes facturar │
│    - Selección individual o masiva      │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 2. GENERAR BORRADOR DE FACTURA          │
│    - Líneas automáticas desde viajes    │
│    - Aplicar tarifa de cada viaje       │
│    - Calcular subtotales                │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 3. APLICAR RECARGOS                     │
│    - Fuel surcharge automático          │
│    - Detention si aplica                │
│    - Maniobras, escoltas, etc.          │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 4. REVISAR Y AJUSTAR                    │
│    - Verificar montos                   │
│    - Aplicar descuento (si autorizado)  │
│    - Agregar notas/observaciones        │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 5. TIMBRAR CFDI                         │
│    - Generar XML con datos fiscales     │
│    - Incluir complemento Carta Porte    │
│    - Enviar a PAC                       │
│    - Recibir UUID y sellos              │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 6. ENVIAR AL CLIENTE                    │
│    - Email con PDF + XML                │
│    - Publicar en portal cliente         │
│    - Adjuntar POD si requiere           │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│ 7. SEGUIMIENTO DE COBRANZA              │
│    - Registrar pagos                    │
│    - Alertas de vencimiento             │
│    - Estados de cuenta                  │
└─────────────────────────────────────────┘

---

Datos del Módulo

Entidades Principales

Entidad	Descripción	Estado
Lane	Ruta origen-destino	IMPLEMENTADA
Tarifa	Precio por lane/servicio	IMPLEMENTADA
RecargoCatalogo	Tipos de recargos	IMPLEMENTADA
FacturaTransporte	Factura CFDI	IMPLEMENTADA
LineaFactura	Conceptos facturados	IMPLEMENTADA
FuelSurcharge	Índice de combustible	IMPLEMENTADA

Ver archivo: ENTITIES.md

---

Requerimientos Funcionales

Ver archivo: REQUERIMIENTOS.md

---

Integración con PAC

PAC	Tipo	Uso
Finkok	Primario	Timbrado, cancelación
SW Sapien	Respaldo	Failover

Servicios requeridos:

• Timbrado de CFDI 4.0
• Complemento Carta Porte 3.1
• Cancelación de CFDI
• Consulta de estatus

---

Métricas del Módulo

KPI	Fórmula	Meta
Días a facturar	Avg(fecha_factura - fecha_pod)	<3 días
Recargos capturados	% viajes con recargos aplicados	>95%
Facturas rechazadas	% facturas con error PAC	<2%
DSO	Días promedio de cobranza	<45 días

---

Dependencias

Este módulo depende de:

• MAI-007 (POD): Viajes cerrados con evidencia
• MAI-002 (Tarifas): Precios y recargos
• MAE-016 (Carta Porte): Complemento CFDI
• erp-core/partners: Datos fiscales del cliente

Otros módulos dependen de este:

• erp-core/financial: Conciliación contable
• MAI-015 (Portal Cliente): Consulta de facturas

---

Historias de Usuario

Ver carpeta: historias-usuario/

US	Título	Prioridad
US-MAI009-001	Generar factura desde viajes	Alta
US-MAI009-002	Aplicar recargos automáticos	Alta
US-MAI009-003	Timbrar CFDI con Carta Porte	Alta
US-MAI009-004	Gestionar conciliación y pagos	Media
US-MAI009-005	Generar estados de cuenta	Media

---

Módulo MAI-009 - ERP Transportistas - Sistema SIMCO v4.0.0