rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
569eaeb5a4
erp-transportistas-v2/docs/02-definicion-modulos/MAI-009-facturacion-transporte/REQUERIMIENTOS.md
Adrian Flores Cortes 569eaeb5a4 docs: Add MAI-009 (Facturación) and MAI-010 (Liquidaciones) specifications 
MAI-009 Facturación Transporte (31 SP):
- README, REQUERIMIENTOS (7 RF), RESUMEN-EPICA
- 5 User Stories: generación factura, recargos, CFDI/Carta Porte,
  conciliación/pagos, estados de cuenta

MAI-010 Liquidaciones (31 SP):
- README, REQUERIMIENTOS (6 RF), RESUMEN-EPICA
- 5 User Stories: esquemas pago, cálculo por viaje, viáticos,
  deducciones, generar/autorizar liquidación

Part of Phase 2 - P0 Critical Modules specification

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 02:05:03 -06:00

7.6 KiB
Raw Blame History

REQUERIMIENTOS.md - MAI-009: Facturación de Transporte

Version: 1.0.0 Fecha: 2026-01-27 Fuente: REQ-GIRO-TRANSPORTISTA.md - Sección 4.8

Requerimientos Funcionales

RF-4.8.1: Factura por Viaje/Embarque/OT

Descripción: El sistema debe permitir configurar si la facturación se realiza por viaje individual, por embarque (grupo de OTs), o por OT específica.

Criterios de Aceptación:

  1. Configuración por cliente: facturar por viaje, embarque u OT
  2. Selección de viajes cerrados (con POD) pendientes de facturar
  3. Facturación masiva de múltiples viajes en una sola factura
  4. Facturación individual (una factura por viaje)
  5. Agrupación automática por periodo (semanal, quincenal, mensual)
  6. Generación de borrador editable antes de timbrar

Mapeo a DDL:

  • Tabla: billing.facturas_transporte
  • Tabla: billing.lineas_factura
  • Vista: v_viajes_por_facturar

Endpoints Requeridos:

  • GET /api/v1/facturacion/viajes-pendientes - Listar viajes a facturar
  • POST /api/v1/facturas - Crear factura
  • GET /api/v1/facturas/:id - Obtener factura
  • PUT /api/v1/facturas/:id - Actualizar borrador

Prioridad: Alta

RF-4.8.2: Cálculo Automático de Recargos

Descripción: El sistema debe calcular y aplicar automáticamente los recargos correspondientes: fuel surcharge, demoras (detention) por tiempos reales, reentregas, cambios de destino.

Criterios de Aceptación:

  1. Fuel surcharge: aplicar % vigente sobre tarifa base
  2. Detention en carga: calcular si tiempo real > tolerancia
  3. Detention en descarga: calcular si tiempo real > tolerancia
  4. Reentrega: aplicar cargo si hubo reexpedición
  5. Cambio de destino: calcular diferencial de tarifa
  6. Mostrar desglose de cada recargo en la factura
  7. Permitir ajustar o eliminar recargos con justificación

Mapeo a DDL:

  • Tabla: billing.recargos_catalogo
  • Tabla: billing.fuel_surcharge
  • Tabla: billing.lineas_factura (con recargoId)

Endpoints Requeridos:

  • POST /api/v1/facturas/:id/calcular-recargos - Calcular recargos
  • PUT /api/v1/facturas/:id/lineas/:lineaId - Ajustar línea
  • DELETE /api/v1/facturas/:id/lineas/:lineaId - Eliminar línea

Prioridad: Alta

RF-4.8.3: Integración con POD

Descripción: El sistema debe anexar el POD y evidencias de entrega a la factura/expediente digital para soporte de cobranza.

Criterios de Aceptación:

  1. Vincular factura con viajes y sus PODs
  2. Incluir URL de evidencias (fotos, firma) en factura
  3. Generar expediente digital con: factura PDF, XML, POD, carta porte
  4. Enviar expediente completo al cliente
  5. POD disponible para descarga desde portal cliente

Mapeo a DDL:

  • Tabla: billing.facturas_transporte (viajeIds, otIds)
  • Relación con: tracking.pods

Endpoints Requeridos:

  • GET /api/v1/facturas/:id/expediente - Obtener expediente
  • GET /api/v1/facturas/:id/expediente/zip - Descargar ZIP

Prioridad: Alta

RF-4.8.4: Conciliación

Descripción: El sistema debe permitir comparar: cotización original vs factura emitida vs monto cobrado, para identificar diferencias y ajustes.

Criterios de Aceptación:

  1. Mostrar comparativo: cotizado vs facturado
  2. Identificar diferencias (recargos no cotizados, descuentos aplicados)
  3. Registrar ajustes con justificación
  4. Generar notas de crédito/débito cuando aplique
  5. Dashboard de conciliación por periodo

Mapeo a DDL:

  • Vista: v_conciliacion_facturas
  • Tabla: billing.notas_credito_debito

Endpoints Requeridos:

  • GET /api/v1/facturacion/conciliacion - Reporte de conciliación
  • POST /api/v1/notas - Crear nota de crédito/débito

Prioridad: Media

RF-4.8.5: Estados de Cuenta por Cliente

Descripción: El sistema debe generar estados de cuenta con: viajes, cargos, abonos, notas, y análisis de antigüedad de saldos (aging).

Criterios de Aceptación:

  1. Estado de cuenta por cliente con periodo seleccionable
  2. Mostrar: facturas emitidas, notas, pagos recibidos, saldo
  3. Análisis de aging: corriente, 30 días, 60 días, 90 días, +90 días
  4. Alertas de facturas próximas a vencer
  5. Exportar a PDF y Excel
  6. Envío automático periódico al cliente

Mapeo a DDL:

  • Vista: v_estado_cuenta_cliente
  • Vista: v_aging_cartera

Endpoints Requeridos:

  • GET /api/v1/clientes/:id/estado-cuenta - Estado de cuenta
  • GET /api/v1/facturacion/aging - Reporte de aging
  • POST /api/v1/clientes/:id/estado-cuenta/enviar - Enviar por email

Prioridad: Media

RF-4.8.6: Timbrado CFDI

Descripción: El sistema debe generar el CFDI 4.0 con complemento Carta Porte 3.1 y timbrarlo mediante PAC autorizado.

Criterios de Aceptación:

  1. Generar XML CFDI 4.0 con datos fiscales
  2. Incluir complemento Carta Porte (MAE-016)
  3. Enviar a PAC para timbrado
  4. Recibir y almacenar UUID, sello digital, cadena original
  5. Generar PDF representación impresa
  6. Manejar errores de validación SAT
  7. Proceso de cancelación con motivo

Mapeo a DDL:

  • Tabla: billing.facturas_transporte (uuidCfdi, xmlCfdi)

Endpoints Requeridos:

  • POST /api/v1/facturas/:id/timbrar - Timbrar CFDI
  • POST /api/v1/facturas/:id/cancelar - Cancelar CFDI
  • GET /api/v1/facturas/:id/pdf - Obtener PDF
  • GET /api/v1/facturas/:id/xml - Obtener XML

Prioridad: Alta

RF-4.8.7: Registro de Pagos

Descripción: El sistema debe permitir registrar pagos parciales o totales y actualizar el estado de la factura.

Criterios de Aceptación:

  1. Registrar pago con: monto, fecha, referencia, método
  2. Soportar pagos parciales con saldo pendiente
  3. Marcar factura como PAGADA cuando saldo = 0
  4. Generar complemento de pago si aplica (PPD)
  5. Conciliar con movimientos bancarios (opcional)

Mapeo a DDL:

  • Tabla: billing.pagos_factura
  • Tabla: billing.facturas_transporte (montoPagado, fechaPago)

Endpoints Requeridos:

  • POST /api/v1/facturas/:id/pagos - Registrar pago
  • GET /api/v1/facturas/:id/pagos - Historial de pagos

Prioridad: Alta

Requerimientos No Funcionales

RNF-001: Integración PAC

El sistema debe soportar al menos 2 PACs con failover automático.

RNF-002: Performance

La generación de factura (sin timbrado) debe completarse en <5 segundos.

RNF-003: Retención

Los CFDIs deben almacenarse por al menos 5 años según normativa SAT.

RNF-004: Disponibilidad

El proceso de timbrado debe tener 99.5% de disponibilidad.

Validaciones de Negocio

Validación Descripción Acción si falla
FAC_001 Viaje con POD válido Bloquear facturación
FAC_002 Datos fiscales cliente completos Alertar, bloquear timbrado
FAC_003 Carta Porte completa si aplica Bloquear timbrado
FAC_004 Tarifa vigente aplicada Alertar si tarifa vencida
FAC_005 Fuel surcharge actualizado Alertar si >30 días

Matriz de Trazabilidad

RF Tabla DDL Entity Endpoint US
RF-4.8.1 facturas_transporte FacturaTransporte /facturas US-MAI009-001
RF-4.8.2 lineas_factura LineaFactura /facturas/:id/lineas US-MAI009-002
RF-4.8.3 facturas_transporte FacturaTransporte /facturas/:id/expediente US-MAI009-001
RF-4.8.4 v_conciliacion - /facturacion/conciliacion US-MAI009-004
RF-4.8.5 v_estado_cuenta - /clientes/:id/estado-cuenta US-MAI009-005
RF-4.8.6 facturas_transporte FacturaTransporte /facturas/:id/timbrar US-MAI009-003
RF-4.8.7 pagos_factura PagoFactura /facturas/:id/pagos US-MAI009-004

MAI-009 REQUERIMIENTOS - ERP Transportistas - Sistema SIMCO v4.0.0