INTRODUCTION

<aside> 💬 By using the SVMP API, you can utilize various data provided within SVMP, such as tracking the location of ships and cargoes, as well as historical and future forecasting trajectories.

This article describes the parameters for calling each API and the properties of the returned object.

If you have any questions, please contact us at [email protected].

</aside>

1. API

1) User Authentication

<aside> 🔑 SVMP API uses Basic Auth (account/password) authentication for API user authentication. If you send the issued user account and password together in the Request Header, you can use it immediately.

</aside>

1) Cargo Insight (API)

The steps for tracking the cargo are as follows.

- Send basic information for tracking cargo

Request URL

POST /api/v2/cargo?bookingNo={your-booking-No}&carrierCode={SCAC-code}
POST /api/v2/cargo?mblNo={your-master-bl-No}&carrierCode={SCAC-code}

{
  "bookingRegno": "{Booking Registration No}",
  "hbls": [
    {
      "ciNo": "{Commercial Invoice No}",
      "consigneeCode": "{Your Consignee Code}",
      "consigneeName": "{Your Consignee Name}",
      "containers": [
        {
          "commodify": "{Your Commodity}",
          "containerNo": "{Your Container No}",
          "gw": {Your Gross weight},
          "hscode": "{Your hscode}",
          "qty": {Your Container Qty},
          "sealNo1": "{SealNo#1}",
          "sealNo2": "{SealNo#2}",
          "sealNo3": "{SealNo#3}",
          "size": "{Your container size}",
          "type": "{Your container type}"
        }
      ],
      "hblNo": "{Your house BL}",
      "ownerCode": "{Your Cargo Owner Code}",
      "ownerName": "{Your Cargo Owner Name}",
      "shipperCode": "{Your Cargo Shipper Code}",
      "shipperName": "{Your Cargo Shipper Name}"
    }
  ],
  "srNo": "{Shipping Request No}"
}

Response body

{
  "code": 201,
  "message": "CREATED",
  "error": false,
  "timestamp": "2021-12-09T09:21:48Z"
}

- Check the cargo location tracking information after transmission

Request URL

GET /api/v2/cargo/search?bookingNo={your-booking-No}
GET /api/v2/cargo/search?mblNo={your-master-bl-No}

Response body

{
  "code": 200,
  "message": "OK",
  "error": false,
  "timestamp": "2021-12-09T09:32:01Z",
  "response": {
    "documentId": "{SVMP Key}",
    "carrierCode": "{Carrier Code}",
    "bookingNo": "{Your Booking No}",
    "mblNo": "{Your Master B/L No}",
    "bookingRegno": "{Booking Registration No}",
    "srNo": "{Shipping Requer No}",
    "blStatus": "ON",
    "locations": [
      {
        "documentId": "{SVMP Key}",
        "partialSeq": 0,
        "locationSeq": 1,
        "locationId": "{SVMP Location Key}",
        "locationCode": "",
        "locationName": "BUSAN, KOREA",
        "locationType": "POL", //{POR, POL, TSD, TSL, POD, PVY}
        "terminalId": null,
        "terminalName": "HYUNDAI PUSAN NEWPORT",
        "eta": "2021-11-08 22:20",
        "ata": "2021-11-10 20:09",
				"carrierAta": null,
				"etb": "2021-11-08 22:50",
				"atb": "2021-11-10 20:40",
				"carrierAtb": null,
        "etd": "2021-11-12 20:00",
        "atd": "2021-11-12 20:58",
				"carrierAtd": null,
        "pta": null,
        "imoNo": "9863340",
        "shipName": "{Ship Name}",
        "voyageNo": "0005W",
        "shipData": { "Ship Detail Info"
          }
        },
        "portData": { "Port Detail Info"
        }
      },
			{}
    ],
    "hbls": [ // {Your House B/L Info}
      {
        "documentId": "{SVMP key}",
        "hblNo": "string",
        "ciNo": "string",
        "shipperCode": "string",
        "shipperName": "string",
        "consigneeCode": "string",
        "consigneeName": "string",
        "ownerCode": "{Cargo Owner Name:Optional}",
        "ownerName": "{Cargo Owner Name:Optional}",
        "containers": [
          {
            "documentId": "{SVMP Key}",
            "containerNo": "string",
            "hblNo": "string",
            "partialSeq": 0,
            "size": "string",
            "type": "string",
            "commodify": "string",
            "hscode": "string",
            "qty": 0,
            "gw": 0,
            "sealNo1": "string",
            "sealNo2": "string",
            "sealNo3": "string",
            "trackings": [
							{
								"documentId": "{SVMP Key}",
                "containerNo": "{Container NO}",
                "trackingSeq": 0,
                "eventCode": null,
                "eventTime": "202111082220",
                "eventStatus": "Actual",
                "eventDesc1": "GATE-OUT-EMPTY",
                "eventDesc2": "",
                "locationName": "Busan new port terminal Co.ltd",
                "imoNo": null,
                "shipName": null,
                "voyageNo": null
							}
		        ]
          }
        ]
      }
    ]
  }
}

2) Alerts for Cargo (Notification of Cargo arrival/Delay)

<aside> 💡 You can retrieve information on cargoes whose difference between the estimated arrival time (ETA) and the predicted arrival time (PTA) of the registered cargo (based on M-B/L) is longer than the set standard time. The movement of the vessel changes in real time, so in the case of PTA calculation there may be some differences from the actual because it is performed at a specific time.

</aside>

Request URL

GET /v1/alarm/cargo

Response body

{
    "code": 200,
    "message": "OK",
    "error": false,
    "timestamp": "2021-12-10T07:08:47Z",
    "response": [{
            "mblV2DTO": {
                "documentId": "{SVMP Key}",
                "carrierCode": "MAEU",
                "bookingNo": null,
                "mblNo": "{master bl No}",
                "bookingRegno": "",
                "srNo": "",
                "blStatus": "ON",
                "locations": [{
                        "documentId": "{SVMP Key}",
                        "partialSeq": 0,
                        "locationSeq": 0,
                        "locationId": null,
                        "locationCode": "",
                        "locationName": "Busan, Korea, South",
                        "locationType": "POR",
                        "terminalId": null,
                        "terminalName": "Busan new port terminal Co.ltd",
                        "eta": null,
                        "ata": null,
												"carrierAta": null,
												"etb": null,
												"atb": null,
												"carrierAtb": null,
                        "etd": "2021-11-03 14:19",
                        "atd": null,
												"carrierAtd": null,
                        "pta": null,
                        "imoNo": null,
                        "shipName": "",
                        "voyageNo": "",
                        "shipData": null,
                        "portData": null
                    },
	                    { // 선적지 정보
                        "documentId": "{SVMP Key}",
                        "partialSeq": 0,
                        "locationSeq": 1,
                        "locationId": "dc822048-5534-11e9-a747-54802853d888",
                        "locationCode": "",
                        "locationName": "Busan, Korea, South",
                        "locationType": "POL",
                        "terminalId": "d20f5180-bbcc-11ea-b607-049226dae5ce",
                        "terminalName": "Busan new port terminal Co.ltd",
                        "eta": null,
                        "ata": "2021-11-05 17:38",
												"carrierAta": "2021-11-05 17:40",
												"etb": null,
												"atb": null,
												"carrierAtb": null,
                        "etd": "2021-11-06 11:32",
                        "atd": "2021-11-06 22:52",
												"carrierAtd": "2021-11-06 22:54",
                        "pta": null,
                        "imoNo": "9260445",
                        "shipName": "ARTHUR MAERSK",
                        "voyageNo": "142E",
                        "shipData": {
                            // Ship Deatil Data
                            }
                        },
                        "portData": {
                            // Port Detail Data
                        }
                    },
                    { // 양하지 정보
                        "documentId": "{SVMP Key}",
                        "partialSeq": 0,
                        "locationSeq": 2,
                        "locationId": "aa925038-e0c8-11e9-a622-54802853d888",
                        "locationCode": "",
                        "locationName": "Savannah, United States",
                        "locationType": "POD",
                        "terminalId": "d2188e9e-bbcc-11ea-b607-049226dae5ce",
                        "terminalName": "Savannah Garden City Terminal L738",
                        "eta": "2021-12-08 05:17",
                        "ata": null,
												"carrierAta": null,
												"etb": null,
												"atb": null,
												"carrierAtb": null,
                        "etd": null,
                        "atd": null,
												"carrierAtd": null,
                        "pta": "2021-12-10 15:55",
                        "imoNo": "9260445",
                        "shipName": "ARTHUR MAERSK",
                        "voyageNo": "142E",
                        "shipData": {
                            // Ship Detail Data
                            }
                        },
                        "portData": {
                            // Port Detail Data
                        }
                    }
                ],
                "hbls": [{
                    "documentId": "{SVMP Key}",
                    "hblNo": "SVH.214348845",
                    "ciNo": "",
                    "shipperCode": "",
                    "shipperName": "",
                    "consigneeCode": "",
                    "consigneeName": "",
                    "ownerCode": null,
                    "ownerName": null,
                    "containers": [{
                        "documentId": "{SVMP Key}",
                        "containerNo": "{Container No}",
                        "hblNo": "SVH.214348845",
                        "partialSeq": 0,
                        "size": "40",
                        "type": "Dry",
                        "commodify": "",
                        "hscode": "",
                        "qty": null,
                        "gw": null,
                        "sealNo1": "",
                        "sealNo2": "",
                        "sealNo3": "",
                        "trackings": [{
                                "documentId": "{SVMP Key}",
                                "containerNo": "{Container NO}",
                                "trackingSeq": 0,
                                "eventCode": null,
                                "eventTime": "202110281407",
                                "eventStatus": "Actual",
                                "eventDesc1": "GATE-OUT-EMPTY",
                                "eventDesc2": "",
                                "locationName": "Busan new port terminal Co.ltd, Busan, Korea, South",
                                "imoNo": null,
                                "shipName": null,
                                "voyageNo": null
                            }
                        ]
                    }]
                }]
            }

        },
        "diffHour": 58 //delay hours of ETA VS PTA 
    }]
}

2. SVMP Screen Integration (Map View Embed)

1) User Authentication

<aside> 🔑 In the case of user authentication for screen interlocking, since the authentication token is passed to the URL, the authentication token expires after a certain period of time to to reduce the risk of external exposure of URLs. Therefore, it is recommended to configure the screen interlocking system so that it issues a new token before the expiration date and interlocks it.

</aside>

- Issue authentication token

Request URL

GET /api/v1/user/authToken

Response body

{
  "code": 200,
  "message": "OK",
  "error": false,
  "timestamp": "2021-12-09T06:52:33Z",
  "response": [
    {
			"userId": "{user-account-email}",
      "tokenId": "{your-user-token}",
      "registDt": "2021-09-29T20:02:31Z",
      "expiredDt": "2022-11-14T05:03:50Z"
    }
  ]
}

<aside> 🔤 You can access the shipment tracking information sent by SVMP via URL using your UI or API. Such information may be included on Customer's system or accessed through a link.

</aside>

<aside> 🇰🇷 Cargo Insight 화면을 시스템 내부에 포함시킬 수 있습니다.

</aside>

Example

Untitled

Request URL

// Inquiry through Booking No.
<https://svmp.seavantage.com/#/cargo/tracking?authToken={your-auth-Token}&bookingNo={your-booking-No}>

// Inquiry through M-B/L No.
<https://svmp.seavantage.com/#/cargo/tracking?authToken={your-auth-Token}&mblNo={your-master-bl-No}>

<aside> 🎉 new add-on

The cargo insight screen has been improved to be responsive to fit the screen size of multiple devices.

Add embed option

// Added option to hide panel.
// hiddenPanel=info,timeline,all
hiddenPanel=info : hides only the top info panel
hiddenPanel=timeline : hides only the left timeline panel
hiddenPanel=all : hide all panels except map

</aside>

<aside> 💡 If you want to embed the cargo insight screen inside another system, please refer to the following.

</aside>

<iframe src="<https://svmp.seavantage.com/#/cargo/tracking?authToken={your-auth-Token}&mblNo={your-master-bl-No}>" style="border:1px #000000 solid;" name="cargoTracking" scrolling="no" frameborder="1" marginheight="0px" marginwidth="0px" height="780px" width="1200px" allowfullscreen></iframe>