# 運單管理

# 2D-API-1.1 創建運單

POST /order/homeexpress/create

接口類型 請求接口
用途 開發者可經此 API 創建Zeek斑馬到家運單

# API 使用說明 - 配送產品請求參數表

在使用不同配送產品時,對傳入接口的請求參數有不同要求。請參考以下請求參數表。

參數 即收即送
(到家/到櫃/特惠)
倉庫即送
(到家/到櫃/特惠)
product_code 到家:HDP-ECOMM-H
到櫃:HDP-ECOMM-L
特惠:HDP-ECN-H
到家:HDP-SFWH-H
到櫃:HDP-SFWH-L
特惠:HDP-WHECN-H
商家訂單號
client_order_id
必填 必填
寄件人
sender.name
必填 不需要填寫
寄件電話區號
sender.country_code
必填 不需要填寫
寄件電話
sender.phone
必填 不需要填寫
寄件地址方式
sender.type
傳入 11 不需要填寫
寄件地址
sender.address
必填 不需要填寫
寄件日期
pickup.date
必填 選填
** 參考 "收件日期" delivery.date 的說明。
寄件時間
pickup.period
必填 不需要填寫
收件地址方式
recipient.type
到家:11
到櫃:4
特惠:11
到家:11
到櫃:4
特惠:11
收件地址
recipient.address
到家:必填
到櫃:不需要填寫
特惠:必填
到家:必填
到櫃:不需要填寫
特惠:必填
收件智能櫃編號
recipient.locker_code
到家:不需要填寫
到櫃:必填
特惠:不需要填寫
到家:不需要填寫
到櫃:必填
特惠:不需要填寫
收件日期
delivery.date
到家:選填
到櫃:不需要填寫
特惠:選填
到家:選填
到櫃:不需要填寫
特惠:選填
** 當開發者沒有傳入"寄件日期" pickup.date時,
Zeek 系統會因應貨件到達倉庫的時間,選擇最合適的派件日期。
故此開發者不需要傳入delivery.datedelivery.period
收件時間
delivery.period
到家:選填
到櫃:不需要填寫
特惠:選填
到家:選填
到櫃:不需要填寫
特惠:選填
** 參考 "收件日期" delivery.date 的說明。
箱的大小
box_size_code
到家:必填
到櫃:必填、只限 XS
特惠:必填
到家:選填
到櫃:必填、只限 XS
特惠:必填
箱的總數
box_quantity
到家:必填、接受 1 - 254 的整數
到櫃:必填、只接受 1
特惠:必填、接受 1 - 254 的整數

*就各產品於實際營運時所支持的數量及重量,請與業務同事確認
到家:選填、接受 1 - 254 的整數
到櫃:選填、只接受 1
特惠:選填、接受 1 - 254 的整數

*就各產品於實際營運時所支持的數量及重量,請與業務同事確認
貨物的重量
total_weight
必填、只接受 0 至最大值的整數。

各服務支持的最大值:
到家:100000 (即是100Kg)
到櫃:5000 (即是5Kg)
特惠:5000 (最大5Kg)
選填、只接受 0 至最大值的整數。

各服務支持的最大值:
到家:100000 (最大100Kg)
到櫃:5000 (最大5Kg)
特惠:5000 (最大5Kg)
物品詳情
item_detail
限制為最高 50項 不限制
商品編號
item_detail.code
選填 必填
貨物名稱
item_detail.name
選填 必填
貨物價值
item_detail.price
選填 選填
商品出庫數量
item_detail.quantity
選填 必填

# API 使用說明 - 有關 Value plus 增值服務

# 有關 Value plus

「Zeek斑馬到家」基本賠償金額為每張訂單港幣200元或以遺失或損壞的貨物的實際現金價值(以較低者為準)。

而「Zeek斑馬到家」亦增設予寄件人選購的增值服務(Value plus)。

有關增值服務(Value plus)的申報價值、物流保障費用及最高賠償金額可向客戶服務部查詢。

# 傳入 VAS 參數

如需使用 Value plus,請於以下參數中傳入指定值:

  • vas.code:傳入 HK2DOOR_VALUEPLUS
  • vas.value:傳入貨物金額

# 請求參數

^T 者請參看上表 API 使用說明 - 配送產品請求參數表

名稱 類型 是否必須 默認值 說明 備註
merchant_id int Yes - 商家ID 平台提供
client_order_id string(30) Yes* - 商家訂單號 ^T
client_shipment_code string(30) No - 第三方運單號
shipment_code string No - 到家運單號 僅供使用到家指定服務的商家使用,一般開發者無需傳入這個字段
product_code string No* HDP-ECOMM-H 產品代號 ^T
box_size_code string No* - 箱的大小 ^T
跟據 Box size code 對應表,傳入代號。
box_quantity int No* - 箱的總數 ^T
total_weight int No* - 貨物的重量 ^T
單位:克
remark string(1024) No - 客戶備註
vas array No [] VAS 服務
vas.code string Yes - VAS 服務 Code
vas.count string No - 選項數量 (請參閱個別的 VAS 傳入規則)
vas.value string No - - 選項金額 (請參閱個別的 VAS 傳入規則)
vas.fee string No - 選項價格 (請參閱個別的 VAS 傳入規則)
item_detail array Yes - 物品詳情 ^T
詳見item_detail結構
sender object Yes - 發件人信息 ^T
詳見sender結構
recipient object Yes - 收件人信息 ^T
詳見recipient結構
pickup object Yes - 寄件時間設定 ^T
詳見pickup結構
delivery object Yes - 收件時間設定 ^T
詳見delivery結構

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "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": [
            {
                // 詳見 item_detail 結構
            }
        ],
        "sender": {
            // 詳見 sender 結構 
        },
        "recipient": {
            // 詳見 recipient 結構 
        },
        "pickup": {
            // 詳見 pickup 結構
        },
        "delivery": {
            // 詳見 delivery 結構
        }
    }
}

item_detail 結構

名稱 類型 是否必須 默認值 說明 備註
code string(128) Yes - 編號
name string(128) Yes - 名稱
price int Yes - 貨物價值 單位:分 (1 元 = 100分)
quantity int Yes - 數量

sender結構

名稱 類型 是否必須 默認值 說明 備註
type int Yes - 地址設置方式 ^T
name string(128) Yes - 發件人姓名
country_code string(5) Yes - 發件人電話區號
phone string(64) Yes - 發件人電話
district string(64) Yes - 區域 ^T
請填 HK
address object / string Yes - 發件地址 ^T
請參考 sender.address 結構。
longitude string(32) No - 地址經度
latitude string(32) No - 地址緯度

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "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": ""
        },
        
        // 其他數據
    }
}

sender.address結構

名稱 類型 是否必須 默認值 說明 備註
flat string No -
floor string No -
block string No -
building string Yes - 大廈
street string Yes - 街道
district string Yes - 地區 請參考 區域及地區參數列表
area string Yes - 區域 請參考 區域及地區參數列表
postal_code string No - 郵政編碼

注意:

  • 若不是按"區域及地區參數列表"傳入areadistrict參數的話,則需要在 sender 結構中傳入地址的經度和緯度 (latitude, longitude)
  • 所有參數的長度總和不能超過 200 字元。

recipient結構

名稱 類型 是否必須 默認值 說明 備註
type int Yes - 地址設置方式 ^T
name string(128) Yes - 收件人姓名
country_code string(5) No - 收件人電話國家區號 到櫃:只支持852
phone string(64) Yes - 收件人電話 到櫃:只支持首位號碼為 4, 5, 6, 7, 8, 9 的電話號碼
country_code_2 string(5) No - 備用收件人電話國家區號 到櫃:只支持852
phone_2 string(64) No - 備用收件人電話 到櫃:只支持首位號碼為 4, 5, 6, 7, 8, 9 的電話號碼
district string(64) Yes - 區域 請填 HK
address object / string Yes - 收件地址 ^T
請參考 recipient.address 結構
locker_code string Yes - 智能櫃編號 ^T
longitude string(32) No - 地址經度
latitude string(32) No - 地址緯度

"到家" 例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "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": ""
        },
        
        // 其他數據
    }
}

"到智能櫃" 例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        // 其他數據

        "recipient": {
            "type": 4,
            "name": "Cliff",
            "phone": "91234567",
            "country_code":"852",
            "phone_2": "91234567",
            "country_code_2":"852",
            "locker_code": "H852UA36P"
        },
        
        // 其他數據
    }
}

recipient.address結構

名稱 類型 是否必須 默認值 說明 備註
flat string No -
floor string No -
block string No -
building string Yes - 大廈
street string Yes - 街道
district string Yes - 地區 請參考 區域及地區參數列表
area string Yes - 區域 請參考 區域及地區參數列表
postal_code string No - 郵政編碼

注意:

  • 若不是按 區域及地區參數列表 傳入areadistrict參數的話,則需要在 recipient 結構中傳入地址的經度和緯度 (latitude, longitude)
  • 所有參數的長度總和不能超過 200 字元。

pickup結構

名稱 類型 是否必須 默認值 說明 備註
date string Yes - 寄件日期 例如:2018-07-18
period string Yes - 寄件時間 例如:12:00-16:00

delivery結構

名稱 類型 是否必須 默認值 說明 備註
date string Yes - 收件日期 例如:2018-07-18
period string Yes - 收件時間 例如:12:00-16:00

# 返回結果

 {
    "error": 0,
    "data": {
        "order_id": "20180615080181522",//平台訂單號
        "client_order_id": "15104092022333",//商家訂單號
        "timestamp": 1510680568 //推送時間
    }
}

# 2D-API-1.2 PDF 格式運單

POST /order/homeexpress/waybill_pdf

接口類型 請求接口
用途 下單後,開發者可請求此 API 獲取 PDF 格式的運單

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
order_id string(128) Yes - 平台訂單號
merchant_id int Yes - 商家ID
paper_size string No "A4" 紙張大小 "A4" / "100X150"
copies int No 2 打印張數 只適用於"A4"
只能傳1(1張A4一個運單)或 2(1張A4兩個運單)。

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "merchant_id": 123,
        "order_id": "20180615080181522",
        "page_size": "A4",
        "copies": "1"
    }
}

# 返回結果

 {
    "error": 0,
    "data": {
        "order_id": "20180615080181522",//平台訂單號
        "client_order_id": "14570817752333",//商家訂單號
        "waybill_pdf_url": "",
        "timestamp": 1510680568 //推送時間
    }
}

# 2D-API-1.3 JSON 格式運單

POST /order/homeexpress/waybill

接口類型 請求接口
用途 下單後,開發者可請求此 API 獲取 JSON 格式的運單

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
order_id string(128) Yes - 平台訂單號
merchant_id int Yes - 商家ID

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "merchant_id": 123,
        "order_id": "20180615080181522"
    }
}

# 返回結果

{
    "error": 0,
    "data": {
        "order_id": "HD2018082317013392",
        "tracking_no": "HD2018082317013392", // 向下兼容,和 order_id 一樣 (Backend compatible, same as order_id)
        "client_order_id": "VLV-Test20180823771522920",
        "client_ref_id": "VLV-Test20180823771522920", // 向下兼容,和 client_order_id 一樣 (Backend compatible, same as client_order_id)
        "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": "",
            "longitude": "114.1584",
            "latitude": "22.2804"
        },
        "recipient": {
            "phone": "91234567",
            "phone_2": "",
            "name": "Cliff",
            "address": "尖沙咀科學館道2號香港科學館",
            "district": "",
            "region": "",
            "area": "",
            "locker_code": "",
            "locker_address": "",
            "longitude": "114.1775",
            "latitude": "22.3009"
        },
        "pickup": {
            "date": "2018-08-24",
            "period": "12:00 - 16:00"
        },
        "delivery": {
            "date": "2018-08-24",
            "period": "18:00 - 23:00"
        }
    }
}

# 2D-API-1.5 運單跟踪狀態回調

POST 由開發者提供

接口類型 回調接口
用途 當訂單狀態更改時,回調開發者提供的回調接口

# 請求失敗處理

當 Zeek 平台調用回調接口,收到的回應不是成功時,平台會判斷為通知失敗,此時平台會定期重新發起通知,通知頻率為15/15/30/180/1800/1800/1800/1800/3600 秒。

# 接口授權

Zeek 平台會以授權和簽名 的方式,在接口傳入簽名,所以開發者需要以同樣的方式去驗證簽名。

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
order_id string(128) Yes - 平台訂單號
client_order_id string Yes - 商家訂單號
timestamp int Yes - 推送時間戳
url_index string Yes - 回調url前綴 order_status
order_status int Yes - 訂單狀態
status_desc string Yes - 狀態描述

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "order_id": "2018080772026801",
        "client_order_id": "201808076580818698",
        "timestamp": 1533609085,
        "url_index": "order_status",
        "order_status": 2,
        "status_desc": "貨件派送中"
    }
}

# 返回結果

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

# 2D-API-1.6 訂單狀態路由

POST /order/homeexpress/list_order_log

接口類型 請求接口
用途 開發者可請求此 API 獲取訂單狀態路由

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
order_id string(128) - 平台訂單號
merchant_id int - 商家ID

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "order_id": "2018080772026801",
        "merchant_id": "2"
    }
}

# 返回結果

{
    "error": 0,
    "data": [
        {
            "code": "8",
            "title": "商家下單(8)",
            "detail": "訂單已建立。",
            "addtime": "2019-02-19 08:28"
        },
        {
            "code": "15",
            "title": "貨件正等待派送(15)",
            "detail": "已安排派送。",
            "addtime": "2019-02-19 08:30"
        },
        {
            "code": "2",
            "title": "貨件派送中(2)",
            "detail": "貨件派送中,預計於 2019-02-21 18:00 派送,請留意派送員電話通知。",
            "addtime": "2019-02-19 08:30"
        },
        {
            "code": "6",
            "title": "訂單異常(6)",
            "detail": "派送失敗,貨件已退回集散中心 \n如有疑問,請聯絡客戶服務熱線:2121 2211。",
            "addtime": "2019-02-19 08:34"
        },
        {
            "code": "6",
            "title": "訂單異常(6)",
            "detail": "派送失敗,貨件已退回集散中心 \n如有疑問,請聯絡客戶服務熱線:2121 2211。",
            "addtime": "2019-02-19 08:34"
        }
    ]
}

# 2D-API-1.7 取消運單

POST /order/homeexpress/cancel

接口類型 請求接口
用途 調用此接口以取消運單。運單只能在當前狀態是 8 並且在截單時間之前,才能取消訂單。

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
order_id string(128) - 平台訂單號
merchant_id int - 商家ID 平台提供

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "merchant_id" : 2,
        "order_id": "2018080772026801"
    }
}

# 返回結果

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