O presente guia detalha o processo de utilização da API v3 da Clicksign para configurar um Envelope com Assinatura Presencial.

O objetivo principal deste fluxo é garantir que a assinatura de um signatário seja validada através de um Token Presencial, o que exige a criação de um Requisito de Evidência Presencial no documento. Essa modalidade é intrinsecamente ligada à figura do Anfitrião de Assinatura (signature_host), que é o responsável por supervisionar o ato físico da assinatura.

A sequência de passos apresentada a seguir orienta sobre como criar o envelope, o documento, o signatário com o anfitrião, e como adicionar os requisitos necessários para disparar esse processo de autenticação diferenciado.

Sequência de Endpoints

POST /envelopes: Criação do Envelope.
POST /envelopes/:envelope_id/documents: Adição do Documento ao Envelope.
POST /envelopes/:envelope_id/signers: Criação do Signatário, obrigando a inclusão do objeto signature_host.
POST /envelopes/:envelope_id/requirements: Criação do Requisito de Qualificação (action: "agree", role: "sign").
POST /envelopes/:envelope_id/requirements: Criação do Requisito de Evidência Presencial (action: "provide_evidence", auth: "presential").
PATCH /envelopes/:envelope_id: Ativação do Envelope (status: "running").
POST /envelopes/:envelope_id/notifications: Envio da Notificação (que aciona a geração do token e notifica as partes interessadas).

🚧
Atenção
A assinatura presencial requer obrigatoriamente um signature_host (anfitrião) configurado no signatário. O anfitrião será responsável por supervisionar fisicamente a assinatura e receberá o token presencial por email.

Fluxo Completo de Criação

1. Criar o Envelope

Para mais detalhes sobre os parâmetros e opções disponíveis durante a criação de um envelope, consulte a referência completa de envelope.

Atributo	Descrição	Exemplo
`name` Obrigatório	Nome identificador do envelope.	Meu Primeiro Envelope

Endpoint: POST /api/v3/envelopes

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes \
  --header 'Authorization: {{token}}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
  "data": {
    "type": "envelopes",
    "attributes": {
      "name": "Meu Primeiro Envelope"
    }
  }
}'

2. Adicionar Documento ao Envelope

Atributo	Descrição	Exemplo
`filename` Obrigatório	Nome do arquivo do documento.	ContratoPresentencial.pdf
`content_base64` Obrigatório	Conteúdo do documento em base64 com prefixo data URI.	data:application/pdf;base64,JVBERi0x...

Endpoint: POST /api/v3/envelopes/:envelope_id/documents

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{{envelope_id}}/documents \
  --header 'Authorization: {{token}}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
  "data": {
    "type": "documents",
    "attributes": {
      "filename": "ContratoPresenticial.pdf",
      "content_base64": "data:application/pdf;base64,JVBERi0xLjcNCiXi48/TDQo0..."
    }
  }
}'

3. Criar Signatário com Anfitrião

Para mais detalhes sobre os parâmetros e opções disponíveis durante a criação de um Signatário com Anfitrião, consulte a referência completa de Signatário.

Atributo	Descrição	Exemplo
`name` Obrigatório	Nome completo do signatário.	João Silva Santos
`email` Obrigatório	Email do signatário.	joao.santos@example.com
`signature_host` Obrigatório	Dados do anfitrião responsável pela supervisão presencial.	Ver estrutura abaixo
`signature_host.name` Obrigatório	Nome completo do anfitrião.	Maria Supervisora
`signature_host.email` Obrigatório	Email do anfitrião que receberá o token presencial.	maria.supervisora@example.com
`signature_host.communicate_events`	Configuração de comunicação com o anfitrião.	Ver estrutura abaixo
`communicate_events`	Configuração de comunicação com o signatário.	Ver estrutura abaixo

Endpoint: POST /api/v3/envelopes/:envelope_id/signers

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{{envelope_id}}/signers \
  --header 'Authorization: {{token}}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
        "type": "signers",
        "attributes": {
            "name": "João Silva Santos",
            "email": "joao.santos@example.com",
            "signature_host": {
                "name": "Maria Supervisora",
                "email": "maria.supervisora@example.com",
                "communicate_events": {
                    "signature_host_signature_request": "email"
                }
            },
            "communicate_events": {
                "document_signed": "email",
                "signature_request": "email",
                "signature_reminder": "email"
            }
        }
    }
}'

4. Criar Requisitos de Assinatura

Para mais detalhes sobre os parâmetros e opções disponíveis durante a criação de um Requisitos, consulte a referência completa de requisitos.

Atributo	Descrição	Exemplo
`action` Obrigatório	Ação requerida. Para assinatura deve ser "agree".	agree
`role` Obrigatório	Papel do signatário. Para assinatura deve ser "sign".	sign
`relationships.document` Obrigatório	Referência ao documento criado anteriormente.	Ver estrutura abaixo
`relationships.signer` Obrigatório	Referência ao signatário criado anteriormente.	Ver estrutura abaixo

Endpoint: POST /api/v3/envelopes/:envelope_id/requirements

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{{envelope_id}}/requirements \
  --header 'Authorization: {{token}}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
  "data": {
    "type": "requirements",
    "attributes": {
        "action": "agree",
        "role": "sign"
    },
    "relationships": {
        "document":{
            "data": { "type": "documents", "id": "{{document_id}}"}
        },
        "signer":{
            "data": { "type": "signers", "id": "{{signer_id}}"}
      }
    }
  }
}'

5. Criar Requisitos de Evidência Presencial

Para mais detalhes sobre os parâmetros e opções disponíveis durante a criação de um Requisitos, consulte a referência completa de requisitos.

🚧
Atenção
Não é permitido usar assinatura presencial com biometria facial em conjunto ao Widget Embedded nesta versão.

Atributos para cadastrar a assinatura presencial de signatários

Para mais detalhes sobre os parâmetros e opções disponíveis durante a criação de um signatário, consulte a referência completa de signatário.

Atributo	Descrição	Exemplo
`action` Obrigatório	Ação requerida. Para evidência presencial deve ser "provide_evidence".	provide_evidence
`auth` Obrigatório	Tipo de autenticação. Para assinatura presencial deve ser "presential".	presential
`relationships.document` Obrigatório	Referência ao documento (mesmo do requirement anterior).	Ver estrutura abaixo
`relationships.signer` Obrigatório	Referência ao signatário (mesmo do requirement anterior).	Ver estrutura abaixo

Endpoint: POST /api/v3/envelopes/:envelope_id/requirements

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{{envelope_id}}/requirements \
  --header 'Authorization: {{token}}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
  "data": {
    "type": "requirements",
    "attributes": {
        "action": "provide_evidence",
        "auth": "presential"
    },
    "relationships": {
        "document":{
            "data": { "type": "documents", "id": "{{document_id}}"} 
        },
        "signer":{
            "data": { "type": "signers", "id": "{{signer_id}}"}
      }
    }
  }
}'

6. Ativar o Envelope

Atributo	Descrição	Exemplo
`status` Obrigatório	Status do envelope. Para ativar deve ser "running".	running

Endpoint: PATCH /api/v3/envelopes/:envelope_id

curl --request PATCH \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{{envelope_id}} \
  --header 'Authorization: {{token}}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
  "data": {
    "id": "{{envelope_id}}",
    "type": "envelopes",
    "attributes": {
        "status": "running"
    }
  }
}'

7. Enviar Notificações

Para mais detalhes sobre os parâmetros e opções disponíveis durante a criação de uma Notificação, consulte a referência completa de Notificações.

Atributo	Descrição	Exemplo
`message`	Mensagem personalizada (opcional). Se null, usa mensagem padrão.	null

Endpoint: POST /api/v3/envelopes/:envelope_id/notifications

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{{envelope_id}}/notifications \
  --header 'Authorization: {{token}}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
  "data": {
    "type": "notifications",
    "attributes": {
      "message": null
    }
  }
}'

Como Funciona o Processo de Assinatura Presencial

Criação do Token: Após ativar o envelope, o sistema gera automaticamente um token presencial de 6 caracteres alfanuméricos
Notificação do Anfitrião: O anfitrião recebe email com o token presencial
Supervisão Presencial: O anfitrião deve estar fisicamente presente durante a assinatura
Validação do Token: O signatário insere o token no momento da assinatura
Assinatura Validada: Após validação do token, a assinatura é processada e registrada como evidência presencial

Aspectos Técnicos

Token Presencial

Formato: 6 caracteres alfanuméricos (gerado automaticamente).
Validade: 24 horas.
Uso único: Cada token só pode ser usado uma vez.
Expiração: Tokens expirados não podem ser utilizados.

Validações do Sistema

Verificação obrigatória de signature_host no signatário.
Validação de que o requirement de evidência presencial está associado a um signer com signature_host.
Controle de expiração e uso único do token.

Estados do Envelope

draft: Estado inicial, permite modificações
running: Envelope ativo, notifications enviadas, tokens gerados
closed: Todas as assinaturas concluídas

❗️
Se alguma requisição falhar
Sempre verifique o BODY da resposta. O retorno da requisição mostrará o motivo pelo qual a requisição não foi aceita pelos servidores da Clicksign.