Documentação
These docs are for v2.0. Click to read the latest docs for v3.2.

Adicionar requisito de autenticação

POST /api/v3/envelopes/{{envelopeid}}/requirements

📘

Requisição para criar um novo requisito em um envelope na plataforma Clicksign. Um requisito é uma condição que deve ser cumprida por um signatário para que ele possa assinar. "Autenticação" significa que o signatário deve enviar uma prova de identidade para assinar. Essa é uma requisição POST para /envelopes/{{envelopeid}}/requirements, sendo {{envelopeid}}a variável id gerada na criação do envelope. Em Authorizationadicione o access token de sua conta. No body, deverão ser enviados os atributos listados abaixo.

POST /api/v3/envelopes/{{envelopeid}}/requirements HTTP/1.1
Host: sandbox.clicksign.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: access token

Tipo de dados

AtributoDescriçãoObrigatório
typeDetermina o tipo de dados, que aqui deve ser requirements.Sim

Atributos do requisito de autenticação

AtributoDescriçãoObrigatórioPadrãoExemplo
actionDetermina a ação que o signatário deve realizar para cumprir o requisito, que aqui deve ser provide_evidence.Simprovide_evidenceprovide_evidence
auth

Determina o tipo de autenticação para realizar assinatura.

Opções:

  • address_proof: Define o comprovante de endereço como autenticação.

  • email: Define o envio de token por e-mail.

  • facial_biometrics: Define a solicitação de biometria facial como ponto de autenticação adicional para o signatário. Quando esta autenticação está habilitada para um signatário, as autenticações official_document_enabled,
    liveness_enabled e selfie_enabled, não são permitidas.

  • biometric: Define solicitação de biometria SERPRO como ponto de autenticação adicional para o signatário. Neste cenário, não é necessário que o signatário envie um documento com foto, pois a validação do documento é realizada por meio de consulta na base de dados da SERPRO. Essa abordagem garante maior segurança e agilidade no processo de verificação de identidade. Quando esta autenticação está habilitada para um signatário, o CPF é um dado obrigatório e as autenticações official_document_enabled,
    liveness_enabled e selfie_enabled, não são permitidas.

  • handwritten: Define a solicitação de assinatura manuscrita como ponto de autenticação no momento da assinatura.

  • icp_brasil: Define a assinatura via certificado digital.

  • liveness: Define a solicitação de selfie dinâmica como ponto de autenticação adicional para o signatário.

  • official_document: Define a solicitação da foto (frente e verso) do documento oficial como ponto de autenticação do signatário no momento da assinatura.

  • pix: Define a autenticação via transação com Pix, essa opção substitui o Token. (CPF do signatário é obrigatória).
    Veja mais sobre o Pix como autenticação.

  • selfie: Define a solicitação de selfie como ponto de autenticação ao signatário no momento da assinatura, utilizando a câmera do dispositivo. Algumas incompatibilidades podem ocorrer como: caso o navegador não tenha suporte ao plugin; dispositivo não possua câmera instalada corretamente ou usuário tenha bloqueado acesso à câmera.

  • sms: Define o envio de token por SMS.

  • whatsapp: Define o envio de token por Whatsapp.Só é permitido enviar uma das opções.

SimSem valor padrãosms
🚧

Importante

  • A autenticação biometric possui um custo de R$ 4,50 por consulta realizada com sucesso à base de dados da SERPRO, sendo o resultado do reconhecimento facial positivo ou negativo. A cobrança não será gerada apenas nos casos em que o sistema estiver inoperante ou retornar um erro inesperado.
  • A autenticação documentoscopypossui um custo de R$ 4,50 por solicitação realizada, sendo o resultado a validação ou invalidação do documento enviado. A cobrança não será gerada apenas nos casos em que o sistema estiver inoperante.

Relações do requisito

Em relationships deve ser indicado o signer e o document, descritos a seguir:

AtributoDescriçãoObrigatórioPadrãoExemplo
document

Um objeto com as relações do requisito com outros recursos.

Em "type": "documents", "id": "{{documentid}}" adicione o id gerado ao criar o documento.

SimSem valor padrão{
"data": { "type": "documents", "id": "6793c70a-360a-42a8-966c-473998c9a2ed"}
}
signers

Um objeto com as relações do requisito com outros recursos.

Em "type": "signers", "id": "{{signerid}}" adicione o id gerado ao criar o signatário.

SimSem valor padrão{
"data": { "type": "signers", "id": "8b3ec0c2-16f8-4fb9-9c2b-cbf51abc9e87"}
}
❗️

Se a requisição para a Clicksign 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. Confira mais detalhes em Mensagens de erro.

Exemplo completo

Request

POST /api/v3/envelopes/{{envelopeid}}/requirements HTTP/1.1
Host: sandbox.clicksign.com
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Authorization: access token
{
  "data": {
    "type": "requirements",
    "attributes": {
        "action": "provide_evidence",
        "auth": "whatsapp"
    },
    "relationships": {
        "document":{
            "data": { "type": "documents", "id": "{{documentid}}"}
        },
        "signer":{
            "data": { "type": "signers", "id": "{{signerid}}"}
      }
    }
  }
}

Response

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json; charset=utf-8
{
    "data": {
        "id": "6158b524-f7b3-4aa1-980a-cf371ea33a77",
        "type": "requirements",
        "links": {
            "self": "https://3.clicksign.dev/api/v3/envelopes/62ff38bc-b8fd-4e02-a1ce-6a1ff0f502a7/requirements/6158b524-f7b3-4aa1-980a-cf371ea33a77"
        },
        "attributes": {
            "action": "provide_evidence",
            "auth": "whatsapp",
            "created": "2023-07-04T12:48:46.000-03:00",
            "modified": "2023-07-04T12:48:46.000-03:00"
        }
    }
}