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