rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/README.md
Adrian Flores Cortes aebaad4fe9 chore: Consolidar y purgar documentación duplicada (TASK-006) 
Consolidación:
- MAI-003/RESUMEN-EPICA.md -> README.md (criterios, riesgos, distribución)
- MAE-016/RESUMEN-EPICA.md -> README.md (criterios, métricas, valor negocio)

Archivos eliminados:
- MAI-003-ordenes-transporte/RESUMEN-EPICA.md
- MAE-016-carta-porte/RESUMEN-EPICA.md

Documentación de purga en orchestration/tareas/2026-01-27/TASK-006

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 11:44:16 -06:00

240 lines
13 KiB
Markdown
Raw Permalink 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
```
---
## Criterios de Aceptacion de la Epica
1. Se puede generar una carta porte desde cualquier viaje despachado con datos completos
2. Las validaciones detectan todos los campos obligatorios faltantes segun el tipo de CFDI
3. El timbrado con al menos un PAC (Finkok o Facturapi) funciona correctamente
4. El PDF generado incluye todos los datos del complemento Carta Porte y codigo QR
5. La cancelacion envia correctamente los motivos 01-04 al PAC
6. El expediente fiscal muestra UUID, XML, PDF y estado del CFDI por viaje
7. El operador puede descargar el PDF/XML desde la app para consulta offline
8. El reporte fiscal mensual lista todos los CFDI con filtros por tipo, estado y fecha
## Metricas de Exito
| Metrica | Objetivo |
|---------|----------|
| Tasa de timbrado exitoso al primer intento | > 95% |
| Tiempo promedio de generacion y timbrado | < 10 segundos |
| CFDI cancelados por errores del sistema | < 2% |
| Cobertura de viajes con carta porte | 100% de viajes que lo requieren |
## Distribucion por Prioridad (User Stories)
| Prioridad | Historias | Story Points | Porcentaje |
|-----------|-----------|--------------|------------|
| P0 (Critico) | 4 | 26 | 52% |
| P1 (Importante) | 5 | 21 | 42% |
| P2 (Deseable) | 1 | 3 | 6% |
## Valor de Negocio
1. **Cumplimiento fiscal obligatorio:** Evita multas y decomiso de mercancias por falta del complemento Carta Porte durante el traslado.
2. **Automatizacion operativa:** Elimina la captura manual de datos fiscales al construir el complemento desde los datos del viaje (ubicaciones, mercancias, operador, unidad).
3. **Trazabilidad fiscal:** Cada viaje queda vinculado a su UUID de CFDI, XML, PDF y QR, creando un expediente fiscal auditable.
4. **Reduccion de errores:** Las validaciones previas al timbrado detectan datos faltantes o incorrectos antes de enviar al PAC, evitando rechazos y cancelaciones innecesarias.
5. **Disponibilidad en ruta:** El operador porta el documento en formato digital (PDF/QR) incluso sin conectividad, cumpliendo con los requerimientos de inspeccion en carretera.
## Riesgos Identificados
| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Cambio de version del complemento por el SAT | Media | Alto | Parametrizar version en DDL (campo version_carta_porte), estructura modular del XML |
| Rechazo de timbrado por datos invalidos | Alta | Medio | Validacion exhaustiva previa al envio, mensajes de error claros |
| Indisponibilidad del PAC | Baja | Alto | Soportar multiples PAC con failover automatico |
| Catalogos SAT desactualizados | Media | Medio | Proceso de actualizacion periodica de catalogos, versionamiento |
| Cancelacion rechazada por el SAT | Media | Medio | Informar al usuario el estatus de cancelacion y opciones disponibles |
---
*MAE-016 Carta Porte CFDI - ERP Transportistas v1.0.0 - Sistema SIMCO v4.0.0*
Reference in New Issue View Git Blame Copy Permalink