iframe

iframe não é recomendado

Incorporar por iframe não é recomendado. Prefira os SDKs.

iframe básico

<iframe
  src="https://app.kivosign.com.br/embed/sign/abc123xyz"
  width="100%"
  height="800"
  frameborder="0"
  allow="clipboard-write"
></iframe>

Use a URL de incorporação correta

A URL depende do modo de incorporação (por exemplo, link direto ou token de assinatura). Use a URL de incorporação que a KivoSign fornece para o seu fluxo.

Personalizando o iframe

Você pode personalizar a assinatura incorporada passando opções codificadas no fragmento da URL do iframe (tudo o que vem depois do #).

A KivoSign espera que o fragmento seja o base64 de:

encodeURIComponent(JSON.stringify(options))

Opções suportadas

Opção	Tipo	Descrição
`name`	`string`	Pré-preenche o nome do signatário.
`email`	`string`	Pré-preenche o e-mail do signatário.
`lockName`	`boolean`	Trava o campo de nome (impede a edição).
`lockEmail`	`boolean`	Trava o campo de e-mail (impede a edição).
`language`	`string`	Força o idioma da incorporação (ex.: `pt-BR`).
`darkModeDisabled`	`boolean`	Desativa o modo escuro.
`allowDocumentRejection`	`boolean`	Permite ou não a recusa do documento.
`css`	`string`	Injeta CSS personalizado na incorporação.
`cssVars`	`object`	Sobrescreve as variáveis CSS da incorporação (veja a página Variáveis CSS).

Exemplo

const buildEmbedSrc = (host: string, token: string) => {
  const options = {
    name: 'Ana Souza',
    email: 'ana@exemplo.com',
    lockName: true,
    lockEmail: true,
    language: 'pt-BR',
    darkModeDisabled: false,
    allowDocumentRejection: true,
    css: ':root { --radius: 12px; }',
    cssVars: {},
  };

  const encodedOptions = btoa(encodeURIComponent(JSON.stringify(options)));

  return `${new URL(`/embed/sign/${token}`, host).toString()}#${encodedOptions}`;
};

buildEmbedSrc('https://app.kivosign.com.br', 'token-de-assinatura');

Parâmetros de consulta

Algumas opções são lidas no servidor e por isso vão como parâmetros de consulta comuns, e não no fragmento.

Parâmetro	Vale para	Descrição
`clientUserId`	`/embed/sign/:token`	Identificador opaco do signatário, usado para pré-preencher e guardar a assinatura entre incorporações. Veja Assinaturas salvas.
`externalId`	`/embed/direct/:token`	Seu ID de referência, gravado no documento criado a partir do modelo direto.

const src = new URL(`/embed/sign/${token}`, host);

src.searchParams.set('clientUserId', 'usr_8f2c1b4e');

return `${src.toString()}#${encodedOptions}`;

Use identificadores opacos

Os parâmetros de consulta fazem parte da requisição HTTP e aparecem nos logs de requisição da KivoSign. Nunca coloque e-mail ou outro dado pessoal em clientUserId; use um ID opaco.

Por que usar o fragmento da URL?

O fragmento não é enviado ao servidor na requisição HTTP, mas fica disponível para a aplicação incorporada no navegador. É um jeito prático de passar configurações do lado do cliente sem mudar a URL base.

iframe básico

Personalizando o iframe

Opções suportadas

Exemplo

Parâmetros de consulta

Nesta página