### Run Application with Docker Compose
Source: https://developers.clicksign.com/docs/exemplo-pratico-com-docker
Start only the application for envelopes using Docker Compose. Ensure Docker is running before execution.
```bash
docker compose up envelope
```
--------------------------------
### Clone the Embedded Test Repository
Source: https://developers.clicksign.com/docs/exemplo-pratico-com-docker
Clone the public repository for testing the Clicksign Embedded Widget. Ensure you have git installed.
```bash
git clone https://github.com/clicksign/embedded-test.git
cd embedded-test
```
--------------------------------
### Consultar um Aceite Específico via WhatsApp
Source: https://developers.clicksign.com/docs/como-criar-um-aceite-via-whatsapp
Use este endpoint GET para verificar o status de um termo de aceite específico. Substitua 'SEU_ID_AQUI' pelo ID do aceite que você deseja consultar e 'SEU_TOKEN_AQUI' pelo seu Access Token.
```bash
curl --request GET \
--url https://sandbox.clicksign.com/api/v3/acceptance_term/whatsapps/SEU_ID_AQUI \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI'
```
--------------------------------
### Requisição HTTP para obter envelopes
Source: https://developers.clicksign.com/docs/informacoes-gerais
Exemplo de requisição HTTP GET para listar envelopes, utilizando o ambiente Sandbox. Certifique-se de incluir o access_token no header de autorização e os cabeçalhos Accept e Content-Type no formato application/vnd.api+json.
```http
GET /api/v3/envelopes HTTP/2
Host: sandbox.clicksign.com
Authorization: {{access_token}}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```
--------------------------------
### Inicializar e Utilizar noWidget.js
Source: https://developers.clicksign.com/docs/assinatura-incorporada-implementacoes-e-testes
Demonstra como inicializar a classe noWidget com a chave do signatário e o ambiente, e como usar os métodos mount e attach para gerenciar a exibição de documentos e a ação de assinatura.
```javascript
const nw = new noWidget('SIGNER_KEY', 'sandbox');
nw.mount({ containerId: 'widget' });
nw.attach('click', 'submitButton', () => {
const data = { ... }; // Colete os dados do formulário
nw.sign(data)
.then(() => console.log('Sucesso!'))
.catch((error) => console.error('Erro:', error));
});
```
--------------------------------
### Comparativo: Processo corporativo com aprovações
Source: https://developers.clicksign.com/docs/migracao-da-api-19-para-30
Ilustra a evolução do gerenciamento de processos corporativos com aprovações da API 1.9 para a API 3.0. A API 3.0 oferece automação de fluxo e acompanhamento centralizado, reduzindo o tempo de execução.
```html
Com a API 1.9:
* Gerenciamento manual da sequência
* Múltiplos sistemas para acompanhar
* Retrabalho se houver mudanças
* Tempo: Semanas
Com a API 3.0:
* Fluxo automatizado no envelope
* Acompanhamento centralizado
* Usuário observador (jurídico)
* Tempo: Dias
```
--------------------------------
### Webhook Request Body Example
Source: https://developers.clicksign.com/docs/disparos-de-webhooks
This JSON body represents the data sent with a webhook request, detailing the event that triggered it, information about the document, and associated signers.
```json
{
event: { /* Evento que disparou o Webhook */
"name": "add_signer",
"data": {
"user": {
"email": "email@empresa.com",
"name": "Empresa de Teste"
},
"account": {
"key": "35286aca-beef-490d-ad23-bc5e78441232"
},
"signers": [
{
"key": "c9d50ca2-543f-49ee-924a-345f23088434",
"request_signature_key": "c08a5ed5-3c74-987c-830f-ae9b9ddd7b85",
"email": "email@empresa.com",
"created_at": "2018-04-24T22:42:40.180-03:00",
"sign_as": "witness",
"auths": [
"sms"
],
"phone_number": "11987654321",
"phone_number_hash": "66e0c202cea2d29452067233e8e0f8fe2808cca773852ab537e40cf4a68d16ae"
}
]
},
"occurred_at": "2018-04-25T01:42:40.197Z"
},
"document": { /* Documento */
//...
},
"signers": [ /* Signatários deste documento */
//...
],
"events": [ /* Array completo com todos eventos deste documento */
{
"name": "add_signer",
//...
},
{
"name": "sign",
//...
},
{
"name": "upload",
//...
}
]
}
}
```
--------------------------------
### Comparativo: Contrato com múltiplos documentos
Source: https://developers.clicksign.com/docs/migracao-da-api-19-para-30
Demonstra a diferença entre a API 1.9 e a API 3.0 para o gerenciamento de contratos com múltiplos documentos. A API 3.0 simplifica o processo com um único envelope e configuração centralizada.
```html
Com a API 1.9:
* 4 envios separados
* Configuração individual para cada documento
* Impossível corrigir erros sem reenviar tudo
* Processo demorado e burocrático
Com a API 3.0:
* 1 único envelope
* Configuração centralizada
* Possível corrigir enquanto o envelope estiver em processo
* Mais agilidade e flexibilidade
```
--------------------------------
### API Request Headers - Limit Exceeded
Source: https://developers.clicksign.com/docs/limite-de-requisicoes
Example of HTTP response headers when the rate limit has been exceeded. It indicates zero remaining requests and provides the reset timestamp.
```HTTP
HTTP/2 429 Too Many Requests
Date: Thu, 29 Feb 2024 17:00:15 GMT
X-Rate-Limit: 50
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: 1709226020
```
--------------------------------
### Estrutura HTML para Assinatura Incorporada
Source: https://developers.clicksign.com/docs/assinatura-incorporada-implementacoes-e-testes
Exemplo de estrutura HTML necessária para a implementação da Assinatura Incorporada. Inclui um container para os documentos e um botão para iniciar a assinatura.
```html
```
--------------------------------
### Preparar Elementos HTML para Signer
Source: https://developers.clicksign.com/docs/primeiros-passos-1
Prepare os elementos HTML necessários para a renderização do componente de aceite e o botão de confirmação.
```html
```
--------------------------------
### Document Field JSON Example
Source: https://developers.clicksign.com/docs/exemplo-documento
This JSON object represents the structure of the 'Document' field. It includes essential information about a document, its status, associated URLs, and references to signers and events.
```json
{
"key"=>"db4a2cf7-0a48-481f-b669-54f2a2260ac2",
"account_key"=>"f9d9b699-fa73-4949-b8c5-c45df202744b",
"path"=>"/blank-4.pdf",
"filename"=>"blank-4.pdf",
"uploaded_at"=>"2023-03-13T14:28:02.235Z",
"updated_at"=>"2023-03-13T16:37:09.228Z",
"finished_at"=>"2023-03-13T16:37:02.628Z",
"deadline_at"=>"2023-04-12T11:27:53.617-03:00",
"status"=>"closed",
"auto_close"=>true,
"locale"=>"pt-BR",
"metadata"=>{},
"sequence_enabled"=>false,
"signable_group"=>null,
"remind_interval"=>3,
"block_after_refusal"=>false,
"downloads"=>
{
"original_file_url"=> "/2023/03/13/888twv3942_blank_4.pdf",
"signed_file_url"=> "/2023/03/13/1q42v26p3o_blank_4_Clicksign.pdf",
"ziped_file_url"=> "/2023/03/13/99e8ang3j2_blank_4_Clicksign.zip"
},
"template"=>null,
"signers"=> [ < Veja exemplo de Signatários > ],
"events"=> [ < Veja exemplos de Eventos >],
"attachments"=>[],
"links"=> {"self"=>"/db4a2cf7-0a48-481f-b669-54f2a2260ac2"}
}
```
--------------------------------
### API Request Headers - Limit Not Exceeded
Source: https://developers.clicksign.com/docs/limite-de-requisicoes
Example of HTTP response headers when a request is within the rate limit. It shows the total allowed requests, remaining requests, and the reset time.
```HTTP
HTTP/2 200 OK
Date: Thu, 29 Feb 2024 12:33:58 GMT
X-Rate-Limit: 50
X-Rate-Limit-Remaining: 49
X-Rate-Limit-Reset: 1709210040
```
--------------------------------
### Exemplo de URL da API 1.9 (Legada)
Source: https://developers.clicksign.com/docs/descubra-sua-versao-da-api
URLs que iniciam com /v1 ou /v2 indicam o uso da API legada 1.9. Esta versão não recebe mais atualizações.
```html
https://app.clicksign.com/api/v1/...
```
--------------------------------
### Carregar e Configurar o Widget Embedded com JavaScript
Source: https://developers.clicksign.com/docs/implementando-o-widget-embedded
Inicialize o widget com o ID do signatário, defina o endpoint (sandbox ou produção), e renderize-o no container especificado. Callbacks opcionais para eventos como 'loaded', 'signed', e 'resized' podem ser adicionados.
```javascript
var widget = new Clicksign('ID_DO_SIGNATARIO');
// Defina o endpoint apropriado (Sandbox ou Produção)
widget.endpoint = 'https://sandbox.clicksign.com'; // Ou 'https://app.clicksign.com'
// (Opcional) Defina a URL de origem se estiver usando WebView
widget.origin = window.origin;
// Renderize o widget dentro do container
widget.mount('container');
// (Opcional) Adicione callbacks para eventos
widget.on('loaded', function(event) {
console.log('Widget carregado!');
});
widget.on('signed', function(event) {
console.log('Documento assinado!');
// Redirecione o usuário ou execute alguma ação
// window.location.href = '/obrigado';
});
widget.on('resized', function(event) {
console.log('Widget redimensionado:', event.data.height);
document.getElementById('container').style.height = event.data.height + 'px';
});
```
--------------------------------
### Signers Field JSON Example
Source: https://developers.clicksign.com/docs/exemplo-signers
This JSON object represents the structure for the Signers field. It includes essential details like key, name, email, phone number, documentation, birthday, and creation timestamp.
```json
{
"key": "00000000-0000-0000-0000-000000000000",
"name": "Nome Genérico",
"email": "usuario@example.com",
"phone_number": "0000000000",
"documentation": "000.000.000-00",
"has_documentation": true,
"birthday": "2000-01-01",
"created_at": "2025-01-01T00:00:00.000-03:00"
}
```
--------------------------------
### Inicializar e Configurar MultiSigner
Source: https://developers.clicksign.com/docs/primeiros-passos-1
Configure o MultiSigner com sua chave de API, defina o modo de operação e adicione os documentos e participantes. O botão de confirmação é habilitado quando o usuário concorda com os termos.
```javascript
// 1. Crie uma nova instância do MultiSigner com sua chave de API
const signerMultiplo = new MultiSigner("SUA_API_KEY");
// 2. Defina o ambiente de operação
signerMultiplo.mode = "staging";
// 3. Adicione os conteúdos, cada um com seu respectivo participante
signer.set = {
name: "Nome do participante",
documents: [
{
name: "cpf",
value: "000.000.000-00",
},
],
tags: ["saler", "2025"],
};
signer.contents = [
{
name: "Contrato de Prestação de Serviço Nº 001",
key: "25783eb5-0538-414b-87b4-684afc5f3fd9",
},
{
name: "Termo de Uso Nº 001",
key: "ffe6e132-81d5-4503-a56e-e2219d0cef95",
},
{
name: "Termo de Uso Nº 002",
key: "ffe6e132-81d5-4503-a56e-e2219d0cef95",
},
{
name: "Termo de Uso Nº 003",
key: "ffe6e132-81d5-4503-a56e-e2219d0cef95",
},
{
name: "Termo de Uso Nº 004",
key: "ffe6e132-81d5-4503-a56e-e2219d0cef95",
},
{
name: "Termo de Uso Nº 005",
key: "ffe6e132-81d5-4503-a56e-e2219d0cef95",
},
{
name: "Termo de Uso Nº 006",
key: "ffe6e132-81d5-4503-a56e-e2219d0cef95",
},
];
// 4. Renderize o componente
signerMultiplo.mount("#signer");
// 5. Habilite o botão quando o usuário aceitar os termos
const next = document.querySelector("#next");
// Função chamada quando usuário clicar no checkbox "eu concordo"
signer.toggle = (agreed) => {
next.disabled = !agreed;
};
// 6. Adicione o evento de clique para formalizar o aceite de todos os itens
next.addEventListener("click", (ev) => {
ev.preventDefault();
next.disabled = true;
// Função que vai ser executada ao confirmar o aceite
signer
.agree()
.then((response) => {
console.log("success");
// Informação gerada que deve ser salva
response.json().then((data) => console.log(data));
})
.catch((response) => {
// Quando algo der errado
console.log("failed");
})
.finally(() => {
console.log("always");
next.disabled = false;
document.querySelector("#signer").remove();
next.remove();
});
});
```
--------------------------------
### Preparar Elementos HTML para MultiSigner
Source: https://developers.clicksign.com/docs/primeiros-passos-1
Crie os elementos HTML necessários para a exibição do componente de assinatura e o botão de confirmação.
```html
```
--------------------------------
### Comando cURL para obter envelopes
Source: https://developers.clicksign.com/docs/informacoes-gerais
Exemplo de comando cURL para realizar uma requisição GET para a API Clicksign, buscando envelopes no ambiente Sandbox. O comando demonstra como configurar os headers de Authorization, Content-Type e Accept.
```curl
curl --request GET \
--url 'https://sandbox.clicksign.com/api/v3/envelopes' \
--header 'Authorization: {{access_token}}' \
--header 'Content-Type: application/vnd.api+json' \
--header 'accept: application/vnd.api+json'
```
--------------------------------
### Exemplo Completo de Implementação do Widget Embedded
Source: https://developers.clicksign.com/docs/implementando-o-widget-embedded
Um exemplo completo de HTML que demonstra como carregar e interagir com o Widget Embedded, incluindo um campo de entrada para o ID da assinatura e um botão para carregar o widget.
```html
Simple widget usage
```
--------------------------------
### Exemplo de URL da API 3.0 (Atual)
Source: https://developers.clicksign.com/docs/descubra-sua-versao-da-api
URLs que iniciam com /v3 indicam o uso da API 3.0, a versão mais recente e atualizada da Clicksign.
```html
https://app.clicksign.com/api/v3/...
```
--------------------------------
### Clonar Repositório de Teste
Source: https://developers.clicksign.com/docs/assinatura-incorporada-implementacoes-e-testes
Clone o repositório público do GitHub para experimentar o Widget com Assinatura Incorporada em um ambiente isolado. Ideal para testes iniciais.
```shell
git clone https://github.com/clicksign/embedded-test.git
# Acessar pasta do exemplo
cd embedded-test/v3/embedded_signature
```
--------------------------------
### Exemplo de Tags para Assinatura Posicionada
Source: https://developers.clicksign.com/docs/docs-modelos
Utilize estas tags no seu arquivo Word (.docx) para definir locais específicos onde as assinaturas manuscritas dos signatários serão aplicadas no documento final. O 'ID' deve ser um identificador único para cada signatário.
```plaintext
TERMO DE COMPROMISSO
Declaro estar de acordo com as cláusulas citadas.
Vendedor: {{~position_sign_vendedor}}
Comprador: {{~position_sign_comprador}}
```
--------------------------------
### Inicializar e Configurar o Signer
Source: https://developers.clicksign.com/docs/primeiros-passos-1
Configure o Signer com sua chave de API, defina o ambiente, os dados do participante e os documentos para aceite. Habilite o botão de confirmação com base no aceite do usuário e finalize o processo de aceite.
```javascript
// 1. Crie uma nova instância do Signer com sua chave de API
const signer = new Signer("SUA_API_KEY");
// 2. Defina o ambiente de operação ("staging" para testes)
signer.mode = "staging";
// 3. Defina quem irá dar o aceite (o participante)
signer.set = {
name: "Nome do participante",
documents: [
{
name: "cpf",
value: "000.000.000-00",
},
],
tags: ["customer", "2025"],
};
// 4. Adicione o conteúdo para o qual o aceite será coletado
signer.contents = [
{
name: "LGPD",
url: "https://urlexample.com/pdf/sample.pdf",
tags: ["lgpd", "2025"],
},
{
name: "Termo de Uso",
url: "https://www.urlexample.com/images/sample.pdf",
tags: ["tou", "2025"],
},
{
name: "Contrato de Prestação de Serviço",
url: "https://www.urlexample.com/pdf/sample.pdf",
tags: ["contract", "2025"],
},
];
// 5. Renderize o componente na div #signer
signer.mount("#signer");
// 6. Habilite o botão "Eu concordo" quando o usuário aceitar os termos
const next = document.querySelector("#next");
// Função chamada quando o usuário clicar no checkbox "eu concordo"
signer.toggle = (agreed) => {
next.disabled = !agreed;
};
// 7. Adicione o evento de clique para formalizar o aceite
next.addEventListener("click", (ev) => {
ev.preventDefault();
next.disabled = true;
// Função que vai ser executada ao confirmar o aceite
signer
.agree()
.then((response) => {
// Informação gerada que deve ser salva
response.json().then((data) => {
alert(`Chave do envelope gerado: ${data.envelope.key}`);
});
})
.catch((response) => {
// Quando algo der errado
console.log("failed");
})
.finally(() => {
console.log("always");
document.querySelector("#signer").remove();
next.remove();
});
});
```
--------------------------------
### Abrir Página de Exemplo no Navegador
Source: https://developers.clicksign.com/docs/assinatura-incorporada-implementacoes-e-testes
Comando para abrir o arquivo index.html em navegadores como Firefox ou Google Chrome, permitindo visualizar o widget em funcionamento.
```shell
# para firefox
firefox index.html
# para google-chrome
google-chrome index.html
```
--------------------------------
### Ativar Envelope para Assinatura
Source: https://developers.clicksign.com/docs/guia-de-criacao-o-passo-a-passo-padrao
Altere o status de um envelope para 'running' para iniciar o processo de assinatura. Este método é adequado para operações de menor escala.
```json
{
"data": {
"id": "ID_DO_ENVELOPE",
"type": "envelopes",
"attributes": {
"status": "running"
}
}
}
```
--------------------------------
### Exemplo de Corpo de Requisição para Evento Auto Close
Source: https://developers.clicksign.com/docs/evento-auto-close
Este é um exemplo da estrutura JSON recebida quando o evento 'auto_close' é disparado. Ele contém informações sobre o evento, como o nome, a data de ocorrência e dados associados ao documento.
```json
{
"event"=>{
"name"=>"auto_close",
"data"=>null,
"occurred_at"=>"2017-05-05T14:57:25.191-03:00"
},
document: < Veja exemplo de documentos >
}
```
--------------------------------
### Criar um Aceite via WhatsApp
Source: https://developers.clicksign.com/docs/como-criar-um-aceite-via-whatsapp
Utilize este endpoint POST para enviar um termo de aceite para o número de telefone do cliente. Certifique-se de substituir 'SEU_TOKEN_AQUI' pelo seu Access Token e '5511999998888' pelo número do cliente.
```bash
curl --request POST \
--url https://sandbox.clicksign.com/api/v3/acceptance_term/whatsapps \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI' \
--header 'Content-Type: application/vnd.api+json' \
--data '{ \
"data": { \
"type": "acceptance_term_whatsapps", \
"attributes": { \
"title": "Adesão ao Plano Premium 2026", \
"content": "Eu aceito os termos de serviço e a política de privacidade da Empresa Exemplo para o contrato 123.", \
"phone_number": "5511999998888", \
"sender_name_option": "account_name" \
} \
} \
}'
```
--------------------------------
### Incluir a Biblioteca do Widget Embedded
Source: https://developers.clicksign.com/docs/implementando-o-widget-embedded
Adicione esta tag script ao corpo da sua página HTML para carregar a biblioteca do Widget Embedded.
```html
```
--------------------------------
### Informações para Contato com Suporte
Source: https://developers.clicksign.com/docs/mensagens-de-erro
Lista de detalhes essenciais a serem fornecidos ao Time de Suporte da Clicksign para auxiliar na depuração de problemas de integração.
```text
- Ambiente: sandbox ou produção
- Conta
- E-mail do operador
- Path da requisição
- Método da requisição
- Código HTTP de erro
- JSON enviado
- JSON recebido
- Key do documento
- E-mails contidos na lista de assinatura
- Horário da requisição
- IP de origem
- Print screen
```
--------------------------------
### Informações para Debug de Webhooks
Source: https://developers.clicksign.com/docs/melhores-praticas-webhooks
Ao entrar em contato com o suporte para problemas com Webhooks, forneça o máximo de detalhes possível para agilizar a depuração. Inclua informações sobre o ambiente, conta, URL do Webhook, e-mail do operador, chave do documento, evento e horário da requisição.
```text
- Ambiente: sandbox ou produção
- Conta
- URL do Webhook
- E-mail do operador
- Key do documento
- Evento
- Horário da requisição
```
--------------------------------
### Configurar Ação de Assinatura Parcial em Envelopes
Source: https://developers.clicksign.com/docs/aproveitamento-de-assinaturas-parciais-em-documentos-expirados
Utilize o atributo `deadline_partial_signature_action` na criação de envelopes via API para definir o comportamento após a expiração. O valor 'closed' finaliza o documento com assinaturas coletadas, enquanto 'canceled' o cancela se todas as assinaturas não forem concluídas.
```json
{
"data": {
"type": "envelopes",
"attributes": {
"deadline_partial_signature_action": "closed"
}
}
}
```
--------------------------------
### Requisição de Ativação Assíncrona (cURL)
Source: https://developers.clicksign.com/docs/ativacao-escala-performatica
Utilize este comando cURL para enviar uma requisição POST ao endpoint de ativação assíncrona. Certifique-se de substituir os placeholders pela sua chave de envelope e token de autenticação.
```bash
curl --request POST \
--url [https://app.clicksign.com/api/v3/envelopes/SUA_CHAVE_DO_ENVELOPE/activate](https://app.clicksign.com/api/v3/envelopes/SUA_CHAVE_DO_ENVELOPE/activate) \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer SEU_TOKEN_AQUI' \
--header 'Content-Type: application/vnd.api+json'
```