Documents Gateway - Innleiðing á undirskriftarþjónustu
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
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 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 receive 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 a request to that specified endpoint with signer information and signed document will be made.
{ "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 its 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 a 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.