ULIP Integration Requirement Document

ULIP Integration Requirement Document

Version No.: 1.0

Date: 08/11/2021

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, Noida, India.
 ULIP Integration Requirement Document

Revision History

Version Date Author Reviewer Significant Changes

1.0 08/11/2021 Girish Chander Baseline Version

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 2 of 20
 ULIP Integration Requirement Document

Table of Contents

Introduction ................................................................................................................................................. 4
1.1 Purpose .................................................................................................................................... 4
The Overall Description .............................................................................................................................. 4
1.2 Data Integration between MBPT System and ULIP application .............................................. 5
1.3 NMPT/01 .................................................................................................................................. 5
1.3.1 Technical Approach ..................................................................................................... 5
1.4 NMPT/02 .................................................................................................................................. 8
1.4.1 Technical Approach ..................................................................................................... 8
1.5 NMPT/03 ................................................................................................................................ 11
1.5.1 Technical Approach ................................................................................................... 11
1.6 NMPT/04 ................................................................................................................................ 13
1.6.1 Technical Approach ................................................................................................... 14
1.7 NMPT/05 ................................................................................................................................ 17
1.7.1 Technical Approach ................................................................................................... 17
1.8 Data Transmission & Authentication Mechanism .................................................................. 19

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 3 of 20
 ULIP Integration Requirement Document

Introduction

1.1 Purpose

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

1. Data Integration between NMPT and ULIP web service: Identification of operational
points where data integration between NMPT and ULIP web service will be needed.

2. Technical Approach for performing Data Integration

The Overall Description

User will share the information such as VCN number, BE Number, and Shipping Bill
Number based on data send by user ULIP system will call respective NMPT API for
accessing information.

Following are the point for accessing information:

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

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

3. NMPT/01 API will take VCN number from user and get data from NMPT API.

4. NMPT/02 API will take BE number from user and get data from NMPT API.

5. NMPT/03 API will take VCN Number from user and get data from NMPT API for
different Terminal.

6. NMPT/04 API will take BE number from user and get data from NMPT API for different
Terminal.

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 4 of 20
 ULIP Integration Requirement Document

7. NMPT/05 API will take Shipping Bill Number from user and get data from NMPT API for
different Terminal.

1.2 Data Integration between NMPT System and ULIP application

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

1.3 NMPT/01

This API will take VCN number and connect with NMPT API to get data.

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d
1 vcn_no vessel call number as ^[a-zA-Z0- Required Min 2
available in NMPT 9]{2,14}$ Max 14
system.
1.3.1 Technical Approach
1. All the data will be shared through rest web services.
2. ULIP system will provide VCN number for which detail is required.
3. NMPT API will share details of vessel information which exist in NMPT system in JSON
format.
4. NMPT 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:

VCN number HAL12100007

is shared by ULIP system, then NMPT-integration will make a request to NMPT API.

Request:

The request must be of the following format, where driving license number and date of birth is
passed within the URL body in JSON format.

https://www.ldbstaging.co.in/ulip/v1.0.0/NMPT/01

{"vcn_no": "HAL12100007"}

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 5 of 20
 ULIP Integration Requirement Document

Curl URL

curl --location --
request POST 'http://localhost:8085/ulip/v1.0.0/NMPT/01' \
--header 'Content-Type: application/json' \
--
header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZX
N0MSIsImlhdCI6MTYzNjM0ODg0MCwiYXBwcyI6ImRhdGFwdXNoIn0.E78_Oa5DYP7
m4Jpq2Q9kXK8gQDiScqndwwNkIicBOzQmXudwXRJbNwjRVSJKkI1cYaEZK45oS4_1
sMS1Q_ggRA' \
--data-raw '{
"vcn_no":"HAL12100007"
}'

For obtaining authentication token, refer Section 1.8

Response

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

a) In case of invalid format

1. Invalid vcn number

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered a
t: vcn_no. Format should follow ^[a-zA-Z0-9]{2,14}$"
}

b) In case of vcn number does not exist in NMPT system

{
"response": [
{
"response":{

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 6 of 20
 ULIP Integration Requirement Document

"status":"1",
"Error":256,
"message":"Invalid VCN Number"
}
,
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success" }

c) In case VCN number exist

{
"response": [
{
"response": {
"imo_number": "9414319",
"vcn_no": "HAL12100007",
"vessel_name": "NOEL",
"shipping_line_code": "OCL1",
"shipping_agent_code": "",
"application_type": "I",
"eta": "05042021 13:40",
"etd": "08042021 19:25",
"ata": "07042021 16:20",
"atd": "09042021 23:10",
"port_of_arrival_name": "INCCU1",
"last_port_of_call_name": "MYPKG",
"vessel_type": "C"
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: vessel 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.

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 7 of 20
 ULIP Integration Requirement Document

1.4 NMPT/02

This API will take import gate details and connect with NMPT API to get data.

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d
1 be_no BE Number as available [0-9]{1,7} Required Min=1,
in NMPT system. Max=7

1.4.1 Technical Approach

6. All the data will be shared through rest web services.
7. ULIP system will provide BE Number for which detail is required.
8. NMPT API will share details of cargo information which exist in NMPT system in JSON
format.
9. NMPT Integration will add JSON in response key in response body.
10. ULIP system will provide the data in JSON Object format in response body.

Example:

BE number is shared by ULIP system, then NMPT- integration will make a request to
NMPT API.

Request:

The request must be of the following format, where driving license number and date of birth is
passed within the URL body in JSON format.

https://www.ldbstaging.co.in/ulip/v1.0.0/NMPT/02

{"be_no" : "3437935”}

Curl URL

curl --location --request POST 'http://localhost:8085/ulip/v1.0.0/NMPT/02' \

--header 'Content-Type: application/json' \
--
header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdC
I6MTYzNjM0ODg0MCwiYXBwcyI6ImRhdGFwdXNoIn0.E78_Oa5DYP7m4Jpq2Q9kXK8gQDiScqndwwN
kIicBOzQmXudwXRJbNwjRVSJKkI1cYaEZK45oS4_1sMS1Q_ggRA' \

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 8 of 20
 ULIP Integration Requirement Document

--data-raw '{
"be_no":"3437935"
}'
'

For obtaining authentication token, refer Section 1.8

Response

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

d) In case of invalid format

1. Invalid BE number

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered
at: beNO. Format should follow [0-9]{1,7}"
}

e) In case of BE number does not exist in NMPT system

{
"response": [
{
"response": {
"status":"1",
"message":"No records found "
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

f) In case BE number exist

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 9 of 20
 ULIP Integration Requirement Document

"response": [
{
"response": {
"igm_no": "2279238",
"igm_date": "05042021",
"line_no": "75",
"sub_line_no": "1",
"bl_no": "SHACB21007945",
"be_no": "3437935",
"be_date": "05042021",
"importer_name": "GLOBAL ISPAAT PRIVATE LIMITED",
"importer_address": "M-
18/19,CUNCOLIM INDUSTRIAL ESTATE,CUNCOLIM,SALCETTE",
"cha_code": "AGWPP3748ACH001",
"nature_of_cargo": "C",
"cargo_type": "",
"goods_description": "USED INDUSTRIAL SEWING MACHINE HS:84522
900",
"marks_no": "N/M",
"no_of_packages_qty": "723",
"type_of_packages": "PCS",
"unit_of_measurement": "KGS",
"country_of_origin": "SN",
"out_of_charge_no": "2041189007",
"out_of_charge_date": "05042021",
"delivery_order_no": "3242",
"do_date": "05042021",
"mode_of_transport": "R",
"survey_date": "",
"surveyor_code": "",
"vehicle_info": null
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: BE Number 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.

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 10 of 20
 ULIP Integration Requirement Document

1.5 NMPT/03

This API will take VCN Number and connect with NMPT API to get data.

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d
1 vcn_no vessel call number as ^[a-zA-Z0- Required Min 2
available in NMPT 9]{2,14}$ Max 14
system.
1.5.1 Technical Approach
11. All the data will be shared through rest web services.
12. ULIP system will provide VCN Number for which detail is required.
13. NMPT API will share details of cargo information which exist in NMPT system in JSON
format.
14. NMPT Integration will add JSON in response key in response body.
15. ULIP system will provide the data in JSON Object format in response body.

Example:

VCN number INNML121070010

is shared by ULIP system, then NMPT-integration will make a request to NMPT API.

Request:

The request must be of the following format, where driving license number and date of birth is
passed within the URL body in JSON format.

https://www.ldbstaging.co.in/ulip/v1.0.0/NMPT/03

{
"vcn_no":"INNML121070010"
}

Curl URL

curl --location --request POST 'http://localhost:8085/ulip/v1.0.0/NMPT/03' \

--header 'Content-Type: application/json' \
--
header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdC
I6MTYzNjM0ODg0MCwiYXBwcyI6ImRhdGFwdXNoIn0.E78_Oa5DYP7m4Jpq2Q9kXK8gQDiScqndwwN
kIicBOzQmXudwXRJbNwjRVSJKkI1cYaEZK45oS4_1sMS1Q_ggRA' \

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 11 of 20
 ULIP Integration Requirement Document

--data-raw '{
"vcn_no":"INNML121070010"
}'

For obtaining authentication token, refer Section 1.8

Response

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

g) In case of invalid format

1. Invalid VCN number

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered a
t: vcn_no. Format should follow ^[a-zA-Z0-9]{2,14}$"
}

h) In case of VCN number does not exist in NMPT system

{
"response": [
{
"response":{
"status":"1",
"message":"No records found "},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

i) In case VCN number exist

{
{

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 12 of 20
 ULIP Integration Requirement Document

"response": [
{
"response": {
"imo_number": "1234555",
"vcn_no": "INNML121070010",
"vessel_name": "TEST_VSL_01",
"shipping_line_code": "17789",
"shipping_agent_code": "17789",
"application_type": "B",
"eta": "21072021 16:20",
"etd": "21072021 20:11",
"ata": "11072021 00:00",
"atd": "20072021 14:00",
"port_of_arrival_name": "INNML1",
"last_port_of_call_name": "",
"vessel_type": "C"
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: export 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.6 NMPT/04

This API will take import gate details and connect with NMPT API to get data.

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d
1 be_no BE Number as available [0-9]{1,7} Required Min=1,
in NMPT system. Max=7

1.6.1 Technical Approach

16. All the data will be shared through rest web services.

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 13 of 20
 ULIP Integration Requirement Document

17. ULIP system will provide BE Number for which detail is required.
18. NMPT API will share details of cargo information which exist in NMPT system in JSON
format.
19. NMPT Integration will add JSON in response key in response body.
20. ULIP system will provide the data in JSON Object format in response body.

Example:

BE number is shared by ULIP system, then NMPT- integration will make a request to
NMPT API.

Request:

The request must be of the following format, where driving license number and date of birth is
passed within the URL body in JSON format.

https://www.ldbstaging.co.in/ulip/v1.0.0/NMPT/04

{
"be_no" : " 5236246
”}

Curl URL

curl --location --request POST 'http://localhost:8085/ulip/v1.0.0/NMPT/04' \

--header 'Content-Type: application/json' \
--
header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdC
I6MTYzNjM0ODg0MCwiYXBwcyI6ImRhdGFwdXNoIn0.E78_Oa5DYP7m4Jpq2Q9kXK8gQDiScqndwwN
kIicBOzQmXudwXRJbNwjRVSJKkI1cYaEZK45oS4_1sMS1Q_ggRA' \
--data-raw '{
"be_no":"5236246"
}'
'

For obtaining authentication token, refer Section 1.8

Response

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

j) In case of invalid format

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 14 of 20
ULIP Integration Requirement Document

2. Invalid BE number

{
"response": null,
"error": "true",
"code": "400",
"message": "Data format failed OR wrong value entered
at: beNo. Format should follow [0-9]{1,7}"
}

k) In case of BE number does not exist in NMPT system

{
"response": [
{
"response": {
"status":"1",
"message":"No records found "
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

l) In case BE number exist

{
"response": [
{
"response": {
"igm_no": "2290480",
"igm_date": "26082021",
"line_no": "21-0",
"sub_line_no": "21-0",
"bl_no": "21BXO",
"be_no": "5236246",
"be_date": "28082021",
"importer_name": "",
"importer_address": "",
"cha_code": "122",

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 15 of 20
 ULIP Integration Requirement Document

"nature_of_cargo": "DB",
"cargo_type": "PC",
"goods_description": "DRIED RAW CASHEW NUTS",
"marks_no": "NIL",
"no_of_packages_qty": "207.48",
"type_of_packages": "BGS",
"unit_of_measurement": "MT",
"country_of_origin": "GUINEA-BISSAU",
"out_of_charge_no": "2043098319",
"out_of_charge_date": "08092021",
"delivery_order_no": "120210901123712",
"do_date": "01092021",
"mode_of_transport": "R",
"survey_date": "",
"surveyor_code": "",
"vehicle_info": [
{
"truck_entry_permit_no": "GP2109130000001",
"vehicle_number": "KA19A2093",
"truck_exit_time": "",
"truck_entry_time": "13092021"
}
]
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: BE Number 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.7 NMPT/05

This API will take export gate details and connect with NMPT 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: 1.0 Page 16 of 20
 ULIP Integration Requirement Document

1 Shipping_bill Shipping Bill Numberas [0-9]{7} Required 7

_no available in NMPT
system.
1.7.1 Technical Approach
21. All the data will be shared through rest web services.
22. ULIP system will provide Shipping Bill Number for which detail is required.
23. NMPT API will share details of cargo information which exist in NMPT system in JSON
format.
24. NMPT Integration will add JSON in response key in response body.
25. ULIP system will provide the data in JSON Object format in response body.

Example:

Shipping Bill number is shared by ULIP system, then NMPT- integration will make a
request to NMPT API.

Request:

The request must be of the following format, where driving license number and date of birth is
passed within the URL body in JSON format.

https://www.ldbstaging.co.in/ulip/v1.0.0/NMPT/05

{
"shipping_bill_no" : "9890556”}

Curl URL

curl --location --request POST 'http://localhost:8085/ulip/v1.0.0/NMPT/05' \

--header 'Content-Type: application/json' \
--
header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdC
I6MTYzNjM0ODg0MCwiYXBwcyI6ImRhdGFwdXNoIn0.E78_Oa5DYP7m4Jpq2Q9kXK8gQDiScqndwwN
kIicBOzQmXudwXRJbNwjRVSJKkI1cYaEZK45oS4_1sMS1Q_ggRA' \
--data-raw '{
"shipping_bill_no":"9890556"
}'

For obtaining authentication token, refer Section 1.8

Response

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 17 of 20
 ULIP Integration Requirement Document

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

m) In case of invalid format

3. Invalid Shipping Bill number

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

n) In case of Shipping Bill number does not exist in NMPT system

{
"response": [
{
"response": {
"status":"1",
"message":"No records found "
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

o) In case Shipping Bill number exist

Development In Progress

Status Code 200: Shipping Bill Number 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.

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 18 of 20
 ULIP Integration Requirement Document

1.8 Data Transmission & Authentication Mechanism

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

https://www.ldbstaging.co.in/ulip/v1.0.0/NMPT/01

Body:
{ "vcn_no":"HAL12100007"}

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 -X POST
‘https://www.ldbstaging.co.in/ulip/v1.0.0/user/login
-H 'accept: application/json'
-H 'content-type: application/json'
-data ‘{"username":"xxxxxx","password":" XXxxx@12345"} ‘

Authorization:
Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJpbnRlcmNvbnQiLCJpYXQiOjE1ODU1NjYyMzcsImFwcHMi
OiJkYXRhcHVzaCJ9.jb-23DbkWpz-3ptsuuZofzH-
ce7jd0xR5WlkFfBPO_Dzjop01dSx9OamqsjsgUAryLUPtUDiMX07oHG4L2AfFQ

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 vehicle details as follow -

curl -X POST \
https://www.ldbstaging.co.in/ulip/v1.0.0/NMPT/01 \

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 19 of 20
ULIP Integration Requirement Document

-H 'accept: application/json' \
-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTIzMDQyNywiYXBwcyI6ImRh
dGFwdXNoIn0.rhumwWJ8BWeeHe9CYmIV1UKyJk-kLHA_ovX5Zi2OwxEv-td-
KpxnfbKDI_8FZsOoggqx3Al-Du1y2qMoUD7uzA' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 8e8a19a4-ea1e-6373-f616-e2e4af9a1338' \
-d '{"vcnNo": " HAL12100007"}'

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 20 of 20