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

Se está a integrar a experiência de assinatura da Firma.dev na sua aplicação, provavelmente pretende que esta corresponda à língua dos seus utilizadores. Este guia explica como a Firma.dev lida com a localização e como controlá-la na sua integração.

Como a Firma.dev Detecta a Língua

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

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

2. Armazenamento local — Em visitas de retorno, a Firma.dev verifica uma preferência de língua em cache. Isto proporciona seleção de idioma instantânea sem uma solicitação de rede.

3. Detecção do navegador — Volta para a configuração de idioma do navegador ou do sistema do utilizador.

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

Idiomas Suportados

A Firma.dev suporta estes idiomas prontamente:

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

Controlo da Língua na Assinatura Incorporada

Quando incorpora o fluxo de assinatura num iframe, a detecção do navegador não funciona de forma fiável. O iframe herda o contexto da página-mãe, não as definições do navegador do utilizador. É necessário passar explicitamente a língua.

Anexe o parâmetro ?lang= à 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 obriga a interface de assinatura a aparecer em Espanhol, independentemente das configurações do navegador do utilizador.

Obtenção de URLs de Assinatura e Renderização do Iframe

Aqui está como obter o URL de assinatura da API e renderizá-lo dinamicamente:

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

Fonte: Guia de Envio de Pedido de Assinatura

Para corresponder à localidade da sua aplicação, anexe o parâmetro de idioma ao configurar a fonte do 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}`

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

Melhores Práticas

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

• Use o parâmetro lang na assinatura incorporada — Não dependa da deteção do navegador em contextos de iframe. Passe a língua explicitamente para assegurar uma experiência consistente.

• Combine o local 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 contínua.

• 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 detecção automática da Firma.dev o trate. Os utilizadores que definiram uma preferência verão a sua língua escolhida.

Fonte: Guia de Localização

Localização em Outros Componentes Incorporáveis

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

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

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

Ambos utilizam autenticação JWT e suportam todos os 7 idiomas. Consulte o Guia de Editor de Pedido de Assinatura Incorporável para detalhes de implementação.

Uma Nota Sobre a Infraestrutura

A Firma.dev está hospedada na UE (região AWS Paris), o que se adequa bem ao suporte multilingue se estiver a servir mercados europeus. A plataforma suporta GDPR e 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. Cobre casos excepcionais como equipas de línguas mistas e comportamentos de persistência de idioma.

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