Início rápido
Antes de iniciar este tutorial, garanta que já tenha a aplicação de integração criada.
Todo o fluxo de assinatura gira em torno de envelopes, o que significa que sempre que for iniciar um novo fluxo, é necessário que um envelope seja criado previamente.
Criando um envelope
Para que possamos realizar as assinaturas, é necessário a criação de um envelope para adicionar os documentos e as pessoas que vão assinar.
Criamos então o envelope com a seguinte requisição:
{
"title": "Contrato de aluguel apto. 243 de João Pedro",
"subject": "Aluguel do apto. 243",
"message": "Segue o contrato de aluguel do apto. 243. Favor realizar a assinatura até sexta-feira."
}
O title
é somente para seu próprio controle de saber do que se trata o envelope, onde subject
é o assunto do email que o destinatário receberá e message
a mensagem que estará contida no corpo do email.
A resposta lhe trará o id
do envelope criado, exemplo:
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"hashid": "JU4AC",
"state": "draft",
"subject": "Aluguel do apto. 243",
"message": "Segue o contrato de aluguel do apto. 243. Favor realizar a assinatura até sexta-feira.",
"action_reminder_frequency": null,
"effective_date_reminder_at": null,
"expire_at": null,
"updated_at": "2022-05-24T14:15:22Z",
"created_at": "2022-05-24T14:15:22Z",
}
Todo envelope recém criado entra no estado de draft
, rascunho, o que significa que pode ser manipulado e editado livremente antes que seja feito o envio.
Para saber todos os estados que um envelope possui, confira no diagrama de máquina de estado clicando aqui.
Consulte a referência da API para mais detalhes sobre os endpoints existentes e o que significa cada campo.
Adicionando documento
Com o envelope criado, faremos o upload do documento que desejamos que seja assinado. Para isso, deve ser feito o upload via form-data
para o endpoint POST https://apisx.assine.online/v1/envelopes/{envelope}/documents
. Exemplo:
- cURL
- Javascript
curl -X POST https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents
-d @contrato-aluguel.pdf
-H 'Authorization: Bearer <seu-access-token>'
-H 'Accept: application/json'
const input = document.querySelector('input[type="file"]');
const envelopeId = '497f6eca-6276-4993-bfeb-53cbbbba6f08';
const data = new FormData();
data.append('file', input.files[0]);
fetch(`https://apisx.assine.online/v1/envelopes/{$envelopeId}/documents`, {
method: 'POST',
body: data,
headers: {
'Authorization': "Bearer {$accessToken}",
'Accept': 'application/json'
}
});
console.log(response.json());
Com isso, o documento é adicionado e será retornado uma resposta similar a:
{
"id": "e89a828b-4f17-4019-9596-fb1973bd94fe",
"name": "contrato-aluguel.pdf",
"stage": "original",
"sha1": "cf23df2207d99a74fbe169e3eba035e633b65d94",
"fields": [],
"contents": [],
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"links": {
"download": "https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents/e89a828b-4f17-4019-9596-fb1973bd94fe/download",
"display": "https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents/e89a828b-4f17-4019-9596-fb1973bd94fe/display",
"preview": "https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents/e89a828b-4f17-4019-9596-fb1973bd94fe/preview",
"background_sheet": null
}
}
O stage
do documento indica qual estágio está atualmente o documento, sendo que quando assinado se tornará signed
.
Adicionando um destinatário
Não é necessário adicionar um destinatário após a adição do documento, você pode escolher a ordem que achar melhor, ou até mesmo fazer em simultâneo. Para adicionarmos um destinatário chamamos:
{
"type": "signer",
"signature_type": "simple",
"addressees": [
{
"via": "email",
"value": "joao.pedro@example.com",
"name": "João Pedro"
}
]
}
Aqui temos o type
como signer
para assinantes, e um array de addressees para quem é a pessoa endereçada, da qual informamos a via
que será notificado tendo o value
equivalente a esta via.
A resposta será similar à:
{
"id": "95aced30-605c-45e4-bac4-fa297c075863",
"state": "queued",
"type": "signer",
"routing_order": null,
"signature_type": "simple",
"notified_at": null,
"addressees": [
{
"via": "email",
"value": "joao.pedro@example.com",
"name": "João Pedro",
"ran_action_at": null,
"identifiers": [],
"triggers": []
}
]
}
Como o envelope ainda não foi enviado, todo novo destinatário entra com o estado de queued
, enfileirado.
Para saber todos os estados que um destinatário possui, confira no diagrama de máquina de estado clicando aqui.
Enviando o envelope
Com tudo pronto, podemos então enviar o envelope fazendo uma requisição em POST https://apisx.assine.online/v1/envelopes/{envelope}/send
. Exemplo:
- cURL
- Javascript
curl -X POST https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/send
-H 'Authorization: Bearer <seu-access-token>'
-H 'Accept: application/json'
const envelopeId = '497f6eca-6276-4993-bfeb-53cbbbba6f08';
fetch(`https://apisx.assine.online/v1/envelopes/{$envelopeId}/send`, {
method: 'POST',
headers: {
'Authorization': "Bearer {$accessToken}",
'Accept': 'application/json'
}
});
console.log(response.json());
Se estiver tudo correto, teremos uma resposta com status 202 Accepted
similar à:
{
"action_token": null
}
O campo de action_token
só devolverá algum valor quando você envia um documento para si mesmo assinar, pois este é o token necessário para autenticar quando é realizado a assinatura.
Com isso, chegará um email para o destinatário similar ao exemplo:
Com isso o assinante deve clicar em "Analisar documentos" e será levado a tela de assinatura:
Consultando o envelope
A qualquer momento você pode consultar o envelope enviado pelo endpoint:
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"hashid": "JU4AC",
"state": "completed",
"title": "Contrato de aluguel apto. 243 de João Pedro",
"subject": "Aluguel do apto. 243",
"message": "Segue o contrato de aluguel do apto. 243. Favor realizar a assinatura até sexta-feira."
"expire_at": null,
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2012-05-24T14:15:22Z"
"sender": {
"name": "John Doe",
"email": "john.doe@example.com",
"avatar": "http://avatar-url"
},
"recipients": [
{
"id": "95aced30-605c-45e4-bac4-fa297c075863",
"state": "done",
"type": "signer",
"routing_order": null,
"signature_type": "simple",
"notified_at": null,
"addressees": [
{
"via": "email",
"value": "joao.pedro@example.com",
"name": "João Pedro",
"ran_action_at": "2022-05-24T14:20:22Z",
"identifiers": [],
"triggers": []
}
]
}
],
"documents": [
{
"id": "e89a828b-4f17-4019-9596-fb1973bd94fe",
"name": "contrato-aluguel.pdf",
"stage": "signed",
"sha1": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3",
"fields": [],
"contents": [],
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"links": {
"download": "https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents/e89a828b-4f17-4019-9596-fb1973bd94fe/download",
"display": "https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents/e89a828b-4f17-4019-9596-fb1973bd94fe/display",
"preview": "https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents/e89a828b-4f17-4019-9596-fb1973bd94fe/preview",
"background_sheet": "https://apisx.assine.online/v1/envelopes/497f6eca-6276-4993-bfeb-53cbbbba6f08/documents/e89a828b-4f17-4019-9596-fb1973bd94fe/background-sheet"
}
}
]
}
Com a query de ?extended=true
, os relacionamentos são adicionados aos dados do envelope. Podemos ver então que o estado do envelope se torna completed
depois que todos os estados dos destinatários se tornam done
.
Perceba que já é disponibilizado o link para realizar o download do documento assinado, basta chamar o endpoint usando método HTTP GET
e salvar localmente onde desejar.
Isso conclui uma assinatura simples com um assinante.