ULIP Integration Requirement Document

ULIP Integration Requirement Document

Version No.: 1.0

Date: 08/07/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/07/2021 Hasan Mhad Khan Baseline Version

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

Table of Contents

Introduction ................................................................................................................................................. 4
1.1 Purpose .................................................................................................................................... 4
The Overall Description .............................................................................................................................. 4
1.2 Data Integration between MPT System and ULIP application ................................................. 4
1.3 MPT/01 ..................................................................................................................................... 4
1.3.1 Technical Approach ..................................................................................................... 5
1.4 MPT/02 ..................................................................................................................................... 7
1.4.1 Technical Approach ..................................................................................................... 8
1.5 MPT/03 ................................................................................................................................... 11
1.5.1 Technical Approach ................................................................................................... 11
1.6 Data Transmission & Authentication Mechanism .................................................................. 14
1.7 Authentication Mechanism MPT API...................................................................................... 15

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

Introduction

1.1 Purpose

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

1. Data Integration between MPT and ULIP web service: Identification of operational
points where data integration between MPT 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 MPT 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 MPT API.

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

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

5. MPT/03 API will take shipping bill number from user and get data from MPT API.

1.2 Data Integration between MPT System and ULIP application

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

1.3 MPT/01

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

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

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d
1 vcnNo vessel call number as ^[a-zA-Z0- Required Min 2
available in MPT system. 9]{2,14}$ Max 12

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. MPT API will share details of vessel information which exist in MPT system in JSON
format.
4. MPT 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 20200345 is shared by ULIP system, then MPT-integration will make a
request to MPT 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.ulip.dpiit.gov.in/ulip/v1.0.0/MPT/01

{"vcnNo": "123456789012"}

Curl URL

curl -X POST \
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/MPT/01 \
-H 'accept: application/json' \
-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTczMzQ0NCwiYXBwcyI6ImRh
dGFwdXNoIn0.-
FTXGNLmro8bXz45XsfCWkz05u4fdnxpIYXK7HZ7ufbAtbXejm0rsYiv8rzjiUr0bjg1TAxp6vb838
uxtet63g' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 62dad653-e293-dbff-983e-388f64ae1cd8' \
-d '{"vcnNo": "1234567890122"}'

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

For obtaining authentication token, refer Section 1.6

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 at: vcnNo.
Format should follow ^[a-zA-Z0-9]{2,14}$”
}

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

{
"response": [
{
"response": {
"IMO_NUMBER": "",
"APPLICATION_TYPE": "",
"VCN_NO": "",
"SHIPPING_AGENT_CODE": "",
"ATA": "00000000 00:00",
"ATD": "00000000 00:00",
"PORT_OF_ARRIVAL_NAME": "INMRM1",
"VESSEL_TYPE": "",
"ETA": "00000000 00:00",
"ETD": "00000000 00:00",
"LAST_PORT_OF_CALL_NAME": "",
"VESSEL_NAME": "",
"SHIPPING_LINE_CODE": ""
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success" }
c) In case vcn number exist

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

{
"response": [
{
"response": {
"IMO_NUMBER": "9728186",
"APPLICATION_TYPE": "",
"VCN_NO": "000020200345",
"SHIPPING_AGENT_CODE": "",
"ATA": "00000000 00:00",
"ATD": "00000000 00:00",
"PORT_OF_ARRIVAL_NAME": "INMRM1",
"VESSEL_TYPE": "",
"ETA": "00000000 00:00",
"ETD": "00000000 00:00",
"LAST_PORT_OF_CALL_NAME": "",
"VESSEL_NAME": "MEDI GLADSTONE",
"SHIPPING_LINE_CODE": ""
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: vehicle 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 MPT/02

This API will take BE number and connect with MPT API to get data.

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d
1 beNo Bill of Entry Number as [0-9]{7} Required 7
available in MPT system.

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

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. MPT API will share details of cargo information which exist in MPT system in JSON format.
9. MPT 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 2458667 is shared by ULIP system, then MPT-integration will make a

request to MPT 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.ulip.dpiit.gov.in/ulip/v1.0.0/MPT/02

{"beNo": " 2458667"}

Curl URL

curl -X POST \
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/MPT/02 \
-H 'accept: application/json' \
-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTczMzQ0NCwiYXBwcyI6ImRh
dGFwdXNoIn0.-
FTXGNLmro8bXz45XsfCWkz05u4fdnxpIYXK7HZ7ufbAtbXejm0rsYiv8rzjiUr0bjg1TAxp6vb838
uxtet63g' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: d0fa9f41-ec93-2b83-9b90-754b6ad24395' \
-d '{"beNo": "2458667"}'

For obtaining authentication token, refer Section 1.6

Response

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

d) In case of invalid format

Doc Ref. No: ULIP Integration Doc Version No: 1.0 Page 8 of 16
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]{7}"
}

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

{
"response": [
{
"response": {
"DELIVERY_ORDER_NO": "",
"IMPORTER_NAME": "",
"IGM_NO": "",
"BL_NO": "",
"SURVEY_DATE": "",
"IMPORTER_ADDRESS": "",
"SUB_LINE_NO": "",
"SURVEYOR_CODE": "",
"BE_DATE": "",
"MARKS_NO": "",
"VEHICLE_INFO": [],
"CHA_CODE": "",
"COUNTRY_OF_ORIGIN": "",
"IGM_DATE": "",
"DO_DATE": "",
"TYPE_OF_PACKAGES": "",
"CARGO_TYPE": "",
"NO_OF_PACKAGES_QTY": "",
"UNIT_OF_MEASUREMENT": "",
"LINE_NO": "",
"GOODS_DESCRIPTION": "",
"MODE_OF_TRANSPORT": "",
"OUT_OF_CHARGE_NO": "",
"NATURE_OF_CARGO": "",
"OUT_OF_CHARGE_DATE": "",
"BE_NO": ""
},
"responseStatus": "SUCCESS"
}

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

],
"error": "false",
"code": "200",
"message": "Success"
}

f) In case vcn number exist

{
"response": [
{
"response": {
"DELIVERY_ORDER_NO": "",
"IMPORTER_NAME": "DECCAN FINE CHEMICALS (INDIA) PRIVATE
LIMITED",
"IGM_NO": "2219622",
"BL_NO": "579859849",
"SURVEY_DATE": "",
"IMPORTER_ADDRESS": "100 PERCENT EOU SANTA MONICA WORKS
,IIHAS",
"SUB_LINE_NO": "0",
"SURVEYOR_CODE": "",
"BE_DATE": "18032019",
"MARKS_NO": "NM",
"VEHICLE_INFO": [
{
"TRUCK_ENTRY_PERMINT_NO": "",
"VEHICLE_NUMBER": "GA 06 T 3272",
"TRUCK_EXIT_TIME": "19032019",
"TRUCK_ENTRY_TIME": ""
},
{
"TRUCK_ENTRY_PERMINT_NO": "",
"VEHICLE_NUMBER": "GA 06 T 4953",
"TRUCK_EXIT_TIME": "19032019",
"TRUCK_ENTRY_TIME": ""
},
{
"TRUCK_ENTRY_PERMINT_NO": "",
"VEHICLE_NUMBER": "GA 06 T 3271",
"TRUCK_EXIT_TIME": "19032019",
"TRUCK_ENTRY_TIME": ""
}
],
"CHA_CODE": "AACFJ1077GCH001",
"COUNTRY_OF_ORIGIN": "CN",

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

"IGM_DATE": "15032019",
"DO_DATE": "",
"TYPE_OF_PACKAGES": "CON",
"CARGO_TYPE": "",
"NO_OF_PACKAGES_QTY": "3",
"UNIT_OF_MEASUREMENT": "KGS",
"LINE_NO": "18",
"GOODS_DESCRIPTION": "DIMETHYLCARBONATE",
"MODE_OF_TRANSPORT": "R",
"OUT_OF_CHARGE_NO": "2032294737",
"NATURE_OF_CARGO": "C",
"OUT_OF_CHARGE_DATE": "19032019",
"BE_NO": "2458667"
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: vehicle 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.5 MPT/03
This API will take shipping bill number and connect with MPT API to get data.

S. Field Name Field Description Format Require Length

No. d/Not –
Require
d
1 shppingBillNo Shipping Bill number as [0-9]{7} Required 7
available in MPT system.

1.5.1 Technical Approach

11. All the data will be shared through rest web services.
12. ULIP system will provide shipping Bill number for which detail is required.
13. MPT API will share details of cargo information which exist in MPT system in JSON format.
14. MPT Integration will add JSON in response key in response body.

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

15. ULIP system will provide the data in JSON Object format in response body.

Example:

Shipping Bill number 4164154 is shared by ULIP system, then MPT-integration will
make a request to MPT 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.ulip.dpiit.gov.in/ulip/v1.0.0/MPT/03

{"shippingBillNo": "4164154"}

Curl URL

curl -X POST \
https://www.ulip.dpiit.gov.in/ulip/v1.0.0/MPT/03 \
-H 'accept: application/json' \
-H 'authorization: Bearer
eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ0ZXN0MSIsImlhdCI6MTYyNTczMzQ0NCwiYXBwcyI6ImRh
dGFwdXNoIn0.-
FTXGNLmro8bXz45XsfCWkz05u4fdnxpIYXK7HZ7ufbAtbXejm0rsYiv8rzjiUr0bjg1TAxp6vb838
uxtet63g' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 74f68893-0e56-f20f-8581-827680413bb4' \
-d '{"shippingBillNo": "4164154"}
'

For obtaining authentication token, refer Section 1.6

Response

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

g) In case of invalid format

3. Invalid shipping bill number

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

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

h) In case of shipping bill number does not exist in MPT system

{
"response": [
{
"response": {
"SHIPPING_BILL_DATE": "00000000",
"VEHICLE_INFO": [],
"EXPORTER_NAME": "",
"ROTATION_NO": "",
"LEO_DATE": "00000000",
"EGM_DATE": "",
"ROTATION_DATE": "",
"VCN_NO": "",
"ALLOW_FOR_SHIPMENT_DATE": "",
"PORT_OF_ORIGIN": "",
"PORT_WHERE_SB_FILED": "",
"CARGO_TYPE": "",
"PORT_OF_DESTINATION_CODE": "",
"PORT_OF_LOADING": "",
"EGM_NO": "",
"SHIPPING_BILL_NO": "",
"NATURE_OF_CARGO": ""
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

i) In case vcn number exist

{
"response": [
{

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

"response": {
"SHIPPING_BILL_DATE": "00000000",
"VEHICLE_INFO": [],
"EXPORTER_NAME": "",
"ROTATION_NO": "",
"LEO_DATE": "00000000",
"EGM_DATE": "",
"ROTATION_DATE": "",
"VCN_NO": "",
"ALLOW_FOR_SHIPMENT_DATE": "",
"PORT_OF_ORIGIN": "",
"PORT_WHERE_SB_FILED": "",
"CARGO_TYPE": "",
"PORT_OF_DESTINATION_CODE": "",
"PORT_OF_LOADING": "",
"EGM_NO": "",
"SHIPPING_BILL_NO": "",
"NATURE_OF_CARGO": ""
},
"responseStatus": "SUCCESS"
}
],
"error": "false",
"code": "200",
"message": "Success"
}

Status Code 200: vehicle 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 Data Transmission & Authentication Mechanism

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

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

Body:
{"vcnNo": "1234567890122"}

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

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

• 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.ulip.dpiit.gov.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.ulip.dpiit.gov.in/ulip/v1.0.0/MPT/01 \
-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": "1234567890122"}'

1.7 Authentication Mechanism MPT API

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

To connect with the MPT system, we need a username and password from the MPT
system.
Below is the step to generate authorization header

1- Create a string in the below format

username:password
2- Encode the above string with a Base64 encoder.
3- Now create a header in the below format
authorization: Basic <Base64 encode string here>

Curl

curl -X GET \
'https://eportal.mptgoa.com:8000/zvesdet/vesseldet?sap-
client=150&vcn_no=123456789012' \
-H 'accept: application/json' \
-H 'authorization: Basic V0VCX1VTRVI6bXB0Z29hQDE=' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-H 'postman-token: 9f6947b1-e3da-6623-a624-73574c51afab' \
-d '{
"uid": "WEB_USER",
"pwd": "mptgoa@1"
}'

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