rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ec43d9c6cd
erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/README.md
Adrian Flores Cortes ec43d9c6cd docs: Add Phase 3 secondary modules specifications (P1/P2/P3) 
Modules documented:
- MAI-003 (OT): README, REQUERIMIENTOS, RESUMEN-EPICA, 10 US
- MAI-006 (Tracking): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-008 (Incidencias): 3 US (18 SP)
- MAI-011 (Flota): README, REQUERIMIENTOS, RESUMEN-EPICA
- MAI-012 (Combustible): 3 US (18 SP)
- MAI-013 (Mantenimiento): 3 US (18 SP)
- MAI-014 (Carriers): 3 US (18 SP)
- MAI-015 (Portal): 3 US (18 SP)
- MAE-016 (Carta Porte): 10 US
- MAE-017 (HOS): 3 US (16 SP)
- MAE-018 (Reportes): 3 US (18 SP)

Phase 2+3 complete: 13 modules, 50+ User Stories

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

192 lines
10 KiB
Markdown
Raw Blame History

# MAE-016: Carta Porte CFDI
**Modulo:** MAE-016 | **Version:** 1.0.0 | **Actualizado:** 2026-01-27
**Epica:** EPIC-MAE-016 - Carta Porte CFDI
**Schema BD:** compliance
**DDL:** `database/ddl/08-compliance-schema-ddl.sql`
---
## Descripcion
Modulo de generacion, timbrado y administracion del **Complemento Carta Porte version 3.1** para CFDI, conforme a los lineamientos del Servicio de Administracion Tributaria (SAT). Este complemento es obligatorio para el traslado de bienes y mercancias en territorio nacional por via de autotransporte federal.
El modulo automatiza la construccion del XML del complemento a partir de los datos operativos del viaje (origen, destino, mercancias, operador, unidad, remolques), ejecuta las validaciones de campos obligatorios conforme a los catalogos del SAT, se integra con un Proveedor Autorizado de Certificacion (PAC) para el timbrado digital y ofrece funcionalidades de descarga PDF, cancelacion con motivo y expediente fiscal por viaje.
---
## Contexto Legal y Normativo
- **Base legal:** Regla 2.7.7.1 de la Resolucion Miscelanea Fiscal vigente; articulo 29-A del Codigo Fiscal de la Federacion.
- **Version complemento:** Carta Porte 3.1, vigente desde el **17 de julio de 2024**.
- **Obligatoriedad:** Toda persona fisica o moral que transporte bienes o mercancias en territorio nacional por via terrestre, maritima, aerea o ferroviaria debe emitir CFDI con complemento Carta Porte.
- **Sanciones:** La falta de este documento durante el traslado implica multas y posible decomiso de mercancias por parte de la autoridad fiscal.
- **Catalogos SAT:** Se utilizan catalogos oficiales de claves de producto/servicio, unidades de medida, tipos de permiso SCT, configuracion vehicular, claves de material peligroso y tipos de figura de transporte.
- **Motivos de cancelacion:** 01 (Comprobante emitido con errores con relacion), 02 (Comprobante emitido con errores sin relacion), 03 (No se llevo a cabo la operacion), 04 (Operacion nominativa relacionada en factura global).
---
## Tipos de CFDI con Carta Porte
| Tipo | Enum DDL | Descripcion | Escenario |
|------|----------|-------------|-----------|
| **CFDI de Ingreso** | `INGRESO` | Factura por servicio de transporte prestado a un tercero | Empresa transportista que cobra por el traslado de mercancias del cliente |
| **CFDI de Traslado** | `TRASLADO` | Comprobante de traslado de mercancias propias | Empresa que mueve sus propias mercancias sin cobrar servicio de flete |
---
## Actores
| Actor | Responsabilidad |
|-------|-----------------|
| **Facturador** | Genera la carta porte desde el viaje, valida datos, solicita timbrado al PAC, descarga PDF/XML |
| **Contador** | Revisa expediente fiscal, gestiona cancelaciones, genera reportes fiscales mensuales |
| **Coordinador de Operaciones** | Asegura que los datos del viaje (mercancias, ubicaciones, figuras) esten completos antes del despacho |
| **Operador/Conductor** | Porta el PDF/XML en la unidad durante el traslado; consulta en modo offline desde la app movil |
---
## Funcionalidades Principales
1. **Generacion automatica desde viaje:** El sistema construye el complemento Carta Porte 3.1 a partir de los datos del viaje (ubicaciones, mercancias, operador, unidad, remolques) sin captura manual redundante.
2. **Validacion de campos SAT:** Antes de enviar al PAC, el sistema valida todos los campos obligatorios segun el tipo de CFDI (Ingreso/Traslado), incluyendo catalogos SAT (BienesTransp, ClaveUnidad, ConfigVehicular, TipoPermiso, TipoFigura).
3. **Timbrado con PAC:** Integracion con proveedores autorizados de certificacion (Finkok, Facturapi, SW Sapien) para timbrar el CFDI y obtener UUID fiscal, cadena de certificacion y sello digital.
4. **Generacion de PDF:** Representacion impresa del CFDI con complemento Carta Porte, incluyendo datos fiscales, mercancias, ubicaciones, figuras de transporte y codigo QR de verificacion.
5. **Cancelacion de CFDI:** Envio de solicitud de cancelacion al SAT a traves del PAC con motivo (01, 02, 03, 04), UUID de sustitucion cuando aplica y bitacora de cancelaciones.
6. **Expediente fiscal por viaje:** Asociacion del UUID del CFDI timbrado, XML, PDF y QR con el viaje/OT, permitiendo consulta rapida y auditoria.
7. **Disponibilidad offline:** El operador puede descargar y consultar el PDF, XML y QR desde la app movil en modo offline, cumpliendo con la obligacion de portarlo durante el traslado.
8. **Reporte fiscal mensual:** Generacion de reporte con todos los CFDI emitidos, cancelados y vigentes en un periodo, agrupados por tipo, serie, estado y totales.
---
## Entidades (desde DDL - schema compliance)
| Tabla | Descripcion | Campos clave |
|-------|-------------|--------------|
| `compliance.cartas_porte` | CFDI con complemento Carta Porte 3.1 | id, viaje_id, tipo_cfdi, uuid_cfdi, emisor_rfc, receptor_rfc, estado, xml_cfdi, pdf_url |
| `compliance.ubicaciones_carta_porte` | Nodos Ubicacion (origen/destino) de la carta porte | id, carta_porte_id, tipo_ubicacion, codigo_postal, fecha_hora_salida_llegada, distancia_recorrida |
| `compliance.mercancias_carta_porte` | Nodo Mercancias transportadas en el complemento | id, carta_porte_id, bienes_transp, descripcion, cantidad, peso_en_kg, material_peligroso |
| `compliance.figuras_transporte` | Nodo FiguraTransporte (operador, propietario, arrendador) | id, carta_porte_id, tipo_figura, rfc_figura, num_licencia |
| `compliance.autotransporte_carta_porte` | Nodo Autotransporte federal (vehiculo, permisos, remolques) | id, carta_porte_id, perm_sct, num_permiso_sct, config_vehicular, placa_vm, remolques |
### ENUMs
| Enum | Valores | Uso |
|------|---------|-----|
| `compliance.estado_carta_porte` | BORRADOR, VALIDADA, TIMBRADA, CANCELADA | Ciclo de vida del CFDI |
| `compliance.tipo_cfdi_carta_porte` | INGRESO, TRASLADO | Tipo de comprobante fiscal |
---
## API Endpoints (propuestos)
| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| POST | `/api/v1/carta-porte` | Crear carta porte desde viaje |
| GET | `/api/v1/carta-porte/:id` | Obtener detalle de carta porte |
| GET | `/api/v1/carta-porte` | Listar cartas porte (filtros: estado, fecha, tipo_cfdi) |
| POST | `/api/v1/carta-porte/:id/validar` | Validar campos obligatorios SAT |
| POST | `/api/v1/carta-porte/:id/timbrar` | Timbrar CFDI con PAC |
| GET | `/api/v1/carta-porte/:id/pdf` | Descargar PDF de la carta porte |
| GET | `/api/v1/carta-porte/:id/xml` | Descargar XML del CFDI |
| POST | `/api/v1/carta-porte/:id/cancelar` | Cancelar CFDI con motivo |
| GET | `/api/v1/carta-porte/expediente/:viajeId` | Consultar expediente fiscal del viaje |
| POST | `/api/v1/carta-porte/:id/mercancias` | Agregar mercancias a la carta porte |
| PUT | `/api/v1/carta-porte/:id/mercancias/:mercanciaId` | Actualizar mercancia |
| POST | `/api/v1/carta-porte/:id/figuras` | Registrar figuras de transporte |
| POST | `/api/v1/carta-porte/:id/autotransporte` | Configurar datos de autotransporte federal |
| GET | `/api/v1/carta-porte/reporte-fiscal` | Generar reporte fiscal mensual |
---
## Historias de Usuario
| ID | Titulo | SP | Prioridad | Estado |
|----|--------|----|-----------|--------|
| US-MAE016-001 | Generar carta porte desde viaje | 8 | P0 | Backlog |
| US-MAE016-002 | Validar datos obligatorios SAT | 5 | P0 | Backlog |
| US-MAE016-003 | Timbrar CFDI con PAC | 8 | P0 | Backlog |
| US-MAE016-004 | Descargar PDF de carta porte | 3 | P1 | Backlog |
| US-MAE016-005 | Cancelar CFDI con motivo | 5 | P1 | Backlog |
| US-MAE016-006 | Consultar expediente fiscal | 3 | P1 | Backlog |
| US-MAE016-007 | Agregar mercancias transportadas | 5 | P0 | Backlog |
| US-MAE016-008 | Registrar figuras de transporte | 5 | P1 | Backlog |
| US-MAE016-009 | Configurar datos autotransporte federal | 5 | P1 | Backlog |
| US-MAE016-010 | Generar reporte fiscal mensual | 3 | P2 | Backlog |
**Total Story Points:** 50
---
## Dependencias
### Depende de
| Modulo | Razon |
|--------|-------|
| MAI-001 Fundamentos | Auth, RBAC, multi-tenancy, tenant_id para RLS |
| MAI-003 Ordenes de Transporte | Datos de OT/embarque como origen de la carta porte |
| MAI-005 Despacho | Viaje despachado como prerequisito para generar carta porte |
| MAI-009 Facturacion Transporte | CFDI de Ingreso se vincula con factura de transporte |
| MAI-011 Gestion de Flota | Datos de unidad, remolques, operadores (placas, licencias, permisos SCT) |
### Bloquea a
| Modulo | Razon |
|--------|-------|
| MAI-007 POD y Cierre | El cierre operativo requiere la carta porte timbrada |
| MAI-015 Portal Cliente | El portal muestra carta porte al cliente para descarga |
| MAE-018 Reportes y KPIs | Los reportes fiscales consolidan datos de cartas porte |
---
## Flujo Principal
```
1. GENERAR CARTA PORTE
Coordinador/Facturador selecciona viaje despachado
Sistema extrae datos: emisor, receptor, ubicaciones, mercancias, operador, unidad
Crea registro en compliance.cartas_porte con estado BORRADOR
2. AGREGAR/VERIFICAR MERCANCIAS
Sistema carga mercancias del viaje/OT
Facturador ajusta claves SAT (bienes_transp, clave_unidad)
Registra peso_en_kg, material_peligroso si aplica
3. REGISTRAR FIGURAS DE TRANSPORTE
Sistema carga operador asignado como tipo_figura '01' (Operador)
Se agregan propietario ('02') o arrendador ('03') si aplica
Valida num_licencia del operador
4. CONFIGURAR AUTOTRANSPORTE
Sistema carga datos de unidad: perm_sct, config_vehicular, placa_vm
Agrega remolques con sub_tipo_rem y placa
Valida catalogo de configuracion vehicular SAT
5. VALIDAR DATOS SAT
Sistema ejecuta validaciones de campos obligatorios
Verifica catalogos SAT (BienesTransp, ClaveUnidad, ConfigVehicular)
Si pasa: estado = VALIDADA. Si falla: muestra errores especificos
6. TIMBRAR CON PAC
Sistema genera XML del CFDI con complemento Carta Porte 3.1
Envia a PAC (Finkok/Facturapi/SW)
Recibe uuid_cfdi, fecha_timbrado, sello, cadena
Estado = TIMBRADA. Almacena xml_cfdi
7. GENERAR PDF Y QR
Sistema genera representacion impresa con datos fiscales
Incluye codigo QR de verificacion SAT
Almacena pdf_url y qr_url
8. CANCELAR (si requiere)
Facturador/Contador selecciona motivo (01, 02, 03, 04)
Si motivo 01: indica uuid_sustitucion
Envia solicitud al PAC
Estado = CANCELADA. Registra fecha_cancelacion y motivo
```
---
*MAE-016 Carta Porte CFDI - ERP Transportistas v1.0.0 - Sistema SIMCO v4.0.0*
Reference in New Issue View Git Blame Copy Permalink