# Order management

# 2D-API-1.1 Create Order

POST /order/homeexpress/create


API type	Request API
Usage	Create Zeek2Door order

# API usage - Delivery product parameters

Please input the request parameters according to the Zeek2Door delivery product.

Parameter	Pick-up Delivery (Scheduled delivery / Self pickup / Economy Service)	Warehouse Delivery (Scheduled delivery / Self pickup / Economy Service)	Lite post
`product_code`	Scheduled delivery：`HDP-ECOMM-H` Self pickup：`HDP-ECOMM-L` Economy Service：`HDP-ECN-H`	Scheduled delivery (Warehouse in)`HDP-SFWH-H` Self pickup (Warehouse in)：`HDP-SFWH-L` Economy service (Warehouse in)：`HDP-WHECN-H`	Lite post: `HDP-PND-1-H`
Client order ID `client_order_id`	Required	Required	Required
Sender `sender.name`	Required	Not required	Required
Sender country code `sender.country_code`	Required	Not required	Required
Sender phone `sender.phone`	Required	Not required	Required
Sender address type `sender.type`	Input `11`	Not required	Input `11`
Sender address `sender.address`	Required	Not required	Required
Pickup date `pickup.date`	Required	Optional ** Refer to "Dropoff date" `delivery.date`.	Required
Pickup period `pickup.period`	Required	Not required	Required
Recipient Phone `recipient.phone`	Scheduled delivery : Required Self pickup : Required, only supports phone number starting from 4, 5, 6, 7, 8, 9 Economy Service : Required	Scheduled delivery (Warehouse in) : Required Self pickup (Warehouse in) : Required, only supports phone number starting from 4, 5, 6, 7, 8, 9 Economy Service (Warehouse in) : Required	Lite post : Required, only supports phone number starting from 4, 5, 6, 7, 8, 9
Recipient address type `recipient.type`	Scheduled delivery：`11` Self pickup：`4` Economy Service：`11`	Scheduled delivery (Warehouse in)：`11` Self pickup (Warehouse in)：`4` Economy Service (Warehouse in)：`11`	Lite post : `11`
Recipient address `recipient.address`	Scheduled delivery：Required Self pickup：Not required EconomyService：Required	Scheduled delivery (Warehouse in)：Required Self pickup (Warehouse in)：Not required Economy Service (Warehouse in)：Required	Lite post : Required
Locker code `recipient.locker_code`	Scheduled delivery：Not required Self pickup：Required Economy Service：Not required	Scheduled delivery (Warehouse in)：Not required Self pickup (Warehouse in)：Required Economy Service (Warehouse in)：Not required	Lite post : Not Required
Dropoff date `delivery.date`	Scheduled delivery：Optional Self pickup：Not required Economy Service：Optional	Scheduled delivery (Warehouse in)：Optional Self pickup (Warehouse in)：Not required Economy Service (Warehouse in)：Optional ** When "Pickup date" `pickup.date` is not being input, Zeek will determine the most suitable dropoff date according to the parcel-warehouse-arrival time. Thus, you are not required to input `delivery.date` and `delivery.period`.	Lite post : Optional
Dropoff period `delivery.period`	Scheduled delivery：Optional Self pickup：Not required Economy Service：Optional	Scheduled delivery (Warehouse in)：Optional Self pickup (Warehouse in)：Not required Economy Service (Warehouse in)：Optional ** Refer to "Dropoff date" `delivery.date`.	Lite post : Optional
Box size `box_size_code`	Scheduled delivery：Required Self pickup：Required, XS only Economy Service：Required	Scheduled delivery (Warehouse in)：Optional Self pickup (Warehouse in)：Required, XS only Economy Service (Warehouse in)：Required	Lite post : Required
Box quantity `box_quantity`	Scheduled delivery：Required, accept integers from 1 to 254 Self pickup：Required, accept 1 only Economy Service：Required, accept integers from 1 to 254 *Please contact our Sales for the supported quantity and weight in particular delivery product.	Scheduled delivery (Warehouse in)：Optional, accept integers from 1 to 254 Self pickup (Warehouse in)：Optional, accept 1 only Economy Service (Warehouse in)：Optional,accept integers from 1 to 254. *Please contact our Sales for the supported quantity and weight in particular delivery product.	Lite post : Optional, accept 1 only *Please contact our Sales for the supported quantity and weight in particular delivery product.
Total parcel weight `total_weight`	Required, accepts from 10 (exclusive, ie. 0.01Kg) to the maximum integer value. Max. value of each service： Scheduled delivery：100000 (ie. 100Kg) Self pickup：5000 (ie. 5Kg) Economy Service：100000 (ie. 100Kg)	Optional, accepts from 10 (exclusive, ie. 0.01Kg) to the maximum integer value. Max. value of each service： Scheduled delivery (Warehouse in)：100000 (ie. 100Kg) Self Pickup (Warehouse in)：5000 (ie. 5Kg) Economy Service (Warehouse in)：100000 (ie. 100Kg)	Optional, accepts from 10 (exclusive, ie. 0.01Kg) to the maximum integer value. Max. value of each service： Lite post : 2000 (ie. 2Kg)
Item details `item_detail`	Maximum 50 items	Not limited	Maximum 50 items
Item code `item_detail.code`	Optional	Required	Optional
Item name `item_detail.name`	Optional	Required	Optional
Item price `item_detail.price`	Optional	Optional	Optional
Item quantity `item_detail.quantity`	Optional	Required	Optional

# API Usage - About "Value plus" VAS

# About "Value plus"

The basic compensation amount of Zeek2Door is HKD 200 per order, or the actual value of the demaged / lost goods. (The lowest one will be applied).

"Value plus" is a optional VAS offered by Zeek2Door.

Please contact our Sales for further details of "Value plus" compensation coverage.

# Input VAS parameters

In order to apply "Value plus", please input the specific parameter values:

vas.code：Input HK2DOOR_VALUEPLUS
vas.value：Input parcel value

# Request

For ^T , please refer to API usage - Delivery product parameters above

Name	Type	Mandatory	Default	Description	Remarks
merchant_id	int	Yes	-	Merchant ID	Provided by Zeek
client_order_id	string(30)	Yes*	-	Client order ID	^T Cannot send the same client_order_id multiple times within 60 seconds.
client_shipment_code	string(30)	No	-	Client waybill number	Cannot duplicate
shipment_code	string	No	-	Zeek waybill number	Only applicable to merchants who are using particular Zeek2Door services. No need to input for most developers.
product_code	string	No*	`HDP-ECOMM-H`	Product code	^T
box_size_code	string	No*	-	Box size	^T Refer to Box size code.
box_quantity	int	No*	-	Box quantity	^T
total_weight	int	No*	-	Total weight	^T Unit：Gram
remark	string(1024)	No	-	Remarks
vas	array	No	`[]`	VAS
vas.code	string	Yes	-	VAS code
vas.count	string	No	-	VAS count (Please refer to the rule of corresponding VAS)
vas.value	string	No	-	VAS value (Please refer to the rule of corresponding VAS)
vas.fee	string	No	-	VAS amount (Please refer to the rule of corresponding VAS)
cod	object	No	-	COD	- Only applicable to merchants who enabled the COD service. Please contact Zeek team for amount limit and status. - Only applicable to Zeek2Door and Economy, not support Parcel Locker.
cod.service_fee	string	No	-	Freight charge COD	- Support 2 decimal places. - Example：`"20.30"`
cod.cash	string	No	-	Item value COD	- Support 2 decimal places. - Example：`"20.30"`
item_detail	array	Yes	-	Item details	^T Refer to `item_detail` format
sender	object	Yes	-	Sender information	^T Refer to `sender` format
recipient	object	Yes	-	Recipient information	^T Refer to `recipient`format
pickup	object	Yes	-	Pickup time	^T Refer to `pickup` format
delivery	object	Yes	-	Dropoff time	^T Refer to `delivery` format

例子:

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "merchant_id": 123,
        "client_order_id": "15104092022333",
        "client_shipment_code": "VLV171120-1218",
        "shipment_code": "HO171120",
        "product_code": "HDP-ECOMM-H",
        "box_size_code": "XS",
        "box_quantity": 3,
        "total_weight": 1000,
        "remark": "",
        "vas": [
            {
                "code": "HK2DOOR_VALUEPLUS",
                "value": "3.00"
            },
        ],
        "item_detail": [
            {
                // Refer to item_detail format
            }
        ],
        "sender": {
            // Refer to sender format
        },
        "recipient": {
            // Refer to recipient format
        },
        "pickup": {
            // Refer to pickup format
        },
        "delivery": {
            // Refer to delivery format
        }
    }
}

item_detail format

Name	Type	Mandatory	Default	Description	Remarks
code	string（128）	Yes	-	Item code
name	string（128）	Yes	-	Item code
price	int	Yes	-	Item price	Unit：Cent (1 Dollar = 100 Cents)
quantity	int	Yes	-	Quantity

sender format

Name	Type	Mandatory	Default	Description	Remarks
type	int	Yes	-	Address type	^T
name	string（128）	Yes	-	Sender name
country_code	string（5）	Yes	-	Sender country code
phone	string（64）	Yes	-	Sender phone
district	string（64）	Yes	-	District	^T Please input `HK`
address	object / string	Yes	-	Sender address	^T Refer to `sender.address` format
longitude	string（32）	No	-	Longitude
latitude	string（32）	No	-	Latitude

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        // Other data

        "sender": {
            "type": 11,
            "name": "VLV Sender",
            "country_code":"852",
            "phone": "91234567",
            "address": {
                "flat": "1",
                "floor": "3",
                "block": "",
                "building": "明珠大楼",
                "street": "鴨寮街195-201號",
                "district": "深水埗區",
                "area": "九龍"
            },
            "longitude": "",
            "latitude": ""
        },
        
        // Other data
    }
}

sender.address format

Name	Type	Mandatory	Default	Description	Remarks
flat	string	No	-	Flat
floor	string	No	-	Floor
block	string	No	-	Block
building	string	Yes	-	Building
street	string	Yes	-	Street
district	string	Yes	-	District	Refer to Area & District
area	string	Yes	-	Area	Refer to Area & District
postal_code	string	No	-	Postal code

Reminder：

If area and district are not input acccording to "Area & District", Please input the latitude and longitude in sender.
The length of all parameters cannot exceed 200 characters.

recipient format

Name	Type	Mandatory	Default	Description	Remarks
type	int	Yes	-	Address type	^T
name	string（128）	Yes	-	Recipient name
country_code	string（5）	No	-	Recipient country code	Parcel Locker：Only 852 is supported
phone	string（64）	Yes	-	Recipient phone	Parcel Locker：Only supports phone number starting from 4, 5, 6, 7, 8, 9
country_code_2	string（5）	No	-	Backup recipient country code	Parcel Locker：Only 852 is supported
phone_2	string（64）	No	-	Backup recipient phone	Parcel Locker：Only supports phone number starting from 4, 5, 6, 7, 8, 9
district	string（64）	Yes	-	District	Please input `HK`
address	object / string	Yes	-	Recipient address	^T Refer to `recipient.address` format
locker_code	string	Yes	-	Locker code	^T
longitude	string（32）	No	-	Longitude
latitude	string（32）	No	-	Latitude

"Zeek2Door" example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        // Other data

        "recipient": {
            "type": 11,
            "name": "Cliff",
            "phone": "91234567",
            "country_code":"852",
            "phone_2": "91234567",
            "country_code_2":"852",
            "address": {
                "flat": "",
                "floor": "2",
                "block": "",
                "building": "東廣場",
                "street": "成業街7號",
                "district": "觀塘區",
                "area": "九龍"
            },
            "longitude": "",
            "latitude": ""
        },
        
        // Other data
    }
}

"Parcel Locker" example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        // Other data

        "recipient": {
            "type": 4,
            "name": "Cliff",
            "phone": "91234567",
            "country_code":"852",
            "phone_2": "91234567",
            "country_code_2":"852",
            "locker_code": "H852UA36P"
        },
        
        // Other data
    }
}

recipient.address format

Name	Type	Mandatory	Default	Description	Remarks
flat	string	No	-	Flat
floor	string	No	-	Floor
block	string	No	-	Block
building	string	Yes	-	Building
street	string	Yes	-	Street
district	string	Yes	-	District	Refer to Area & District
area	string	Yes	-	Area	Refer to Area & District
postal_code	string	No	-	Postal code

Reminder：

If area and district are not input acccording to "Area & District", Please input the latitude and longitude in sender.
The length of all parameters cannot exceed 200 characters.

pickup format

Name	Type	Mandatory	Default	Description	Remarks
date	string	Yes	-	Pickup date	Example：`2018-07-18`
period	string	Yes	-	Pickup period	Example：`12:00-16:00`

delivery format

Name	Type	Mandatory	Default	Description	Remarks
date	string	Yes	-	Dropoff date	Example：`2018-07-18`
period	string	Yes	-	Dropoff period	Example：`12:00-16:00`

# Response

 {
    "error": 0,
    "data": {
        "order_id": "20180615080181522",// Order ID
        "client_order_id": "15104092022333",// Client order ID
        "order_url": "https://track.zeek.one/hk/en/HD2022020929901111/b4cee0", // Order Tracker URL
        "timestamp": 1510680568
    }
}

# 2D-API-1.2 Get PDF waybill

POST /order/homeexpress/waybill_pdf


API type	Request API
Usage	Get waybill in PDF file

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Yes	-	Order ID
merchant_id	int	Yes	-	Merchant ID
paper_size	string	No	`"A4"`	Page size	`"A4"` / `"100X150"` * Some self pickup point providers may not support `paper_size` parameters
copies	int	No	2	Number of copies	Only applicable for `"A4"`. Please input either `1`（1 copy in a A4 sized paper）or `2`（2 copies in a A4 sized paper）。* Some self pickup point providers may not support 'copies' parameters

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "merchant_id": 123,
        "order_id": "20180615080181522",
        "paper_size": "A4",
        "copies": "1"
    }
}

# Response

 {
    "error": 0,
    "data": {
        "order_id": "20180615080181522",// Order ID
        "client_order_id": "14570817752333",// Client order ID
        "waybill_pdf_url": "", // PDF file URL
        "timestamp": 1510680568
    }
}

# 2D-API-1.3 Get JSON waybill

POST /order/homeexpress/waybill


API type	Request API
Usage	Get waybill in JSON format

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Yes	-	Order ID
merchant_id	int	Yes	-	Merchant ID

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "merchant_id": 123,
        "order_id": "20180615080181522"
    }
}

# Response

{
    "error": 0,
    "data": {
        "order_id": "HD2018082317013392",
        "tracking_no": "HD2018082317013392", // Same as order_id
        "shipment_code": "TEST12345", // Zeek waybill number
        "client_order_id": "VLV-Test20180823771522920",
        "client_ref_id": "VLV-Test20180823771522920", // Same client_order_id
        "client_shipment_code": "PU12345", // Client waybill number
        "tpl_order_id": "GF000003191HK", // 3PL order id
        "tpl_waybill_no": "GF000003165HK", // 3PL waybill number

        "lang": "zh_TW",
        "region": "HK",
        "fee": {
            "payment_method": "1",
            "shipping_fee": "0.00",
            "item_fee": "0.00",
            "amount": "0.00"
        },
        "box_size_code": "XS",
        "box_quantity": 1,
        "total_weight": "3.00",
        "product": "即收即送",
        "service_type": "即收即送",
        "remark": "Testing Order From VLV",
        "sender": {
            "phone": "91234567",
            "name": "VLV Sender",
            "address": "中環皇后大道中9號",
            "district": "",
            "region": "",
            "area": ""
        },
        "recipient": {
            "phone": "91234567",
            "phone_2": "",
            "name": "Cliff",
            "address": "尖沙咀科學館道2號香港科學館",
            "district": "",
            "region": "",
            "area": "",
            "locker_code": "",
            "locker_address": ""
        },
        "pickup": {
            "date": "2018-08-24",
            "period": "12:00 - 16:00"
        },
        "delivery": {
            "date": "2018-08-24",
            "period": "18:00 - 23:00"
        },
        "status": { // Order status
            "code": "9005",
            "name": "正在前往取件",
            "lastmodify": "2020-07-22 16:06"
        },
        "partner": { // Partner info
            "name": "陳大文",
            "country_code": "852",
            "phone": "17612008",
            "position": {
                "code": "R", // Position code
                "name": "電單車司機", // Position name
                "vehicle_number": "RJ 456" // Vehicle number
            }
        },
        "receipts": [ // ePOD (Electronic proof of delivery) image URLs
            "https://ap1-img.zeek.one/1.jpeg",
            "https://ap1-img.zeek.one/2.jpeg",
            "https://ap1-img.zeek.one/3.jpeg",
        ]
    }
}

# 2D-API-1.9 Order status callback

POST The endpoint URL is provided by developer


API type	Callback API
Usage	- When order status updates, Zeek platform will send latest status code to the callback API. - The order statuses in Order status code (From July 2021) are being sent.

# Request failure handling

When Zeek platform cannot receive a successful response from callback API, it will be regarded as failure. Then the platform will retry. The retry frequency is 15/15/30/180/1800/1800/1800/1800/3600 in seconds.

# API Authentication

Zeek platform will pass signature to developer's callback API. The signature is generated according to Authentication. Therefore, please verify the signature by the same way.

# Request

Name	Type	Mandatory	Default	Description	Remarks
merchant_id	string	Yes	-	Merchant ID
order_id	string（128）	Yes	-	Order ID
shipment_code	string（128）	Yes	-	Zeek waybill number
client_order_id	string	Yes	-	Client order Id
client_shipment_code	string	Yes	-	Client waybill number
order_status	int	Yes	-	Order status code	Refer to Order status code (From July 2021)
status_desc	string	Yes	-	Status description
exception_description	string	Yes	-	Exception description
timestamp	int	Yes	-	Status trigger time

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "order_id": "HD2018080772026801",
        "shipment_code": "HD2018080772026801",
        "client_order_id": "201808076580818698",
        "client_shipment_code":"", 
        "order_status": 9005,
        "status_desc": "貨件正等待攬收",
        "exception_description":"派送失敗，貨件已退回集散中心",
        "merchant_id": "143",
        "timestamp": 1533609085
    }
}

# Response

{
    "error": 0,
    "err_msg": "",
}

# 2D-API-1.10 Get order event tracking

POST /order/homeexpress/event_track


API type	Request API
Usage	Get an order event tracking

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Yes	-	Order Id
merchant_id	int	Yes	-	Merchant ID

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "order_id": "2018080772026801",
        "merchant_id": "2"
    }
}

# Response

{
  "error": 0,
  "data": {
    "events": [
      {
        "message": "收到商家下單訊息 HD2021071564998952",
        "datetime": "2021-07-15 18:24"
      },
      {
        "message": "貨件到達集散中心 (Zeek物流中心)。",
        "datetime": "2021-07-15 18:27"
      },
      {
        "message": "貨件已攬收。",
        "datetime": "2021-07-15 18:27"
      },
      {
        "message": "貨件派送中。預計於2021-07-16 18:00-23:00派送。",
        "datetime": "2021-07-15 18:31"
      },
      {
        "message": "貨件已派送至收方，感謝使用，期待再次為您服務。",
        "datetime": "2021-07-15 18:32"
      }
    ]
  }
}

# 2D-API-1.5 Order status callback (Old version)

POST The endpoint URL is provided by developer


API type	Callback API
Usage	- When order status updates, Zeek platform will send latest status code to the callback API. - The order statuses in Order status code (Old version) are being sent.

# Request failure handling

# API Authentication

Zeek platform will pass signature to developer's callback API. The signature is generated according to Authentication. Therefore, please verify the signature by the same way.

# Request

Name	Type	Mandatory	Default	Description
order_id	string（128）	Yes	-	Order ID
client_order_id	string	Yes	-	Client order ID
timestamp	int	Yes	-	Timestamp
order_status	int	Yes	-	Order status
status_desc	string	Yes	-	Status description

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "order_id": "2018080772026801",
        "client_order_id": "201808076580818698",
        "timestamp": 1533609085,
        "order_status": 2,
        "status_desc": "貨件派送中"
    }
}

# Response

{
    "error": 0,
    "err_msg": "",
}

# 2D-API-1.6 Get order status tracking (Old version)

POST /order/homeexpress/list_order_log


API type	Request API
Usage	- Get an order status tracking. - The order statuses in Order status code (Old version) are being sent.

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Yes	-	Order ID
merchant_id	int	Yes	-	Merchant ID

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "order_id": "2018080772026801",
        "merchant_id": "2"
    }
}

# Response

{
  "error": 0,
  "data": [
    {
      "code": "8",
      "title": "寄方下單",
      "detail": "",
      "addtime": "2021-07-15 18:24"
    },
    {
      "code": "1",
      "title": "貨件正等待攬收",
      "detail": "",
      "addtime": "2021-07-15 18:25"
    },
    {
      "code": "9",
      "title": "貨件已攬收",
      "detail": "貨件已攬收。",
      "addtime": "2021-07-15 18:27"
    },
    {
      "code": "2",
      "title": "貨件派送中",
      "detail": "貨件派送中。預計於2021-07-16 18:00-23:00派送。",
      "addtime": "2021-07-15 18:31"
    },
    {
      "code": "4",
      "title": "收方已簽收貨件",
      "detail": "貨件已派送至收方，感謝使用，期待再次為您服務。",
      "addtime": "2021-07-15 18:32"
    }
  ]
}

# 2D-API-1.7 Cancel Order

POST /order/homeexpress/cancel


API type	Request API
Usage	- Cancel an order. - You can only cancel order when its status is `8` and before the cutoff time.

# Request

Name	Type	Mandatory	Default	Description	Remarks
order_id	string（128）	Yes	-	Order Id
merchant_id	int	Yes	-	Merchant ID

Example：

{
    "auth": {
        // Refer to "Specification"
    },
    "data": {
        "meta": {
            // Refer to "Specification"
        },
        "merchant_id" : 2,
        "order_id": "2018080772026801"
    }
}

# Response

{
    "error": 0,
    "data": {
        "order_id": "20180615080181522"
    }
}

← List of APIs General →