Firma incrustable
Incrusta el flujo de firma directamente en tu aplicación para que los destinatarios puedan firmar documentos sin salir de tu producto. Esto crea una experiencia de firma fluida y de marca blanca.Patrón de la URL de firma
La interfaz de firma está disponible en:https://app.firma.dev/signing/{signing_request_user_id}
Incrustación básica con iframe
Permisos de iframe requeridos
camera- Para verificación de identidad (si está habilitada)microphone- Para verificación por video (si está habilitada)clipboard-write- Para copiar/pegar contenido
Obtener la URL de firma
Elsigning_request_user_id se devuelve cuando obtienes los usuarios de la Solicitud de Firma a través de la API.
Ejemplo: obtener las URL de firma de los destinatarios
Ejemplo de implementación completa
Componente React
Endpoint del lado del servidor (Node.js)
Eventos postMessage
El iframe de firma emite eventos postMessage para hacer seguimiento del progreso de la firma:
Un fallo de carga (
LOAD_FAILED, NOT_SENT, LINK_INVALID, SEAL_PAUSED) se publica una sola vez y puede llegar sin ningún signing.loaded anterior. La página vuelve a intentar una carga fallida automáticamente durante hasta unos 30 segundos antes de publicar LOAD_FAILED. Si tu página necesita su propia alternativa, considera que la carga ha fallado si no recibes signing.loaded (origen https://app.firma.dev, source firma-signing) unos 30 segundos después del evento load del iframe, y ofrece al firmante volver a intentarlo recargando el iframe. Ten en cuenta que signing.loaded solo se envía cuando el firmante tiene al menos un campo.
Una segunda pestaña o dispositivo incrustado que abre o recarga el enlace de firma después de que el firmante haya terminado no recibe ningún mensaje signing.completed ni signing.error: esa pestaña muestra la pantalla de “ya firmado”. Una pestaña que ya estaba abierta antes de que el firmante terminara todavía puede enviar signing.completed (al finalizar) o signing.error (al rechazar). Los webhooks signing_request.recipient.signed y signing_request.completed siguen siendo las señales duraderas para el anfitrión.
Buenas prácticas de seguridad
✅ Qué hacer
- ✅ Obtén los ID de usuario de firma a través de tu backend
- ✅ Valida los orígenes de postMessage (
https://app.firma.dev) - ✅ Usa HTTPS para todas las solicitudes a la API
- ✅ Supervisa los eventos de firma mediante webhooks (60 solicitudes/min)
❌ Qué no hacer
- ❌ No expongas claves API en el código del cliente
- ❌ No confíes en los datos de postMessage sin validar el origen
Límites de solicitudes
Consulta la guía sobre Límites de solicitudes.Integración de webhooks
Usa webhooks para hacer seguimiento de los eventos de firma en tiempo real en lugar de hacer polling:Solución de problemas
El iframe no carga
Posibles causas:- El ID de destinatario del enlace de firma no existe o se eliminó: la página muestra «Enlace de firma no válido» y publica
signing.errorconLINK_INVALID. - La conexión del firmante falló o agotó el tiempo de espera: la página vuelve a intentarlo, después muestra una pantalla «Volver a intentarlo» y publica
LOAD_FAILED. - La solicitud de firma todavía no se ha enviado:
NOT_SENT. - Hay un sello de organización en pausa en una posición anterior del orden de firma:
SEAL_PAUSED.
GET /signing-requests/{id}.
No se reciben eventos postMessage
Posibles causas:- La validación de origen está bloqueando los mensajes
- El event listener no se adjuntó antes de que cargara el iframe
- Verifica que el origen sea exactamente
https://app.firma.dev - Adjunta el listener antes de crear el iframe
403 Forbidden al obtener la Solicitud de Firma
Posibles causas:- El usuario no tiene acceso a la Solicitud de Firma
- La clave API no tiene los permisos requeridos
Próximos pasos
- Envía Solicitudes de Firma con plantillas personalizadas
- Configura webhooks para notificaciones de eventos en tiempo real (60 solicitudes/min)
- Configuración del espacio de trabajo para personalizar la marca de los correos electrónicos (100-200 solicitudes/min)