Document signing integration with Dokobit 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 user;
5. Download the signed document;
6. Delete the document.

1.  Upload files for signing
First of all you need to make 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

Second step is to check if 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 few seconds. If you receive other status, it means that there is an error in integration. File upload status must be checked by making GET request to "/api/file/upload/FILE_TOKEN/status.json" with file token from 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 received response with {"status":"uploaded"}, you can call signing creation endpoint. Make POST request to "/api/signing/create.json" by specifying 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 in this response it 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 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 to include iframe in your system where user will sign your documents.  
5. Download signed document
After successful signing you have two ways to get signed file, via postback url (5.1) or via javascript callback (5.2).
5.1. When requesting "/api/signing/create.json" you can pass postback_url parameter and after each signature there will be a request made to that specified endpoint with signer information and signed document.
{
    "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 have Javascript events, add it's support following 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" and fetch signed document by using "file" parameter in 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.

Still need help? Contact us Contact us