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

1. POST /envelopes: Criação do Envelope.
2. POST /envelopes/:envelope_id/documents: Adição do Documento ao Envelope.
3. POST /envelopes/:envelope_id/signers: Criação do Signatário, obrigando a inclusão do objeto signature_host.
4. POST /envelopes/:envelope_id/requirements: Criação do Requisito de Qualificação (action: "agree", role: "sign").
5. POST /envelopes/:envelope_id/requirements: Criação do Requisito de Evidência Presencial (action: "provide_evidence", auth: "presential").
6. PATCH /envelopes/:envelope_id: Ativação do Envelope (status: "running").
7. 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.

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

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.

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": "[email protected]",
            "signature_host": {
                "name": "Maria Supervisora",
                "email": "[email protected]",
                "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.

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.

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

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.

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

1. Criação do Token: Após ativar o envelope, o sistema gera automaticamente um token presencial de 6 caracteres alfanuméricos
2. Notificação do Anfitrião: O anfitrião recebe email com o token presencial
3. Supervisão Presencial: O anfitrião deve estar fisicamente presente durante a assinatura
4. Validação do Token: O signatário insere o token no momento da assinatura
5. 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.