# 一般查詢

# 2D-API-1.4 下單可選日期時間

POST /order/homeexpress/get_datetime

接口類型 請求接口
用途 - 在調用 2D-API-1.1 創建訂單 接口時,需要輸入寄件和收件的時間段 (pickupdelivery 參數),本接口提供對接方可供選擇的收派時間段。故此,在對接方的前端介面中,需要先按以下的 如何讓用戶選擇寄件和收件時段 說明的時間段選取規則,提供用戶可選的收件和派件時間段,然後才創建訂單。

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
merchant_id int Yes - 商家ID
product_code string No HDP-ECOMM-H 產品代號 請參看 API 使用說明 - 配送產品請求參數表

例子:

{
    "auth": {
        "..."
    },
    "data": {
        "merchant_id": 123,
        "product_code": "HDP-ECOMM-H"
    }
}

# 返回結果

{
    "error": 0,
    "data": {
        "meta": {
            "datetime": "2018-12-19 16:20:24",
            "workingday_code": "289",
            "product_type": "DoorPickup",
            "destination_type": "Home"
        },
        "pickup": {
            "default": {
                "description": "即收即送市區收件",
                "slot": [
                    {
                        "datetime": "2018-12-20 12:00-16:00",
                        "workingday_code": "290.48",
                        "description": "12月20日 (四) 12:00-16:00"
                    },
                    {
                        "datetime": "2018-12-21 12:00-16:00",
                        "workingday_code": "291.48",
                        "description": "12月21日 (五) 12:00-16:00"
                    },
                    {
                        "datetime": "2018-12-22 12:00-16:00",
                        "workingday_code": "292.48",
                        "description": "12月22日 (六) 12:00-16:00"
                    },
                    {
                        "datetime": "2018-12-24 12:00-16:00",
                        "workingday_code": "293.48",
                        "description": "12月24日 (一) 12:00-16:00"
                    },
                    {
                        "datetime": "2018-12-27 12:00-16:00",
                        "workingday_code": "294.48",
                        "description": "12月27日 (四) 12:00-16:00"
                    }
                ]
            }
        },
        "delivery": {
            "default": {
                "description": "市區到家派送",
                "slot": [
                    {
                        "datetime": "2018-12-20 18:00-23:00",
                        "workingday_code": "290.72",
                        "description": "12月20日 (四) 18:00-23:00",
                        "acceptable": "289.55-290.52"
                    },
                    {
                        "datetime": "2018-12-21 18:00-23:00",
                        "workingday_code": "291.72",
                        "description": "12月21日 (五) 18:00-23:00",
                        "acceptable": "290.55-291.52"
                    },
                    {
                        "datetime": "2018-12-22 10:30-17:00",
                        "workingday_code": "292.4",
                        "description": "12月22日 (六) 10:30-17:00",
                        "acceptable": "291.23-292.2"
                    },
                    {
                        "datetime": "2018-12-22 18:00-23:00",
                        "workingday_code": "292.72",
                        "description": "12月22日 (六) 18:00-23:00",
                        "acceptable": "291.55-292.52"
                    },
                    {
                        "datetime": "2018-12-24 10:30-17:00",
                        "workingday_code": "293.4",
                        "description": "12月24日 (一) 10:30-17:00",
                        "acceptable": "291.23-293.2"
                    },
                    {
                        "datetime": "2018-12-24 18:00-23:00",
                        "workingday_code": "293.72",
                        "description": "12月24日 (一) 18:00-23:00",
                        "acceptable": "291.55-293.52"
                    },
                    {
                        "datetime": "2018-12-27 10:30-17:00",
                        "workingday_code": "294.4",
                        "description": "12月27日 (四) 10:30-17:00",
                        "acceptable": "291.23-294.2"
                    },
                    {
                        "datetime": "2018-12-27 18:00-23:00",
                        "workingday_code": "294.72",
                        "description": "12月27日 (四) 18:00-23:00",
                        "acceptable": "291.55-294.52"
                    },
                    {
                        "datetime": "2018-12-28 10:30-17:00",
                        "workingday_code": "295.4",
                        "description": "12月28日 (五) 10:30-17:00",
                        "acceptable": "294.23-295.2"
                    },
                    {
                        "datetime": "2018-12-28 18:00-23:00",
                        "workingday_code": "295.72",
                        "description": "12月28日 (五) 18:00-23:00",
                        "acceptable": "294.55-295.52"
                    }
                ]
            },
            "sp1": {
                "description": "馬灣,愉景灣到家派送",
                "slot": [
                    {
                        "datetime": "2018-12-20 12:00-16:00",
                        "workingday_code": "290.48",
                        "description": "12月20日 (四) 12:00-16:00",
                        "acceptable": "288.31-290.28"
                    },
                    {
                        "datetime": "2018-12-22 12:00-16:00",
                        "workingday_code": "292.48",
                        "description": "12月22日 (六) 12:00-16:00",
                        "acceptable": "290.31-292.28"
                    },
                    {
                        "datetime": "2018-12-27 12:00-16:00",
                        "workingday_code": "294.48",
                        "description": "12月27日 (四) 12:00-16:00",
                        "acceptable": "289.31-294.28"
                    },
                    {
                        "datetime": "2018-12-29 12:00-16:00",
                        "workingday_code": "296.48",
                        "description": "12月29日 (六) 12:00-16:00",
                        "acceptable": "294.31-296.28"
                    },
                    {
                        "datetime": "2019-01-01 12:00-16:00",
                        "workingday_code": "298.48",
                        "description": "01月01日 (二) 12:00-16:00",
                        "acceptable": "295.31-298.28"
                    }
                ]
            },
            "sp2": {
                "description": "東涌到家派送",
                "slot": [
                    {
                        "datetime": "2018-12-20 16:00-22:30",
                        "workingday_code": "290.64",
                        "description": "12月20日 (四) 16:00-22:30",
                        "acceptable": "288.47-290.44"
                    },
                    {
                        "datetime": "2018-12-22 16:00-22:30",
                        "workingday_code": "292.64",
                        "description": "12月22日 (六) 16:00-22:30",
                        "acceptable": "290.47-292.44"
                    },
                    {
                        "datetime": "2018-12-27 16:00-22:30",
                        "workingday_code": "294.64",
                        "description": "12月27日 (四) 16:00-22:30",
                        "acceptable": "289.47-294.44"
                    },
                    {
                        "datetime": "2018-12-29 16:00-22:30",
                        "workingday_code": "296.64",
                        "description": "12月29日 (六) 16:00-22:30",
                        "acceptable": "294.47-296.44"
                    },
                    {
                        "datetime": "2019-01-01 16:00-22:30",
                        "workingday_code": "298.64",
                        "description": "01月01日 (二) 16:00-22:30",
                        "acceptable": "295.47-298.44"
                    }
                ]
            }
        }
    }
}

# 如何讓用戶選擇寄件和收件時段

開發者需要按一定的規則在前端介面給用戶顯示收件和派件時段選項,按下來將會以一個例子說明:

1.假設接口返回以下數據:

{
    "error": 0,
    "data": {
        "meta": {
            "datetime": "2018-12-19 16:20:24",
            "workingday_code": "289",
            "product_type": "DoorPickup",
            "destination_type": "Home"
        },
        "pickup": {
            "default": {
                "description": "即收即送市區收件",
                "slot": [
                    {
                        "datetime": "2018-12-20 12:00-16:00",
                        "workingday_code": "290.48",
                        "description": "12月20日 (四) 12:00-16:00"
                    },
                    {
                        "datetime": "2018-12-21 12:00-16:00",
                        "workingday_code": "291.48",
                        "description": "12月21日 (五) 12:00-16:00"
                    }
                ]
            }
        },
        "delivery": {
            "default": {
                "description": "市區到家派送",
                "slot": [
                    {
                        "datetime": "2018-12-20 18:00-23:00",
                        "workingday_code": "290.72",
                        "description": "12月20日 (四) 18:00-23:00",
                        "acceptable": "289.55-290.52"
                    },
                    {
                        "datetime": "2018-12-21 18:00-23:00",
                        "workingday_code": "291.72",
                        "description": "12月21日 (五) 18:00-23:00",
                        "acceptable": "290.55-291.52"
                    }
                ]
            },
            "sp1": {
                "description": "馬灣,愉景灣到家派送",
                "slot": [
                    {
                        "datetime": "2018-12-20 12:00-16:00",
                        "workingday_code": "290.48",
                        "description": "12月20日 (四) 12:00-16:00",
                        "acceptable": "288.31-290.28"
                    }
                ]
            }
        }
    }
}

2.用戶先從 `pickup.default.slot` 中選擇其中一個**收件時段**,例如選擇了以下的時段:
{
    "datetime": "2018-12-20 12:00-16:00",
    "workingday_code": "290.48",
    "description": "12月20日 (四) 12:00-16:00"
}

3.系統從以上時段中,獲得了 `workingday_code` (WDC) 的值為 `290.48`。

4.然後系統需要選擇合適的**派件時段** 供用戶選擇。

先選擇使用的配送區域類別 (即是 delivery.defaultdelivery.sp1,本例子會使用 delivery.default),然後找出它的時段 slot

"slot": [
    {
        "datetime": "2018-12-20 18:00-23:00",
        "workingday_code": "290.72",
        "description": "12月20日 (四) 18:00-23:00",
        "acceptable": "289.55-290.52"
    },
    {
        "datetime": "2018-12-21 18:00-23:00",
        "workingday_code": "291.72",
        "description": "12月21日 (五) 18:00-23:00",
        "acceptable": "290.55-291.52"
    }
]

5.最後,在以上時段中,比較 `acceptable` 字段和在第 3 步選取了的 WDC 值,只選取 WDC 值在`acceptable` 範圍內的時段。在本例子中,WDC 是 `290.48`,故此,以下的 **派件時段** 會被選出來,並顯示給用戶選擇。
{
    "datetime": "2018-12-20 18:00-23:00",
    "workingday_code": "290.72",
    "description": "12月20日 (四) 18:00-23:00",
    "acceptable": "289.55-290.52" 
}

# 2D-API-1.8 自提點列表

POST /pickup_points

接口類型 請求接口
用途 獲取自提點列表

# 請求參數

名稱 類型 是否必須 默認值 說明 備註
area string No - 地區 - 沒有傳人的話,默認為列出所有地區的自提點
- 可傳入的地區:
1. 中西區
2. 九龍城區
3. 元朗區
4. 北區
5. 南區
6. 大埔區
7. 屯門區
8. 東區
9. 沙田區
10. 油尖旺區
11. 深水埗區
12. 灣仔區
13. 荃灣區
14. 葵青區
15. 西貢區
16. 觀塘區
17. 離島區
18. 黃大仙區
{
    "auth": {
        "..."
    },
    "data": {
        "area": "沙田區"
    }
}

# 返回結果

{
    "error": 0,
    "data": [
        {
            "locker_code": "H852UA36P",
            "locker_brand": "alfred",
            "district": "沙田區",
            "name": "禾輋廣場(2號)",
            "address": "新界沙田德厚街3號禾輋廣場2/F(近香港賽馬會)",
            "coordinate": "22.342123,114.42423"
        },
        {
            "locker_code": "H852UA36P",
            "locker_brand": "alfred",
            "district": "沙田區",
            "name": "禾輋廣場(2號)",
            "address": "新界沙田德厚街3號禾輋廣場2/F(近香港賽馬會)",
            "coordinate": "22.342123,114.42423"
        },
        {
            "locker_code": "H852UA36P",
            "locker_brand": "alfred",
            "district": "沙田區",
            "name": "禾輋廣場(2號)",
            "address": "新界沙田德厚街3號禾輋廣場2/F(近香港賽馬會)",
            "coordinate": "22.342123,114.42423"
        }
    ]
}