Documentação

Tutorial de uso

Três endpoints para criar a assinatura

Esta página mostra como criar assinaturas/rubricas posicionadas nos três endpoints da API v3: um requisito por vez com requirements, várias operações numa só chamada com bulk_requirements e o envelope completo de uma vez com envelope_bulk_creations.

Antes de começar

Leia a página Como identificar as coordenadas, e guarde os valores para implementação.
As regras de validação, os erros e as dúvidas frequentes estão em Regras, erros e dúvidas.

Todos os exemplos deste guia foram executados no Sandbox, e as respostas mostradas são reais.

Servidor Sandbox: https://sandbox.clicksign.com

Headers de todas as requisições:

Authorization: <seu access token>
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

O access token vai sem o prefixo Bearer.

Montando o campo positions

Cada ponto de rubrica é um item da lista positions, com a página e a posição nela:

{ "page": "1", "position": [0.85, 0.9] }

Vários pontos na mesma rubrica

positions é uma lista. Inclua um item para cada lugar em que o signatário deve rubricar, na mesma página ou em páginas diferentes:

"positions": [
  { "page": "1", "position": [0.1, 0.8] },
  { "page": "1", "position": [0.6, 0.8] }
]

Para rubricar várias páginas, repita o item mudando o page.

Tipo de rubrica (kind)

kindResultado
initialsRubrica com as iniciais do signatário. É o padrão quando kind não é enviado
manuscriptRubrica manuscrita, desenhada pelo signatário

Cada signatário pode ter, no mesmo documento, uma rubrica initials e uma manuscript.

Diagrama de sequência

Abaixo você poderá entender como a solução se integra ao nosso ecossistema:


Inclusão individual: requirements

Neste fluxo, você cria o envelope, adiciona o documento e o signatário e, por fim, a assinatura/rubrica posicionada.

Referência da API: Criar Requisito de Rubrica.

Passo 1: criar o envelope

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes \
  --header 'Authorization: <seu access token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
      "type": "envelopes",
      "attributes": {
        "name": "Contrato de Prestação de Serviços",
        "locale": "pt-BR",
        "auto_close": true
      }
    }
  }'

Guarde o data.id da resposta: ele é o {envelope_id}.

Passo 2: adicionar o documento

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

Guarde o data.id: ele é o {document_id}.

Passo 3: adicionar o signatário

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{envelope_id}/signers \
  --header 'Authorization: <seu access token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
      "type": "signers",
      "attributes": {
        "name": "Maria Silva",
        "email": "[email protected]",
        "communicate_events": {
          "signature_request": "email",
          "signature_reminder": "none",
          "document_signed": "email"
        }
      }
    }
  }'

Guarde o data.id: ele é o {signer_id}.

Passo 4: adicionar qualificação e autenticação

Para ativar o envelope, todo signatário precisa de um requisito de qualificação (agree) e um de autenticação (provide_evidence). Envie os dois em POST /api/v3/envelopes/{envelope_id}/requirements:

{
  "data": {
    "type": "requirements",
    "attributes": { "action": "agree", "role": "sign" },
    "relationships": {
      "document": { "data": { "type": "documents", "id": "{document_id}" } },
      "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
    }
  }
}
{
  "data": {
    "type": "requirements",
    "attributes": { "action": "provide_evidence", "auth": "email" },
    "relationships": {
      "document": { "data": { "type": "documents", "id": "{document_id}" } },
      "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
    }
  }
}

Passo 5: criar a assinatura/rubrica posicionada

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{envelope_id}/requirements \
  --header 'Authorization: <seu access token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
      "type": "requirements",
      "attributes": {
        "action": "rubricate",
        "kind": "initials",
        "positions": [
          { "page": "1", "position": [0.85, 0.9] }
        ]
      },
      "relationships": {
        "document": { "data": { "type": "documents", "id": "{document_id}" } },
        "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
      }
    }
  }'

Resposta 201 Created:

{
  "data": {
    "id": "dc6d5952-fae0-4088-8206-e3897401f193",
    "type": "requirements",
    "links": {
      "self": "https://sandbox.clicksign.com/api/v3/envelopes/70ac93db-354e-4fee-b96b-59d538c5e56d/requirements/dc6d5952-fae0-4088-8206-e3897401f193"
    },
    "attributes": {
      "action": "rubricate",
      "kind": "initials",
      "rubric_field": null,
      "positions": [
        { "page": "1", "position": [0.85, 0.9] }
      ],
      "created": "2026-10-09T15:45:18.210-03:00",
      "modified": "2026-10-09T15:45:18.210-03:00"
    }
  }
}

Passo 6 (opcional): rubrica manuscrita em dois pontos

O mesmo signatário pode ter também uma rubrica manuscrita:

{
  "data": {
    "type": "requirements",
    "attributes": {
      "action": "rubricate",
      "kind": "manuscript",
      "positions": [
        { "page": "1", "position": [0.1, 0.8] },
        { "page": "1", "position": [0.6, 0.8] }
      ]
    },
    "relationships": {
      "document": { "data": { "type": "documents", "id": "{document_id}" } },
      "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
    }
  }
}

Resposta 201 Created, com os dois pontos em positions:

"attributes": {
  "action": "rubricate",
  "kind": "manuscript",
  "rubric_field": null,
  "positions": [
    { "page": "1", "position": [0.1, 0.8] },
    { "page": "1", "position": [0.6, 0.8] }
  ],
  "created": "2026-10-09T15:45:20.804-03:00",
  "modified": "2026-10-09T15:45:20.804-03:00"
}

Passo 7: consultar a rubrica

curl --request GET \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{envelope_id}/requirements/{requirement_id} \
  --header 'Authorization: <seu access token>' \
  --header 'Accept: application/vnd.api+json'

Resposta 200 OK, no mesmo formato da criação, com positions. A listagem GET /api/v3/envelopes/{envelope_id}/requirements também traz positions em cada assinatura/rubrica posicionada.

Passo 8: ativar o envelope

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

Resposta 200 OK, com "status": "running". O signatário recebe o convite e rubrica nos pontos definidos.

Deu erro? Veja Regras, erros e dúvidas.

Atualizações em lote: bulk_requirements

O endpoint POST /api/v3/envelopes/{envelope_id}/bulk_requirements recebe uma lista de operações no formato JSON:API Atomic Operations. Cada operação add tem o mesmo data do endpoint de requisitos.

Referência da API: Criação e Exclusão de Requisitos.

Qualificação, autenticação e assinatura/rubrica posicionada numa só chamada

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelopes/{envelope_id}/bulk_requirements \
  --header 'Authorization: <seu access token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "atomic:operations": [
      {
        "op": "add",
        "data": {
          "type": "requirements",
          "attributes": { "action": "agree", "role": "sign" },
          "relationships": {
            "document": { "data": { "type": "documents", "id": "{document_id}" } },
            "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
          }
        }
      },
      {
        "op": "add",
        "data": {
          "type": "requirements",
          "attributes": { "action": "provide_evidence", "auth": "email" },
          "relationships": {
            "document": { "data": { "type": "documents", "id": "{document_id}" } },
            "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
          }
        }
      },
      {
        "op": "add",
        "data": {
          "type": "requirements",
          "attributes": {
            "action": "rubricate",
            "kind": "initials",
            "positions": [
              { "page": "1", "position": [0.85, 0.95] }
            ]
          },
          "relationships": {
            "document": { "data": { "type": "documents", "id": "{document_id}" } },
            "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
          }
        }
      }
    ]
  }'

Resposta 200 OK, com um resultado por operação, na mesma ordem (objetos resumidos; cada item também traz links.self, created e modified):

{
  "atomic:results": [
    { "data": { "id": "eb88bf55-0fd9-46ae-90d3-d7f53acafd26", "type": "requirements", "attributes": { "action": "agree", "role": "sign", "rubric_field": null } } },
    { "data": { "id": "e39cf287-2188-4d42-a4d3-5e541c813ed5", "type": "requirements", "attributes": { "action": "provide_evidence", "auth": "email", "rubric_field": null } } },
    {
      "data": {
        "id": "696bd361-06ec-4629-8189-878a5c163c26",
        "type": "requirements",
        "attributes": {
          "action": "rubricate",
          "kind": "initials",
          "rubric_field": null,
          "positions": [ { "page": "1", "position": [0.85, 0.95] } ]
        }
      }
    }
  ]
}

Trocar a posição de uma rubrica

Não existe edição de requisito: para mudar a posição, remova a rubrica atual e crie outra. Com bulk_requirements, as duas operações cabem numa só chamada:

{
  "atomic:operations": [
    { "op": "remove", "ref": { "type": "requirements", "id": "{requirement_id}" } },
    {
      "op": "add",
      "data": {
        "type": "requirements",
        "attributes": {
          "action": "rubricate",
          "kind": "manuscript",
          "positions": [ { "page": "1", "position": [0.1, 0.85] } ]
        },
        "relationships": {
          "document": { "data": { "type": "documents", "id": "{document_id}" } },
          "signer":   { "data": { "type": "signers",   "id": "{signer_id}" } }
        }
      }
    }
  ]
}

Resposta 200 OK. A remoção volta como { "data": {} } e a nova rubrica vem com a posição atualizada:

{
  "atomic:results": [
    { "data": {} },
    {
      "data": {
        "id": "d2b834b4-832d-4777-8eb8-abe389a049ee",
        "type": "requirements",
        "attributes": {
          "action": "rubricate",
          "kind": "manuscript",
          "rubric_field": null,
          "positions": [ { "page": "1", "position": [0.1, 0.85] } ]
        }
      }
    }
  ]
}

Deu erro? Veja Regras, erros e dúvidas.

Fluxo simplificado: envelope_bulk_creations

O endpoint POST /api/v3/envelope_bulk_creations cria envelope, documento, signatários e requisitos de uma vez. A assinatura/rubrica posicionada entra como mais um item em signers[].requirements, sem relationships, porque o documento e o signatário são criados na mesma chamada.

Referência da API: Criar Envelope em Lote.

curl --request POST \
  --url https://sandbox.clicksign.com/api/v3/envelope_bulk_creations \
  --header 'Authorization: <seu access token>' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
    "data": {
      "type": "envelope-bulk-creation",
      "attributes": {
        "envelope": {
          "name": "Contrato de Prestação de Serviços",
          "locale": "pt-BR",
          "auto_close": true
        },
        "document": {
          "filename": "contrato.pdf",
          "content_base64": "data:application/pdf;base64,JVBERi0xLjcN...",
          "metadata": { "source": "integracao" }
        },
        "signers": [
          {
            "name": "Maria Silva",
            "email": "[email protected]",
            "requirements": [
              { "action": "agree", "role": "sign" },
              { "action": "provide_evidence", "auth": "email" },
              {
                "action": "rubricate",
                "kind": "initials",
                "positions": [
                  { "page": "1", "position": [0.85, 0.9] }
                ]
              }
            ]
          }
        ]
      }
    }
  }'

Resposta 201 Created:

{
  "data": {
    "id": "d7903b31-8840-4d0b-9bc4-f379b8bcc239",
    "type": "envelope_bulk_creations",
    "links": {
      "self": "https://sandbox.clicksign.com/api/v3/envelope_bulk_creations/d7903b31-8840-4d0b-9bc4-f379b8bcc239"
    },
    "attributes": {
      "job_id": "d7903b31-8840-4d0b-9bc4-f379b8bcc239",
      "enqueued_at": "2026-10-09T15:45:34.685-03:00"
    }
  }
}

A criação é assíncrona: a resposta confirma o recebimento e devolve o job_id. Em poucos segundos, o envelope aparece na conta já ativado (running), com o job_id em metadata. Para conferir a rubrica:

  1. Busque o envelope pelo nome: GET /api/v3/envelopes?filter[name]=Contrato de Prestação de Serviços.
  2. Liste os requisitos: GET /api/v3/envelopes/{envelope_id}/requirements. A rubrica aparece com positions:
"attributes": {
  "action": "rubricate",
  "kind": "initials",
  "rubric_field": null,
  "positions": [ { "page": "1", "position": [0.85, 0.9] } ]
}

Deu erro? Veja Regras, erros e dúvidas.



❓Precisa de ajuda? Entre em contato com o Suporte

💰Dúvida sobre planos e preços? Veja o comparativo

🔍Não sabe qual versão está usando? Descubra a sua versão

📚Respostas rápidas? Visite nosso FAQ

Updated about 8 hours ago

Did this page help you?