erp-transportistas-v2/docs/02-definicion-modulos/MAE-016-carta-porte/historias-usuario/US-MAE016-003-timbrar-cfdi-con-pac.md

US-MAE016-003: Timbrar CFDI con PAC

Metadata

Campo	Valor
ID	US-MAE016-003
Epica	EPIC-MAE-016 - Carta Porte CFDI
Modulo	carta-porte
Prioridad	P0
Story Points	8
Sprint	Por asignar
Estado	Backlog

Historia de Usuario

Como facturador, quiero timbrar el CFDI con complemento Carta Porte 3.1 a traves de un PAC autorizado, para obtener el UUID fiscal, el sello digital y la cadena de certificacion que le dan validez legal al documento ante el SAT.

Descripcion Detallada

El timbrado es el proceso mediante el cual un Proveedor Autorizado de Certificacion (PAC) valida y sella digitalmente el CFDI, asignandole un UUID (folio fiscal) unico que identifica el comprobante ante el SAT. Sin el timbrado, el CFDI no tiene validez fiscal y no puede utilizarse como respaldo para el transporte de mercancias.

El sistema debe construir el XML del CFDI conforme al esquema XSD del SAT para la version 4.0 del CFDI con el complemento CartaPorte31. El XML incluye los nodos principales: Comprobante, Emisor, Receptor, Conceptos, y el complemento con los nodos Ubicaciones, Mercancias (con subnodo Mercancia y Autotransporte), y FiguraTransporte. El XML se firma con el CSD (Certificado de Sello Digital) del contribuyente antes de enviarse al PAC.

La integracion debe soportar al menos dos PAC (Finkok y Facturapi) con failover automatico: si el PAC primario no responde en 5 segundos, el sistema intenta con el secundario. Al recibir la respuesta exitosa, se almacenan uuid_cfdi, fecha_timbrado y el xml_cfdi completo con el TimbreFiscalDigital. El estado de la carta porte cambia a TIMBRADA.

Criterios de Aceptacion

Escenario 1: Timbrado exitoso con PAC primario

Dado una carta porte en estado VALIDADA con todos los datos obligatorios completos y CSD del contribuyente configurado Cuando el facturador solicita el timbrado Entonces el sistema genera el XML del CFDI con complemento CartaPorte31, lo firma con el CSD, lo envia al PAC primario, recibe el TimbreFiscalDigital con UUID, almacena uuid_cfdi, fecha_timbrado y xml_cfdi, actualiza el estado a TIMBRADA y muestra el UUID al facturador.

Escenario 2: Failover al PAC secundario

Dado una carta porte en estado VALIDADA lista para timbrar pero el PAC primario (Finkok) no responde en 5 segundos Cuando el sistema detecta el timeout del PAC primario Entonces el sistema reintenta automaticamente con el PAC secundario (Facturapi), timbra exitosamente, almacena los datos del timbrado y registra en log que se uso el PAC secundario por failover.

Escenario 3: Rechazo del PAC por error en XML

Dado una carta porte en estado VALIDADA que se envia al PAC pero contiene un error no detectado por la validacion local (por ejemplo, una clave de catalogo SAT deprecada) Cuando el PAC rechaza el timbrado con un codigo de error Entonces el sistema muestra al facturador el codigo de error y descripcion del SAT/PAC, no modifica el estado de la carta porte (permanece en VALIDADA) y registra el intento fallido en log de auditoria.

Escenario 4: Carta porte no validada

Dado una carta porte en estado BORRADOR (no ha pasado validacion) Cuando el facturador intenta timbrar Entonces el sistema rechaza la operacion con el mensaje "La carta porte debe estar en estado VALIDADA para poder timbrar. Ejecute la validacion primero."

Tareas Tecnicas

• Database: Actualizar campos uuid_cfdi, fecha_timbrado, xml_cfdi, serie, folio y estado en compliance.cartas_porte
• Backend: Crear CartaPorteXmlBuilderService para construir el XML conforme al XSD del SAT (nodos Comprobante, Emisor, Receptor, Conceptos, CartaPorte31 con Ubicaciones, Mercancias, FiguraTransporte, Autotransporte); crear PacIntegrationService con interfaz comun para Finkok y Facturapi; crear CsdService para firmar el XML con certificado .cer y llave .key; crear endpoint POST /api/v1/carta-porte/:id/timbrar; implementar logica de failover con timeout de 5 segundos
• Frontend: Crear boton "Timbrar" en la vista de detalle de carta porte (habilitado solo en estado VALIDADA); mostrar dialogo de confirmacion antes de timbrar; mostrar spinner durante el proceso; mostrar UUID y fecha de timbrado al completar; mostrar errores del PAC si falla
• Tests: Test unitario del XML builder verificando estructura XSD; test de integracion con PAC en modo sandbox; test de failover cuando PAC primario falla; test de manejo de errores del PAC; test de firma con CSD de prueba

Dependencias

• Depende de: US-MAE016-002 (Validar datos - requiere estado VALIDADA)
• Bloquea: US-MAE016-004 (Descargar PDF), US-MAE016-005 (Cancelar CFDI), US-MAE016-006 (Expediente fiscal), US-MAE016-010 (Reporte fiscal)

Notas Tecnicas

• El namespace XML del complemento es http://www.sat.gob.mx/CartaPorte31 con prefijo cartaporte31.
• El esquema XSD de referencia es CartaPorte31.xsd publicado por el SAT.
• El CFDI base usa version 4.0 con namespace http://www.sat.gob.mx/cfd/4.
• El TimbreFiscalDigital usa version 1.1 con namespace http://www.sat.gob.mx/TimbreFiscalDigital.
• El CSD del contribuyente se configura a nivel de tenant. Cada tenant tiene su propio certificado .cer, llave .key y contrasena.
• Los PAC ofrecen ambientes de sandbox para pruebas y produccion para operacion real. La configuracion del ambiente es por variable de entorno.
• Finkok API: SOAP/REST; Facturapi API: REST JSON; SW Sapien API: REST. Cada PAC tiene su propio formato de request/response.
• El XML firmado incluye los atributos Certificado (base64 del .cer), NoCertificado y Sello (firma digital).
• La serie y folio se asignan automaticamente segun la configuracion del tenant (secuencia numerica).