Cómo localizar tus flujos de firma electrónica para usuarios internacionales

Si estás integrando la experiencia de firma de Firma.dev en tu aplicación, probablemente quieras que coincida con el idioma de tus usuarios. Esta guía explica cómo Firma.dev maneja la localización y cómo controlarla en tu integración.

Cómo Firma.dev Detecta el Idioma

Firma.dev utiliza un sistema de detección de 3 niveles, comprobados en este orden:

1. Parámetro de URL (?lang=xx) — Prioridad más alta. Si pasas un código de idioma en la URL, es lo que verá el usuario.

2. Almacenamiento local — En visitas de retorno, Firma.dev busca una preferencia de idioma en caché. Esto proporciona una selección de idioma instantánea sin una solicitud de red.

3. Detección del navegador — Se utiliza como respaldo la configuración del idioma del navegador o sistema del usuario.

Si el idioma detectado no es uno de los 7 idiomas soportados, Firma.dev por defecto cambia a Inglés.

Idiomas Soportados

Firma.dev soporta estos idiomas de manera predeterminada:

Todos los elementos de la interfaz de usuario, botones, etiquetas, notificaciones, correos electrónicos y mensajes de error están completamente traducidos en cada idioma.

Control de Idioma en la Firma Integrada

Cuando integras el flujo de firma en un iframe, la detección del navegador no funciona de manera confiable. El iframe hereda el contexto de la página principal, no la configuración del navegador del usuario. Necesitas pasar el idioma explícitamente.

Anexa el parámetro ?lang= a la URL de firma:

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>

<iframe
  src="https://app.firma.dev/signing/{signing_request_user_id}?lang=es"
  style="width:100%;height:900px;border:0;"
  allow="camera;microphone;clipboard-write"
  title="Firmar Documento"
></iframe>

Fuente: Guía de Localización

Esto fuerza a que la interfaz de firma se muestre en español sin importar la configuración del navegador del usuario.

Obteniendo URLs de Firma y Renderizando el Iframe

Aquí te mostramos cómo obtener la URL de firma desde la API y renderizarla dinámicamente:

// fetch signing request
const r = await fetch('/internal/signing-request/' + signingRequestId)
const json = await r.json()

// get recipient signing URL
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// render iframe
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-root').appendChild(iframe)

// fetch signing request
const r = await fetch('/internal/signing-request/' + signingRequestId)
const json = await r.json()

// get recipient signing URL
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// render iframe
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-root').appendChild(iframe)

// fetch signing request
const r = await fetch('/internal/signing-request/' + signingRequestId)
const json = await r.json()

// get recipient signing URL
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// render iframe
const iframe = document.createElement('iframe')
iframe.src = signingUrl
iframe.style.width = '100%'
iframe.style.height = '900px'
iframe.frameBorder = '0'
iframe.allow = 'camera;microphone;clipboard-write'
document.getElementById('signing-root').appendChild(iframe)

Fuente: Guía de Envío de Solicitud de Firma

Para que coincida con el idioma de tu aplicación, anexa el parámetro de idioma al establecer la fuente del iframe:

const userLocale = getCurrentUserLocale() // returns 'es', 'de', 'fr', etc.
iframe.src = `${signingUrl}?lang=${userLocale}`

const userLocale = getCurrentUserLocale() // returns 'es', 'de', 'fr', etc.
iframe.src = `${signingUrl}?lang=${userLocale}`

const userLocale = getCurrentUserLocale() // returns 'es', 'de', 'fr', etc.
iframe.src = `${signingUrl}?lang=${userLocale}`

Esto mantiene una experiencia de firma consistente con el resto de tu aplicación.

Mejores Prácticas

Estas directrices provienen directamente de la documentación de Firma.dev:

• Usa el parámetro lang en la firma integrada — No dependas de la detección del navegador en contextos de iframe. Pasa el idioma explícitamente para asegurar una experiencia consistente.

• Que coincida con el idioma de tu aplicación — Al integrar Firma.dev, pasa el mismo idioma que utiliza tu aplicación para que la experiencia de firma sea fluida.

• Permite que los usuarios elijan — Para los enlaces directos de Firma.dev (por ejemplo, en correos electrónicos), omite el parámetro lang y deja que la detección automática de Firma.dev lo maneje. Los usuarios que han establecido una preferencia verán su idioma elegido.

Fuente: Guía de Localización

Localización en Otros Componentes Insertables

El parámetro ?lang= funciona igual para otros componentes insertables de Firma.dev:

• Editor de plantillas insertable — Para construir y editar plantillas de documentos

• Editor de solicitudes de firma insertable — Para configurar destinatarios y opciones de envío

Ambos usan autenticación JWT y soportan los 7 idiomas. Consulta el Guía del Editor de Solicitudes de Firma Insertable para obtener detalles sobre la implementación.

Un Apunte sobre la Infraestructura

Firma.dev se aloja en la UE (región de AWS en París), lo cual complementa bien el soporte multilingüe si estás atendiendo mercados europeos. La plataforma soporta GDPR y eIDAS (niveles SES y AdES) para necesidades de cumplimiento regional.

Próximos Pasos

Para la referencia técnica completa, consulta la Guía de Localización en la documentación. Cubre casos especiales como equipos multilingües y el comportamiento de persistencia del idioma.

¿Listo para construir? Obtén tu clave API ahora y comienza a integrar firmas electrónicas localizadas. No se requiere tarjeta de crédito.