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

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

Como Funciona o Parâmetro ?lang=

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, substituindo quer a deteção automática do navegador quer quaisquer predefinições ao nível do espaço de trabalho. O signatário não precisa de fazer nada; basta seguir o link e a interface já está na língua correta.

Os sete códigos de idioma suportados são:

Um URL de assinatura padrão tem o seguinte aspeto:

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

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 é toda a alteração. Sem chamadas adicionais à API, sem modificações de modelo, sem configuração por signatário.

Um Pedido de Assinatura, Vários Links Localizados

O padrão prático para documentos com várias partes ou internacionais: crie um único pedido de assinatura com os e-mails automatizados da Firma.dev desativados, obtenha os URLs de assinatura para cada destinatário e depois acrescente o parâmetro ?lang= apropriado a cada um antes de enviar através do seu próprio sistema.

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

// Criar pedido de assinatura com os e-mails desativados
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: 'Signatário', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Obter URLs de assinatura para cada destinatário
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()

// Enviar e-mails através do seu próprio sistema com ?lang= acrescentado
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}?lang=fr`
  await yourEmailService.send({
    to: user.email,
    subject: 'Por favor assine o seu documento',
    body: `Clique aqui para assinar: ${signingUrl}`
  })
}

// Criar pedido de assinatura com os e-mails desativados
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: 'Signatário', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Obter URLs de assinatura para cada destinatário
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()

// Enviar e-mails através do seu próprio sistema com ?lang= acrescentado
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}?lang=fr`
  await yourEmailService.send({
    to: user.email,
    subject: 'Por favor assine o seu documento',
    body: `Clique aqui para assinar: ${signingUrl}`
  })
}

// Criar pedido de assinatura com os e-mails desativados
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: 'Signatário', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Obter URLs de assinatura para cada destinatário
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()

// Enviar e-mails através do seu próprio sistema com ?lang= acrescentado
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}?lang=fr`
  await yourEmailService.send({
    to: user.email,
    subject: 'Por favor assine o seu documento',
    body: `Clique aqui para assinar: ${signingUrl}`
  })
}

O documento é igual para todos. A experiência de assinatura que cada pessoa vê está na sua língua. Constrói o link, a Firma.dev trata da renderização. Substitua ?lang=fr pelo código de idioma que corresponde a cada destinatário.

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

Fallback Automático Sem o Parâmetro

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

Este fallback funciona bem para links diretos em que não controla o contexto de entrega. Mas para assinatura incorporada em iframes, ou em qualquer cenário em que está a construir URLs do lado do servidor, passar explicitamente ?lang= é a abordagem mais fiável. A deteção de idioma do navegador dentro de um iframe pode ser inconsistente dependendo de como a aplicação principal está configurada.

A recomendação da documentação é simples: use ?lang= em contextos incorporados e quando conhece a língua do signatário; deixe a deteção do navegador tratar disso para links diretos em que não o faz.

O Quadro Completo da Localização

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

Idioma da experiência de assinatura é controlado por ?lang= no link, ou pela deteção do navegador como fallback. Isto abrange tudo o que o signatário vê durante o fluxo de assinatura.

E-mails de notificação são controlados pelo campo language nas definições do espaço de trabalho. Defina o espaço de trabalho para francês e todos os e-mails automatizados de assinatura serão enviados em francês, sem necessidade de um modelo personalizado.

Estilos de assinatura são tratados automaticamente com base no nome de cada signatário. Nomes gregos, cirílicos, japoneses e coreanos recebem tipos de letra de assinatura construídos para o respetivo sistema de escrita, sem qualquer configuração.

Juntas, estas três camadas cobrem a experiência completa: os e-mails que entram, o próprio fluxo de assinatura e o aspeto da assinatura no documento. O Firma.dev's guia de localização cobre as três em detalhe.

Obtenha a sua chave de API e comece a construir gratuitamente, sem necessidade de cartão de crédito.