ULIP Integration Requirement Document

ULIP Integration Requirement Document

Version No.: 2.0

Date: 01/10/2024

Project Name: ULIP

This document contains proprietary information of NLDSL. Unauthorized access, copying and replication are
prohibited. This document must not be copied in whole or part by any means, without the written authorization of
NLDSL, New Delhi, India.
 ULIP Integration Requirement Document

Revision History

Version Date Author Reviewer Significant Changes

1.0 20/06/2023 Ayush Arya Nayab Ali Baseline Version

2.0 01/10/2024 Ayush Arya Nayab Ali Updated

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 2 of 10
 ULIP Integration Requirement Document

Table of Contents

Introduction ................................................................................................................................................. 4
1.1 Purpose .................................................................................................................................... 4
The Overall Description .............................................................................................................................. 4
1.2 Data Integration between EWAYBILL System and ULIP application ...................................... 4
1.3 EWAYBILL/01 .......................................................................................................................... 4
1.3.1 Technical Approach .................................................................................................... 5
1.4 Data Transmission & Authentication Mechanism .................................................................... 7

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 3 of 10
 ULIP Integration Requirement Document

Introduction

1.1 Purpose

The purpose of this document is to define and provide details for accessing API for EWAY
BILL system information (information about ewbNo available in EWAY Bill system) from
ULIP system.
This document details the following points:

1. Data Integration between EWAYBILL and ULIP web service: Identification of

operational points where data integration between EWAYBILL and ULIP web service will
be needed.

2. Technical Approach for performing Data Integration

The Overall Description

User will share the information such as EWB number based on data send by user ULIP
system will call respective EWAYBILL API for accessing information.

Following are the point for accessing vehicle information: -

1. This API will share data based on information provided by user.

2. ULIP will expose API for getting data from EWAYBILL API.

3. EWAYBILL/01 API will take EWB number from user and get data from EWAYBILL API.

1.2 Data Integration between EWAYBILL System and ULIP application

User will share information to ULIP system based on data shared ULIP will provide data
to user.

1.3 EWAYBILL/01

This API will take EWB (e-way bill) number and connect with EWAYBILL API to get
data.

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 4 of 10
 ULIP Integration Requirement Document

1 ewbNo Enter the EWB number as [0-9]{12} Required 12

available in EWAYBILL
system.
1.3.1 Technical Approach
1. All the data will be shared through rest web services.
2. ULIP system will provide EWB number for which detail is required.
3. EWAYBILL API will share details of e-way bill information which exist in EWAYBILL
system in JSON format.
4. EWAYBILL Integration will add JSON in response key in response body.
5. ULIP system will provide the data in JSON Object format in response body.

Example:

EWB number 101000609218 is shared by ULIP system, then EWAYBILL-integration will

make a request to EWAYBILL API.

Request:

The request must be of the following format, where e-way bill (EWB) number is passed within
the URL body in JSON format.

For staging -
https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01

{
"ewbNo": "101000609218"
}

Curl URL

curl --location --
request POST 'https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01' \
--
header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNjg3MjM
4MjU3LCJhcHBzIjoiZGF0YXB1c2gifQ.auwp_xfX_FBUJLB-7iNOyr5Wa1H2PeboAok-0uAADvNVADPK1C-
MEW9ne5FKttsuDjoOTdkbs_RC9xtMLrCF6g' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"ewbNo": "101000609218"
}'

For production -
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 5 of 10
 ULIP Integration Requirement Document

{
"ewbNo": "101000609218"
}

Curl URL
curl --location 'https://www.ulip.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01' \
--header 'Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNzI3NzYyNzcxLCJhcHBzIjoiZGF0YXB1c2gif
Q.9_kJwxuXfJYoMt0QeMgOSWi01EaxXQkZQ1JLevfNo-vJ5vjCY9oIemZ_B4hiiq2ZCog-yAbIUgL6YN-
TVie3cA' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"ewbNo": "871347047092"
}'

For obtaining authentication token, refer Section 1.4

Response

To acknowledge the above request, ULIP will send the below response -

1. Invalid ewbNo number

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered at: ewbNo. Format should fo
llow [0-9]{12}"
}

2. In case nhno number exist

{
"response": [
{
"response": {
"fromPincode": 301404,
"hsnCode": "",
"ewayBillDate": "29/11/2017 04:30:00 PM",
"validUpto": " 11:59:00 PM",
"ewbNo": 101000609218,
"toPincode": 302014,

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 6 of 10
 ULIP Integration Requirement Document

"VehiclListDetails": [
{
"vehicleNo": "RJ14CG4508",
"enteredDate": "29/11/2017 04:30:00 PM",
"transMode": "1"
}
],
"status": "ACT"
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

3. In case nhno number not exist

{
"response": [
{
"response": {
"errorCodes": "404"
},
"responseStatus": "ERROR"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: EWAYBILL data response

Status Code 400: Bad request (Invalid json syntax, invalid json key)
Status Code 401 or 403: Unauthenticated or Unauthorized
Status Code 500: Some internal server error occurred
Status Code 502: Server is not responding.

1.4 Data Transmission & Authentication Mechanism

All data exchange would be done over secure HTTP (HTTPS). Request from ULIP's system would
be made in EWAYBILL system through a data exchange URL that has following form:

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 7 of 10
 ULIP Integration Requirement Document

For staging -
https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01

{
"ewbNo": "101000609218"
}

Access to above data exchange URL would be authorized by use of a security mechanism
implemented by the ULIP system. It is as follows:

 First time access: It would require a username and password [which would be shared with
user beforehand]. Once user hit with valid user id and password, ULIP system will return a
basic authorization token to user, using that token user will communicate with ULIP system
until token will not get expired.

Brief summary of HTTP Basic Authentication is as follows:

First time when User will hit ULIP secured API through username and password for access token
as follow-

curl --location --request POST

'https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/user/login ' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "xxxx",
"password": "xxxx@123"
}'

Authorization:
Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNjg3MjM4MjU3LCJhcHBzIjoiZGF0YXB1
c2gifQ.auwp_xfX_FBUJLB-7iNOyr5Wa1H2PeboAok-0uAADvNVADPK1C-
MEW9ne5FKttsuDjoOTdkbs_RC9xtMLrCF6g'

Upon successful authentication, the user would be logged into the ULIP system and get an access
token. Though this token user can communicate with ULIP. This token has expiry time which
represent user session. The session time out for the same to be fixed hour, generally it is for 30
minutes. If there is no request coming from user for 30 minutes, then session (token) will be
expired and user need to re authenticate.

Using The above token, user can request ULIP system for cargo details as follow -
curl --location --
request POST 'https://www.ulipstaging.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01' \
Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 8 of 10
 ULIP Integration Requirement Document

--
header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNjg3Mj
M4MjU3LCJhcHBzIjoiZGF0YXB1c2gifQ.auwp_xfX_FBUJLB-7iNOyr5Wa1H2PeboAok-
0uAADvNVADPK1C-MEW9ne5FKttsuDjoOTdkbs_RC9xtMLrCF6g' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"ewbNo": "101000609218"
}'

For production –

curl --location 'https://www.ulip.dpiit.gov.in/ulip/v1.0.0/user/login' \

--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "xxxx",
"password": "xxxx@123"
}'

Authorization:
Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNzI3MTYxMDgwLCJhcHBzIjoiZGF0
YXB1c2gifQ.XhVZm7NiCD05-
v9091WJQhYzdk1a0Shs_ley0T4R2MX63swRyxHbHxh6bVXtzqWvWiSLwwNGRQIcqGhr49hpGg

Upon successful authentication, the user would be logged into the ULIP system and get an access
token. Though this token user can communicate with ULIP. This token has expiry time which
represent user session. The session time out for the same to be fixed hour, generally it is for 30
minutes. If there is no request coming from user for 30 minutes, then session (token) will be
expired and user need to re authenticate.

Using The above token, user can request ULIP system for details as follow -

https://www.ulip.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01

curl --location 'https://www.ulip.dpiit.gov.in/ulip/v1.0.0/EWAYBILL/01' \

--header 'Authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1bGlwIiwiaWF0IjoxNzI3NzYyNzcxLCJhcHBzIjoiZGF0
YXB1c2gifQ.9_kJwxuXfJYoMt0QeMgOSWi01EaxXQkZQ1JLevfNo-
vJ5vjCY9oIemZ_B4hiiq2ZCog-yAbIUgL6YN-TVie3cA' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"ewbNo": "871347047092"

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 9 of 10
 ULIP Integration Requirement Document

}'

Doc Ref. No: ULIP Integration Doc Version No: 2.0 Page 10 of 10