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, aqui está o caminho mais rápido para uma experiência localizada para cada um deles. Acrescente ?lang=fr ao link de um signatário francês, ?lang=de ao link de um signatário alemão, e a Firma.dev trata do resto. Todas as telas que eles veem, desde instruções e botões até ao texto legal, carregam nessa língua desde a primeira página. Não é necessária 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, sobrepondo tanto a deteção automática do navegador como quaisquer predefinições ao nível do espaço de trabalho. O signatário não precisa fazer nada, basta seguir o link e a interface já está na língua certa.

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

Um URL de assinatura padrão parece 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 um override 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

É toda a alteração. Nenhuma chamada API adicional, nenhuma modificação de modelo, nenhuma configuração por signatário.

Um Pedido de Assinatura, Múltiplos Links Localizados

O padrão prático para documentos multi-partes ou internacionais: crie um único pedido de assinatura com os e-mails automáticos da Firma.dev desativados, obtenha os URLs de assinatura para cada destinatário, então acrescente o parâmetro ?lang= apropriado 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ê trata da construção do link, a Firma.dev trata da renderização. Troque ?lang=fr para o código de língua que corresponde a cada destinatário.

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

Fallback Automático Sem o Parâmetro

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

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

A recomendação dos documentos é direta: use ?lang= em contextos incorporados e quando souber o local do signatário, deixe a deteção do navegador lidar com links diretos onde você não o faz.

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 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 fallback. Isto cobre tudo o que o signatário vê durante o fluxo de assinatura.

E-mails 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 e-mails de assinatura automáticos serão enviados em francês, sem necessidade de 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 fontes de assinatura criadas para o seu sistema de escrita sem qualquer configuração.

Juntas, estas três camadas cobrem toda a experiência: os e-mails a entrar, o próprio fluxo de assinatura e como a assinatura se apresenta 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, sem necessidade de cartão de crédito.