# 運單管理

# 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
小件輕郵:HDP-PND-1-H
商家訂單號
client_order_id
必填 必填 必填
寄件人
sender.name
必填 不需要填寫 必填
寄件電話區號
sender.country_code
必填 不需要填寫 必填
寄件電話
sender.phone
必填 不需要填寫 必填
寄件地址方式
sender.type
傳入 11 不需要填寫 傳入 11
寄件地址
sender.address
必填 不需要填寫 必填
寄件日期
pickup.date
必填 選填
** 參考 "收件日期" delivery.date 的說明。
必填
寄件時間
pickup.period
必填 不需要填寫 必填
收件人電話
recipient.phone
特派:必填
自取:必填,只支持首位號碼為 4, 5, 6, 7, 8, 9 的電話號碼
特惠:必填
特派(倉庫交件):必填
自取(倉庫交件):必填,只支持首位號碼為 4, 5, 6, 7, 8, 9 的電話號碼
特惠(倉庫交件):必填
小件輕郵:必填,只支持首位號碼為 4, 5, 6, 7, 8, 9 的電話號碼
收件地址方式
recipient.type
特派:11
自取:4
特惠:11
特派(倉庫交件):11
自取(倉庫交件):4
特惠(倉庫交件):11
小件輕郵: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 的整數

*就各產品於實際營運時所支持的數量及重量,請與業務同事確認
小件輕郵:選填、只接受 1

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

各服務支持的最大值:
特派:100000 (即是100Kg)
自取:5000 (即是5Kg)
特惠:100000 (即是100Kg)
選填、只接受大於 10 (即是0.01Kg) 至最大值的整數。

各服務支持的最大值:
特派(倉庫交件):100000 (最大100Kg)
自取(倉庫交件):5000 (最大5Kg)
特惠(倉庫交件):100000 (即是100Kg)
選填、只接受大於 10 (即是0.01Kg) 至最大值的整數。

各服務支持的最大值:
小件輕郵:2000 (即是2Kg)
物品詳情
item_detail
限制為最高 50項 不限制 限制為最高 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
不能於60秒內重複請求 client_order_id 相同的訂單
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 傳入規則)
cod object No - 代收運費和貨款 - 僅供已啟用代收貨款服務的商家使用,有關啟用狀態及金額上限,請與到家業務人員聯繫
- 僅支持到家及特惠服務,暫不支持到櫃服務
cod.service_fee string No - 代收運費 - 支持小數點後兩位。
- 例子:"20.30"
cod.cash string No - 代收貨款 - 支持小數點後兩位。
- 例子:"20.30"
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 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 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",//商家訂單號
        "order_url": "https://track.zeek.one/hk/en/HD2022020929901111/b4cee0", // Order Tracker URL
        "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",
        "paper_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 一樣
        "shipment_code": "TEST12345", // 到家運單號
        "client_order_id": "VLV-Test20180823771522920",
        "client_ref_id": "VLV-Test20180823771522920", // 和 client_order_id 一樣
        "client_shipment_code": "PU12345", // 第三方運單號
        "tpl_order_id": "GF000003191HK", // 第三方供應商訂單號
        "tpl_waybill_no": "GF000003165HK", // 第三方供應商運單號	
        "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": { // 運單狀態
            "code": "9005",
            "name": "正在前往取件",
            "lastmodify": "2020-07-22 16:06"
        },
        "partner": { // 配送員信息
            "name": "陳大文",
            "country_code": "852",
            "phone": "17612008",
            "position": {
                "code": "R", // 工種代號
                "name": "電單車司機", // 工種名稱
                "vehicle_number": "RJ 456" // 車輛的車牌
            }
        },
        "receipts": [ // 簽收圖片連結
            "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 運單狀態回調

POST 由開發者提供

接口類型 回調接口
用途 - 當訂單狀態更改時,請求開發者提供的回調接口
- 這裡發送的是2021年7月開始的狀態碼

# 請求失敗處理

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

# 接口授權

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

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
merchant_id string Yes - 商家ID
order_id string(128) Yes - 平台訂單號
shipment_code string(128) Yes - 平台運單號
client_order_id string Yes - 商家訂單號
client_shipment_code string Yes - 第三方運單號
order_status int Yes - 訂單狀態碼 2021年7月開始的狀態碼
status_desc string Yes - 狀態描述
exception_description string Yes - 異常描述
timestamp int Yes - 狀態觸發時間

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "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
    }
}

# 返回結果

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

# 2D-API-1.10 運單路由追蹤

POST /order/homeexpress/event_track

接口類型 請求接口
用途 開發者可請求此 API 獲取運單路由追蹤

# 請求參數

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

例子:

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

# 返回結果

{
  "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 運單狀態回調(舊狀態)

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 - 推送時間戳
order_status int Yes - 訂單狀態
status_desc string Yes - 狀態描述

例子:

{
    "auth": {
        // 參看 "開發說明"
    },
    "data": {
        "meta": {
            // 參看 "開發說明"
        },
        "order_id": "2018080772026801",
        "client_order_id": "201808076580818698",
        "timestamp": 1533609085,
        "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": "寄方下單",
      "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 取消運單

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