569eaeb5a4
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>
235 lines
7.6 KiB
Markdown
235 lines
7.6 KiB
Markdown
# 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*
|