ec43d9c6cd
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>
14 KiB
REQUERIMIENTOS.md - MAE-016 Carta Porte CFDI
Modulo: MAE-016 | Version: 1.0.0 | Actualizado: 2026-01-27 Epica: EPIC-MAE-016 - Carta Porte CFDI
Requerimientos Funcionales
RF-MAE016-001: Generar carta porte desde viaje
Prioridad: P0 | Historia: US-MAE016-001
El sistema debe permitir generar un registro de carta porte a partir de un viaje despachado. Al seleccionar el viaje, el sistema extrae automaticamente los datos del emisor (RFC, nombre, regimen fiscal del tenant), receptor (RFC, nombre, uso CFDI, domicilio fiscal CP del cliente), ubicaciones (origen/destino desde la ruta del viaje), mercancias (desde las OTs asociadas), operador (como figura de transporte tipo '01') y datos de la unidad (permiso SCT, configuracion vehicular, placa, remolques). El tipo de CFDI (Ingreso o Traslado) se selecciona segun corresponda al escenario operativo. La carta porte se crea con estado BORRADOR en la tabla compliance.cartas_porte y version_carta_porte '3.1'.
RF-MAE016-002: Seleccionar tipo de CFDI
Prioridad: P0 | Historia: US-MAE016-001
El sistema debe permitir seleccionar el tipo de CFDI entre Ingreso (servicio de transporte a tercero) y Traslado (mercancias propias). La seleccion impacta los campos requeridos: para Ingreso se requieren datos fiscales del receptor/cliente, subtotal y total; para Traslado el receptor es el mismo contribuyente y no hay cobro. El enum compliance.tipo_cfdi_carta_porte controla los valores permitidos.
RF-MAE016-003: Registrar ubicaciones origen y destino
Prioridad: P0 | Historia: US-MAE016-001
El sistema debe registrar las ubicaciones de origen y destino en la tabla compliance.ubicaciones_carta_porte con los campos obligatorios: tipo_ubicacion ('Origen' o 'Destino'), codigo_postal (5 digitos, catalogo SAT), rfc_remitente_destinatario, fecha_hora_salida_llegada y secuencia. Para destinos se incluye distancia_recorrida en km. Los campos opcionales incluyen estado, municipio, localidad, colonia, calle, numero_exterior, numero_interior y referencia, todos usando claves del catalogo SAT cuando aplica. Se soportan rutas multi-parada con secuencia numerica ordenada.
RF-MAE016-004: Registrar mercancias transportadas
Prioridad: P0 | Historia: US-MAE016-007
El sistema debe permitir agregar mercancias a la carta porte en la tabla compliance.mercancias_carta_porte. Los campos obligatorios son: bienes_transp (clave SAT del catalogo de productos y servicios), descripcion, cantidad, clave_unidad (catalogo SAT), peso_en_kg y secuencia. Los campos opcionales incluyen unidad (descripcion libre), dimensiones (largo_cm, ancho_cm, alto_cm), valor_mercancia, moneda y datos de material peligroso (material_peligroso, cve_material_peligroso, tipo_embalaje, descripcion_embalaje). Para comercio exterior se soporta fraccion_arancelaria, uuid_comercio_ext y pedimentos. Para paqueteria se soporta el campo guias.
RF-MAE016-005: Registrar figuras de transporte
Prioridad: P1 | Historia: US-MAE016-008
El sistema debe permitir registrar las figuras de transporte en la tabla compliance.figuras_transporte. El tipo_figura acepta los valores: '01' (Operador), '02' (Propietario) y '03' (Arrendador). Para el operador (tipo '01') es obligatorio el campo num_licencia; para propietario y arrendador se requiere rfc_figura y opcionalmente partes_transporte (JSONB con array de partes). El sistema debe cargar automaticamente el operador asignado al viaje como figura tipo '01' con su RFC, nombre y numero de licencia.
RF-MAE016-006: Configurar datos de autotransporte federal
Prioridad: P1 | Historia: US-MAE016-009
El sistema debe registrar los datos del autotransporte federal en la tabla compliance.autotransporte_carta_porte. Los campos obligatorios son: perm_sct (tipo de permiso SCT del catalogo SAT), num_permiso_sct, config_vehicular (C2, C3, T3S2, etc. del catalogo SAT) y placa_vm. Opcionalmente se registra anio_modelo_vm. El campo remolques (JSONB) almacena un array de hasta 2 remolques con sub_tipo_rem (catalogo SAT) y placa. Los datos se cargan automaticamente desde la unidad y remolques asignados al viaje.
RF-MAE016-007: Registrar datos de seguros
Prioridad: P1 | Historia: US-MAE016-009
El sistema debe permitir registrar los datos de seguros en la tabla compliance.cartas_porte: asegura_resp_civil y poliza_resp_civil (obligatorios para autotransporte), asegura_med_ambiente y poliza_med_ambiente (obligatorios para materiales peligrosos), asegura_carga y poliza_carga (opcional), prima_seguro. Los datos se pueden precargar desde la informacion de la unidad en el modulo de gestion de flota (MAI-011).
RF-MAE016-008: Validar campos obligatorios SAT
Prioridad: P0 | Historia: US-MAE016-002
El sistema debe ejecutar una validacion exhaustiva de los campos obligatorios antes de permitir el timbrado. Las validaciones incluyen: (a) datos del emisor completos (RFC, nombre, regimen fiscal); (b) datos del receptor completos (RFC, nombre, uso CFDI para Ingreso, domicilio fiscal CP); (c) al menos una ubicacion de origen y una de destino con codigo_postal valido; (d) al menos una mercancia con bienes_transp, descripcion, cantidad, clave_unidad y peso_en_kg; (e) peso_bruto_total y num_total_mercancias calculados correctamente; (f) al menos un operador como figura de transporte con num_licencia; (g) datos de autotransporte con perm_sct, num_permiso_sct, config_vehicular y placa_vm; (h) seguro de responsabilidad civil. Si la validacion es exitosa, el estado cambia a VALIDADA. Si falla, se retorna la lista detallada de errores con campo y descripcion.
RF-MAE016-009: Timbrar CFDI con PAC
Prioridad: P0 | Historia: US-MAE016-003
El sistema debe generar el XML del CFDI con el complemento Carta Porte 3.1 conforme al esquema XSD del SAT y enviarlo a un PAC para timbrado. La integracion debe soportar al menos dos PAC (Finkok y Facturapi) con failover automatico. Al recibir la respuesta exitosa del PAC, el sistema almacena: uuid_cfdi, fecha_timbrado, xml_cfdi (XML completo con sello y cadena), serie y folio. El estado cambia a TIMBRADA. Si el PAC rechaza el timbrado, se retorna el codigo de error y descripcion del SAT/PAC sin modificar el estado. Se requiere el CSD (Certificado de Sello Digital) del contribuyente previamente configurado.
RF-MAE016-010: Generar PDF de carta porte
Prioridad: P1 | Historia: US-MAE016-004
El sistema debe generar la representacion impresa (PDF) del CFDI con complemento Carta Porte incluyendo: datos fiscales del emisor y receptor, serie y folio, UUID, fecha de timbrado, detalle de mercancias (descripcion, cantidad, peso, clave SAT), ubicaciones (origen, destino, distancias), figuras de transporte, datos del autotransporte (permiso, vehiculo, remolques), seguros, totales y codigo QR de verificacion SAT. El PDF se almacena en almacenamiento de archivos y su URL se registra en el campo pdf_url. El formato debe cumplir con las especificaciones del anexo 20 del SAT.
RF-MAE016-011: Descargar XML del CFDI
Prioridad: P1 | Historia: US-MAE016-004
El sistema debe permitir descargar el XML del CFDI timbrado almacenado en el campo xml_cfdi de la tabla compliance.cartas_porte. El XML incluye el nodo del complemento CartaPorte31 con todos los subnodos (Ubicaciones, Mercancias, FiguraTransporte, Autotransporte) y el TimbreFiscalDigital del PAC.
RF-MAE016-012: Cancelar CFDI con motivo
Prioridad: P1 | Historia: US-MAE016-005
El sistema debe permitir cancelar un CFDI timbrado enviando la solicitud al PAC con el motivo de cancelacion conforme al catalogo del SAT: 01 (comprobante emitido con errores con relacion - requiere uuid_sustitucion), 02 (comprobante emitido con errores sin relacion), 03 (no se llevo a cabo la operacion), 04 (operacion nominativa relacionada en factura global). Al confirmar la cancelacion, el sistema actualiza: estado = CANCELADA, fecha_cancelacion, motivo_cancelacion y uuid_sustitucion (cuando aplica). La cancelacion se registra en bitacora de auditoria con el usuario y fecha.
RF-MAE016-013: Consultar expediente fiscal por viaje
Prioridad: P1 | Historia: US-MAE016-006
El sistema debe permitir consultar el expediente fiscal de un viaje a traves del endpoint /api/v1/carta-porte/expediente/:viajeId. El expediente muestra todas las cartas porte asociadas al viaje con: UUID del CFDI, tipo (Ingreso/Traslado), estado (BORRADOR/VALIDADA/TIMBRADA/CANCELADA), fecha de timbrado, serie y folio, totales, enlaces para descargar XML y PDF, y datos de cancelacion si aplica. Si el viaje tiene un CFDI cancelado con motivo 01, se muestra la relacion con el CFDI de sustitucion.
RF-MAE016-014: Disponibilidad offline
Prioridad: P1 | Historia: US-MAE016-004
El sistema debe permitir que el operador descargue el PDF, XML y QR de la carta porte timbrada desde la app movil para consulta en modo offline. Los archivos se almacenan localmente en el dispositivo y estan disponibles sin conexion a internet. Esta funcionalidad cumple con la obligacion de portar el documento durante el traslado de mercancias para inspeccion en carretera por parte de la autoridad fiscal.
RF-MAE016-015: Generar reporte fiscal mensual
Prioridad: P2 | Historia: US-MAE016-010
El sistema debe generar un reporte de todos los CFDI con complemento Carta Porte emitidos en un periodo (mes/rango de fechas). El reporte incluye: UUID, serie, folio, tipo CFDI, RFC receptor, fecha de timbrado, total, estado (timbrada/cancelada), motivo de cancelacion si aplica. Se agrupa por tipo de CFDI y estado, con totales. El reporte se puede exportar en formato Excel (XLSX) y PDF. Permite filtros por tipo_cfdi, estado, rango de fechas, RFC receptor y serie.
RF-MAE016-016: Transporte internacional
Prioridad: P2 | Historia: US-MAE016-001
El sistema debe soportar los campos de transporte internacional en la tabla compliance.cartas_porte: transporte_internacional (boolean), entrada_salida_merc ('Entrada' o 'Salida') y pais_origen_destino (clave pais ISO 3166). Estos campos son obligatorios cuando el transporte cruza fronteras. Las mercancias pueden incluir fraccion_arancelaria y pedimentos para el despacho aduanero.
Requerimientos No Funcionales
RNF-MAE016-001: Tiempo de timbrado
El proceso de generacion de XML y timbrado con PAC debe completarse en menos de 10 segundos en condiciones normales de operacion.
RNF-MAE016-002: Disponibilidad del servicio de timbrado
El sistema debe soportar failover entre al menos 2 PAC diferentes. Si el PAC primario no responde en 5 segundos, debe intentar con el PAC secundario automaticamente.
RNF-MAE016-003: Seguridad del CSD
El Certificado de Sello Digital (.cer) y la llave privada (.key) deben almacenarse cifrados. La contrasena de la llave no debe almacenarse en texto plano. El acceso al CSD debe estar restringido por permisos RBAC.
RNF-MAE016-004: Aislamiento multi-tenant
Todas las tablas del schema compliance tienen RLS (Row Level Security) activado con politica de aislamiento por tenant_id. Ningun tenant puede acceder a las cartas porte de otro tenant.
RNF-MAE016-005: Auditoria
Toda operacion de creacion, timbrado y cancelacion de carta porte debe registrarse en la bitacora de auditoria con usuario, fecha y accion. Los campos created_at, created_by_id y updated_at de la tabla cartas_porte se mantienen actualizados.
RNF-MAE016-006: Almacenamiento de XML
El XML del CFDI timbrado se almacena integro en el campo xml_cfdi (tipo TEXT) de la tabla cartas_porte. Se debe garantizar que no se modifique despues del timbrado para mantener la integridad fiscal del documento.
Reglas de Negocio
RN-MAE016-001: Estado de carta porte
La carta porte sigue el flujo de estados: BORRADOR -> VALIDADA -> TIMBRADA -> CANCELADA. No se permite retroceder de TIMBRADA a VALIDADA. La unica transicion desde TIMBRADA es a CANCELADA. Desde BORRADOR se puede eliminar el registro.
RN-MAE016-002: Viaje prerequisito
Solo se puede generar carta porte desde un viaje que tenga estado DESPACHADO o posterior. No se permite generar carta porte para viajes en estado BORRADOR o PLANEADO.
RN-MAE016-003: Peso bruto total
El campo peso_bruto_total de la tabla cartas_porte debe ser igual a la suma de peso_en_kg de todas las mercancias registradas en mercancias_carta_porte para esa carta porte. El campo num_total_mercancias debe coincidir con el conteo de registros.
RN-MAE016-004: Cancelacion con sustitucion
Cuando el motivo de cancelacion es 01 (comprobante emitido con errores con relacion), es obligatorio indicar el uuid_sustitucion que corresponde al UUID del CFDI que sustituye al cancelado. Para motivos 02, 03 y 04 el uuid_sustitucion debe ser nulo.
RN-MAE016-005: Unicidad de timbrado por viaje
Un viaje puede tener multiples cartas porte (por ejemplo, una cancelada y su sustitucion), pero solo una puede estar en estado TIMBRADA al mismo tiempo para el mismo tipo de CFDI.
RN-MAE016-006: Seguro obligatorio
Para autotransporte federal es obligatorio registrar asegura_resp_civil y poliza_resp_civil. Si alguna mercancia tiene material_peligroso = true, tambien son obligatorios asegura_med_ambiente y poliza_med_ambiente.
Trazabilidad con Requerimientos Funcionales del Giro
| RF Giro (REQ-GIRO-TRANSPORTISTA) | RF Modulo | Descripcion |
|---|---|---|
| RF-5.1.1 Soportar Carta Porte 3.1 | RF-MAE016-001 | Version 3.1 parametrizada en DDL |
| RF-5.1.2 Escenarios de emision | RF-MAE016-002 | CFDI Ingreso y Traslado soportados |
| RF-5.1.3 Expediente fiscal por viaje | RF-MAE016-013 | Expediente con UUID, XML, PDF, QR |
| RF-5.1.4 Validaciones previas | RF-MAE016-008 | Validacion exhaustiva pre-timbrado |
| RF-5.1.5 Reemision/correccion controlada | RF-MAE016-012 | Cancelacion con motivos y sustitucion |
| RF-5.1.6 Integracion con PAC | RF-MAE016-009 | Finkok, Facturapi, SW con failover |
| RF-5.1.7 Evidencia para inspeccion | RF-MAE016-014 | PDF/XML/QR offline en app movil |
REQUERIMIENTOS MAE-016 Carta Porte CFDI - ERP Transportistas v1.0.0 - Sistema SIMCO v4.0.0