1. Introduction
Veri5’ eSign Platform offers APIs that can be used to esign documents using Aadhaar based esign platform.
2. Prerequisite
For a client to get access to APIs, client registration is mandatory. Veri5Digital provides two environments :
- Sandbox Environment
It’s recommended to have the client first do technical integration of the API in the Sandbox environment, followed by testing and certification.
- Production Environment
Post certification in Sandbox Environment, for actual production purposes, clients should move to Production Environment.
The client has to obtain the following values for the following params :
Client Code (client_code), that uniquely identifies the client that is onboarded with the Veri5. Salt (salt), that uniquely identifies the client that is onboarded with the Veri5 and will be used to generate hash for validation.
For invoking APIs, client_code has to be mandatorily passed.
3. API Specification
eSign’s APIs can be consumed at exposed REST Endpoints. Request and Response Payloads are JSON documents or GET requests. API communications should be made over HTTPS.
APIs are exposed to consumers in different environments like SandBox and Production. The primary purpose of the sandbox environment is to expose the APIs to consumers where they can test and do technical integrations before moving to actual production.
| API | Domain | Purpose |
|---|---|---|
| uploadDocument | Veri5 | Upload document for eSign. |
| _initiateEsign | Veri5 | Initiate the eSign process. |
| clientResponseUrl | Client | Client needs to provide. After successfully e-signing the user will be redirected to this url. |
| _downloadDocument | Veri5 | The signed document can be downloaded using this API |
4.1 API : uploadDocument [ POST ]
InputType : Multipart Form Request
Method : POST
URL : https://
_upload Request Details
- Request Header
| Type | Size | Value | Requirement | Requirement |
|---|---|---|---|---|
| ENC | String | 1 | Y/N | Mandatory when data is encrypted |
- Request Body
Refer below table for the request body parameters. Client application should POST these parameters as a FORM Submit Action.
Table : _upload API Request Body Parameters
| Fields | Type | Size | Value | Requirement |
|---|---|---|---|---|
| client_code | AlphaNumeric | 10 | Will be provided on onboarding | Mandatory |
| client_request_id | Alphanumeric | 45 | A unique request Id for each case | Mandatory |
| doc_no | Numeric | 1 | The document index No incase of multiple docs | Optional |
| doc_type | String | Mandatory | ||
| reason | String | 64 | Minimum size should be 10 | Mandatory |
| igner_name | String | 32 | Optional | |
| filename | AlphaNumeric | 32 | Mandatory | |
| rectangle | String | NA | Mandatory | |
| page_no | AlphaNumeric | NA | Single Page: Page no, Multiple Pages: Page nos, separated by <,>, All pages: ’all’ | Mandatory |
| hash | Alphanumeric | NA | Digestmethod:-SHA256, Value: SHA256(salt | client_request_id |
| file | File | NA | Pdf file. Should not have embedded JS. | Mandatory |
4.1.1 Sample Request Payload
Below given code snippet demonstrates how to invoke the Veri5 Digital eSign SDK from a form in clients application.
<form action="https://preprod.aadhaarbridge.com/api/_upload" method="post"
enctype="multipart/form-data">
<input type="text" name="client_code" value="<<your sa code>>">
<input type="text" name="<<client_request_id>>" >
<input type="text" name="<<doc_no>>" >
<input type="text" name="<<doc_type>>" >
<input type="text" name="<<reason>>">
<input type="text" name="<<signer_name>>" >
<input type="text" name="<<signer_location>>" >
<input type="text" name="<<filename>>" >
<input type="text" name="<<rectangle>>" >
<input type="text" name="<<page_no>>" >
<input type="text" name="<<hash>>" >
<input type="file" name="<<file>>" >
<button type="submit">Submit</button>
</form>
Rectangle Field Details
This defines the coordinates of the rectangular box where eSign will appear in the document.
Rectangle(50, 400, 200, 500) <==> (x1, y1, x2, y2)
Points to Note
Action URL should be changed based on the environment whether its Pre Production or Production.
Please ensure correct saCode to be passed.
Ensure that no Spaces before or after the parameter values.
Https protocol is recommended.
4.1.2 _upload Response Details
Response structure is as given below, where fields
success : Indicates the status of the API execution. Possible values are true or false.
errorCode : Contains the error code whose details are given in below table.
message : Message corresponding to the error code.
Note : Error Code is Empty String in case of success is true.
{
"code":"<< 000 | 001 >>",
"message":"",
“responseData”:"only on success"
}
4.1.3 Response Codes And Messages
| Status | Code | message |
|---|---|---|
| SUCCESS | 000 | Uploaded Document |
| FAIL | 001 | Reason for failure |
4.2 API : _initiateEsign
Once the document is successfully uploaded, this API will be used to initiate the eSign process. On success, the user will be redirected to the consent page.
Method : POST
URl : https://hostname/esign/_initiateEsign?id=$id&h=$hash
type: document/Redirect
- _init Request Details
| Fields | Type | Size | Value | Requirement |
|---|---|---|---|---|
| id | AlphaNumeric | NA | responseData received in success response of ‘uploadDocument’ api call | Mandatory |
| hash | Alphanumeric | NA | Digestmethod: SHA256, Value:SHA256(hash_sequence) | Mandatory |
Note: alt will be shared when the client is on boarded.
hash_sequence = id|salt
4.2.1 Response Details
Success:-Redirected to Consent Page.
Failure:- Redirected to error page.
4.3 API : Client Response URL(Client Redirection Portal)
As per the flow after aadhaar verification from ESP page the user will be redirected to client response url.
Type : document/Redirect
URL : https://<clientResponseUrl>/<path>?esign_status=/<success/fail>&id=<id>&h=<hash>
| Params | Type | size | value | Requirement |
|---|---|---|---|---|
| id | AlphaNumeric | NA | This id will be used to request _downloadDocument for downloading the document | Mandatory |
| hash | Alphanumeric | NA | This can used by the client to verify the redirection Digestmethod:-SHA256, Value:SHA256(hash_sequence) | Mandatory |
| esign_status | String | NA | success/fail | Mandatory |
hash_sequence = <id>|<salt>
4.4 API : _downloadDocument[ POST ]
This API is used to download the signed document.
Url : https://<hostname>/esign/_downloadDocument
InputType : JSON
| Params | Type | size | value | Requirement |
|---|---|---|---|---|
| id | AlphaNumeric | NA | The id received in client response url | Mandatory |
| hash | Alphanumeric | NA | This can used by the client to verify the redirection Digestmethod:-SHA256, Value:SHA256(hash_sequence) | Mandatory |
hash_sequence = <id>|<salt>
Request Payload
{
"id":"`<id>`",
"hash":"`<hash value>`"
}
Request Payload
{
"code":"<< 000 | 001 >>",
"message":"",
"responseData": //Only on success response
{
"fileContent":<Base64 encoded String of signed file>,
"fileName":<Original File Name>,
"nameAsPerAadhaar":<>
}
}
Response Codes And Messages
| Status | Code | message |
|---|---|---|
| SUCCESS | 000 | Download Success |
| FAIL | 001 | Reason for failure |
Appendix A: Hash generation
It is essential that we have a definitive protocol to verify the integrity of all the communication between Khosla Labs Platform and Client. So for every request coming to KL, client has to supply a hash which KL will use as the first step of verification.
- Hash should be calculated using the following method: hash=SHA256(Hash-Sequence)
Hash Sequence is specified as follows(no space, no commas, no single/double quotes). Hash sequence is defined for each request and response.
- Document Upload API( uploadDocument) :
salt|client_request_id|filename|page_no|doc_type - Init SDK Request:
id|salt - Client Response URL(Client Redirection Portal):
id|salt - _downloadDocument API
id|salt
For validation:
- Receiving end should calculate hash based on request parameters and match it against the received hash.
- If receivedHash=calculatedHash, then only you should proceed with your application logic.
Sample Code Snippet uploadDocument Request Hash Calculation
Function to calculate Hash based on the input hash sequence parameters.Below given function depicts hash calculation for _upload ( Document Upload ) Api.
private String calculateHash(String salt, String clientRequestId, String filename, String pageNo, String docType) throws NoSuchAlgorithmException {
MessageDigest digest;
digest = MessageDigest.getInstance("SHA-256");
if (digest != null) {
byte[] hash = digest.digest((salt + "|" + client_request_id + "|" + filename + "|" + page_no + "|" + doc_type).getBytes());
return bytesToHex(hash);
}
return null;
}
private final static char[] hexArray = "0123456789ABCDEF".toCharArray();
public static String bytesToHex(byte[] bytes) {
char[] hexChars = new char[bytes.length * 2];
for (int j = 0; j < bytes.length; j++) {
int v = bytes[j] & 0xFF;
hexChars[j * 2] = hexArray[v >>> 4];
hexChars[j * 2 + 1] = hexArray[v & 0x0F];
}
return new String(hexChars);
}