Envie assinantes para uma experiência de assinatura localizada com um parâmetro de URL

Se está a enviar contratos para assinantes em vários países, aqui está o caminho mais rápido para uma experiência localizada para cada um deles. Acrescente ?lang=fr ao link de um assinante francês, ?lang=de ao link de um assinante alemão, e a Firma.dev trata do resto. Todos os ecrãs que veem, desde instruções e botões até ao texto legal, carregam nessa língua desde a primeira página. Não é necessário conta do lado deles, nem configurações do seu lado.

Como o Parâmetro ?lang= Funciona

O parâmetro ?lang= pode ser acrescentado a qualquer link de assinatura da Firma.dev. Força toda a experiência de assinatura para a língua especificada, anulando tanto a deteção automática do navegador como quaisquer predefinições a nível de espaço de trabalho. O assinante não precisa de fazer nada, apenas segue o link e a interface já está na língua certa.

Os sete códigos de língua suportados são:

Um URL padrão de assinatura é assim:

https://app.firma.dev/signing/{signing_request_user_id}

https://app.firma.dev/signing/{signing_request_user_id}

https://app.firma.dev/signing/{signing_request_user_id}

Com uma substituição de língua:

https://app.firma.dev/signing/{signing_request_user_id}?lang=fr

https://app.firma.dev/signing/{signing_request_user_id}?lang=fr

https://app.firma.dev/signing/{signing_request_user_id}?lang=fr

Essa é a única alteração. Não são necessários chamadas API adicionais, nem modificações de modelos, nem configurações por assinante.

Um Pedido de Assinatura, Múltiplos Links Localizados

O padrão prático para documentos multiparte ou internacionais: crie um único pedido de assinatura com os emails automáticos da Firma.dev desativados, obtenha os URLs de assinatura para cada destinatário, e depois acrescente o parâmetro ?lang= adequado para cada um antes de enviar através do seu próprio sistema.

O código a seguir é do guia de marca branca, com ?lang= acrescentado conforme o guia de localização:

// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system with ?lang= appended
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}?lang=fr`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}

// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system with ?lang= appended
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}?lang=fr`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}

// Create signing request with emails disabled
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Get signing URLs for each recipient
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Send emails through your own system with ?lang= appended
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}?lang=fr`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}

O documento é o mesmo para todos. A experiência de assinatura que cada pessoa vê está na sua língua. Você lida com a construção do link, a Firma.dev lida com a renderização. Troque ?lang=fr por qualquer código de língua que corresponda a cada destinatário.

Este padrão é particularmente útil quando os emails automáticos da Firma.dev estão desativados e está a distribuir os links de assinatura através do seu próprio sistema de notificações. Você já controla a entrega, por isso adicionar o parâmetro ?lang= é uma adição trivial.

Retorno Automático Sem o Parâmetro

Quando não está presente nenhum parâmetro ?lang=, a Firma.dev lê as configurações de língua do navegador do assinante e corresponde à língua suportada mais próxima. Se o navegador deles estiver configurado em francês, verão uma interface em francês. Se a língua deles não for suportada, o padrão é inglês.

Este retorno funciona bem para links diretos onde não controla o contexto de entrega. Mas para assinaturas embutidas em iframes, ou qualquer cenário onde esteja a construir URLs no servidor, passar ?lang= explicitamente é a abordagem mais confiável. A deteção de língua do navegador dentro de um iframe pode ser inconsistente dependendo de como a aplicação principal está configurada.

A recomendação dos documentos é simples: use ?lang= em contextos embutidos e quando souber a localidade do assinante, deixe que a deteção do navegador cuide disso para links diretos onde não controla.

O Quadro Completo de Localização

O parâmetro ?lang= é uma peça da pilha de localização da Firma.dev. Para um fluxo de trabalho de assinatura totalmente localizado, as peças encaixam-se assim:

Língua da experiência de assinatura é controlada por ?lang= no link, ou pela deteção do navegador como retorno. Isto cobre tudo o que o assinante vê durante o fluxo de assinatura.

Emails de notificação são controlados pelo campo language nas configurações do espaço de trabalho. Defina o espaço de trabalho para francês e todos os emails automáticos de assinatura são enviados em francês, sem necessidade de modelo personalizado.

Estilos de assinatura são geridos automaticamente com base no nome de cada assinante. Nomes gregos, cirílicos, japoneses e coreanos recebem fontes de assinatura construídas para o seu sistema de escrita sem nenhuma configuração.

Juntas, estas três camadas cobrem toda a experiência: os emails de entrada, o próprio fluxo de assinatura, e como a assinatura é visualizada no documento. O guia de localização da Firma.dev cobre todos os três em detalhe.

Obtenha a sua chave API e comece a construir gratuitamente, não é necessário cartão de crédito.