Fluxo com a página de integração

Use nossa página de edição para facilitar o posicionamento das assinaturas

Caso tenha dificuldades na implementação do arraste das assinaturas que a posicionem corretamente nos eixos x e y do documento, disponibilizamos uma forma de usar o nosso editor para criar um payload com os posicionamentos corretos. Segue um vídeo de exemplo do fluxo:

Exemplo de redirecionamento para integração

Neste fluxo, precisamos gerar um template de workflow, do qual nos fornece um token de integração, e passamos o id e o token deste template para a página de montagem. Depois que é feito a montagem do documento e definido os assinantes, o template é atualizado e você pode usá-lo para gerar e iniciar o seu workflow.

Preparando o fluxo

Estamos assumindo que neste momento você já sabe como fazer login e adquirir um token de sessão para usar os endpoints da API.

Caso precise de um token com um tempo de validade maior, gere um token de aplicação para contas PJ.

Como exemplo, criaremos um fluxo com um documento com um assinante Pedro Cavalcante. Antes de qualquer coisa, precisamos fazer upload dos documentos que queremos que a pessoa assine, baixe aqui um documento de exemplo caso queira:

cURL

curl -X POST \
    -H "Authorization: Bearer 41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4" \
    -F "file=@file-sample.pdf" https://api-v1.assine.online/v1/file

JavaScript

const token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

// Suponha que existe um campo de input[file] com o id "file"
const file = document.getElementById('file').files[0];

const response = await fetch('https://api-v1.assine.online/v1/file', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`
  },
  body: file
});

const data = await response.json();

PHP

$token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

$client = new GuzzleHttp\Client();

$body = fopen('./file-sample.pdf', 'r');

$res = $client->request('POST', 'https://api-v1.assine.online/v1/file', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token
    ],
    'body' => $body
]);

echo $res->getBody();

POST https://api.assine.online/v1/file

Resposta:

{
    "id": 5577,
    "name": "file-sample.pdf",
    "mimeType": "application/pdf",
    "description": "",
    "checksum": "6703901978dcb3dbf2d9915e1d3e066cfe712b0a",
    "size": 142786,
    "uuid": "e2dvb2RfbG9va317ImRhdGEiOnsidXVpZCI6ImIzOWRhYTBjLTU0ZTQtMTFlYS04MDAwLTAyNDJhYzE0MDAwNyJ9LCJobWFjIjoiYjQ3NGIzOTg4ZmQ3MDQ0NzNlNTczNDcyODdkMGZkMDg0MTAxMWYyMzliNGVkMzBjOGY0MDU5OTI1ZGRiNjI2NyIsIm5vbmNlIjoiMjE3ODE1ODIzMTUxODMifQ==",
    "_links": {
        "self": {
            "href": "https://api-v1.assine.online/v1/file/5577"
        }
    }
}

Guarde o id pois o usaremos como referência para criar nosso template.

Montando o template

Precisamos criar um payload para enviar para a API em que faz predefinições do documento que vamos usar e um usuário que deve assinar. Vamos começar estruturando a raiz do nosso payload com informações do template:

{
	"type": 0,
	"name": "Nome do template",
	"settings": {
		"canAddSigners": true
	},
	"template": {...}
}

• type: Tipo do template que estamos criando, sendo os possíveis valores:

  • 0: Temporário, ou seja, usado somente para criar o fluxo de redirecionamento e descartado futuramente.

  • 1: Permanente, ou seja, que pode ser reutilizado para outros fluxos de assinatura.

• name: Um nome de identificação para este template.

• settings: Definições acerca do template, no caso definimos canAddSigners como true o que permite que seja possível incluir mais assinantes pela tela de redirecionamento, no momento esta é a única opção disponível.

• template: Payload de estrutura idêntica ao workflow que iremos montar logo a seguir.

Agora vamos adicionar as demais configurações acerca do workflow que queremos salvar no nosso template:

{
	...
	"template": {
		"autoRemind": 0,
		"dueDate": "2023-01-01 23:59:59",
		"message": "Comentário opcional",
		"priority": 0,
		"sla": 1,
		"files": [{
			"idFile": 5577,
			"name": "Meu documento",
			"specialFields": [],
			"workflowSteps": [{
				"user": {
					"name": "Pedro Cavalcante",
					"email": "[e-mail]"
				},
				"action": 0,
				"signatureType": 0,
				"fields": []
			}]
		}]
	}
}

Todas as configurações aqui seguem o modelo de construção de workflow feito no quickstart. Para sumarizar, aqui definimos que queremos usar o arquivo de id 5577 do qual subimos no passo anterior e queremos que o primeiro e único assinante seja Pedro Cavalcante. Não precisamos definir qual assinatura essa pessoa deve ter neste momento, nem em que local do documento ela deve aparecer pois essas configurações serão feitas na tela de redirecionamento.

Criado o payload, teremos uma estrutura dessa forma:

{
	"type": 0,
	"name": "Nome do template",
	"settings": {
		"canAddSigners": true
	},
	"template": {
		"autoRemind": 0,
		"dueDate": "2023-01-01 23:59:59",
		"message": "Comentário opcional",
		"priority": 0,
		"sla": 1,
		"files": [{
			"idFile": 5577,
			"name": "Meu documento",
			"specialFields": [],
			"workflowSteps": [{
				"user": {
					"name": "Pedro Cavalcante",
					"email": "[e-mail]"
				},
				"action": 0,
				"signatureType": 0,
				"fields": []
			}]
		}]
	}
}

Usamos esse payload para mandar para o endpoint de template da API:

cURL

curl -X POST \
    -H 'Authorization: Bearer 41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4' \
    -H "Content-Type: application/json" \
    https://api-v1.assine.online/v1/workflow-template -d '
{
	"type": 0,
	"name": "Nome do template",
	"settings": {
		"canAddSigners": true
	},
	"template": {
		"autoRemind": 0,
		"dueDate": "2023-01-01 23:59:59",
		"message": "Comentário opcional",
		"priority": 0,
		"sla": 1,
		"files": [{
			"idFile": 5577,
			"name": "Meu documento",
			"specialFields": [],
			"workflowSteps": [{
				"user": {
					"name": "Pedro Cavalcante",
					"email": "[e-mail]"
				},
				"action": 0,
				"signatureType": 0,
				"fields": []
			}]
		}]
	}
}
'

JavaScript

const token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

const body = {
	type: 0,
	name: 'Nome do template',
	settings: {
		canAddSigners: true
	},
	template: {
		autoRemind: 0,
		dueDate: '2023-01-01 23:59:59',
		message: 'Comentário opcional',
		priority: 0,
		sla: 1,
		files: [{
			idFile: 5577,
			name: 'Meu documento',
			specialFields: [],
			workflowSteps: [{
				user: {
					name: 'Pedro Cavalcante',
					email: '[e-mail]'
				},
				action: 0,
				signatureType: 0,
				fields: []
			}]
		}]
	}
};

const response = await fetch('https://api.assine.online/v1/workflow-template', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

const data = await response.json();

PHP

$token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

$client = new GuzzleHttp\Client();

$res = $client->request('POST', 'https://api-v1.assine.online/v1/workflow-template', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token
    ],
    'json' => [
			"type" => 0,
			"name" => "Nome do template",
			"settings" => [
				"canAddSigners" => true
			],
			"template" => [
				"autoRemind" => 0,
				"dueDate" => "2023-01-01 23:59:59",
				"message" => "Comentário opcional",
				"priority" => 0,
				"sla" => 1,
				"files" => [[
					"idFile" => 5577,
					"name" => "Meu documento",
					"specialFields" => [],
					"workflowSteps" => [[
						"user" => [
							"name" => "Pedro Cavalcante",
							"email" => "[e-mail]"
						],
						"action" => 0,
						"signatureType" => 0,
						"fields" => []
					]]
				]]
			]
		]
]);

echo $res->getBody();

POST https://api.assine.online/v1/workflow-template

Resposta:

{
    "id": 11,
    "type": 0,
    "token": "e2dvb2RfbG9va317ImRhdEGiOnsidHlwZSI6InRlbXBsYXRlIiwiaWQiOjExfSwiaG1hYyI6ImNiYjkxMzE0ZDcxZTU0MDM2MTNlZGU0ZWQ2YWM3ZDBiM2ExNWI0NTdjYzUyMTNkMWIzYTE5YzRlNGI3ZTljOTYiLCJub25jZSI6Ijk2NjIxNTgyMzE2Njg2In0=",
    "title": "Template created",
    "status": 201,
    "detail": "Template created"
}

Precisaremos do id e do token da resposta, pois enviaremos estes dados para a tela de construção do documento.

URL de redirecionamento

Agora que temos nosso id e token do template, precisamos definir uma url de callback para que, quando for concluído as edições, o Assine Online redirecione o usuário de volta ao sistema. Vamos supor que o usuário deva voltar para o google (somente exemplo, numa situação real ele deve voltar para o seu sistema):

https://app.assine.online/integration/workflow?id=11&token=e2dvb2RfbG9va317ImRhdEGiOnsidHlwZSI6InRlbXBsYXRlIiwiaWQiOjExfSwiaG1hYyI6ImNiYjkxMzE0ZDcxZTU0MDM2MTNlZGU0ZWQ2YWM3ZDBiM2ExNWI0NTdjYzUyMTNkMWIzYTE5YzRlNGI3ZTljOTYiLCJub25jZSI6Ijk2NjIxNTgyMzE2Njg2In0=&callbackUrl=https://www.google.com

Aqui definimos:

• URL do Assine Online: https://app.assine.online/integration/workflow

• Parâmetros da url:

  • id: Número de id do template que criamos;

  • token: O token de acesso usado para validar a autorização de edição deste template;

  • callbackUrl: URL que o Assine Online irá redirecionar o usuário no fim do fluxo.

O usuário cairá na seguinte tela:

Tela de construção do documento e assinaturas

Aqui ele pode seguir o fluxo normalmente e montar como queira as assinaturas no documento conforme o vídeo:

Exemplo de redirecionamento para integração

Após a conclusão do fluxo na página de configuração, o usuário é redirecionado e o id do template do workflow é adicionado à url de callback. Ao consultarmos o template que criamos:

cURL

curl -X GET \
    -H 'Authorization: Bearer 41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4' \
    https://api.assine.online/v1/workflow-template/11

JavaScript

const token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

const workflowTemplateId = 11;

const response = await fetch(`https://api.assine.online/v1/workflow-template/${workflowTemplateId}`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

PHP

$token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

$workflowTemplateId = 11;

$client = new GuzzleHttp\Client();

$res = $client->request('GET', 'https://api.assine.online/v1/workflow-template/' . $workflowTemplateId, [
    'headers' => [
        'Authorization' => 'Bearer ' . $token
    ]
]);

echo $res->getBody();

GET https://api.assine.online/v1/workflow-template/:workflowTemplateId

Resposta:

{
    "id": 11,
    "template": {
        "autoRemind": 1,
        "dueDate": "2021-02-26 00:00:00",
        "message": "Por favor, assine os documentos: Meu documento",
        "priority": 0,
        "sla": 1,
        "files": [
            {
                "idFolder": null,
                "idFile": 5577,
                "name": "Meu documento",
                "specialFields": [],
                "workflowSteps": [
                    {
                        "user": {
                            "name": "Pedro Cavalcante",
                            "email": "[e-mail]"
                        },
                        "action": 0,
                        "signatureType": 0,
                        // O campo de assinatura (8) que adicionamos
                        "fields": [
                            {
                                "type": "8",
                                "x": "400.32",
                                "y": "45.72",
                                "height": "36.27",
                                "width": "157.62",
                                "page": 1
                            }
                        ]
                    }
                ],
                "_embedded": {
                    "file": {
                        "_links": {
                            "download": {
                                "href": "https://api.assine.online/file?q=e2dvb2RfbG9va317ImRhdGEiOnsidXVpZCI6ImIzOWRhYTBjLTU0ZTQtMTFlYS04MDAwLTAyNDJhYzE0MDAwNyJ9LCJobWFjIjoiMzZkNmE1NjdmMzI1MjQ4MmZlYjYxNDczMTJiZjBhOWFlZTUxMTFiOTUxZTRhOTRlYjE5YjBjMzQ1MmE0NzY1ZSIsIm5vbmNlIjoiNjEwMDE1ODI3MzQxODIifQ=="
                            }
                        }
                    }
                }
            }
        ]
    },
    "settings": {
        "canAddSigners": true
    },
    "token": "e2dvb2RfbG9va317ImRhdGEiOnsidHlwZSI6InRlbXBsYXRlIiwiaWQiOjExfSwiaG1hYyI6IjM1ZDg5ZDEwNWNhZWE3MTQwMTQ0YzQ0MDcwZTQ5ZTRlZjNlOTBkN2QyNDJkZmI1MWRiZjI1ZTkxMmM2ZDc5ZDQiLCJub25jZSI6IjA2ODMxNTgyNzM0MTgyIn0=",
    "type": 0,
    "title": "",
    "status": 200,
    "detail": ""
}

Agora que nosso template está 100% configurado, podemos usar o payload para construir a requisição de criação do workflow em si, basta usar o template criado e informá-lo para o endpoint de workflow:

cURL

curl -X POST \
    -H 'Authorization: Bearer 41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4' \
    -H "Content-Type: application/json" \
    https://api.assine.online/v1/workflow -d '
{
    "autoRemind": 1,
    "dueDate": "2021-02-26 00:00:00",
    "message": "Por favor, assine os documentos: Meu documento",
    "priority": 0,
    "sla": 1,
    "files": [
        {
            "idFolder": null,
            "idFile": 5577,
            "name": "Meu documento",
            "specialFields": [],
            "workflowSteps": [
                {
                    "user": {
                        "name": "Pedro Cavalcante",
                        "email": "[e-mail]"
                    },
                    "action": 0,
                    "signatureType": 0,
                    "fields": [
                        {
                            "type": "8",
                            "x": "400.32",
                            "y": "45.72",
                            "height": "36.27",
                            "width": "157.62",
                            "page": 1
                        }
                    ]
                }
            ],
            "_embedded": {
                "file": {
                    "_links": {
                        "download": {
                            "href": "https://api.assine.online/file?q=e2dvb2RfbG9va317ImRhdGEiOnsidXVpZCI6ImIzOWRhYTBjLTU0ZTQtMTFlYS04MDAwLTAyNDJhYzE0MDAwNyJ9LCJobWFjIjoiMzZkNmE1NjdmMzI1MjQ4MmZlYjYxNDczMTJiZjBhOWFlZTUxMTFiOTUxZTRhOTRlYjE5YjBjMzQ1MmE0NzY1ZSIsIm5vbmNlIjoiNjEwMDE1ODI3MzQxODIifQ=="
                        }
                    }
                }
            }
        }
    ]
}
'

JavaScript

const token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

const payload = {
    autoRemind: 1,
    dueDate: '2021-02-26 00:00:00',
    message: 'Por favor, assine os documentos: Meu documento',
    priority: 0,
    sla: 1,
    files: [
        {
            idFolder: null,
            idFile: 5577,
            name: 'Meu documento',
            specialFields: [],
            workflowSteps: [
                {
                    user: {
                        name: 'Pedro Cavalcante',
                        email: '[e-mail]'
                    },
                    action: 0,
                    signatureType: 0,
                    fields: [
                        {
                            type: '8',
                            x: '400.32',
                            y: '45.72',
                            height: '36.27',
                            width: '157.62',
                            page: 1
                        }
                    ]
                }
            ],
            _embedded: {
                file: {
                    _links: {
                        download: {
                            href: 'https://api.assine.online/file?q=e2dvb2RfbG9va317ImRhdGEiOnsidXVpZCI6ImIzOWRhYTBjLTU0ZTQtMTFlYS04MDAwLTAyNDJhYzE0MDAwNyJ9LCJobWFjIjoiMzZkNmE1NjdmMzI1MjQ4MmZlYjYxNDczMTJiZjBhOWFlZTUxMTFiOTUxZTRhOTRlYjE5YjBjMzQ1MmE0NzY1ZSIsIm5vbmNlIjoiNjEwMDE1ODI3MzQxODIifQ=='
                        }
                    }
                }
            }
        }
    ]
};

const response = await fetch('https://api.assine.online/v1/workflow', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload),
});

const data = await response.json();

PHP

$token = '41f7ff53c1dc5cf4f3db1f33e026b2908cdf88b4';

$client = new GuzzleHttp\Client();

$res = $client->request('POST', 'https://api.assine.online/v1/workflow', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token
    ],
    'json' => [
        "autoRemind" => 1,
        "dueDate" => "2021-02-26 00:00:00",
        "message" => "Por favor, assine os documentos: Meu documento",
        "priority" => 0,
        "sla" => 1,
        "files" => [
            [
                "idFolder" => null,
                "idFile" => 5577,
                "name" => "Meu documento",
                "specialFields" => [],
                "workflowSteps" => [
                    [
                        "user" => [
                            "name" => "Pedro Cavalcante",
                            "email" => "[e-mail]"
                        ],
                        "action" => 0,
                        "signatureType" => 0,
                        "fields" => [
                            [
                                "type" => "8",
                                "x" => "400.32",
                                "y" => "45.72",
                                "height" => "36.27",
                                "width" => "157.62",
                                "page" => 1
                            ]
                        ]
                    ]
                ],
                "_embedded" => [
                    "file" => [
                        "_links" => [
                            "download" => [
                                "href" => "https://api.assine.online/file?q=e2dvb2RfbG9va317ImRhdGEiOnsidXVpZCI6ImIzOWRhYTBjLTU0ZTQtMTFlYS04MDAwLTAyNDJhYzE0MDAwNyJ9LCJobWFjIjoiMzZkNmE1NjdmMzI1MjQ4MmZlYjYxNDczMTJiZjBhOWFlZTUxMTFiOTUxZTRhOTRlYjE5YjBjMzQ1MmE0NzY1ZSIsIm5vbmNlIjoiNjEwMDE1ODI3MzQxODIifQ=="
                            ]
                        ]
                    ]
                ]
            ]
        ]
    ]
]);

echo $res->getBody();

POST https://api.assine.online/v1/workflow

Resposta:

{
    "id": 1242,
    "autoRemind": 1,
    "dueDate": {
        "date": "2021-02-26 00:00:00.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "name": null,
    "message": "Por favor, assine os documentos: Meu documento",
    "priority": 0,
    "sla": 1,
    "status": 0,
    "_embedded": {
        "user": {
            "id": 474,
            "username": "[e-mail]",
            "password": "$2y$10$Vw9uEiHuza.CaPHvmqXmi..PXIKQe/uyuDCnqkJOYWNpagU3X6IWm",
            "status": "1",
            "name": "Jhon Doe",
            "email": "[e-mail]",
            "cellphone": "[phone]",
            "document": "12312312312",
            "country": "Brazil",
            "state": "GO",
            "city": "Goiânia",
            "address": "Av 136, Ed. New York Square 19/20",
            "zipCode": "74000000",
            "dateCreated": {
                "date": "2020-02-20 13:28:28.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "dateLastUpdated": {
                "date": "2020-02-20 13:29:10.000000",
                "timezone_type": 3,
                "timezone": "UTC"
            },
            "_embedded": {
                "businessUnit": {...}
            },
            "_links": {
                "self": {
                    "href": "https://api.assine.online/user/474"
                }
            }
        }
    },
    "_links": {
        "self": {
            "href": "https://api.assine.online/workflow/1242"
        }
    }
}

A partir daqui, basta seguir o fluxo normalmente como é feito no quickstart.