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:

POST https://apisx.assine.online/v1/envelopes
{
  "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.

info

Para saber todos os estados que um envelope possui, confira no diagrama de máquina de estado clicando aqui.

info

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:

POST https://apisx.assine.online/v1/envelopes/{envelope}/recipients
{
  "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.

info

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:

email de pedido de assinatura

Com isso o assinante deve clicar em "Analisar documentos" e será levado a tela de assinatura:

tela de assinatura

Consultando o envelope

A qualquer momento você pode consultar o envelope enviado pelo endpoint:

GET https://apisx.assine.online/v1/envelopes/{envelope}?extended=true
{
  "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.

Início rápido

Criando um envelope​

Adicionando documento​

Adicionando um destinatário​

Enviando o envelope​

Consultando o envelope​

Criando um envelope

Adicionando documento

Adicionando um destinatário

Enviando o envelope

Consultando o envelope