Calculate Delivery Rule

Description

計算外送規則。

Resource

POST /v1/delivery/calculate

Authorization

採用 OAuth 2.0 Bearer Token，詳細使用流程請參考 Auth Login。

Request Body Parameters

Name	Type	Required	Description
thresholds	Threshold (array)	✓	外送規則陣列
distance	float	✓*	實際外送距離（公里） 與 address 二擇一必填
address	string	✓*	外送地址（系統將自動計算距離） 與 distance 二擇一必填
store_id	string	✓**	門市編號 使用 address 時必填
order_amount	int	✓***	訂單金額（元） 正常模式必填，試算模式選填
is_trial_calculation	boolean		是否為試算模式，預設為 false 試算模式下不需提供 order_amount，只回傳外送規則資訊

重要提示： - distance 和 address 必須二擇一填寫： - 若提供 distance：直接使用該距離進行計算 - 若提供 address：系統將根據地址自動計算外送距離（需同時提供 store_id） - 不可同時提供或同時為空 - is_trial_calculation = true 時： - order_amount 變成選填（可不提供或傳 0） - 只回傳距離區間的外送規則資訊，不計算實際費用

Request Body Parameters - Threshold

Name	Type	Required	Description
distance_km	float	✓	外送距離上限（公里）
min_amount	int	✓	最低外送金額（元），0 表示不限金額
extra_delivery_fee	int	✓	未滿最低金額時加收的外送費（元），0 表示未滿時無法外送

Request Body Example

範例 1：正常模式 - 使用 distance

{
    "thresholds": [
        {
            "distance_km": 3.5,
            "min_amount": 100,
            "extra_delivery_fee": 30
        },
        {
            "distance_km": 4.0,
            "min_amount": 200,
            "extra_delivery_fee": 0
        },
        {
            "distance_km": 5.0,
            "min_amount": 0,
            "extra_delivery_fee": 50
        }
    ],
    "distance": 3.0,
    "order_amount": 120,
    "is_trial_calculation": false
}

範例 2：正常模式 - 使用 address

{
    "thresholds": [
        {
            "distance_km": 3.5,
            "min_amount": 100,
            "extra_delivery_fee": 30
        },
        {
            "distance_km": 4.0,
            "min_amount": 200,
            "extra_delivery_fee": 0
        },
        {
            "distance_km": 5.0,
            "min_amount": 0,
            "extra_delivery_fee": 50
        }
    ],
    "address": "台北市信義區信義路五段7號",
    "store_id": "A01",
    "order_amount": 120,
    "is_trial_calculation": false
}

範例 3：試算模式 - 使用 distance

{
    "thresholds": [
        {
            "distance_km": 3.5,
            "min_amount": 100,
            "extra_delivery_fee": 30
        },
        {
            "distance_km": 4.0,
            "min_amount": 200,
            "extra_delivery_fee": 0
        },
        {
            "distance_km": 5.0,
            "min_amount": 0,
            "extra_delivery_fee": 50
        }
    ],
    "distance": 3.0,
    "is_trial_calculation": true
}

範例 4：試算模式 - 使用 address

{
    "thresholds": [
        {
            "distance_km": 3.5,
            "min_amount": 100,
            "extra_delivery_fee": 30
        },
        {
            "distance_km": 4.0,
            "min_amount": 200,
            "extra_delivery_fee": 0
        },
        {
            "distance_km": 5.0,
            "min_amount": 0,
            "extra_delivery_fee": 50
        }
    ],
    "address": "台北市信義區信義路五段7號",
    "store_id": "A01",
    "is_trial_calculation": true
}

Response Body Parameters

正常模式回傳參數

Name	Type	Description
can_deliver	boolean	是否可外送
extra_delivery_fee	number	外送費（元），無法外送時為 null
total_amount	number	總金額（訂單金額 + 外送費），無法外送時為 null
message	string	詳細說明訊息
format_message	string	格式化訊息模板（使用 {} 作為佔位符）
distance	number	實際外送距離（公里）
distance_km	number	適用的距離範圍上限（公里）
order_amount	number	訂單金額（元） 僅在 order_amount >= min_amount 或 order_amount < min_amount 情況下出現
min_amount	number	最低外送金額（元） 僅在 order_amount >= min_amount 情況下出現
minimum_amount_required	number	最低外送金額要求（僅在未達最低金額時出現）
shortage	number	差額（僅在未達最低金額時出現）

試算模式回傳參數

Name	Type	Description
can_deliver	boolean	是否可外送（試算模式固定為 true，除非超過距離範圍）
extra_delivery_fee	number	預估外送費（元）
message	string	外送規則說明訊息
format_message	string	格式化訊息模板（使用 {} 作為佔位符）
distance	number	實際外送距離（公里）
min_amount	number	最低外送金額（元）
distance_km	number	適用的距離範圍上限（公里）

Response Example

正常模式回應

Http code = 200 (可外送 - 免外送費)

{
    "can_deliver": true,
    "extra_delivery_fee": 0,
    "total_amount": 120,
    "message": "外送距離 3.0 公里，訂單金額 120 元已滿最低外送金額 100 元，免外送費。",
    "format_message": "外送距離 {distance} 公里，訂單金額 {order_amount} 元已滿最低外送金額 {min_amount} 元，免外送費。",
    "distance_km": 3.5,
    "distance": 3.0,
    "order_amount": 120,
    "min_amount": 100
}

Http code = 200 (可外送 - 需加收外送費)

{
    "can_deliver": true,
    "extra_delivery_fee": 30,
    "total_amount": 110,
    "message": "外送距離 3.5 公里，訂單金額 80 元未滿最低外送金額 100 元，需加收外送費 30 元。",
    "format_message": "外送距離 {distance} 公里，訂單金額 {order_amount} 元未滿最低外送金額 {minimum_amount_required} 元，需加收外送費 {extra_delivery_fee} 元。",
    "minimum_amount_required": 100,
    "shortage": 20,
    "distance": 3.5,
    "distance_km": 4.0,
    "order_amount": 80
}

Http code = 200 (無法外送 - 未達最低金額)

{
    "can_deliver": false,
    "extra_delivery_fee": null,
    "total_amount": null,
    "message": "外送距離 4.0 公里，訂單金額 150 元未滿最低外送金額 200 元，無法外送。",
    "format_message": "外送距離 {distance} 公里，訂單金額 {order_amount} 元未滿最低外送金額 {minimum_amount_required} 元，無法外送。",
    "minimum_amount_required": 200,
    "shortage": 50,
    "distance": 4.0,
    "distance_km": 4.0,
    "order_amount": 150
}

Http code = 200 (無法外送 - 超過距離)

{
    "can_deliver": false,
    "extra_delivery_fee": null,
    "message": "外送距離 6.0 公里已超過最大外送範圍 5.0 公里，無法外送。",
    "format_message": "外送距離 {distance} 公里已超過最大外送範圍 {distance_km} 公里，無法外送。",
    "distance": 6.0,
    "distance_km": 5.0
}

Http code = 200 (不限金額 - 固定收費)

{
    "can_deliver": true,
    "extra_delivery_fee": 50,
    "total_amount": 170,
    "message": "外送距離 4.6 公里（5.0 公里內），不限金額，需收取外送費 50 元。",
    "format_message": "外送距離 {distance} 公里（{distance_km} 公里內），不限金額，需收取外送費 {extra_delivery_fee} 元。",
    "distance_km": 5.0,
    "distance": 4.6
}

試算模式回應

Http code = 200 (試算 - 有最低金額且未滿加收外送費)

請求： distance = 3.0，規則：distance_km = 3.5, min_amount = 100, extra_delivery_fee = 30

{
    "can_deliver": true,
    "extra_delivery_fee": 30,
    "message": "此地址距離門市 3.0 公里，訂單金額未滿 100 將加收 30 外送費。",
    "format_message": "此地址距離門市 {distance} 公里，訂單金額未滿 {min_amount} 將加收 {extra_delivery_fee} 外送費。",
    "min_amount": 100,
    "distance_km": 3.5,
    "distance": 3.0
}

Http code = 200 (試算 - 有最低金額且滿額免運)

請求： distance = 3.9，規則：distance_km = 4.0, min_amount = 200, extra_delivery_fee = 0

{
    "can_deliver": true,
    "extra_delivery_fee": 0,
    "message": "此地址距離門市 3.9 公里，訂單金額滿 200 免外送費。",
    "format_message": "此地址距離門市 {distance} 公里，訂單金額滿 {min_amount} 免外送費。",
    "min_amount": 200,
    "distance_km": 4.0,
    "distance": 3.9
}

Http code = 200 (試算 - 不限金額固定收費)

請求： distance = 4.6，規則：distance_km = 5.0, min_amount = 0, extra_delivery_fee = 50

{
    "can_deliver": true,
    "extra_delivery_fee": 50,
    "message": "此地址距離門市 4.6 公里，不限金額外送費為 50 元。",
    "format_message": "此地址距離門市 {distance} 公里，不限金額外送費為 {extra_delivery_fee} 元。",
    "min_amount": 0,
    "distance_km": 5.0,
    "distance": 4.6
}

Http code = 200 (試算 - 超過距離)

{
    "can_deliver": false,
    "extra_delivery_fee": null,
    "message": "外送距離 6.0 公里已超過最大外送範圍 5.0 公里，無法外送。",
    "format_message": "外送距離 {distance} 公里已超過最大外送範圍 {distance_km} 公里，無法外送。",
    "distance": 6.0,
    "distance_km": 5.0
}

Error Response

Http code = 404 (錯誤 - 缺少外送規則)

{
    "message": "缺少外送規則"
}

Http code = 400 (錯誤 - 參數驗證失敗 - 距離為負數)

{
    "message": "外送距離不可為負數"
}

Http code = 400 (錯誤 - 參數驗證失敗 - 距離格式錯誤)

{
    "message": "外送距離格式錯誤，必須為數字"
}

Http code = 400 (錯誤 - 參數驗證失敗 - 金額為負數)

{
    "message": "訂單金額不可為負數"
}

Http code = 400 (錯誤 - 參數驗證失敗 - 金額格式錯誤)

{
    "message": "訂單金額格式錯誤，必須為數字"
}

Http code = 400 (錯誤 - distance 與 address 都未提供)

{
    "message": "distance 和 address 必須至少提供一個"
}

Http code = 400 (錯誤 - distance 與 address 同時提供)

{
    "message": "distance 和 address 只能擇一填寫，不可同時提供"
}

Http code = 400 (錯誤 - 地址距離計算失敗)

{
    "message": "地址距離計算失敗: [錯誤詳情]"
}

format_message 說明

所有回應都包含 format_message 欄位，用於前端自訂訊息顯示格式。格式化訊息使用 {} 作為佔位符，對應的欄位名稱如下：

佔位符	對應欄位	說明
{distance}	distance	實際外送距離
{distance_km}	distance_km	距離範圍上限
{order_amount}	order_amount	訂單金額
{min_amount}	min_amount	最低外送金額
{minimum_amount_required}	minimum_amount_required	最低金額要求
{extra_delivery_fee}	extra_delivery_fee	外送費
{shortage}	shortage	差額

規則配置範例說明

以 Request Body Example 中的配置為例：

距離範圍	最低金額	外送費	規則說明
≤ 3.5 公里	100 元	30 元	滿 100 元免外送費，未滿加收 30 元
≤ 4.0 公里	200 元	0 元	必須滿 200 元才可外送，滿額免外送費
≤ 5.0 公里	不限	50 元	不限金額，一律收取 50 元外送費
> 5.0 公里	-	-	無法外送