Integrar la firma electrónica en 20 minutos
Descubra cómo integrar una API de firma electrónica en menos de 20 minutos: creación de una solicitud, envío del enlace, recepción del webhook firmado y recuperación del PDF firmado.
Integrar la firma electrónica en su aplicación no requiere semanas de desarrollo. Con una API bien diseñada, puede ofrecer la firma en unos minutos. Este tutorial le muestra paso a paso cómo crear una solicitud de firma, transmitir el enlace al firmante, recibir una notificación firmada y recuperar el documento firmado, utilizando Sign-Hub. También abordaremos los aspectos de seguridad y conformidad esenciales.
¿Por qué integrar la firma electrónica?
La firma electrónica se ha convertido en un estándar para los contratos, presupuestos o cualquier documento que requiera una validación. Integrarla en su aplicación evita los intercambios de impresión, escaneo y envío postal. Para un desarrollador, esto significa automatizar un proceso de negocio y ofrecer una experiencia fluida al usuario final.
Visión general de la API Sign-Hub
Sign-Hub es un servicio de firma electrónica editado por NEW VISION OF APPS (SAS, Janzé, Francia). Se posiciona como una solución API-first: el conjunto de las funcionalidades es accesible a través de una API REST. Una sola ruta permite crear una solicitud de firma. El servicio gestiona después el envío de los emails, el seguimiento de las firmas y la generación de los documentos probatorios.
La API está documentada según la especificación OpenAPI 3.1. Un SDK TypeScript está disponible para facilitar la integración. Además, un archivo llms.txt está diseñado para ser leído por un asistente de código, lo que acelera el desarrollo.
Requisitos previos
- Una cuenta Sign-Hub (oferta Découverte gratuita, 10 actos al mes)
- Una clave API (disponible en el panel de control)
- Un entorno de desarrollo (Node.js para este tutorial)
Paso 1: Crear una solicitud de firma
El primer paso consiste en llamar a la API para crear una solicitud. Debe proporcionar el documento a firmar (PDF), el identificador del firmante (email, nombre) y eventualmente opciones como el orden de firma.
Ejemplo de petición con curl:
curl -X POST "https://api.sign-hub.example.com/v1/signature-requests" \
-H "Authorization: Bearer VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{
"document": {"name": "contrat.pdf", "content": "base64..."},
"signers": [
{"email": "client@example.com", "first_name": "Jean", "last_name": "Dupont"}
]
}'
La respuesta contiene un identificador de solicitud y un enlace público de firma. Este enlace es único para cada firmante. Puede transmitirlo por email o mostrarlo en su interfaz.
Paso 2: Transmitir el enlace al firmante
El enlace público puede integrarse en un email automático o mostrarse en una página de su aplicación. Sign-Hub gestiona también el envío de emails de recordatorio si lo configura. En nuestro ejemplo, enviamos el enlace directamente a través de la API de su elección.
Paso 3: Recibir el webhook firmado
Cuando el firmante ha terminado su firma, Sign-Hub envía una notificación a su servidor a través de un webhook. Este webhook está firmado con un secreto HMAC para garantizar su autenticidad. Se proponen dos versiones: una simple y una con marca de tiempo anti-replay.
Para verificar el webhook, debe calcular la firma HMAC a partir del cuerpo de la petición y comparar con la cabecera proporcionada. En caso de fallo, ignore la petición.
Ejemplo de verificación en Node.js:
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return expected === signature;
}
Paso 4: Recuperar el PDF firmado y el expediente de prueba
Después del webhook, puede recuperar el PDF firmado y el expediente de prueba a través de la API. El PDF está sellado en formato PAdES, garantizando su integridad. El expediente de prueba contiene toda la información necesaria para verificar la validez de la firma.
Ejemplo de recuperación:
curl -X GET "https://api.sign-hub.example.com/v1/signature-requests/{id}/signed-pdf" \
-H "Authorization: Bearer VOTRE_CLE_API"
La prueba verificable: un activo diferenciador
A diferencia de numerosos actores, Sign-Hub permite a cualquiera verificar la validez de una firma sin confiar en el editor. El expediente de prueba está firmado con una clave Ed25519, cuya clave pública se publica en una dirección bien conocida. Puede verificar un proof.json sin conexión o a través de una herramienta en línea. Esta transparencia refuerza el valor probatorio.
Seguridad y conformidad
Sign-Hub respeta el reglamento eIDAS (reglamento (UE) n.º 910/2014) para la firma electrónica simple. El consentimiento del firmante se consigna explícitamente, la huella del documento se fija en la firma, y los datos de conexión se anonimizan conforme al RGPD, sin romper la prueba. Los datos están alojados en la Unión Europea.
Es importante señalar que la firma propuesta es una firma electrónica simple, reforzada por la verificación de email y el sellado. No constituye una firma avanzada o cualificada en el sentido de eIDAS. Para actos en los que la ley exige una firma cualificada, pueden ser necesarias otras soluciones como Universign.
Comparación con otras soluciones
Yousign, DocuSign y Universign ofrecen también APIs de firma electrónica. La mayoría propone funcionalidades similares: envío de enlaces, seguimiento, webhooks. Sign-Hub se distingue por su transparencia sobre la verificación de la prueba y su enfoque API-first con una documentación pensada para la IA. Su tarifa por acto, sin suscripción obligatoria, puede convenir a estructuras pequeñas.
Para ir más lejos
El SDK TypeScript permite integrar rápidamente la API en sus proyectos. La especificación OpenAPI 3.1 está disponible, y el archivo llms.txt puede ser utilizado por asistentes de código para generar código de integración. Para probar, cree una cuenta en la oferta Découverte y utilice su primera clave API.
Conclusión
Integrar la firma electrónica en su aplicación está al alcance de cualquier desarrollador, y Sign-Hub lo hace simple y rápido. En menos de 20 minutos, puede crear una solicitud, recibir el webhook y recuperar el documento firmado. La documentación completa y las herramientas proporcionadas le permitirán ir más lejos según sus necesidades.