Assinando da caixa de entrada
Ao logar na sua conta via integração, é possível acessar os envelopes que foram enviados para você e assiná-los se desejar.
Listando a caixa de entrada
Para saber o que existe de envelope na sua caixa de entrada, use o seguinte endpoint estando logado:
{
"data": [
{
"id": "597f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "signer",
"state": "waiting",
"via": "email",
"value": "john.doe@example.com",
"name": "John Doe",
"routing_order": null,
"signature_type": "simple",
"notified_at": "2022-05-24T14:15:22Z",
"identifiers": [],
"fields": [],
"triggers": [],
"envelope": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"hashid": "KE78C",
"state": "in-transit",
"title": "Contrato de aluguel do John Doe",
"subject": "Contrato de aluguel",
"message": null,
"expire_at": null,
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"sender": {
"name": "João Pedro",
"email": "joao.pedro@example.com",
"avatar": "https://avatar-url.png"
},
"action_token": "aG1hYyBhb2xpdW9pZTthanhkZmdzZA=="
},
}
],
}
Para ter todos os detalhes dos parâmetros disponíveis e demais ações para a caixa de entrada, confira neste link a referência da API.
Perceba que para cada envelope recebido existe uma propriedade de action_token, usando este token para então realizar a ação no
envelope em questão, lembrando que você pode executar ações somente quando o seu estado está como waiting.
Assinando envelope
Sendo assim, executando a ação do envelope você estará assinando (para type: signer) ou aprovando (para type: approver). Para assinar usamos o endpoint:
{
"latitude": "38.871861",
"longitude": "-77.0584556",
"access_token": null,
"certificate_alias": null
}
Nenhum dos campos é obrigatório para realizar a assinatura, sendo que outro detalhe é que os campos de access_token e certificate_alias são para caso
deseje ou seja obrigatório a assinatura usando certificado do Bird ID.
A resposta devolverá o mesmo corpo de mensagem da listagem de inbox, porém com os dados atualizados, podendo assim fazer download do arquivo
assinado caso tenha sido o último a assinar e o envelope esteja com o estado de completed.
Preenchimento de campos
Há casos em que o remetente (a pessoa que lhe enviou o documento para assinar) tenha incluso alguns campos de formulário para que sejam preenchidos. Ao listar a sua caixa de entrada, caso tenha uma lista de fields onde o campo seja obrigatório, exemplo:
{
"data": [
{
"id": "597f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "signer",
"state": "waiting",
"via": "email",
"value": "john.doe@example.com",
"name": "John Doe",
"routing_order": null,
"signature_type": "simple",
"notified_at": "2022-05-24T14:15:22Z",
"identifiers": [],
"fields": [
{
"id": "697f6eca-6276-4993-bfeb-53cbbbba6f08",
"recipient": "597f6eca-6276-4993-bfeb-53cbbbba6f08",
"is_required": true,
"type": "text",
"name": "CPF",
"options": [],
"description": "Número do CPF",
"placeholder": "",
"title": "CPF",
"value": "",
"filled_at": null,
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"widgets": [
{
"page": 0,
"x_axis": 15,
"y_axis": 340,
"width": 200,
"height": 60,
"rotation": 0,
"background_color": "#FFFFFF",
"border_color": "#000000",
"border_width": 0,
"text_color": "#000000",
"opacity": 0,
"font_size": 12,
"font_family": "Courier"
}
]
}
],
"triggers": [],
"envelope": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"hashid": "KE78C",
"state": "in-transit",
"title": "Contrato de aluguel do John Doe",
"subject": "Contrato de aluguel",
"message": null,
"expire_at": null,
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"sender": {
"name": "João Pedro",
"email": "joao.pedro@example.com",
"avatar": "https://avatar-url.png"
},
"action_token": "aG1hYyBhb2xpdW9pZTthanhkZmdzZA=="
},
}
],
}
No caso acima, devemos preencher o campo 697f6eca-6276-4993-bfeb-53cbbbba6f08 que é do tipo text.
Pragmaticamente é dificil descobrir do que se trata o campo para que preencha o valor corretamente, para isso indicamos que assine documentos utilizando a interface
da aplicação para que os campos façam mais sentido. Mas caso queira preencher os campos por conta própria, nesse exemplo dissemos que o campo precisa de um CPF,
então podemos chamar o endpoint:
{
"value": "273.979.940-32"
}
Sendo que o token da url é o seu action_token gerado quando fez a listagem da sua caixa de entrada, e o field é o id do campo que queremos preencher, no caso o campo 697f6eca-6276-4993-bfeb-53cbbbba6f08. Após o preenchimento, teremos a resposta:
{
"id": "597f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "signer",
"state": "waiting",
"via": "email",
"value": "john.doe@example.com",
"name": "John Doe",
"routing_order": null,
"signature_type": "simple",
"notified_at": "2022-05-24T14:15:22Z",
"identifiers": [],
"fields": [
{
"id": "697f6eca-6276-4993-bfeb-53cbbbba6f08",
"recipient": "597f6eca-6276-4993-bfeb-53cbbbba6f08",
"is_required": true,
"type": "text",
"name": "CPF",
"options": [],
"description": "Número do CPF",
"placeholder": "",
"title": "CPF",
"value": "273.979.940-32",
"filled_at": "2022-05-24T14:20:22Z",
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"widgets": [
{
"page": 0,
"x_axis": 15,
"y_axis": 340,
"width": 200,
"height": 60,
"rotation": 0,
"background_color": "#FFFFFF",
"border_color": "#000000",
"border_width": 0,
"text_color": "#000000",
"opacity": 0,
"font_size": 12,
"font_family": "Courier"
}
]
}
],
"triggers": [],
"envelope": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"hashid": "KE78C",
"state": "in-transit",
"title": "Contrato de aluguel do John Doe",
"subject": "Contrato de aluguel",
"message": null,
"expire_at": null,
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"sender": {
"name": "João Pedro",
"email": "joao.pedro@example.com",
"avatar": "https://avatar-url.png"
},
"action_token": "aG1hYyBhb2xpdW9pZTthanhkZmdzZA=="
},
}
Depois que todos os campos obrigatórios são preenchidos, você pode então realizar a assinatura.
Assinando com Bird ID
Há casos onde você deseja ou o Bird ID é obrigatório para assinar o envelope. Quando é obrigatório, temos um envelope na caixa de entrada como o exemplo:
{
"data": [
{
"id": "597f6eca-6276-4993-bfeb-53cbbbba6f08",
"type": "signer",
"state": "waiting",
"via": "email",
"value": "john.doe@example.com",
"name": "John Doe",
"routing_order": null,
"signature_type": "qualified",
"notified_at": "2022-05-24T14:15:22Z",
"identifiers": [],
"fields": [],
"triggers": [],
"envelope": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"hashid": "KE78C",
"state": "in-transit",
"title": "Contrato de aluguel do John Doe",
"subject": "Contrato de aluguel",
"message": null,
"expire_at": null,
"created_at": "2022-05-24T14:15:22Z",
"updated_at": "2022-05-24T14:15:22Z",
"sender": {
"name": "João Pedro",
"email": "joao.pedro@example.com",
"avatar": "https://avatar-url.png"
},
"action_token": "aG1hYyBhb2xpdW9pZTthanhkZmdzZA=="
},
}
],
}
A propriedade de signature_type está definida como qualified o que exige um certificado Bird ID para realizar a assinatura, para isso devemos enviar o cpf e otp para o seguinte endpoint
para conseguir o access_token utilizado para assinar com o seu certificado Bird ID:
{
"cpf_cnpj": "273.979.940-32",
"otp": "829065"
}
Se estiver tudo correto, terá a resposta:
{
"access_token": "aG1hYyBpb3V5ZWh3a2p5cG9pdWV5aA==",
"expires_in": 7200,
"certificates": [
{
"alias": "JOHN DOE:27397994032",
"has_valid_date": true,
"was_revoked": false,
"has_trusted_chain": false,
"validity": {
"not_before": "2020-08-24T14:15:22Z",
"not_after": "2025-08-24T14:15:22Z"
}
}
]
}
Com isso você pode usar o access_token gerado dentro do tempo definido no expires_in em conjunto com o alias para realizar a assinatura do envelope.