Skip to main content

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