Document signing integration with Documents Gateway
You need to make the following steps to implement document signing:
1. Upload files for signing;
2. Check if files are already uploaded;
3. Create signing page by passing document list and signers information;
4. Render signing page for the user;
5. Download the signed document;
6. Delete the document.
You can check more documentation at
https://gateway-sandbox.dokobit.com/api/doc.
1.
Upload files for signing
First of all, you need to make a POST request to "/api/file/upload.json" with three required params - file name, file digest and file URL.
REQUEST
URL: "https://gateway-sandbox.dokobit.com/api/file/upload.json?access_token=YOUR_ACCESS_TOKEN
METHOD: POST
BODY:
{
"file": {
"name": "agreement.pdf",
"digest": "a50edb61f4bbdce166b752dbd3d3c434fb2de1ab", (SHA256 HEX encoded value of file content)
"url": "https://gateway-sandbox.dokobit.com/Resources/test.pdf"
}
}
RESPONSE
{
"status": "ok",
"token": "FILE_TOKEN"
}
2. Check if files are already uploaded
The second step is to check if the file is already uploaded. Before any further step, you need to receive response with status "uploaded" from file upload status endpoint. If you receive status "pending", then you need to repeat status request after a few seconds. If you receive other status, it means that there is an integration error. File upload status must be checked by making a GET request to "/api/file/upload/FILE_TOKEN/status.json" with the file token from the previous response.
REQUEST
URL: https://gateway-sandbox.dokobit.com/api/file/upload/FILE_TOKEN/status.json?access_token=YOUR_ACCESS_TOKEN
METHOD: GET
RESPONSE
{
"status": "uploaded"
}
or
{
"status": "pending"
}
3. Create signing page by passing document list and signers information
Once you receive response with {"status":"uploaded"}, you can call signing creation endpoint. Make a POST request to "/api/signing/create.json" by specifying the signers' information and files for signing.
REQUEST
URL: https://gateway-sandbox.dokobit.com/api/signing/create.json?access_token=YOUR_ACCESS_TOKEN
METHOD: POST
BODY:
{
"type": "pdf",
"name": "agreement",
"signers": {
"0": {
"id": "YOUR_PROVIDED_FIRST_SIGNER_ID",
"name": "Name 1",
"surname": "Surname 1",
"signing_purpose": "signature"
},
"1": {
"id": "YOUR_PROVIDED_SECOND_SIGNER_ID",
"name": "Name 2",
"surname": "Surname 2",
"signing_purpose": "signature"
}
},
"files": {
"0": {
"token": "FILE_TOKEN"
}
}
}
RESPONSE
{
"status": "ok",
"token": "SIGNING_TOKEN",
"signers": {
"YOUR_PROVIDED_FIRST_SIGNER_ID": "FIRST_SIGNER_TOKEN",
"YOUR_PROVIDED_SECOND_SIGNER_ID": "SECOND_SIGNER_TOKEN"
}
}
As you can see, this response contains SIGNING_TOKEN and different signer tokens (FIRST_SIGNER_TOKEN and SECOND_SIGNER_TOKEN) for each signer, so it means that each signer will get a unique URL for signing.
4. Render signing page for user
Now you can create signing URLs for each signer:
https://gateway-sandbox.dokobit.com/signing/SIGNING_TOKEN?access_token=FIRST_SIGNER_TOKEN https://gateway-sandbox.dokobit.com/signing/SIGNING_TOKEN?access_token=SECOND_SIGNER_TOKEN
Once you have these URLs, we suggest including iframe in your system where the user will sign your documents.
5. Download signed document
After successful signing, you have two ways to get a signed file, via postback URL (5.1) or javascript callback (5.2).
5.1. When requesting "/api/signing/create.json", you can pass the postback_url parameter, and after each signature, a POST request to the specified endpoint with signer information and signing status will be made. When the "signing_completed" action is sent, the request will include the "file" parameter with the URL to fetch the signed document. More information about webhooks can be found here:
Dokobit Webhooks
{
"status": "ok",
"token": "SIGNING_TOKEN",
"action": "signing_completed|signer_signed|signing_archived",
"file": "https://gateway-sandbox.dokobit.com/api/signing/SIGNING_TOKEN/download", // append ?access_token=YOUR_ACCESS_TOKEN when downloading file
"signer": "60001019906"
"signer_info": [
"code": "60001019906",
"phone": "+37000000766",
"country_code": "lt",
"signing_option": "mobile",
"type": "qes|aes|es"
]
}
5.2. If you want to support Javascript events, follow the instructions here
https://gateway-sandbox.dokobit.com/api/iframe-integration. You can specify following javascript methods for handling successful and failed signing cases:
Isign.onSignSuccess = function(){
alert('Document was successfully signed');
};
Isign.onSignError = function(){
alert('Unable to sign document');
};
After receiving "onSignSuccess" callback, you can request signing status from your backend by making GET request to "/api/signing/SIGNING_TOKEN/status.json". You need to receive a response with the status "completed". If you receive status "pending", then you need to repeat the status request after a few seconds. Afterwards, fetch signed document by using "file" parameter in the following response:
REQUEST
URL: https://gateway-sandbox.dokobit.com/api/signing/SIGNING_TOKEN/status.json?access_token=YOUR_ACCESS_TOKEN
METHOD: GET
RESPONSE
{
"status": "completed",
"signers": {
"FIRST_SIGNER_TOKEN": {
"status": "signed",
"signing_time": "2019-06-04 11:59:14",
"signature_id": "Signature1"
},
"SECOND_SIGNER_TOKEN": {
"status": "pending"
}
}
"file": "https://gateway-sandbox.dokobit.com/api/signing/SIGNING_TOKEN/download", // append ?access_token=YOUR_ACCESS_TOKEN when downloading file
}
6. Once you download the document, we recommend deleting it by using this API method - https://gateway-sandbox.dokobit.com/api/doc#_api_signing_delete.