Shipwaves - Rates Inventory API
Introduction
The API enables you to programmatically access freight rates inventory available with Shipwaves.
The consumer of the API can get the list of rates available by sending the port of loading, port of discharge, container type and expected shipment date.
Overview
The API follows modern RESTful conventions and speaks JSON in both directions. As the API uses JSON for both requests and responses, we will assume that requests with a payload are using properly formatted JSON, however, we still recommend setting the Content-Type header to the value application/json.
The client is required to send an bearer token in a HTTP “Authorization” header. The key should be prefixed by the string literal “Bearer”, with whitespace separating the two strings. Example:
Authorization: Bearer da1f33df-c679-44fc-bcb8-545643ad1cd6
Error Codes
Success Response: status:200
Forbidden Response: status:403 (Incorrect bearer token)
Not Found: status:404
Bad Gateway: status: 502
Service Unavailable: status:503
Base URL
The base URL for all production API endpoints is https://api.shipwaves.com/
API Response
The success property in the response body from the Shipwaves API has to be checked to determine if/whether the response was successfully processed.
Failed Response
{"success":0, "data":{...}}
Any response with success property set to 0 would mean that request wasn't processed completely and data property within the response body would provide details of the reason for failure.
Success Response
{"success":1, "data":{...}}
Response with success property set to 1 would mean that request was processed successfully.
HTTP Request
GET /rates/v3/inventory
Header
Content-Type: application/json
curl "https://[BASE_URL]/api/rates/v3/inventory?filter[shipmentType]=FCL&filter[pol]=INNSA&filter[pod]=AEJEA&filter[equipmentType]=20'ST&filter[validFrom]=2023-02-07T05:30:00.000Z&filter[validUntil]=2023-02-28T05:30:00.000Z" \
-H "Content-Type: application/json"
Query Parameters
Query Parameter, filter with pol and pod is mandatory for this endpoint to yield result.
| Parameter | Type | Description |
|---|---|---|
| filter[pol] | string | Port of Loading UNLOC. |
| filter[pod] | string | Port of Destination UNLOC. |
| filter[equipmentType] | string | Equipment Type (Refer Equipment Types endpoint). |
| filter[shipmentType] | string | Shipment Type ['FCL', 'LCL', 'AIR']. Defaults to FCL |
| filter[validFrom] | string | Rate Valid from - ISO Date. |
| filter[validUntil] | string | Rate Valid Until - ISO Date. |
| skip | integer | Offset items in result response. |
| limit | integer | Number of items in result response. Defaults to 20 |
Response Status
Response Fields
Sample response:
{
"success": 1,
"data": {
"count": 1,
"items": [
{
"recordId": 12345,
"vendor": {
"name": "Mediterranean Shipping Company (MSC)"
},
"rateCategory": "Freight",
"shipmentType": "FCL",
"name": "Freight",
"equipmentType": "20'ST",
"freeDays": "-",
"pol": {
"raw": "NHAVA SHEVA",
"displayName": "Jawaharlal Nehru (Nhava Sheva), Maharashtra, India (INNSA)",
"code": "INNSA",
"name": "Jawaharlal Nehru (Nhava Sheva), Maharashtra, India"
},
"pod": {
"raw": "JEBEL ALI",
"displayName": "Jebel Ali, United Arab Emirates (AEJEA)",
"code": "AEJEA",
"name": "Jebel Ali, United Arab Emirates"
},
"transitTime": "-",
"transShipments": "-",
"validFrom": "2023-02-07T11:00:00.000Z",
"validUntil": "2023-02-28T11:00:00.000Z",
"commodity": "FAK",
"total": 250,
"currency": "USD",
"rateItems": [
{
"name": "Basic Ocean Freight",
"rateBasis": "Per Equipment",
"rate": 250,
"quantity": 1,
"taxPercentage": 0,
"totalTax": 0,
"total": 250,
"currency": "USD",
}
]
}
]
},
"permissions": {
"Authorized": true
}
}
Description of an item in data.items of the response.
| Field | Type | Description |
|---|---|---|
| recordId | integer | Identifier |
| vendor | object | Vendor Vendor |
| rateCategory | string | Purchase Order Number |
| shipmentType | string | Sales Order Number |
| name | string | Name of the Item |
| equipmentType | string | Equipment Type |
| freeDays | string | Free Days at Destination |
| pol | string | Port of Loading Port |
| pod | string | Port of Discharge Port |
| transitTime | string | Transit Time of the Vessel |
| transShipments | array | Array of transhipment Ports |
| validFrom | string | Rate valid from. ISO Date form. |
| validUntil | string | Rate valid until. ISO Date form. |
| commodity | string | Commodity |
| total | string | Total Cost |
| currency | string | Currency |
| rateItems | array | Array of Rate Items |
Vendor
| Field | Type | Description |
|---|---|---|
| name | string | Name of the Company |
Port
| Field | Type | Description |
|---|---|---|
| displayName | string | Display name of the port |
| code | string | Code Identifier of the port |
| name | string | Name of the port |
Rate Item
| Field | Type | Description |
|---|---|---|
| name | string | Name of the rate item |
| rateBasis | string | Basis of rate |
| rate | float | Cost of the item |
| quantity | float | Quantity of items |
| taxPercentage | float | Tax percentage for the item |
| totalTax | float | Total tax amount |
| total | float | Total amount |
| currency | string | Curreny of the item |
Shipwaves - Tracking API
Introduction
The API enables you to programmatically access tracking data points of a shipment subscribed using the Shipwaves platform.
The consumer of the API can query the tracking data by Purcahase Order, Sales Order or Container Numbers.
Overview
The API follows modern RESTful conventions and speaks JSON in both directions. As the API uses JSON for both requests and responses, we will assume that requests with a payload are using properly formatted JSON, however, we still recommend setting the Content-Type header to the value application/json.
The client is required to send an bearer token in a HTTP “Authorization” header. The key should be prefixed by the string literal “Bearer”, with whitespace separating the two strings. Example:
Authorization: Bearer da1f33df-c679-44fc-bcb8-545643ad1cd6
Error Codes
Success Response: status:200
Forbidden Response: status:403 (Incorrect bearer token)
Not Found: status:404
Bad Gateway: status: 502
Service Unavailable: status:503
API Response
The success property in the response body from the Shipwaves API has to be checked to determine if/whether the response was successfully processed.
Failed Response
{"success":0, "data":{...}}
Any response with success property set to 0 would mean that request wasn't processed completely and data property within the response body would provide details of the reason for failure.
Success Response
{"success":1, "data":{...}}
Response with success property set to 1 would mean that request was processed successfully.
Base URL
The base URL for all production API endpoints is https://api.shipwaves.com/
Get Tracking Data By Order
HTTP Request
GET /api/tracking/orders
Header
Content-Type: application/json
curl "https://[BASE_URL]/api/tracking/order?purchaseOrderNumber=PO-1221&salesOrderReferenceNumber=SO-12112" \
-H "Content-Type: application/json"
Query Parameters
Query Parameter, purchaseOrderNumber or salesOrderNumber is mandatory for this endpoint to yield result.
| Parameter | Type | Description |
|---|---|---|
| purchaseOrderNumber | string | Purchase Order Number. |
| salesOrderNumber | string | Sales Order Number. |
Response Status
Response Fields
Sample response:
{
"success": 1,
"data": {
"_id": "611e5222f99b991112559353",
"shipment": "611e5222f99b190042559343",
"purchaseOrderNumber": "PO-1221",
"salesOrderNumber": "SO-12112",
"containers": [
{
"containerNumber": "OOCU6436380",
"containerTypeIso": "45GP",
"portLoadingLocation": {
"name": "Dubai (Jebel Ali)",
"country": "United Arab Emirates"
},
"portDestinationLocation": {
"name": "Barcelona",
"country": "Spain"
},
"polVsldepartureActual": "2023-01-02T11:56+0000",
"polVsldeparturePlannedInitial": "2023-01-01T14:42+0000",
"polVsldeparturePlannedLast": "2023-01-01T14:42+0000",
"podVslArivalActual": "2023-01-10T02:39+0000",
"podVslArivalPlannedInitial": "2023-01-09T05:27+0000",
"podVslArivalPlannedLast": "2023-01-08T22:05+0000",
"status": "waiting for pickup"
}
],
},
}
| Field | Type | Description |
|---|---|---|
| _id | string | Unique Identifier (hexadecimal) |
| shipment | string | Shipment Identifier (hexadecimal) |
| purchaseOrderNumber | string | Purchase Order Number |
| salesOrderNumber | string | Sales Order Number |
| containers | array | Array of Containers |
Container data
| Field | Type | Description |
|---|---|---|
| containerNumber | string | Container Number |
| containerTypeIso | string | Container Type ISO |
| portLoadingLocation | object | Object of Place |
| portDestinationLocation | object | Object of Place |
| polVsldepartureActual | string | ISO Timestamp |
| polVsldeparturePlannedInitial | string | ISO Timestamp |
| polVsldeparturePlannedLast | string | ISO Timestamp |
| podVslArivalActual | string | ISO Timestamp |
| podVslArivalPlannedInitial | string | ISO Timestamp |
| podVslArivalPlannedLast | string | ISO Timestamp |
| status | string | Status of the container |
Place
| Field | Type | Description |
|---|---|---|
| name | string | Place Name |
| country | string | Country |
Get Tracking Data By Container
HTTP Request
GET /api/tracking/container
Header
Content-Type: application/json
curl "https://[BASE_URL]/api/tracking/container?containerNumber=OOCU6436380" \
-H "Content-Type: application/json"
Query Parameters
Query Parameter, containerNumber is mandatory for this endpoint to yield result.
| Parameter | Type | Description |
|---|---|---|
| containerNumber | string | Container Number. |
Response Status
Response Fields
Sample response:
{
"success": 1,
"data": {
"_id": "611e5222f99b991112559353",
"shipment": "611e5222f99b190042559343",
"containerNumber": "OOCU6436380",
"containerNumber": "OOCU6436380",
"containerTypeIso": "45GP",
"portLoadingLocation": {
"name": "Dubai (Jebel Ali)",
"country": "United Arab Emirates"
},
"portDestinationLocation": {
"name": "Barcelona",
"country": "Spain"
},
"polVsldepartureActual": "2023-01-02T11:56+0000",
"polVsldeparturePlannedInitial": "2023-01-01T14:42+0000",
"polVsldeparturePlannedLast": "2023-01-01T14:42+0000",
"podVslArivalActual": "2023-01-10T02:39+0000",
"podVslArivalPlannedInitial": "2023-01-09T05:27+0000",
"podVslArivalPlannedLast": "2023-01-08T22:05+0000",
"status": "waiting for pickup",
"orders": [
{
"purcahseOrderNumber": "PO-1221",
"salesOrderNumber": "SO-1221",
}
],
},
}
| Field | Type | Description |
|---|---|---|
| _id | string | Unique Identifier (hexadecimal) |
| shipment | string | Shipment Identifier (hexadecimal) |
| containerNumber | string | Container Number |
| containerTypeIso | string | Container Type ISO |
| portLoadingLocation | object | Object of Place |
| portDestinationLocation | object | Object of Place |
| polVsldepartureActual | string | ISO Timestamp |
| polVsldeparturePlannedInitial | string | ISO Timestamp |
| polVsldeparturePlannedLast | string | ISO Timestamp |
| podVslArivalActual | string | ISO Timestamp |
| podVslArivalPlannedInitial | string | ISO Timestamp |
| podVslArivalPlannedLast | string | ISO Timestamp |
| orders | array | Array of Orders |
| status | string | Status of the container |
Order
| Field | Type | Description |
|---|---|---|
| purchaseOrderNumber | string | Purchase Order Number |
| salesOrderNumber | string | Sales Order Number |
Place
| Field | Type | Description |
|---|---|---|
| name | string | Place Name |
| country | string | Country |
Shipwaves - Bank Regularization
Introduction
The Shipwaves API enables easy information flows between Shipwaves and Banks to ease the regularization process for Shippers. Here, you have access to Shipwaves API endpoint/s built for Banks. The API enables you to programmatically access regularization data points of multiple shipments in a single request.
Overview
The API follows modern RESTful conventions and speaks JSON in both directions. As the API uses JSON for both requests and responses, we will assume that requests with a payload are using properly formatted JSON, however, we still recommend setting the Content-Type header to the value application/json.
Authorization
For the POC, we would disable authorization.
Error Codes
Success Response: status:200
Forbidden Response: status:403 (Available after Authorization is enabled)
Not Found: status:404
Bad Gateway: status: 502
Service Unavailable: status:503
API Response
The success property in the response body from the Shipwaves API has to be checked to determine if/whether the response was successfully processed.
Failed Response
{"success":0, "data":{...}}
Any response with success property set to 0 would mean that request wasn't processed completely and data property within the response body would provide details of the reason for failure.
Success Response
{"success":1, "data":{...}}
Response with success property set to 1 would mean that request was processed successfully.
Base URL
The base URL for all the API endpoints is https://api.shipwaves.com
Get Regularization Data
HTTP Request
GET /api/regularize
Header
Content-Type: application/json
curl "https://[BASE_URL]/api/regularize?references=BLHDMLU12021,HBLEMAEU2022" \
-H "Content-Type: application/json"
Query Parameters
Query Parameter, references is mandatory for this endpoint.
| Parameter | Type | Description |
|---|---|---|
| references | string | Multiple reference values can be separated by coma. |
The reference value can be one of the below
Master BL Number
Master AWB Number
Booking Number
House BL number
House AWB number
Response Status
Response Fields
Sample response:
{
"success": 1,
"data": {
"items": [
{
"_id": "611e5222f99b991112559353",
"iec": "0705019951",
"shipment": "611e5222f99b190042559343",
"polUnloc": "INNSA",
"podUnloc": "AEJEA",
"buyerName": "Test 1 Buyer Name",
"buyerAddress": "Test 1 Buyer Address",
"buyerCountryCode": "AE",
"consigneeName": "ABC Consignee",
"consigneeCountryCode": "AE",
"originOfGoodsCountryCode": "IN",
"portOfDestinationCountryCode": "AE",
"tenorAsPerInvoice": "30% ADVANCE BY TT & REMAINING 70% AGAINST SCAN COPY OF BL",
"commodityDescription": "PROCESSED FISH MEAL(DRIED, PULVERISED S IEVED & PACKED IN POWDER FORM)(UNFIT FO R HUMAN CONSUMPTION)",
"carrierName": "Maersk Line",
"blNumber": "BLHDMLU12021",
"blDate": "14-JAN-2022",
"vesselName": "MSC Virtusa",
"authorisedDealerCode": "0510501",
"shippingBillNumber": "6251302",
"shippingBillDate": "13/01/2022",
"invoiceNumber": "E-028A",
"invoiceDate": "24-DEC-2021",
},
{
"_id": "611e5222f99b998812559353",
"iec": "0705019951",
"shipment": "611e5222f99b170042559343",
"polUnloc": "INNSA",
"podUnloc": "NLRTM",
"buyerName": "Test 2 Buyer Name",
"buyerAddress": "Test 2 Buyer Address",
"buyerCountryCode": "NL",
"consigneeName": "XYZ Consignee",
"consigneeCountryCode": "NL",
"originOfGoodsCountryCode": "IN",
"portOfDestinationCountryCode": "NL",
"tenorAsPerInvoice": "D/A 90 days from B/L Date",
"commodityDescription": "PROCESSED FISH MEAL(DRIED, PULVERISED S IEVED & PACKED IN POWDER FORM)(UNFIT FO R HUMAN CONSUMPTION)",
"carrierName": "MSC",
"blNumber": "HBLEMAEU2022",
"blDate": "24-JAN-2022",
"vesselName": "Evergiven",
"authorisedDealerCode": "0510502",
"shippingBillNumber": "6251303",
"shippingBillDate": "22/01/2022",
"invoiceNumber": "E-028B",
"invoiceDate": "04-JAN-2022",
}
],
"count":2
}
| Field | Type | Description |
|---|---|---|
| _id | string | Unique Identifier (hexadecimal) |
| iec | string | - |
| shipment | string | Shipment Identifier (hexadecimal) |
| polUnloc | string | - |
| podUnloc | string | - |
| buyerName | string | - |
| buyerAddress | string | - |
| buyerCountryCode | string | 2 Digit Code ISO 3166 alpha-2 Standard. |
| consigneeName | string | - |
| consigneeCountryCode | string | 2 Digit Code ISO 3166 alpha-2 Standard. |
| originOfGoodsCountryCode | string | 2 Digit Code ISO 3166 alpha-2 Standard. |
| portOfDestinationCountryCode | string | 2 Digit Code ISO 3166 alpha-2 Standard. |
| tenorAsPerInvoice | string | - |
| commodityDescription | string | - |
| carrierName | string | - |
| blNumber | string | - |
| blDate | string | DD-MON-YYYY format |
| vesselName | string | - |
| authorisedDealerCode | string | - |
| shippingBillNumber | string | - |
| shippingBillDate | string | DD/MM/YYYY format |
| invoiceNumber | string | - |
| invoiceDate | string | DD-MON-YYYY format |
Push Events
With push events our service will push the regularization data, once the shipment has sailed. You have to provide a server handling HTTP POST requests submitting the pushed events. In order to secure the push event, it's best to have the endpoint to accept POST request in HTTPS.
Push messages are always sent in JSON format. Your implementation should respond with one of the specified status codes to indicate success. In case of other status codes, our service will interpret this as a failure. Sometimes our support team will send test events - especially during setup and configuration. To support these properly, your server implementation should respond with one of the success status codes and simply log or discard these event messages.
Sample Push Event:
{
"data": {
"_id": "611e5222f99b991112559353",
"iec": "0705019951",
"shipment": "611e5222f99b190042559343",
"polUnloc": "INNSA",
"podUnloc": "AEJEA",
"buyerName": "Test 1 Buyer Name",
"buyerAddress": "Test 1 Buyer Address",
"buyerCountryCode": "AE",
"consigneeName": "ABC Consignee",
"consigneeCountryCode": "AE",
"originOfGoodsCountryCode": "IN",
"portOfDestinationCountryCode": "AE",
"tenorAsPerInvoice": "30% ADVANCE BY TT & REMAINING 70% AGAINST SCAN COPY OF BL",
"commodityDescription": "PROCESSED FISH MEAL(DRIED, PULVERISED S IEVED & PACKED IN POWDER FORM)(UNFIT FO R HUMAN CONSUMPTION)",
"carrierName": "Maersk Line",
"blNumber": "BLHDMLU12021",
"blDate": "14-JAN-2022",
"vesselName": "MSC Virtusa",
"authorisedDealerCode": "0510501",
"shippingBillNumber": "6251302",
"shippingBillDate": "13/01/2022",
"invoiceNumber": "E-028B",
"invoiceDate": "01-JAN-2022"
}
}
HTTP Request
POST /<BANK_ENDPOINT>
Header
Content-Type: application/json