# 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*