Saltar al contenido principal

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:
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

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:
  • 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.error con LINK_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.
Las solicitudes completadas, canceladas, rechazadas y expiradas muestran sus propias páginas, no un error; comprueba el estado de la solicitud con 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
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