# Logistic APIs

# Get Client Logistics

Request

Method: GET
Path: /client_logistics
Description: Get available logistics by logistic type / product type.

Request Header:

Param Description Required Example
Authorization The OAuth2 authentication with the O2O System Y Bearer {O2O Access Token}
Content-Type The MIME type of this content Y application/json

Query String Parameter:

Key Description Required Example Possible Values
logistics_type Include delivery order history in response N logistics_type=normal,sameday normal, on-demand, sameday
product_type Include driver location in response N product_type=normal,high_value normal, fresh_food, high_value
available_only Include delivery order history in response N available_only=true true, false

More information for multi-valued query parameter format: https://www.baeldung.com/spring-request-param

Example Request:

curl --location --request GET 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/client_logistics?logistics_type=on-demand&available_only=false' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}'

Example Response: Success

{
    "status": 200,
    "data": {
        "logistics": [
            {
                "logisticsSid": "LLM01",
                "logisticsName": "Lalamove",
                "logisticsType": "on-demand",
                "available": true
            },
            {
                "logisticsSid": "SENDIT02",
                "logisticsName": "Sendit (On-demand)",
                "logisticsType": "on-demand",
                "available": true
            }
        ]
    }
}

# Prepare Delivery Order

Method: POST
Path: /prepare_delivery
Description: Verify whether the delivery request is valid for the selected logistics or not.

Request Header:

Param Description Required Example
Authorization The OAuth2 authentication with the O2O System Y Bearer {O2O Access Token}
Content-Type The MIME type of this content Y application/json

Request Body:

Param Description Type Required Example
orders DeliveryRequest List<Object> Y DeliveryRequest

Example Request:

curl --location --request POST 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/prepare_delivery' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}' \
--data-raw '{
    "orders": [
        {
            "orderInfo": {
                "refNo": "ORDER-00001",
                "logisticsSid": "LLM01",
                "amount": 1000,
                "cod": false,
                "pickupTime": "2020-04-30T10:10:10+07",
                "optionalRequest": {
                    "opt1": "value1",
                    "DELIVERY_BOX": true
                }
            },
            "packages": [
                {
                    "weight": 1000,
                    "length": 10,
                    "width": 10,
                    "height": 10
                }
            ],
            "packageInfo": {
                "productType": [
                    "normal",
                    "valued"
                ]
            },
            "merchant": {
                "name": "True Shop",
                "firstName": "Mr. True",
                "lastName": "Shop",
                "mobile": "0812345678",
                "email": "shop@true.co",
                "address": "101 Sukhumvit Rd",
                "subDistrict": "บางจาก",
                "district": "พระโขนง",
                "province": "กทม",
                "postcode": "10260",
                "country": "TH",
                "latitude": 13.6851249,
                "longitude": 100.6110206
            },
            "customer": {
                "firstName": "John",
                "lastName": "Doe",
                "mobile": "0987654321",
                "email": "john.doe@gmail.com",
                "address": "89 อาคาร เอไอเอ แคปปิตอล เซ็นเตอร์ Ratchadaphisek Rd",
                "subDistrict": "ดินแดง",
                "district": "ดินแดง",
                "province": "กทม",
                "postcode": "10400",
                "country": "TH",
                "latitude": 13.7622533,
                "longitude": 100.5717568
            }
        }
    ]
}'

Example Response: Success

{
    "status": 200,
    "data": {
        "orders": [
            {
                "refNo": "ORDER-00001",
                "status": "SUCCESS"
            }
        ]
    }
}

# Create Delivery Order

Method: POST
Path: /create_delivery
Description: Verify and create delivery order to the selected logistics.

Request Header:

Param Description Required Example
Authorization The OAuth2 authentication with the O2O System Y Bearer {O2O Access Token}
Content-Type The MIME type of this content Y application/json

Request Body:

Param Description Type Required Example
orders DeliveryRequest List<Object> Y DeliveryRequest

Example Request:

curl --location --request POST 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/create_delivery' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}' \
--data-raw '{
    "orders": [
        {
            "orderInfo": {
            	"refNo": "Q1",
                "logisticsSid": "LLM01",
                "cod": false,
                "pickupTime": "2020-04-30T10:10:10+07",
                "optionalRequest": {
                    "opt1": "value1",
                    "DELIVERY_BOX": true
                }
            },
            "packages": [
                {
                    "weight": 1000,
                    "length": 10,
                    "width": 10,
                    "height": 10
                }
            ],
            "merchant": {
                "name": "test",
                "firstName": "true",
                "lastName": "Shop",
                "mobile": "0812345678",
                "email": "shop@true.co",
                "address": "ถนน พหลโยธิน",
                "subDistrict": "ถนนพญาไท",
                "district": "เขตราชเทวี",
                "province": "กรุงเทพมหานคร",
                "postcode": "10400",
                "country": "thailand",
                "latitude": 13.762641,
                "longitude": 100.552096
            },
            "customer": {
                "firstName": "John",
                "lastName": "Doe",
                "mobile": "0868818358",
                "email": "john.doe@gmail.com",
                "address": "57 ถนนรัชดาภิเษก",
                "subDistrict": "ดินแดง",
                "district": "ดินแดง",
                "province": "กทม",
                "postcode": "10400",
                "country": "thailand",
                "latitude": 13.7615723,
                "longitude": 100.5657865
            }
        }
    ]
}'

Example Response: Success

{
    "status": 200,
    "data": {
        "orders": [
            {
                "refNo": "Q1",
                "orderNo": "DO-S0837LZMM7",
                "status": "PENDING",
                "postPaid": false,
                "documents": [
                    {
                        "trackingNo": "855875168457723904",
                        "currentStatus": "PENDING"
                    }
                ],
                "packages": [
                    {
                        "weight": 1000,
                        "length": 10,
                        "width": 10,
                        "height": 10
                    }
                ]
            }
        ]
    }
}

# Get Quotation

Method: POST
Path: /get_quotation
Description: Get delivery fee. Some logistics might not support this feature.

Request Header:

Param Description Required Example
Authorization The OAuth2 authentication with the O2O System Y Bearer {O2O Access Token}
Content-Type The MIME type of this content Y application/json

Request Body:

Param Description Type Required Example
orders DeliveryRequest List<Object> Y DeliveryRequest

Example Request:

curl --location --request POST 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/get_quotation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}' \
--data-raw '{
    "orders": [
        {
            "orderInfo": {
            	"refNo": "Q1",
                "logisticsSid": "LLM01",
                "cod": false,
                "pickupTime": "2020-04-10T10:10:10+07",
                "optionalRequest": {
                    "opt1": "value1",
                    "DELIVERY_BOX": true
                }
            },
            "packages": [
                {
                    "weight": 1000,
                    "length": 10,
                    "width": 10,
                    "height": 10
                },
                {
                    "weight": 1000,
                    "length": 75,
                    "width": 75,
                    "height": 75
                }
            ],
            "merchant": {
                "name": "test",
                "firstName": "true",
                "lastName": "Shop",
                "mobile": "0812345678",
                "email": "shop@true.co",
                "address": "ถนน พหลโยธิน",
                "subDistrict": "ถนนพญาไท",
                "district": "เขตราชเทวี",
                "province": "กรุงเทพมหานคร",
                "postcode": "10400",
                "country": "thailand",
                "latitude": 13.762641,
                "longitude": 100.552096
            },
            "customer": {
                "firstName": "John",
                "lastName": "Doe",
                "mobile": "0868818358",
                "email": "john.doe@gmail.com",
                "address": "57 ถนนรัชดาภิเษก",
                "subDistrict": "ดินแดง",
                "district": "ดินแดง",
                "province": "กทม",
                "postcode": "10400",
                "country": "thailand",
                "latitude": 13.7615723,
                "longitude": 100.5657865
            }
        }
    ]
}'

Example Response: Success

{
    "status": 200,
    "data": {
        "orders": [
            {
                "refNo": "Q1",
                "fee": 275.00,
                "currency": "THB",
                "packages": [
                    {
                        "weight": 1000,
                        "length": 10,
                        "width": 10,
                        "height": 10,
                        "success": true,
                        "fee": 77.00
                    },
                    {
                        "weight": 1000,
                        "length": 75,
                        "width": 75,
                        "height": 75,
                        "success": true,
                        "fee": 198.00
                    }
                ]
            }
        ]
    }
}

Example Response: Error

{
    "status": 200,
    "data": {
        "orders": [
            {
                "refNo": "Q1",
                "fee": 77,
                "currency": "THB",
                "packages": [
                    {
                        "weight": 1000,
                        "length": 10,
                        "width": 10,
                        "height": 10,
                        "success": true,
                        "fee": 77
                    },
                    {
                        "success": false,
                        "error": "Failed",
                        "message": "package size is not deliverable"
                    }
                ]
            }
        ]
    }
}

# Get Waybill

Method: GET
Path: /waybill?order_no={order_no}

Request Header:

Param Description Required Example
Authorization The OAuth2 authentication with the O2O System Y Bearer {O2O Access Token}
Content-Type The MIME type of this content Y application/json

Example Request:

curl --location --request GET 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/waybill?order_no=DO-Y8RV1HU7GG' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}'

Example Response:

Binary of PDF file

# Get Tracking Status

Method: GET
Path: /tracking?tracking_no={orderNo|trackingNo}

Request Header:

None.

Example Request:

curl --location --request GET 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/tracking?tracking_no=DO-EQ0SGBBHS2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}'

Example Response:

{
    "status": 200,
    "data": {
        "tracking": [
            {
                "refNo": "Q1",
                "orderNo": "DO-EQ0SGBBHS2",
                "trackingNo": "ACC0000050005",
                "currentStatus": "PENDING",
                "logisticsLogo": "https://th.kerryexpress.com/th/img/header/logo.png",
                "logisticsName": "Kerry",
                "logisticsCompanySid": "KERRY",
                "history": [
                    {
                        "status": "PENDING",
                        "message": "waiting for logistics to pick up",
                        "createdAt": "2020-04-09T11:44:22+07"
                    }
                ]
            }
        ]
    }
}

# Get Delivery Order

Method: GET
Path: /get_delivery?order_no={orderNo}

Request Header:

Param Description Required Example
Authorization The OAuth2 authentication with the O2O System Y Bearer {O2O Access Token}
Content-Type The MIME type of this content Y application/json

Query String Parameter:

Key Description Required Example Possible Values
load_history Include delivery order history in response N load_history=true true, false
check_driver_location Include driver location in response N check_driver_location=true true, false

Example Request:

curl --location --request GET 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/get_delivery?order_no=DO-YL6UZG1CCM&load_history=true&check_driver_location=true' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}'

Example Response:

{
    "status": 200,
    "data": {
        "order": {
            "orderNo": "DO-YL6UZG1CCM",
            "refNo": "Q1",
            "status": "PROCESSING",
            "merchantName": "S BG",
            "merchantFirstName": "S",
            "merchantLastName": "BG",
            "merchantMobile": "0812345678",
            "merchantEmail": "shop@true.co",
            "merchantAddress": "ถนน พหลโยธิน",
            "merchantSubDistrict": "ถนนพญาไท",
            "merchantDistrict": "เขตราชเทวี",
            "merchantProvince": "กรุงเทพมหานคร",
            "merchantPostcode": "10400",
            "merchantCountry": "thailand",
            "merchantLatitude": 13.76264100,
            "merchantLongitude": 100.55209600,
            "customerFirstName": "Winnie",
            "customerLastName": "Bonn",
            "customerMobile": "0868818358",
            "customerEmail": "winnie.bonn@gmail.com",
            "customerAddress": "57 ถนนรัชดาภิเษก",
            "customerSubDistrict": "ดินแดง",
            "customerDistrict": "ดินแดง",
            "customerProvince": "กทม",
            "customerPostcode": "10400",
            "customerCountry": "thailand",
            "customerLatitude": 13.76157230,
            "customerLongitude": 100.56578650,
            "postPaid": false,
            "preferPickupTime": "2020-04-17T13:00:00+07",
            "createdAt": "2020-04-17T08:55:39+07",
            "modifiedAt": "2020-04-17T10:55:14+07",
            "optionalRequest": {
                "opt1": "value1",
                "DELIVERY_BOX": true
            },
            "documents": [
                {
                    "companySid": "LALAMOVE",
                    "trackingNo": "855853357300977664",
                    "docType": "delivery",
                    "docGroupId": "1718759F715-CW0P2",
                    "docSeq": 1,
                    "currentStatus": "PICKING",
                    "currentOriginalStatus": "ON_GOING",
                    "history": [
                        {
                            "status": "PENDING",
                            "message": "waiting for logistics to pick up",
                            "createdAt": "2020-04-17T08:55:52+07"
                        },
                        {
                            "status": "PENDING",
                            "originalStatus": "ASSIGNING_DRIVER",
                            "message": "matching shipment with a driver",
                            "driverName": "",
                            "driverPhone": "",
                            "driverPlateNumber": "",
                            "createdAt": "2020-04-17T09:00:21+07"
                        },
                        {
                            "status": "PICKING",
                            "originalStatus": "ON_GOING",
                            "message": "shipment is matched with a driver",
                            "driverName": "Peam Pummarin",
                            "driverPhone": "0874992880",
                            "driverPlateNumber": "",
                            "createdAt": "2020-04-17T10:55:13+07"
                        }
                    ]
                }
            ],
            "packages": [
                {
                    "weight": 500,
                    "length": 10,
                    "width": 10,
                    "height": 10
                },
                {
                    "weight": 300,
                    "length": 5,
                    "width": 5,
                    "height": 5
                }
            ]
        }
    }
}

# Cancel Delivery Order

Method: POST
Path: /cancel_delivery

Request Header:

Param Description Required Example
Authorization The OAuth2 authentication with the O2O System Y Bearer {O2O Access Token}
Content-Type The MIME type of this content Y application/json

Example Request:

curl --location --request POST 'https://platform.weomni-test.com/bifrost/api/ali/projects/{projectId}/cancel_delivery' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {O2O Access Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "orderNo": "DO-2K3DH9132D",
    "documents": [
        {
            "trackingNo": "856939252246646784"
        }
    ]
}'

Example Response: Success

{
    "status": 200,
    "data": {
        "orderNo": "DO-2K3DH9132D",
        "documents": [
            {
                "trackingNo": "856939252246646784",
                "status": "SUCCESS"
            }
        ]
    }
}

Example Response: Error

{
    "status": 400,
    "error": "Bad Request",
    "message": "there is some failed request",
    "data": {
        "order": {
            "orderNo": "DO-25Y4UKMCJG",
            "documents": [
                {
                    "trackingNo": "855432853058490368",
                    "status": "FAILED",
                    "message": "document is not PENDING or PICKING"
                }
            ]
        }
    }
}

# Client Webhook (Callback update delivery status to client)

Method: POST
Description: The client can receive the changes of delivery status by providing webhook URL
The system will POST the TrackingResponse to the given webhook.

Example Webhook Request Body:

{
  "orderNo": "DO-NK8KA54GXE",
  "refNo": "MCDEVLIERY-006",
  "trackingNo": "855415222532313088",
  "currentStatus": "PICKING",
  "logisticsLogo": "https://www.lalamove.com/hs-fs/hubfs/Design/logo/logo_width200-01-1.png?width=200&name=logo_width200-01-1.png",
  "logisticsName": "Lalamove",
  "logisticsCompanySid": "LALAMOVE",
  "history": [
    {
      "status": "PENDING",
      "message": "waiting for logistics to pick up",
      "createdAt": "2020-04-16T03:54:43+07",
      "driverName": "Peam Pummarin",
      "driverPhone": "0874992880",
      "driverPlateNumber": "xxx"
    }
  ]
}

# Appendix I: Request & Response Models

# Request Models

# DeliveryRequest

The following model can be used for getting quotation, prepare delivery order or create delivery order

Field Name Type Required Description
orderInfo OrderInfo Y
merchant ContactInfo Y
customer ContactInfo Y
packages PackageInfo * Array
packageQty number * Ignore when packages is specified

* some logistics requires only number of quantity of delivering package (box), but some logistics requires more details of the package e.g. weight, size, etc.

# OrderInfo

Field Name Type Required Description
refNo string Y The reference number of client order.
logisticsSid string Y Logistics slug id
amount number * ราคาสินค้า (ราคาสำหรับเก็บเงินปลายทาง)
cod boolean N
pickupTime string * Require เมื่อต้องการ get delivery quotation
Format: yyyy-MM-dd HH:mm:ss
E.g. 2019-08-23 23:59:59
optionalRequest Map<String, String> N สำหรับใส่ optional request เช่น insurance, บริการช่วยยกของ, บริการห้องเก็บความเย็น ฯลฯ
  • { "DELIVERY_BOX": true } -> ต้องการมอเตอร์ไซค์ที่มีกล่องใส่อาหาร

# ContactInfo

Field Name Type Required Description
name string Y Shop name / company name
firstName string Y Contact person first name
lastName string Y Contact person last name
mobile string Y
email string Y
address string Y บ้านเลขที่ ตึก ชั้น หมู่ ตรอก ซอย ถนน
subDistrict string Y แขวง / ตำบล
district string Y เขต / อำเภอ
province string Y จังหวัด
postcode string Y รหัสไปรษณีย์
country string Y Format: ISO 3166-1 alpha-2
E.g. TH
latitude number Y
longitude number Y

# PackageInfo

Field Name Type Required Description
weight number grams
length number cm
width number cm
height number cm
productType array N เช่น normal, fresh_food, high_value
price number N ราคาสินค้า

# Response Models

All public APIs will be responded in this format.

Field Name Type Description
status number Status code
error string Error code
message string Error message
data JSON Json ResponseData

# API Response Example

Case Example
success
                    
{
    "status": 200, 
    "data": {
        //.... ResponseData
    } 
} 
                    
                
failed
                    
{
    "status":400,
    "error":"Client Not Found",
    "message":"..."
}
                    
                

# Status Code (HTTP status code)

Code Description
200 OK
400 Bad request
401 Unauthorized
404 Not found
500 Internal server error

# ResponseData

The response data for each APIs.

# LogisticsResponse

Field Name Type Description
logisticsSid string Logistics slug id
logisticsName string Logistics name
logisticsType string
  • normal
  • on-demand
  • sameday
available boolean false when the logistics is after cut-off time.

# QuotationResponse

Field Name Type Description
refNo string The reference number from client
fee number The total delivery fee
currency string The fee currency
packages QuotationPackageResponse [] Array of QuotationPackageResponse
error string Error code
message string Error message

# QuotationPackageResponse

Field Name Type Description
weight number Package weight in grams
length number Package length in cm
width number Package width in cm
height number Package height in cm
fee number The delivery fee of this package.
It value will be present when success is true.
success boolean
error string Error code
message string Error message

# DeliveryResponse

Response for creating delivery order api.

Field Name Type Description
orderNo string The order number
refNo string The reference number from client
status string Order status
error string Error code when failed to confirm
message string Error message when failed to confirm
documents DocumentResponse [] Only trackingNo and currentStatus are returned
packages

# OrderResponse

Field Name Type Description
orderNo string The order number
refNo string The reference number from client.
status string The order status
merchantName string
merchantContactName string
merchantMobile string
merchantEmail string
merchantAddress string
merchantSubDistrict string
merchantDistrict string
merchantProvince string
merchantPostcode string
merchantLatitude number
merchantLongitude number
customerFirstName string
customerLastName string
customerMobile string
customerEmail string
customerAddress string
customerSubDistrict string
customerDistrict string
customerProvince string
customerPostcode string
customerLatitude number
customerLongitude number
amount number
postPaid boolean
productType array Array of string
optionalRequest Json Json object with string key and value
documents DocumentResponse [] Array

# DriverLocation

Field Name Type Description
lat string latitude
lng string longitude

# TrackingResponse

Field Name Type Description
orderNo string The order number
refNo string The reference number from client.
trackingNo string The logistics tracking no
currentStatus string The current document status
logisticsLogo string Logistics logo url
logisticsName string The logistics name
logisticsCompanySid string The logistics company sid
history DocumentHistoryResponse [] Array of the document history ordered by newest to oldest.

# DocumentResponse

Field Name Type Description
companySid string The logistics company slug id
trackingNo string The logistics tracking no
docType string delivery
docGroupId string Group id of documents
docSeq int Sequence of document in group
currentStatus string The current status of the document
history DocumentHistoryResponse [] Array of the document history ordered by newest to oldest.

# DocumentHistoryResponse

Field Name Type Description
status string The document status
message string The status message
createdAt string Date time in the following format.
yyyy-MM-ddTHH:mm:ssX
e.g 2019-09-09T06:05:57+07
Last Updated: 7/17/2020, 11:09:13 AM