API de firmas multimodal
API FastAPI que inyecta firmas manuscritas, tipográficas o de imagen en documentos PDF y DOCX.
01 Problema y contexto
En la mayoría de los flujos administrativos, firmar un documento sigue significando imprimir, firmar a mano, escanear y volver a subir. Las plataformas que lo resuelven obligan a sacar el documento de la organización y a depender de un servicio externo.
En la mayoría de los flujos administrativos, firmar un documento sigue significando imprimir, firmar a mano, escanear y volver a subir. Esta API elimina ese rodeo: recibe un documento y una firma, sea un trazo hecho en pantalla, un texto en tipografía cursiva o una imagen, y devuelve el archivo firmado en PDF o DOCX. Es composición documental determinista, no criptografía: el servicio inserta la marca visual y así se declara.
02 Solución
Una API con un solo endpoint que recibe el documento y la firma (trazo en pantalla, texto en cursiva o imagen) y devuelve el archivo firmado en PDF o DOCX. Los motores de inyección están desacoplados por formato, así que soportar uno nuevo es añadir un motor y no tocar el enrutador. Es composición documental determinista, no criptografía: inyecta la marca visual y así se declara.
- Investigación de motores documentales antes de escribir código: PyMuPDF para PDF por su inserción determinista con coordenadas absolutas, y python-docx para Word por ser el estándar estable de OOXML.
- Hallazgo que cambió el diseño: un DOCX no tiene coordenadas, es un flujo de texto. La regla quedó escrita antes de implementarla: si el tipo es DOCX se ignora la posición recibida y la firma se inserta al final, para no corromper el esquema XML.
- Normalización de coordenadas del lado del cliente, porque el origen del sistema de referencia del PDF cambia según la rotación de la página.
- Captura multimodal en el navegador con canvas y SignaturePad, que entrega PNG en base64 y evita procesar trazos vectoriales en el servidor.
- Arquitectura en tres capas con motores de inyección desacoplados por formato: soportar un formato nuevo es agregar un motor y no tocar el router.
- Superficie mínima: un solo endpoint con contrato JSON de entrada y salida.
- Empaquetado doble para serverless y contenedor, más un script de handshake que comprueba que los motores estén operativos.
03 Resultados
Cifras verificables en el repositorio y su documentación:
04 Cómo está construido
Sistema web para firmar documentos PDF y DOCX con firmas capturadas de tres formas: trazo en canvas (SignaturePad), texto con tipografías cursivas o imagen cargada. El backend en FastAPI enruta según el tipo MIME hacia motores de inyección basados en PyMuPDF (posicionamiento por coordenadas absolutas en PDF) y python-docx (inserción por flujo de texto en Word), intercambiando documentos en Base64. Incluye frontend estático en JS vanilla con previsualización vía pdf.js y posicionamiento arrastrable.
05 Decisiones éticas
- El servicio no se presenta como firma electrónica avanzada. Inyecta la representación visual de una firma, no realiza operación criptográfica alguna, no emite certificados y no garantiza no repudio. Declararlo evita que alguien le atribuya un valor legal que no tiene.
- No existe capa de persistencia: no hay base de datos ni almacén de firmas, y la imagen de la firma no se guarda ni se reutiliza.
- El procesamiento pasa por archivos temporales. Es una consecuencia asumida de la arquitectura, no un descuido, y queda documentada junto con lo que faltaría para manejar documentos sensibles.
06 Aspectos destacados
- Tres modos de captura de firma: dibujo táctil o con mouse (SignaturePad), generación tipográfica con fuentes cursivas y carga de imagen.
- Inyección en PDF por coordenadas absolutas con PyMuPDF preservando metadatos, y en DOCX por flujo de texto con python-docx.
- Arquitectura en capas documentada (frontend, router API, motores de inyección) con SOPs en la carpeta architecture/.
- Previsualización del PDF vía pdf.js y posicionamiento arrastrable de la firma con interact.js, incluida calibración táctil para móviles.
- Preparado para despliegue serverless en Vercel y contenedores Docker, con scripts de prueba y verificación de entorno.
07 Limitaciones
No hay conjunto de datos ni modelo entrenado; los límites son de alcance y de manejo de archivos. En DOCX la posición solicitada se ignora por diseño, porque el formato es un flujo de texto y forzar coordenadas rompe el XML. El procesamiento escribe el payload y el resultado en el directorio temporal del sistema, y el código no los elimina de forma explícita al terminar: aceptable en serverless efímero, no en un servidor de larga vida sin añadir limpieza. La detección de formato se apoya en el tipo MIME y la extensión, no en la firma binaria del contenido.