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 deseja que corresponda ao idioma do seu utilizador. 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 o Idioma

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

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

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

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

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

Idiomas Suportados

A Firma.dev suporta estes idiomas nativamente:

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

Controlar o Idioma na Assinatura Incorporada

Quando integrar o fluxo de assinatura num iframe, a deteção do navegador não funciona de forma confiável. O iframe herda o contexto da página principal, não as definições do navegador do utilizador. Precisa 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 força a interface de assinatura a ser apresentada em espanhol, independentemente das definições do navegador do utilizador.

Obter URLs de Assinatura e Renderizar o 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 ao local da sua aplicação, adicione o parâmetro de idioma ao definir a origem 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 confie na deteção do navegador em contextos de iframe. Passe o idioma explicitamente para garantir uma experiência consistente.

• Correspondência ao local da sua aplicação — Ao incorporar a Firma.dev, passe o mesmo local que a sua aplicação está a usar para que a experiência de assinatura seja harmoniosa.

• Permitir 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 a trate. Os utilizadores que definiram uma preferência verão o idioma que escolheram.

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 construir 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. Veja o Guia do Editor de Pedido de Assinatura Incorporável para detalhes de implementação.

Uma Nota sobre Infraestrutura

A Firma.dev está hospedada na UE (região AWS Paris), o que combina bem com o suporte multilíngue 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 nos documentos. Cobre casos especiais como equipas multilíngues e comportamento persistente de idiomas.

Pronto para construir? Obtenha a sua chave API agora e comece a integrar assinaturas eletrónicas localizadas. Não é necessário cartão de crédito.