API de assinatura eletrônica após o KYC

A assinatura eletrônica da Didit permite que a pessoa que você acabou de verificar assine os seus documentos no mesmo fluxo. Ela percorre cada documento, adiciona a assinatura, as iniciais e os dados que você pedir, e confirma com um código de uso único enviado ao e-mail ou ao telefone que verificou antes. A Didit devolve cada documento assinado com uma assinatura eletrônica avançada (AES), além de um PDF de evidências que vincula a assinatura à identidade verificada. Ela funciona na verificação de usuários (KYC), em que a pessoa verificada assina, e na verificação de empresas (KYB), em que os representantes legais ou pessoas-chave da empresa assinam em nome dela.

Níveis de assinatura

Nível	Disponibilidade	O que é
AES, assinatura eletrônica avançada	Disponível	Cada documento é assinado em PAdES, o formato de assinatura de PDF, com um perfil de validação de longo prazo (`PAdES-B-LT`): a assinatura traz um carimbo de tempo confiável e os dados de revogação necessários para validá-la depois. Ela fica vinculada de forma exclusiva ao signatário por meio da identidade verificada e do código de uso único que ele confirmou, e qualquer alteração no documento após a assinatura a invalida.
QES, assinatura eletrônica qualificada	Em breve	Assinada com um certificado qualificado emitido ao signatário. O console mostra a opção como Em breve, e salvar `signature_level: "qes"` pela API devolve `400` com `qes_provider_not_configured`.

A AES assina somente em PAdES. Os valores xades e cades de signature_format são recusados para a AES com signature_format_not_supported.

Como funciona

O fluxo verifica primeiro o signatário

A etapa de assinatura é executada depois das etapas que estabelecem quem está assinando: verificação de identidade e verificação de e-mail ou de telefone, para o contato que recebe o código. Veja Antes de começar.

A Didit prepara os documentos

Quando o signatário chega à etapa, a Didit copia os documentos e seus campos para a sessão e registra o SHA-256 de cada documento. Alterações posteriores no fluxo não mudam o que este signatário vê.

O signatário percorre cada documento

Em um documento com campos, o signatário é guiado de campo em campo. Ele adota uma assinatura uma única vez, que é aplicada a todos os campos de assinatura e de iniciais, e preenche os campos de texto e de caixa de seleção. Os valores que a Didit obtém da identidade verificada, da sessão ou do seu sistema já estão na página. Em um documento sem campos, ele lê e concorda.

O signatário confirma com um código

Quando algum documento tem campos, o signatário primeiro concorda em assinar os documentos eletronicamente. A Didit então envia um código de seis dígitos ao e-mail ou ao telefone que ele verificou antes na sessão. Digitá-lo autoriza a assinatura em todos os documentos da etapa.

A Didit assina e sela

A Didit preenche a data da assinatura, carimba o valor de cada campo em cada PDF, anexa a página de evidências e então aplica a assinatura PAdES e o carimbo de tempo, de modo que a assinatura cobre tudo o que está na página.

Você recebe os resultados

A decisão e os webhooks da sessão trazem signatures[] com o signatário, a confirmação, o certificado, o carimbo de tempo, os hashes de cada documento e o valor de cada campo. Você baixa os PDFs assinados e o PDF de evidências, e a Didit pode enviar uma cópia por e-mail ao signatário.

Antes de começar

O signatário precisa estar verificado antes de poder assinar. A Didit obtém o nome e o contato dele dos registros verificados da própria sessão, nunca do que você ou o signatário digitam. Para a verificação de usuários (KYC), coloque estas etapas antes da assinatura eletrônica no fluxo:

Verificação de identidade, aprovada, com um nome legível. Sem ela, a etapa registra SIGNATURE_IDENTITY_NOT_VERIFIED.
Verificação de e-mail quando o código vai por e-mail (o padrão) ou verificação de telefone quando vai por SMS. O código só é enviado a um contato verificado na mesma sessão.
Se o fluxo também tem prova de vida, ela deve estar aprovada.

Para enviar ao signatário uma cópia dos documentos assinados por e-mail, a sessão também precisa de um e-mail verificado, mesmo quando o código vai por SMS. Para a verificação de empresas (KYB), os signatários são as pessoas-chave da empresa, cada uma com o próprio KYC aprovado:

`signature_signer`	Quem assina
`legal_representative`	Toda pessoa-chave com o papel `representative` ou `authorized_signatory`
`key_people`	Toda pessoa-chave física com uma sessão de KYC

Uma etapa de KYB tem de 1 a 20 signatários, e cada um precisa ter um KYC aprovado no momento de assinar. Cada um assina a própria cópia dos documentos e confirma com um código enviado ao contato verificado na sua própria sessão de KYC. O nome declarado para a pessoa-chave deve corresponder ao nome verificado dela, sem diferenciar maiúsculas de minúsculas nem espaçamento, ou a etapa registra SIGNATURE_NAME_MISMATCH. A etapa termina quando todos os signatários assinaram ou recusaram.

Documentos

De onde vêm os documentos

signature_documents_source define de onde uma etapa obtém seus documentos:

Valor	Documentos
`workflow` (padrão)	Os documentos que você enviou ao fluxo no console. Todas as sessões assinam os mesmos.
`session`	Os documentos que você envia em `sign.documents` ao criar a sessão. Cada sessão assina os seus.
`both`	Primeiro os documentos do fluxo, depois os da sessão.

Os documentos por sessão são a forma de fazer uma pessoa assinar um contrato com o próprio nome, valor ou condições já preenchidos pelo seu sistema.

Arquivos compatíveis

	Limite
PDF	Até 20 MB e 100 páginas cada. Sem senha, scripts nem arquivos anexados.
Word (`.docx`)	Até 20 MB. Convertido em PDF ao enviá-lo ou ao criar a sessão, e o PDF convertido tem os mesmos limites de um PDF. Arquivos `.doc`, `.docm`, `.odt` e `.rtf` são recusados com `unsupported_type`.
Por signatário	Até 20 documentos e 50 MB no total.

Quando você envia um documento Word, a Didit o converte em PDF durante o envio, em no máximo 60 segundos. As páginas convertidas são o que o signatário vê e assina, então confira-as antes de posicionar os campos: as quebras de linha podem diferir um pouco do Word. O arquivo Word e o seu PDF pertencem ao mesmo documento e são excluídos com ele. O PDF de evidências registra a conversão e o SHA-256 dos dois arquivos. A Didit recusa um arquivo Word com signature_document_not_supported e um reason quando o que seria assinado é ambíguo: ele tem macros (macros), alterações controladas não aceitas (tracked_changes), links para conteúdo externo (external_links) ou objetos incorporados (embedded_objects). Aceite ou rejeite as alterações controladas antes de enviar, para que o PDF mostre o texto com o qual você concordou. Um arquivo que não pode ser convertido é recusado com signature_document_conversion_failed e um destes motivos:

`reason`	O que deu errado
`docx_password_protected`	O arquivo tem senha. Remova-a e envie de novo.
`docx_unreadable`	O arquivo não é um documento Word legível.
`docx_too_many_pages`	O PDF convertido tem mais de 100 páginas.
`docx_too_large`	O arquivo é grande demais para converter.
`conversion_timeout`	A conversão demorou demais. Tente de novo ou envie o documento como PDF.

Campos no documento

Os campos transformam um documento em um modelo que o signatário preenche, como você prepararia um envelope em uma ferramenta de assinatura de desktop. Um documento sem campos mantém o fluxo mais simples: o signatário lê e concorda.

Tipo	O que o signatário faz	Valor
`signature`	Toca nele para aplicar a assinatura que adotou. O primeiro campo de assinatura ou de iniciais abre a etapa em que ele a adota.	`true` depois de aplicado
`initials`	Toca nele para aplicar as iniciais que adotou.	`true` depois de aplicado
`text`	Digita um valor, conferido com a validação do campo. Pode vir preenchido.	String
`checkbox`	Marca ou desmarca. Uma caixa de seleção obrigatória deve estar marcada.	Booleano
`email`	Nada, quando a sessão tem um e-mail verificado, que o preenche somente para leitura. Caso contrário, digita.	String
`full_name`	Nada: a Didit preenche o nome verificado, somente para leitura.	String
`date_signed`	Nada: a Didit preenche a data em que os documentos são assinados.	String
`data`	Nada: a Didit preenche, somente para leitura, um valor da identidade verificada, da sessão ou do seu sistema. Defina a origem em `prefill`.	String

Nesta versão não há seletor de data. Use um campo text para uma data que o signatário informa. Um campo tem estas propriedades:

Propriedade	Regras
`id`	Definido pela Didit.
`key`	Nomeia o campo nos resultados e em `sign.field_values`. Letras minúsculas, dígitos e sublinhados, começando por uma letra, até 64 caracteres (`^[a-z][a-z0-9_]{0,63}$`), e único dentro do documento.
`type`	Um dos tipos acima.
`role`	Quem o preenche, com os valores de `signature_signer`: `verified_person`, `legal_representative` ou `key_people`. Em um documento de sessão, o padrão é o signatário da etapa.
`page`	De 1 até o número de páginas do documento. Em um documento Word, uma página do PDF convertido.
`x`, `y`, `width`, `height`	Frações da página como é exibida (de `0` a `1`), medidas a partir do canto superior esquerdo e arredondadas em 4 casas decimais. O campo deve caber dentro da página. Tem no mínimo `0.02` de largura e `0.012` de altura, e uma assinatura, no mínimo `0.12` por `0.035`.
`required`	`signature` e `initials` são obrigatórios, a menos que você defina `false`. `full_name`, `date_signed` e `data` são sempre obrigatórios.
`label`	De 1 a 80 caracteres, exibido ao signatário e nos resultados.
`placeholder`	Somente `text` e `email`. Até 80 caracteres.
`position`	A ordem em que o signatário é guiado, a partir de `0`. A Didit a define pela posição do campo: por página, depois de cima para baixo, depois da esquerda para a direita.
`validation`	Somente `text`. Veja Validação.
`prefill`	De onde vem o valor. Veja Valores pré-preenchidos.
`editable_when_prefilled`	Somente `text` e `email`: o signatário pode alterar um valor pré-preenchido. Padrão `false`.
`checked_by_default`	Somente `checkbox`: a caixa já começa marcada.
`date_format`	Somente `date_signed`: `DD/MM/YYYY` (padrão), `MM/DD/YYYY`, `YYYY-MM-DD` ou `D MMMM YYYY`.

{
  "id": "6a2f1c0e-4d8b-4f5e-9a51-0c7b2e9d3f10",
  "key": "occupation",
  "type": "text",
  "role": "verified_person",
  "page": 1,
  "x": 0.34,
  "y": 0.4618,
  "width": 0.57,
  "height": 0.0325,
  "required": true,
  "label": "Occupation",
  "placeholder": "For example, nurse",
  "position": 5,
  "validation": { "kind": "any", "min_length": 0, "max_length": 80, "pattern": null, "message": null },
  "prefill": null,
  "editable_when_prefilled": false,
  "checked_by_default": false,
  "date_format": null
}

Um documento aceita até 200 campos, e um signatário até 500 entre os seus documentos. Uma etapa preenche e carimba apenas os campos do seu próprio signatário. Um documento só pode ter campos de vários papéis quando várias etapas de assinatura do fluxo o usam: cada etapa preenche os campos do seu próprio papel e deixa os demais vazios na sua cópia. Um campo de um papel que nenhuma etapa de assinatura do fluxo usa é recusado com role_not_used. Todo papel que tem campos em um documento precisa de pelo menos um campo signature ou initials nele, ou a versão do fluxo não pode ser publicada (signature_field_missing).

Validação

validation se aplica aos campos text:

{ "kind": "any", "min_length": 0, "max_length": 80, "pattern": null, "message": null }

kind: any; letters (letras de qualquer alfabeto, espaços, hífens e apóstrofos); number (dígitos com separador decimal opcional); email; ou pattern.
min_length: de 0 até max_length.
max_length: de 1 a 500. Padrão 120.
pattern: obrigatório com kind: "pattern". Uma expressão regular de até 200 caracteres que o valor inteiro deve atender. Lookarounds e backreferences não são compatíveis.
message: até 120 caracteres, exibida no lugar do erro padrão.

A prévia do console, o fluxo de assinatura e a API aplicam as mesmas regras.

Valores pré-preenchidos

prefill indica a origem do valor de um campo:

`prefill`	Valor
`identity.full_name`, `identity.first_name`, `identity.last_name`	O nome como consta no documento de identidade verificado do signatário.
`identity.date_of_birth`	Do documento de identidade verificado, como `DD/MM/YYYY`.
`identity.nationality`, `identity.document_number`, `identity.document_type`, `identity.issuing_country`	Do documento de identidade verificado.
`identity.address`	O endereço formatado do documento de identidade verificado, ou de um comprovante de endereço na mesma sessão.
`contact.email`, `contact.phone`	O e-mail ou o telefone verificado do signatário.
`company.name`, `company.registration_number`, `company.address`, `company.country`	A empresa verificada, no KYB.
`session.vendor_data`	O `vendor_data` da sessão.
`metadata.<key>`	O valor de `<key>` no `metadata` da sessão, como string.
`api.<key>`	O valor de `<key>` em `sign.field_values`, enviado ao criar a sessão.

Um campo data deve ter um prefill. Um campo full_name sempre usa identity.full_name e um campo email usa contact.email, e um campo text também pode ter um. Os valores dos campos data, full_name e email verificado são fixados quando o signatário começa a assinar: alterações posteriores na sessão não os mudam. Um campo text ou email pré-preenchido é somente leitura, a menos que você defina editable_when_prefilled. Quando a origem do valor de um campo obrigatório não tem valor naquele momento, por exemplo uma sessão sem endereço, o campo não é exibido vazio. A etapa gera SIGNATURE_FIELD_DATA_MISSING e aplica signature_field_data_missing_action (padrão REVIEW). Com NO_ACTION, o signatário ainda pode assinar e o campo fica vazio.

Configure no console

Vá até Fluxos de trabalho, abra um fluxo e adicione a etapa Assinatura eletrônica depois das etapas que verificam o signatário.
Em Documentos, selecione Enviar para adicionar arquivos PDF ou Word e arraste-os na ordem em que o signatário os vê. Os arquivos Word são convertidos em PDF: confira as páginas convertidas antes de posicionar os campos. Substituir troca o arquivo de um documento e mantém os campos dele, exceto os de páginas que o novo arquivo não tem mais.
Em Posicione campos nos documentos, selecione Abrir o editor. Arraste um campo da paleta até a página, ou selecione-o e clique onde ele deve ficar, depois mova e redimensione. Para cada campo, defina Quem preenche, o rótulo, se é Obrigatório, o que ele aceita, de onde vem o valor e a Chave na API (o key do campo). Visualizar como signatário mostra o documento como o signatário o vê em um celular ou no desktop. O editor salva conforme você avança (Salvo no rascunho) e lista o que corrigir antes de você selecionar Concluído.
Ainda em Documentos, escolha de onde vêm os documentos: Este fluxo de trabalho, Cada sessão ou Ambas. Para documentos sem campos, escolha se o signatário deve Ler até o final antes de assinar e dê Um consentimento por documento.
Em Assinatura, escolha o Signatário, o Nível (Avançada (AES)), o Formato e para onde vai o código (Código de uso único por).
Em Regras, defina o que cada aviso faz com o veredito.
Em Avançado, escolha se deve Enviar a cópia assinada por e-mail e Adicionar uma página de evidências, e por quantos dias o link de assinatura permanece válido. Você também pode adicionar regras de status personalizadas.
Salve o fluxo.

Para configurar a mesma etapa pela API, veja Configurações de recursos do fluxo. Os documentos do fluxo e seus campos são gerenciados no console; pela API, envie documentos e campos por sessão.

A experiência de assinatura

A etapa de assinatura é executada na página de verificação hospedada, no SDK Web e nos SDKs nativos, no desktop e em celulares. Você não precisa criar nenhuma interface de assinatura.

Introdução. O signatário vê os documentos que está prestes a assinar.
Cada documento, em ordem. Em um documento com campos, o signatário é guiado pelos campos na ordem de position. O primeiro campo de assinatura ou de iniciais abre uma janela em que ele adota uma assinatura. Os campos opcionais são marcados como Opcional. Os valores que a Didit preencheu aparecem na página com um cadeado e não são etapas. Tocar em um campo na página leva até ele. Em um celular, um campo por vez aparece em um painel que fica acima do teclado. Em uma tela com pelo menos 1200 px de largura, a página fica ao lado da lista de campos. Ao terminar um documento com um campo obrigatório ainda vazio, é mostrado quantos faltam e o fluxo salta para o primeiro. Um documento sem campos é lido e aceito, conforme você configurou.
Revisão. O signatário vê os documentos novamente e, quando algum deles tem campos, concorda em assiná-los eletronicamente.
Código. O signatário pede o código. Ele vale por 5 minutos, um novo pode ser enviado após 60 segundos, e o signatário recebe até 5 códigos e tem 3 tentativas erradas. Esgotá-los registra SIGNATURE_OTP_FAILED.
Assinado. Depois de assinar, o signatário pode baixar os documentos assinados. Se você habilitou, a Didit também envia uma cópia por e-mail.
Recusa. O signatário pode recusar em vez de assinar. Isso registra SIGNATURE_DECLINED. Uma recusa pode ser reaberta enquanto o link de assinatura for válido, então o signatário ainda pode assinar se mudar de ideia.

O fluxo avisa o signatário quando o código expirou, um documento mudou, a assinatura falhou ou o link de assinatura expirou. O link de assinatura permanece válido por signature_link_validity_days (de 1 a 30, padrão 7), contados a partir da criação da sessão. A sessão permanece aberta pelo menos por esse tempo.

Os SDKs nativos mostram a etapa de assinatura a partir da versão que a inclui, listada na visão geral dos SDKs nativos quando for lançada. Documentos com campos exigem uma versão que ofereça suporte a campos: uma versão mais antiga não consegue exibi-los, e a etapa mostra um erro. Documentos sem campos funcionam em todas as versões com a etapa de assinatura. Até que o seu aplicativo execute uma versão compatível com o que o seu fluxo usa, direcione as pessoas à página hospedada ou ao SDK Web.

Adotar uma assinatura

O signatário adota a assinatura e as iniciais uma única vez, em uma janela, na primeira vez que um documento pede qualquer uma delas:

Digitada: o nome verificado dele em um estilo de letra manuscrita à sua escolha, marcado como Do seu documento. Ele não pode digitar outro nome. As iniciais digitadas são as primeiras letras desse nome.
Desenhada: desenhada com o dedo ou o mouse, tanto a assinatura quanto as iniciais.

Todo campo de assinatura ou de iniciais seguinte é aplicado com um toque, e tocar em um já aplicado o remove de novo.

Resultados

O resultado de cada signatário é um item de signatures[] na decisão da sessão e no decision dos webhooks da sessão. Não há um webhook de assinatura separado: o evento status.updated da sessão avisa quando buscar a decisão. Você recebe o PDF assinado de cada documento, um PDF de evidências para cada signatário e o SHA-256 de cada arquivo original e assinado, para poder provar depois que nada mudou. Em documentos com campos, você também recebe o valor de cada campo, de onde veio e quando foi preenchido, além da assinatura adotada e de quando o signatário concordou em assinar eletronicamente. Veja o relatório da assinatura eletrônica para cada campo, os downloads e como validar uma assinatura novamente. No console, a aba Assinatura da sessão mostra os documentos e depois um bloco Campos com uma prévia de cada página, a assinatura e as iniciais adotadas e o valor, o horário e a origem de cada campo. O relatório em PDF inclui uma seção de assinatura e uma página Assinatura eletrônica · campos quando os documentos têm campos.

Preços

A assinatura eletrônica é cobrada uma vez por sessão assinada, qualquer que seja o número de documentos, signatários ou etapas de assinatura. Uma assinatura recusada, que falha ou que expira não é cobrada.

Exclusão dos dados de assinatura

Quando você exclui uma sessão, os dados de assinatura dela são excluídos junto: os documentos enviados com a sessão e seus arquivos Word originais, as cópias preparadas para cada signatário, os PDFs assinados, os PDFs de evidências, as imagens da assinatura e das iniciais adotadas e o valor de cada campo. Os links de download deixam de funcionar. O mesmo acontece quando uma sessão é excluída no fim do seu período de retenção de dados. A exclusão não pode ser desfeita, então baixe antes tudo o que precisar guardar.

Os documentos assinados de uma verificação de empresas pertencem à sessão da empresa. Excluir essa sessão os exclui.
Remover um documento de um fluxo o exclui, com seus campos e seu arquivo Word original. Um signatário que já começou a assinar mantém a cópia que lhe foi mostrada, como parte da sua sessão, até que você exclua essa sessão. Remova documentos somente de fluxos sem sessões aguardando assinatura.
Uma cópia que a Didit já enviou por e-mail ao signatário está na caixa de entrada dele e não é afetada.

Relacionados

Relatório da assinatura eletrônica: signatures[], o PDF assinado, o PDF de evidências e os downloads.
Avisos da assinatura eletrônica: cada aviso e a regra que o controla.
Criar sessão: envie documentos, campos e valores de campos por sessão.
Configurações de recursos do fluxo: cada configuração da etapa.

Autenticação

Verificação

Monitoramento

Plataforma

API de assinatura eletrônica após o KYC

Níveis de assinatura

Como funciona

Antes de começar

Documentos

De onde vêm os documentos

Arquivos compatíveis

Campos no documento

Validação

Valores pré-preenchidos

Configure no console

A experiência de assinatura

Adotar uma assinatura

Resultados

Preços

Exclusão dos dados de assinatura

Relacionados

​Níveis de assinatura

​Como funciona

​Antes de começar

​Documentos

​De onde vêm os documentos

​Arquivos compatíveis

​Campos no documento

​Validação

​Valores pré-preenchidos

​Configure no console

​A experiência de assinatura

​Adotar uma assinatura

​Resultados

​Preços

​Exclusão dos dados de assinatura

​Relacionados

Níveis de assinatura

Como funciona

Antes de começar

Documentos

De onde vêm os documentos

Arquivos compatíveis

Campos no documento

Validação

Valores pré-preenchidos

Configure no console

A experiência de assinatura

Adotar uma assinatura

Resultados

Preços

Exclusão dos dados de assinatura

Relacionados