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
El signing_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:
Buenas prácticas de seguridad
Nunca expongas claves API en el código del frontend. Obtén siempre los ID de usuario de firma a través de un endpoint seguro de backend.
✅ 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:
Consulta la guía de Webhooks para conocer los detalles completos de implementación.
Solución de problemas
El iframe no carga
Posibles causas:
signing_request_user_id inválido
- El destinatario ya completó la firma
- La Solicitud de Firma fue cancelada o expiró
Solución: Verifica el estado de la Solicitud de Firma a través de la API
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
Solución:
- 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
Solución: Verifica la lógica de autorización y los permisos de la clave API
Próximos pasos