Prepare
Testing Environment
HOST:https://apitest.baaship.com
Token:Consult customer service
Production Environment
HOST:https://api.baaship.com
Token:Consult customer service
Parcel Forecast Creation
Service Ability: Create Parcel Forecast

Request URL: host:/createShipment

Request Method: POST

Header (Used for Token Verification):
Parameter Name Example Value
token 4e411a926e7a33ca9d04cd1942ac54a2
Body Request Parameters:
Parameter Name Description Required Data Type Field Length
referenceNo Customer-defined unique order number Yes String 30
productCode Service code
(Take the value from Product Code)		 Yes String 10
orderNo Customer order number No String 30
incoterms Trade terms (choose one of DDU, DDP) No String 30
storeId Store code (shop ID)
- Required for store delivery mode		 Yes (for store delivery) String 20
codAmount COD amount for the parcel Yes (for COD services) Number 10
remark Parcel delivery remarks No String 100
sender Sender information Yes Object  
 company Sender's company No String 100
 contact Sender's contact person Yes String 50
 phone Sender's phone number Yes String 20
 email Sender's email No String 50
 country Sender's country Yes String 50
 province Sender's province/state Yes String 100
 city Sender's city Yes String 100
 address Sender's detailed address Yes String 200
 postCode Sender's postal code Yes String 10
receiver Recipient information Yes Object  
 company Recipient's company No String 100
 contact Recipient's contact person Yes String 50
 phone Recipient's phone number Yes String 20
 email Recipient's email No String 50
 country Recipient's country/region Yes (not for store delivery) String 50
 province Recipient's province/state No String 100
 city Recipient's city/district Yes (not for store delivery) String 100
 suburb Recipient's administrative district No String 100
 address Recipient's detailed address Yes (not for store delivery) String 200
 postCode Recipient's postal code Yes (not for store delivery) String 10
 vat Recipient's tax number/ID No String 10
packageList Parcel goods information Yes Array[PackageList]  
 weight Actual weight of the parcel, unit: kg
Precision up to 3 decimal places		 Yes Number 8
 length Length of the parcel, unit: cm
Precision up to 1 decimal place		 No Number 5
 width Width of the parcel, unit: cm
Precision up to 1 decimal place		 No Number 5
 height Height of the parcel, unit: cm
Precision up to 1 decimal place		 No Number 5
 packageItemList Item details in the parcel Yes Array[PackageItemList]  
  sku SKU code No String 30
        goodsNameEn English/local product name Yes String 100
        goodsNameCn Chinese product name Yes String 100
  fullDescEn Sales description No String 1000
  hsCode HS Code No String 10
  quantity Quantity Yes Number 10
  itemWeight Weight of the item, unit: kg
Precision up to 3 decimal places		 Yes Number 7
  itemValue Value of the item Yes String 10
  currency Currency (e.g., USD) Yes String 5
        itemSellingUrl Item sales link No String 1000
  imageUrl Image link of the item No String 500
Parcel Forecast Creation Request Example:
{
    "referenceNo": "TEST190107003",
    "productCode": "TESTPRODUCT",
    "orderNo": "OD190107003",
    "incoterms": "DDU",
    "remark": "Test Remark",
    "sender": {
        "company": "Test Company",
        "contact": "John Doe",
        "phone": "1234567890",
        "email": "test@example.com",
        "country": "CN",
        "province": "Shanghai",
        "city": "Shanghai",
        "address": "123 Test Street",
        "postCode": "200000"
    },
    "receiver": {
        "company": "Receiver Inc",
        "contact": "Jane Smith",
        "phone": "0987654321",
        "email": "receiver@example.com",
        "country": "US",
        "province": "California",
        "city": "Los Angeles",
        "address": "456 Receiver Ave",
        "postCode": "90001"
    },
    "packageList": [
        {
            "weight": 1.5,
            "length": 20.5,
            "width": 15.0,
            "height": 10.0,
            "packageItemList": [
                {
                    "sku": "SKU123",
                    "goodsNameEn": "Product Name",
                    "goodsNameCn": "产品名称",
                    "fullDescEn": "Product description",
                    "hsCode": "123456",
                    "quantity": 2,
                    "itemWeight": 0.75,
                    "itemValue": "29.99",
                    "currency": "USD"
                }
            ]
        }
    ]
}
Response Field Description:
Field Name Description Data Type
success True or False Boolean
code 200: Success
Other: Failure		 Integer
message Request return message String
requestId Request ID String
data   Object
 waybill Tracking number String
 referenceNo Customer-defined unique order number String
 productCode Service code String
 labelUrl URL address of the label, in PDF format String
Success Example Response:

{
    "success": true,
    "code": 200,
    "message": "success",
    "requestId": "65bcecc674687425",
    "data": [
        {
            "waybill": "T80000045",
            "referenceNo": "TEST240202005",
            "productCode": "TEST",
            "labelUrl": "https://apitest.baaship.com/pdf-file/T80000045/3a8df10c-c1ce-11ee-8445-00163e0cad28.pdf"
        }
    ]
}
Error Code Description:
Error Code Error Description
1001 Token validation error, please check if the entered Token is correct.
1002 Request parameter data structure error, please detect and re-enter.
1003 The length of the input parameters does not meet the requirements.
1004 Interface exception.
1005 Customer-defined order number is duplicated.
1006 The parcel weight exceeds the limit.
1007 The declared value exceeds the limit.
1008 Address issue.
Error Example Response:
{
    "success":false,
    "code":1001,
    "message":"Token incorrect",
    "requestId":"655c00af45b3a785"
}
Create Reverse Shipment
Service Ability: Create Reverse Shipment

Request URL: host:/reverseShipment

Request Method: POST

Header:
Parameter Name Example Value
token 4e411a926e7a33ca9d04cd1942ac54a2
Body Request Parameters:
Parameter Name Description Required Data Type Field Length
referenceNo Customer-defined unique order number Yes String 30
productCode Service code Yes String 10
orderNo Customer order number No String 30
remark Parcel delivery remarks No String 100
sender Sender information Yes Object  
 company Sender's company No String 100
 contact Sender's contact person Yes String 30
 phone Sender's phone number Yes String 20
 email Sender's email No String 50
 country Sender's country Yes String 50
 province Sender's province/state Yes String 40
 city Sender's city Yes String 40
 address Sender's detailed address Yes String 100
 postCode Sender's postal code Yes String 10
packageList Parcel goods information Yes Object  
 weight Actual weight (kg) Yes Number 8
 length Length (cm) No Number 5
 width Width (cm) No Number 5
 height Height (cm) No Number 5
 packageItemList Item details Yes Array  
  sku SKU code No String 30
       goodsNameEn English/local product name Yes String 100
       goodsNameCn Chinese product name Yes String 100
  fullDescEn Sales description No String 1000
  hsCode HS Code No String 10
  quantity Quantity Yes Number 10
  itemWeight Weight of the item, unit: kg
Precision up to 3 decimal places		 Yes Number 7
  itemValue Value of the item Yes String 10
  currency Currency (e.g., USD) Yes String 5
  itemSellingUrl Item sales link No String 1000
  imageUrl Image link of the item No String 500 
								
{
    "referenceNo": "TEST20220123007",
    "productCode": "BNRTN",
    "orderNo": "TEST20220123007",
    "remark": "Test Remark",
    "sender": {
        "company": "TEST COMPANY",
        "contact": "JOHN WAKER",
        "phone": "6732238181",
        "email": "marecarmejia00-test@gmail.com",
        "country": "BN",
        "province": "KAMPONG KAPOK",
        "city": "MUARA",
        "address": "NO. 7 SIMPANG 170, JALAN",
        "postCode": "BT2328"
    },
    "packageList": {
        "weight": "13.109",
        "length": "50",
        "width": "80",
        "height": "45",
        "packageItemList": [
            {
                "sku": "td2902sx880",
                "goodsNameEn": "Computer Bag",
                "goodsNameCn": "电脑包",
                "fullDescEn": "笔记本电脑背包-带2个隔间的电脑包，符合人体工程学的肩带，15英寸笔记本电脑套，拉柄-书籍背包-黑色",
                "hsCode": "36890233",
                "quantity": "1",
                "itemWeight": "2.102",
                "itemValue": "29.9",
                "currency": "USD",
                "itemSellingUrl": "https://www.amazon.com/JanSport-Big-Student-Backpack-Black/dp/B07K74LDCH/",
                "imageUrl": "https://m.media-amazon.com/images/I/51wX5vhTB4L._AC_SX679_.jpg"
            },
            {
                "sku": "dy102348",
                "goodsNameEn": "vacuum cup",
                "goodsNameCn": "保温杯",
                "fullDescEn": "运动和旅行用隔热不锈钢吸管水瓶，不含双酚A，32盎司，冰镇微风",
                "hsCode": "36890235",
                "quantity": "1",
                "itemWeight": "0.88",
                "itemValue": "17.8",
                "currency": "USD",
                "itemSellingUrl": "https://www.amazon.com/Owala-FreeSip-Insulated-Stainless-BPA-Free/dp/B0C59F7Y8J/",
                "imageUrl": "https://m.media-amazon.com/images/I/518uAgWUTgL._AC_SX679_.jpg"
            }
        ]
    }
}
Response Field Description
Field Name Description Data Type
success True or False Boolean
code 200: Success
Other: Failure		 Integer
message Request return message String
requestId Request ID String
data   Object
 waybill Tracking number String
 referenceNo Customer-defined unique order number String
 productCode Service code String
 labelUrl URL address of the label, in PDF format String
Success Example Response:

{
    "success": true,
    "code": 200,
    "message": "success",
    "requestId": "65bcecc674687425",
    "data": [
        {
            "waybill": "T80000045",
            "referenceNo": "TEST240202005",
            "productCode": "TEST",
            "labelUrl": "https://apitest.baaship.com/pdf-file/T80000045/3a8df10c-c1ce-11ee-8445-00163e0cad28.pdf"
        }
    ]
}
Error Code Description:
Error Code Error Description
1001 Token validation error, please check if the entered Token is correct.
1002 Request parameter data structure error, please detect and re-enter.
1003 The length of the input parameters does not meet the requirements.
1004 Interface exception.
1005 Customer-defined order number is duplicated.
1006 The parcel weight exceeds the limit.
Error Example Response:

{
    "success":false,
    "code":1001,
    "message":"Token incorrect",
    "requestId":"655c00af45b3a785"
}
Cancel Shipment
Service Ability: Cancel create&reverse Shipment

Request URL: host:/cancelShipment

Request Method: GET

Header:
token 4e411a926e7a33ca9d04cd1942ac54a2
Body Request Parameters:
Parameter Name Description Required Data Type Field Length
waybill Tracking number Yes String 30 
https://apitest.baaship.com/cancelShipment?waybill=70000000366
Response Field Description:
Field Name Description Data Type
success True or False Boolean
code 200: Success
Other: Failure		 Integer
message Request return message String
requestId Request ID String
waybill Tracking Number String
Success Response:

{
    "success": true,
    "code": 200,
    "message": "success",
    "requestId": "65bcecc674687425",
    "waybill": "T80000045"
}
Error Code Description:
Error Code Error Description
1001 Token validation error
1002 Request parameter data structure error
1003 The length of the input parameters does not meet the requirements
1004 Interface exception
Parcel Tracking
Service Ability: Track Parcel Logistics
Header (Used for Token Verification):
Parameter Name Example Value
token 4e411a926e7a33ca9d04cd1942ac54a2
Body Request Parameters:
Parameter Name Description Required Data Type Field Length
waybill Tracking number Yes String 30

Request URL: host:/tracking GET

https://apitest.baaship.com/tracking?waybill=70000000366
Response Fields
Field Name Description Data Type
success True or False Boolean
code 200: Success
Others: Failure		 Integer
message Request return message String
requestId Request ID String
data   Array
 waybill Tracking number String
 shipmentType Forward/Reverse String
 latestStatus Latest status String
 latestLocalTime Latest status time String
 events Tracking details Array
  statusCode Tracking Status Code String
  location Location of tracking event String
  description Description of tracking event String
  localTime Date of tracking event String
  timeZone Time Zone String
  country Country String
  state State/Province String
  city City String
  postcode postcode String 

{
    "success": true,
    "code": 200,
    "message": "success",
    "requestId": "6593c83cd7a70494",
    "data": [
        {
            "waybill": "40001044465",
            "shipmentType": "Reverse",
            "latestStatus": "Shipment Delivered",
            "latestLocalTime": "2023-12-27 11:00:08",
            "events": [
                {
                    "statusCode": "DL01",
                    "location": "Maraetai",
                    "description": "Your parcel has been delivered.",
                    "localTime": "2023-12-27 11:00:08",
                    "timeZone": "UTC+12",
                    "country": "NZ",
                    "state": "Auckland",
                    "city": "Maraetai",
                    "postcode": "2018"
                },
                // Additional events...
            ]
        }
    ]
}
Error Code Description:
1001 Token validation error
1002 Request parameter error
1003 Interface exception
1004 Waybill does not exist
Get Package Label API

Request URL: host:/getShipmentLabel GET

Parameters:
Parameter Name Description Required Data Type Field Length
waybill Tracking number
waybill and referenceNo, Choose one of them.		 Yes String 30
referenceNo Customer Reference No
waybill and referenceNo, Choose one of them.		 Yes String 30
Request Example:
https://apitest.baaship.com/getShipmentLabel?waybill=70000000366
Response Fields:
Field Name Description Data Type
success True or False Boolean
code 200: Success
Other: Failure		 Integer
message Request return message String
requestId Request ID String
data   Object
 waybill Tracking number String
 referenceNo Customer reference number String
 labelUrl URL address of the label String
Success Response:

{
    "success":true,
    "code":200,
    "message":"success",
    "requestId":"655c779c9af8b772",
    "data":{
        "waybill":"70000000366",
        "referenceNo":"TEST20210923823",
        "labelUrl":"https://apitest.baaship.com/pdf-file/70000000366/ef7ce42a-8807-11ee-ae09-00163e0cad28.pdf"
    }
}
Product Code Type Is COD Weight Limit(kg) Amount Limit Label Size Label Direction
BNRTN Reverse No ≤25 ≤295 USD 100x150mm Vertical
📦 Create Shipment (Logistics Partner API)
RESTful endpoint to create a new shipment · JSON request format

Request URL: POST /v1/shipments

Request Method: POST

Headers
Header Example Value
Content-Type application/json
Authorization Bearer {your_api_token}
Accept application/json
Body Request Parameters
Parameter Name Description Required Data Type Example
waybill Unique identifier. If omitted, system generates one. optional String "EBN87654321"
referenceNo Your internal reference / order number required String "SHABN250101"
weight Total weight (kg) required String "13.0"
length Package length (cm) required String "60"
width Package width (cm) required String "40"
height Package height (cm) required String "30"
codAmount Cash on delivery amount (BND) optional Number 850
codCurrency Currency, use "BND" optional String "BND"
notes Special handling instructions optional String "Fragile items"
sender Sender contact details required Object -
 contact Contact person required String "Zhang Wei"
 phone Phone number required String "+86 13800138000"
 email Email optional String "zhang@example.com"
 country Country required String "China"
 province Province/State required String "Shanghai"
 city City required String "Shanghai"
 address Detailed address required String "123 Nanjing Road"
 postCode Postal code required String "200001"
receiver Recipient details required Object -
 contact Contact person required String "Ahmad Bin Hassan"
 phone Phone required String "+673 7123456"
 email Email optional String "ahmad@example.com"
 country Country required String "Brunei"
 province Province required String "Brunei-Muara District"
 city City required String "Bandar Seri Begawan"
 address Address required String "No. 45, Jalan Sultan"
 postCode Postal code required String "BA1511"
ItemList List of goods in parcel required Array -
 goodsName Product name required String "Floor Scrubber"
 hsCode HS Code required String "847989"
 quantity Quantity required String "1"
 itemWeight Weight per item (kg) required String "5.0"
 itemValue Declared value required Number 150
 currency Currency code required String "BND"
Request Example
{
    "waybill": "EBN87654321",
    "referenceNo": "SHABN250101",
    "weight": "13.0",
    "length": "60",
    "width": "40",
    "height": "30",
    "codAmount": 850,
    "codCurrency": "BND",
    "notes": "Fragile items, handle with care",
    "sender": {
        "contact": "Zhang Wei",
        "phone": "+86 13800138000",
        "email": "zhang.wei@example.com",
        "country": "China",
        "province": "Shanghai",
        "city": "Shanghai",
        "address": "123 Nanjing Road, Huangpu District",
        "postCode": "200001"
    },
    "receiver": {
        "contact": "Ahmad Bin Hassan",
        "phone": "+673 7123456",
        "email": "ahmad.hassan@example.com",
        "country": "Brunei",
        "province": "Brunei-Muara District",
        "city": "Bandar Seri Begawan",
        "address": "No. 45, Jalan Sultan, Kiulap",
        "postCode": "BA1511"
    },
    "ItemList": [
        {
            "goodsName": "Floor Scrubber",
            "hsCode": "847989",
            "quantity": "1",
            "itemWeight": "5.0",
            "itemValue": 150,
            "currency": "BND"
        }
    ]
}
Response Fields
Field Description Type
waybill Unique tracking number String
referenceNo Customer reference String
status created String
timestamp ISO timestamp String
trackingUrl Public tracking link String
Success Response (201)
{
    "waybill": "EBN87654321",
    "referenceNo": "SHABN250101",
    "status": "created",
    "timestamp": "2025-03-16T10:30:00Z",
    "trackingUrl": "https://track.example.com/EBN87654321"
}
⚠️ Error Codes:

400 : Bad Request

401 : Unauthorized

403 : Forbidden

422 : Unprocessable Entity

500 : Internal Server Error

Rate limit: 100 req/min

🔍 Tracking API (Logistics Partner)

Request URL: GET /v1/track/{waybill}

Request Method: GET

Headers
Authorization Bearer {your_api_token}
Accept application/json
Path Parameter
Parameter Required Description
waybill Yes Unique waybill number e.g. EBN87654321
Example Request URL
GET https://api.example.com/v1/track/EBN87654321
Response Fields
Field Type Description
waybill String Tracking number
referenceNo String Order reference
trackingEvents Array List of events
timestamp String ISO datetime
location String Event location
description String Human readable
status String picked_up/in_transit/delivered
pod String Proof of delivery URL (optional)
Success Response Example
{
    "waybill": "EBN87654321",
    "referenceNo": "SHABN250101",
    "trackingEvents": [
        {
            "timestamp": "2025-03-15T08:22:00Z",
            "location": "Shanghai, China",
            "description": "Shipment picked up",
            "status": "picked_up"
        },
        {
            "timestamp": "2025-03-16T11:52:00Z",
            "location": "Bandar Seri Begawan, Brunei",
            "description": "Delivered, signed by Ahmad",
            "status": "delivered",
            "pod": "https://pod.example.com/EBN87654321.jpg"
        }
    ]
}
📌 Error Codes:

401 Unauthorized

403 Forbidden

404 Not Found (Waybill not exist)

500 Server Error

📄 Get POD (Proof of Delivery)

Request URL: GET /v1/pod/{waybill}

Request Method: GET

Headers
Authorization Bearer {api_token}
Accept application/json
Path Parameter
Parameter Required Description
waybill Yes Waybill number of delivered shipment
Example Request
GET https://api.example.com/v1/pod/EBN87654321
Response Fields
Field Type Description
waybill String Waybill number
podUrl String Temporary signed URL to download POD image/PDF
contentType String image/jpeg or application/pdf
sizeBytes Number File size
filename String Suggested filename
generatedAt String ISO timestamp
podMetadata Object signedBy, deliveryDate, deliveryLocation
Success Response
{
    "waybill": "EBN87654321",
    "podUrl": "https://storage.example.com/pods/EBN87654321_signature.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 187234,
    "filename": "EBN87654321_POD.jpeg",
    "generatedAt": "2025-03-16T11:52:31Z",
    "podMetadata": {
        "signedBy": "Ahmad Bin Hassan",
        "deliveryDate": "2025-03-16T11:52:00Z",
        "deliveryLocation": "Bandar Seri Begawan, Brunei"
    }
}
❌ Error Responses:

401 Unauthorized

404 Not Found (POD not available, shipment not delivered)

410 Gone

500 Server Error

Note: POD is only returned when shipment status is delivered. The URL is short-lived (7 days).