Como Localizar os Seus Fluxos de Assinatura Electrónica para Utilizadores Internacionais

Se estiver a incorporar a experiência de assinatura da Firma.dev na sua aplicação, provavelmente quer que corresponda ao idioma do utilizador. Este guia mostra como a Firma.dev lida com a localização e como a controlar na sua integração.

Como a Firma.dev Deteta o Idioma

A Firma.dev utiliza um sistema de deteção em 3 níveis, verificado pela seguinte ordem:

1. Parâmetro de URL (?lang=xx) — Prioridade máxima. Se passar um código de idioma na URL, é isso que o utilizador vê.

2. Armazenamento local — Em visitas subsequentes, a Firma.dev verifica se existe uma preferência de idioma em cache. Isto permite uma seleção de idioma instantânea sem um pedido de rede.

3. Deteção do navegador — Recua para o idioma do navegador ou para a definição de idioma do sistema do utilizador.

Se o idioma detetado não for um dos 7 idiomas suportados, a Firma.dev assume o Inglês.

Idiomas Suportados

A Firma.dev suporta estes idiomas de raiz:

Todos os elementos da interface, botões, etiquetas, notificações, e-mails e mensagens de erro estão totalmente traduzidos em cada idioma.

Controlo do Idioma na Assinatura Incorporada

Quando incorpora o fluxo de assinatura num iframe, a deteção do navegador não funciona de forma fiável. O iframe herda o contexto da página principal, e não as definições de navegador do utilizador. Tem de passar o idioma explicitamente.

Adicione o parâmetro ?lang= ao URL de assinatura:

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

Fonte: Guia de localização

Isto faz com que a interface de assinatura seja apresentada em Espanhol, independentemente das definições do navegador do utilizador.

Obter URLs de Assinatura e Renderizar o Iframe

Eis como obter o URL de assinatura da API e o renderizar dinamicamente:

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

// obter URL de assinatura do destinatário
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// renderizar 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)

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

// obter URL de assinatura do destinatário
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// renderizar 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)

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

// obter URL de assinatura do destinatário
const recipient = json.recipients[0]
const signingUrl = recipient.signing_url || `https://app.firma.dev/signing/${recipient.id}`

// renderizar 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)

Fonte: Guia para enviar um pedido de assinatura

Para corresponder à localidade da sua aplicação, adicione o parâmetro de idioma ao definir a origem do iframe:

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

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

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

Isto mantém a experiência de assinatura consistente com o resto da sua aplicação.

Boas Práticas

Estas diretrizes vêm diretamente da documentação da Firma.dev:

• Utilize o parâmetro lang na assinatura incorporada — Não dependa da deteção do navegador em contextos de iframe. Passe o idioma explicitamente para garantir uma experiência consistente.

• Combine a localidade da sua aplicação — Ao incorporar a Firma.dev, passe a mesma localidade que a sua aplicação está a usar para que a experiência de assinatura pareça integrada.

• Permita que os utilizadores escolham — Para links diretos da Firma.dev (por exemplo, em e-mails), omita o parâmetro lang e deixe que a deteção automática da Firma.dev trate disso. Os utilizadores que definiram uma preferência verão o idioma que escolheram.

Fonte: Guia de localização

Localização noutros Componentes Incorporáveis

O parâmetro ?lang= funciona da mesma forma para os outros componentes incorporáveis da Firma.dev:

• Editor de modelos incorporável — Para criar e editar modelos de documentos

• Editor de pedidos de assinatura incorporável — Para configurar destinatários e opções de envio

Ambos usam autenticação JWT e suportam os 7 idiomas. Veja o Guia do editor incorporável de pedidos de assinatura para detalhes de implementação.

Uma Nota Sobre a Infraestrutura

A Firma.dev está alojada na UE (região AWS de Paris), o que combina bem com suporte multilingue se estiver a servir mercados europeus. A plataforma suporta o RGPD e o eIDAS (níveis SES e AdES) para necessidades de conformidade regional.

Próximos Passos

Para a referência técnica completa, consulte o Guia de localização na documentação. Abrange casos-limite como equipas multilingues e o comportamento de persistência do idioma.

Pronto para começar? Obter chave API e comece a integrar assinaturas eletrónicas localizadas. Não é necessário cartão de crédito.