# 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 recipientformat
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"
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)。

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

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
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"
    }
}