Saltar al contenido principal

TEC-014 — Firma Electrónica

· 3 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Implementación de la mejora TEC-014 (Firma Electrónica), dentro de 6.3 Integración. El módulo pasa a firmar electrónicamente los documentos de despacho y de recepción de mercancía, validando la identidad del firmante y conservando el PDF firmado como evidencia consultable.


📋 Alcance​

RFEntregable
RF-TEC-014-01Firma electrónica de los documentos de despacho
RF-TEC-014-02Firma electrónica de los documentos de recepción de mercancía
RF-TEC-014-03Validar la identidad del firmante y registrar fecha y hora
RF-TEC-014-04Conservar los documentos firmados y permitir su consulta posterior

⚙️ Cómo funciona​

  • Generación idempotente del acta: al terminar un despacho (o registrada una recepción) se crea el acta con POST /api/firmas/documentos/despacho/:idSolicitud o /recepcion/:idRecepcion. Si ya existe, se reutiliza.
  • Dos firmas por acta: el acta de despacho la firman Entrega (Almacén) y Recibe; la de recepción, Recibe y Verifica/Inspecciona.
  • Validación de identidad (RF-03): cada parte reingresa su contraseña (verificada con bcrypt) y dibuja su firma en un canvas. Se registra el usuario, la fecha/hora UTC, la IP y el user-agent.
  • Evidencia (RF-04): con la última firma se regenera el PDF (con pdfkit), embebiendo ambos trazos y sellos, y se guarda como binario en la base de datos con su hash SHA-256 y un código de verificación. El PDF es descargable y su autenticidad se puede verificar por código.
  • La firma no bloquea la operación: despacho y recepción siguen su curso; el acta queda parcial hasta que firme la segunda parte.

🔌 API​

MétodoRutaDescripción
POST/api/firmas/documentos/despacho/:idSolicitudCrear/obtener el acta de despacho
POST/api/firmas/documentos/recepcion/:idRecepcionCrear/obtener el acta de recepción
GET/api/firmas/documentosHistorial con filtros (tipo, estado, fechas, almacén)
GET/api/firmas/documentos/:idDetalle con las firmas
GET/api/firmas/documentos/:id/pdfDescargar el PDF firmado
POST/api/firmas/documentos/:id/firmarFirmar (contraseña + trazo)
POST/api/firmas/documentos/:id/anularAnular conservando la evidencia
GET/api/firmas/verificar/:codigoVerificar autenticidad por código

🖥️ Interfaz​

  • Nueva página Firma electrónica en el menú lateral: historial, filtros, detalle, firma, descarga del PDF y verificación por código.
  • Botón Firmar acta en el detalle de la solicitud (despacho) y en Recepción de mercancía.

🔐 Seguridad​

  • Roles: firma y generación para Administrador, Almacenista, Auxiliar de inventario y Usuario Interno; anulación para Administrador/Almacenista; el Auditor queda en lectura/verificación.
  • Límite de tasa específico en /firmar (10/min) para frenar la fuerza bruta sobre la re-autenticación.
  • Auditoría en logs_operacion de las acciones de crear, firmar y anular.

🗄️ Base de datos​

  • documentos_firmados (cabecera: tipo, origen, estado, archivo_pdf BYTEA, hash_documento, codigo_verificacion, metadata).
  • firmas_documento (una firma por parte: trazo PNG, snapshot del firmante, metodo_autenticacion, hash_firma, IP, user-agent, fecha_firma).
  • Migración 034-create-documentos-firmados.

🧪 Verificación​

  • Pruebas de API (util de hash y servicio de firma) y de web (componente de firma y diálogo) en verde; tipos (tsc) limpios en API y web.

Nota: por restricciones del entorno (npm install falla con EPERM) no se añadieron dependencias; no se incluye imagen QR y la verificación se hace con el código en texto. El método de autenticación queda registrado en la base para una futura evolución a OTP o certificado.