> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluxo de assinatura no onboarding

> A solução de assinatura digital no onboarding permite que o usuário assine um documento como parte do processo, em conjunto com as etapas de análise biométrica

### Modelos de integração

A etapa de assinatura pode ser configurada de três formas distintas, de acordo com a origem e o comportamento esperado do documento a ser assinado. Cada modelo atende a um cenário de uso específico e possui requisitos próprios de configuração, descritos a seguir.

#### Documento fixo

Neste modelo, é configurado um único documento, previamente definido e imutável, que será apresentado a todos os usuários que passarem pela etapa de assinatura. Não há personalização de conteúdo por usuário: o mesmo arquivo é exibido e assinado em todas as execuções do fluxo.

Esse modelo é indicado para casos em que o texto do documento (por exemplo, um termo de uso ou contrato padrão) não varia entre os usuários e não depende de dados coletados durante o onboarding.

#### Documento preenchido dinamicamente por integração

Neste modelo, é configurado um template de documento com campos pré-determinados (placeholders), que são preenchidos dinamicamente com dados enviados via API no momento da integração. Dessa forma, cada usuário recebe uma versão personalizada do documento, contendo suas próprias informações (nome, CPF, dados contratuais, etc.).

A configuração do template e o mapeamento dos campos que serão preenchidos via API não é autoatendida: é necessário entrar em contato com o time de Suporte para definir a estrutura do template e os parâmetros aceitos na integração.

#### Documento consultado via API externa durante a assinatura

Neste modelo, o próprio onboarding é responsável por consultar uma API externa no momento em que o usuário atinge a etapa de assinatura, sinalizando que um novo processo foi iniciado e solicitando a URL do documento a ser assinado. Esse modelo é indicado quando o documento é gerado ou gerenciado por um sistema externo ao onboarding (por exemplo, um sistema de gestão de contratos), e a URL final do documento só está disponível no momento em que o usuário chega a essa etapa.

O fluxo funciona da seguinte maneira:

1. **Acionamento do onboarding para a API externa**: quando o usuário inicia a etapa de assinatura, o onboarding realiza uma chamada `POST` para a rota configurada no projeto, informando o identificador do processo e o CPF do usuário. O corpo da requisição segue o formato abaixo:

   ```JSON theme={"theme":"catppuccin-latte"}
   {
     "id": "<uuid>",
     "cpf": "<número do CPF>"
   }
   ```

   A rota (path) de destino dessa chamada é definida nas configurações do projeto, junto ao time de Suporte, e deve estar disponível publicamente para ser consultada pelo onboarding.

2. **Retorno da API externa com a URL do documento**: após processar a solicitação, a API externa deve retornar ao onboarding a URL pública onde o documento a ser assinado está disponível. Esse retorno é feito por meio de uma chamada `PATCH` para o endpoint de valores do step de assinatura, autenticada via `x-api-key`, conforme o exemplo a seguir:

   ```
   curl --location 'https://api.valid.com/onboarding/api/v1/steps/signer/<UUID>/values' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'x-api-key: <API KEY>' \
   --data '{
       "urls": ["<URL pública para acesso ao documento>"]
   }'
   ```

   Nessa chamada, `<UUID>` corresponde ao identificador único do processo de onboarding (o mesmo `id` recebido na etapa 1), e `<API KEY>` é a chave de autenticação fornecida para o projeto. O campo `urls` deve conter a URL (ou URLs) públicas de acesso ao documento que será apresentado ao usuário.

3. **Exibição e assinatura do documento**: ao receber a(s) URL(s) informadas no passo anterior, o onboarding as utiliza para carregar e exibir o documento na interface do usuário. O usuário então realiza a leitura e a assinatura do documento diretamente na aplicação, concluindo essa etapa do processo de onboarding.

Caso a API externa não responda dentro do tempo esperado ou retorne uma URL inválida, o processo de assinatura não é concluído e o usuário permanece bloqueado nessa etapa até que um retorno válido seja recebido.