taiwan-logistics-skill 1.4.4 → 1.4.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/taiwan-logistics/data/logistics-types.csv +1 -1
- package/assets/taiwan-logistics/data/status-codes.csv +36 -11
- package/assets/taiwan-logistics/examples/ezship-logistics-example.py +37 -0
- package/assets/taiwan-logistics/references/ezship-logistics-api.md +95 -18
- package/assets/taiwan-logistics/references/ondemand-delivery.md +169 -43
- package/dist/index.js +1 -1
- package/package.json +1 -1
|
@@ -51,5 +51,5 @@ HOME,order_status=A05/A06,ezShip 宅配,ezship,home,true,8000,,常溫,order_type
|
|
|
51
51
|
CROSS_BORDER,stCate=TSF,店港澳,ezship,cross_border,false,,,常溫,order_status A11/A12;無代收
|
|
52
52
|
HOME,eprdcl2=001/003/008,新竹物流(直連),hct_direct,home,true,,,常溫/冷凍/冷藏,eprdcl2 001 一般/003 冷凍/008 冷藏;eqmny 代收貨款
|
|
53
53
|
ONDEMAND,LALAMOVE,Lalamove 即時配送,lalamove,ondemand,false,依方案,依車型,常溫,先報價後下單;報價效期5分鐘;同城/當日;可換司機;非批次物流
|
|
54
|
-
ONDEMAND,PANDAGO,pandago 即時配送,pandago,ondemand,false,依報價,34x34x36cm/20kg
|
|
54
|
+
ONDEMAND,PANDAGO,pandago 即時配送,pandago,ondemand,false,依報價,34x34x36cm/20kg,常溫,費用與時間為兩支獨立端點;公開Sandbox僅新加坡(台灣另有Stage環境);不需成為foodpanda餐廳夥伴
|
|
55
55
|
ONDEMAND,UBER_DIRECT,Uber Direct 即時配送,uber_direct,ondemand,false,依報價,依方案,常溫,配送半徑約10英里;可預約最多30天;台灣可用性未經官方確認
|
|
@@ -926,14 +926,39 @@ hct,址誤,Address Error,Address Error,error,地址錯誤無法配送,聯繫商
|
|
|
926
926
|
hct,拒收退回,Refused,Refused Return,returned,收件人拒收,包裹退回,
|
|
927
927
|
hct,商品保留不退,Hold No Return,Held No Return,on_hold,商品保留不退回,聯繫商家
|
|
928
928
|
hct,公司行號休息,Office Closed,Office Closed,error,公司行號休息日無法配送,延後重新配送
|
|
929
|
-
ezship,A01
|
|
930
|
-
ezship,A02
|
|
931
|
-
ezship,A03
|
|
932
|
-
ezship,A04
|
|
933
|
-
ezship,A05
|
|
934
|
-
ezship,A06
|
|
935
|
-
ezship,A11
|
|
936
|
-
ezship,A12
|
|
937
|
-
ezship,
|
|
938
|
-
ezship,
|
|
939
|
-
ezship,
|
|
929
|
+
ezship,A01,超商取貨新訂單(免確認),CVS order,order_type,建單時送出的 order_status:不需在 ezShip 確認,可直接印單;回 sn_id;須帶 st_code,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
930
|
+
ezship,A02,超商取貨新訂單(需確認),CVS order,order_type,建單時送出的 order_status:需在 ezShip 確認後才能印單(預設值);回 sn_id;須帶 st_code,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
931
|
+
ezship,A03,超商取貨新訂單(輕鬆袋/迷你袋,免確認),CVS order,order_type,建單時送出的 order_status:不回 sn_id;須到 ezShip 後台登錄專用編號;須帶 st_code,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
932
|
+
ezship,A04,超商取貨新訂單(輕鬆袋/迷你袋,需確認),CVS order,order_type,建單時送出的 order_status:不回 sn_id;需確認並登錄專用編號;須帶 st_code,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
933
|
+
ezship,A05,宅配新訂單(免確認),Home delivery order,order_type,建單時送出的 order_status:可直接印單;回 sn_id;須帶 rv_addr、rv_zip,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
934
|
+
ezship,A06,宅配新訂單(需確認),Home delivery order,order_type,建單時送出的 order_status:需確認後才能印單;回 sn_id;須帶 rv_addr、rv_zip,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
935
|
+
ezship,A11,店港澳訂單(免確認),HK/Macau store order,order_type,建單時送出的 order_status:無代收;可直接印單;回 sn_id;須帶 st_code,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
936
|
+
ezship,A12,店港澳訂單(需確認),HK/Macau store order,order_type,建單時送出的 order_status:無代收;需確認後才能印單;回 sn_id;須帶 st_code,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
937
|
+
ezship,S01,訂單新增成功,Order created,success,建單回傳;sn_id 須存起來,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
938
|
+
ezship,E00,參數傳遞內容有誤或欄位短缺(XML 版:XML 內容有誤),,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
939
|
+
ezship,E01,su_id 帳號不存在,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
940
|
+
ezship,E02,帳號無取貨付款/網站串接/宅配/店港澳權限,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
941
|
+
ezship,E03,帳號無可用之輕鬆袋或迷你袋,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
942
|
+
ezship,E04,取件門市有誤,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
943
|
+
ezship,E05,金額有誤,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
944
|
+
ezship,E06,取件人 email 格式有誤,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
945
|
+
ezship,E07,取件人手機格式有誤,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
946
|
+
ezship,E08,order_status 內容有誤或為空值,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
947
|
+
ezship,E09,order_type 內容有誤或為空值,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
948
|
+
ezship,E10,取件人姓名內容有誤或為空值,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
949
|
+
ezship,E11,收件地址內容有誤或為空值,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
950
|
+
ezship,E13,店港澳無法使用 order_type=1(取貨付款),,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
951
|
+
ezship,E98,XML 系統發生錯誤無法載入(僅 XML 版),,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
952
|
+
ezship,E99,系統錯誤,,error,建單回傳;此時 sn_id 為 00000000,傳送訂單回傳(ezship_WebOrder_HttpRequest_v15.pdf/ezship_WebOrder_XML_v15s.pdf)
|
|
953
|
+
ezship,S01,尚未寄件或尚未收到超商總公司提供的寄件訊息,Not yet shipped,pending,貨況查詢回傳;times 1 第一次配送/2 第二次配送/8 退還寄件人/9 非常規配送,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
954
|
+
ezship,S02,運往取件門市途中,In transit,in_transit,貨況查詢回傳;times 1 第一次配送/2 第二次配送/8 退還寄件人/9 非常規配送,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
955
|
+
ezship,S03,已送達取件門市,Arrived at store,at_store,貨況查詢回傳;times 1 第一次配送/2 第二次配送/8 退還寄件人/9 非常規配送,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
956
|
+
ezship,S04,已完成取貨,Picked up,picked_up,貨況查詢回傳;times 1 第一次配送/2 第二次配送/8 退還寄件人/9 非常規配送,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
957
|
+
ezship,S05,退貨(已退回物流中心/再寄一次給取件人/退回給寄件人),Returned,returned,貨況查詢回傳;times 1 第一次配送/2 第二次配送/8 退還寄件人/9 非常規配送,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
958
|
+
ezship,S06,配送異常(刪單/門市閉店/貨故),Delivery exception,error,貨況查詢回傳;times 1 第一次配送/2 第二次配送/8 退還寄件人/9 非常規配送,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
959
|
+
ezship,E00,參數傳遞內容有誤或欄位短缺,,error,貨況查詢回傳,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
960
|
+
ezship,E01,su_id 帳號不存在,,error,貨況查詢回傳,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
961
|
+
ezship,E02,su_id 帳號無網站串接權限,,error,貨況查詢回傳,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
962
|
+
ezship,E03,sn_id 店到店編號有誤,,error,貨況查詢回傳,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
963
|
+
ezship,E04,su_id 帳號與 sn_id 店到店編號無法對應,,error,貨況查詢回傳,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
964
|
+
ezship,E99,系統錯誤,,error,貨況查詢回傳,貨況查詢回傳(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
@@ -80,6 +80,25 @@ DELIVERY_TIMES = {
|
|
|
80
80
|
'9': '非常規配送',
|
|
81
81
|
}
|
|
82
82
|
|
|
83
|
+
# 貨況查詢回傳的 order_status(ezship_status_api.pdf/ezship_status_api_byorder.pdf)
|
|
84
|
+
# 與建單回傳的 S01/E 代碼同名但意義不同,不可共用對照表
|
|
85
|
+
TRACKING_STATUS = {
|
|
86
|
+
'S01': '尚未寄件或尚未收到超商總公司提供的寄件訊息',
|
|
87
|
+
'S02': '運往取件門市途中',
|
|
88
|
+
'S03': '已送達取件門市',
|
|
89
|
+
'S04': '已完成取貨',
|
|
90
|
+
'S05': '退貨(已退回物流中心/再寄一次給取件人/退回給寄件人)',
|
|
91
|
+
'S06': '配送異常(刪單/門市閉店/貨故)',
|
|
92
|
+
}
|
|
93
|
+
TRACKING_ERRORS = {
|
|
94
|
+
'E00': '參數傳遞內容有誤或欄位短缺',
|
|
95
|
+
'E01': 'su_id 帳號不存在',
|
|
96
|
+
'E02': 'su_id 帳號無網站串接權限',
|
|
97
|
+
'E03': 'sn_id 店到店編號有誤',
|
|
98
|
+
'E04': 'su_id 帳號與 sn_id 店到店編號無法對應',
|
|
99
|
+
'E99': '系統錯誤',
|
|
100
|
+
}
|
|
101
|
+
|
|
83
102
|
# 這兩個狀態無法呈現最終貨況,需登入 ezShip 系統查詢
|
|
84
103
|
NEEDS_MANUAL_CHECK = {'S05': '包裹退貨', 'S06': '包裹配送異常'}
|
|
85
104
|
|
|
@@ -279,6 +298,8 @@ def parse_status_result(query: Dict[str, str]) -> Dict[str, str]:
|
|
|
279
298
|
'sn_id': query.get('sn_id', ''),
|
|
280
299
|
'order_no': query.get('order_no', ''),
|
|
281
300
|
'order_status': status,
|
|
301
|
+
'status_desc': TRACKING_STATUS.get(status, ''),
|
|
302
|
+
'error': TRACKING_ERRORS.get(status, ''),
|
|
282
303
|
'times': times,
|
|
283
304
|
'times_desc': DELIVERY_TIMES.get(times, f'未知 {times}'),
|
|
284
305
|
# sdate 由超商或宅配公司提供;udate 是 ezShip 收到該狀態的時間
|
|
@@ -341,6 +362,22 @@ def _self_test() -> int:
|
|
|
341
362
|
failed += not ok
|
|
342
363
|
print(f' [{"PASS" if ok else "FAIL"}] A11/A12 歸類為店港澳(ezShip 支援港澳店配)')
|
|
343
364
|
|
|
365
|
+
# 貨況:S01 在貨況查詢代表尚未寄件,不是建單成功
|
|
366
|
+
r = parse_status_result({'sn_id': '12345678', 'order_status': 'S01', 'times': '1'})
|
|
367
|
+
ok = r['status_desc'].startswith('尚未寄件') and r['error'] == '' and not r['needs_manual_check']
|
|
368
|
+
failed += not ok
|
|
369
|
+
print(f' [{"PASS" if ok else "FAIL"}] 貨況 S01 解析為尚未寄件')
|
|
370
|
+
|
|
371
|
+
r = parse_status_result({'sn_id': '12345678', 'order_status': 'E03'})
|
|
372
|
+
ok = r['error'] == TRACKING_ERRORS['E03'] and r['status_desc'] == ''
|
|
373
|
+
failed += not ok
|
|
374
|
+
print(f' [{"PASS" if ok else "FAIL"}] 貨況 E03 解析為店到店編號有誤')
|
|
375
|
+
|
|
376
|
+
r = parse_status_result({'sn_id': '12345678', 'order_status': 'S06', 'times': '8'})
|
|
377
|
+
ok = r['needs_manual_check'] and r['times_desc'] == '退還給寄件人'
|
|
378
|
+
failed += not ok
|
|
379
|
+
print(f' [{"PASS" if ok else "FAIL"}] 貨況 S06 標記需登入後台查詢')
|
|
380
|
+
|
|
344
381
|
# 特殊字元
|
|
345
382
|
try:
|
|
346
383
|
check_no_special_chars("order'123", 'web_para')
|
|
@@ -74,7 +74,7 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
|
|
|
74
74
|
| 回傳 | 說明 |
|
|
75
75
|
|---|---|
|
|
76
76
|
| `processID` | 原值回傳 |
|
|
77
|
-
| `stCate` | **`TOK` OK/`TLF` 萊爾富/`TFM`
|
|
77
|
+
| `stCate` | **`TOK` OK/`TLF` 萊爾富/`TFM` 全家/`TSF` 店港澳** |
|
|
78
78
|
| `stCode` / `stName` / `stAddr` / `stTel` | 門市代號/名稱/地址/電話 |
|
|
79
79
|
| `webPara` | 原值回傳 |
|
|
80
80
|
|
|
@@ -122,7 +122,7 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
|
|
|
122
122
|
**建單失敗代碼**(回傳於 `order_status`):`E00` 參數短缺、`E01` 帳號不存在、`E02` 無代收/串接/宅配/店港澳權限、`E03` 無可用輕鬆袋或迷你袋、`E04` 門市有誤、`E05` 金額有誤、`E06` email 格式、`E07` 手機格式、`E08` `order_status` 有誤、`E09` `order_type` 有誤、`E10` `rv_name` 有誤、`E11` `rv_addr` 有誤、`E13` 店港澳無法使用;成功為 `S01`。
|
|
123
123
|
|
|
124
124
|
> ⚠️ **`rv_name` 超過四個中英文字,超商取貨單會印不完整**,可能導致取貨問題。官方特別提醒。
|
|
125
|
-
> 💡 **港澳配送**(`A11`/`A12
|
|
125
|
+
> 💡 **港澳配送**(`A11`/`A12`):ezShip 是本 skill 少數支援港澳店配的聚合商;店港澳只能 `order_type=3`,報值金額商務會員 0–2,500(XML 版欄位定義)。
|
|
126
126
|
|
|
127
127
|
回傳:`order_id`、`sn_id`、`order_status`、`webPara`。
|
|
128
128
|
|
|
@@ -139,9 +139,9 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
|
|
|
139
139
|
| ezShip 店到店編號 | `.../emap/ezship_request_order_status_api.jsp` |
|
|
140
140
|
| 購物網站訂單編號 | `.../emap/ezship_request_order_status_api_byorder.jsp` |
|
|
141
141
|
|
|
142
|
-
送出:`su_id`、`order_no
|
|
142
|
+
送出:`su_id`、`sn_id`(依店到店編號)或 `order_no`(依訂單編號,≤25)、`rtn_url`、`web_para`。
|
|
143
143
|
|
|
144
|
-
回傳:`sn_id`、`order_no
|
|
144
|
+
回傳:`sn_id`、`order_no`(僅依訂單編號查詢)、`order_status`、`webPara`,另有三個時序欄位:
|
|
145
145
|
|
|
146
146
|
| 參數 | 說明 |
|
|
147
147
|
|---|---|
|
|
@@ -149,11 +149,93 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
|
|
|
149
149
|
| `sdate` | 配送狀態發生日期(`yyyy/mm/dd`),由超商或宅配公司提供 |
|
|
150
150
|
| `udate` | ezShip 接收到該狀態的時間(`yyyy/mm/dd hh24:mi`)|
|
|
151
151
|
|
|
152
|
+
**貨況 `order_status`**(`ezship_status_api.pdf`、`ezship_status_api_byorder.pdf`):
|
|
153
|
+
|
|
154
|
+
| 代碼 | 說明 |
|
|
155
|
+
|---|---|
|
|
156
|
+
| `S01` | 尚未寄件或尚未收到超商總公司提供的寄件訊息 |
|
|
157
|
+
| `S02` | 運往取件門市途中 |
|
|
158
|
+
| `S03` | 已送達取件門市 |
|
|
159
|
+
| `S04` | 已完成取貨 |
|
|
160
|
+
| `S05` | 退貨(已退回物流中心/再寄一次給取件人/退回給寄件人)|
|
|
161
|
+
| `S06` | 配送異常(刪單/門市閉店/貨故)|
|
|
162
|
+
| `E00` | 參數傳遞內容有誤或欄位短缺 |
|
|
163
|
+
| `E01` | `su_id` 帳號不存在 |
|
|
164
|
+
| `E02` | `su_id` 帳號無網站串接權限 |
|
|
165
|
+
| `E03` | `sn_id` 店到店編號有誤 |
|
|
166
|
+
| `E04` | `su_id` 與 `sn_id` 無法對應 |
|
|
167
|
+
| `E99` | 系統錯誤 |
|
|
168
|
+
|
|
169
|
+
> ⚠️ `S01` 在建單回傳代表「訂單新增成功」,在貨況查詢代表「尚未寄件」;`E00`–`E04` 兩邊意義也不同,解析時要分開處理。
|
|
170
|
+
|
|
152
171
|
> ⚠️ **有速率限制且會被停權**:官方明文「若因大量反覆查詢結案資料,導致 ezShip 系統忙碌或運行困難,ezShip 將中斷其網路串接之權利」,**建議每筆查詢間隔 3 秒以上**,已結案貨件勿重複查詢。不要做整批預先輪詢。
|
|
153
172
|
> ⚠️ **`order_status` 回傳 `S05`(包裹退貨)或 `S06`(包裹配送異常)時無法呈現最終貨況**,需登入 ezShip 系統查詢。
|
|
154
173
|
> ⚠️ 訂單號碼重複時,**以最後一次上傳的訂單資料為準**。
|
|
155
174
|
> ⚠️ 以訂單編號查詢**不適用簡易版**串接的訂單。
|
|
156
175
|
|
|
176
|
+
## 2.2 XML 版 — 傳送訂單
|
|
177
|
+
|
|
178
|
+
電子地圖與貨況查詢同參數版;傳送訂單改以 HTTP POST 將 XML 放在 **`web_map_xml`** 參數送到
|
|
179
|
+
`https://www.ezship.com.tw/emap/ezship_xml_order_api_ex.jsp`(`ezship_xml_order_api.jsp` 已於 2017 年底停用)。
|
|
180
|
+
欄位依 `ezship_WebOrder_XML_v15s.pdf`(版本 1.5),標籤為 camelCase。
|
|
181
|
+
|
|
182
|
+
**訂單 `<ORDER>`**
|
|
183
|
+
|
|
184
|
+
| 標籤 | 必要 | 型態/長度 | 說明 |
|
|
185
|
+
|---|:---:|---|---|
|
|
186
|
+
| `suID` | Y | varchar 100 | 賣家 ezShip 帳號;取貨付款訂單帳號須在合約期間內 |
|
|
187
|
+
| `orderID` | Y | varchar 10 | 購物網站訂單編號 |
|
|
188
|
+
| `orderStatus` | Y | varchar 3 | `A01`–`A06`、`A11`、`A12`,同參數版 |
|
|
189
|
+
| `orderType` | Y | varchar 1 | `1` 取貨付款/`3` 取貨不付款 |
|
|
190
|
+
| `orderAmount` | Y | number 5 | 範圍同參數版;店港澳只能 `orderType=3`,報值金額商務會員 0–2,500 |
|
|
191
|
+
| `rvName` | Y | varchar 60 | 取件人姓名;`orderType=3` 須為證件上真實姓名 |
|
|
192
|
+
| `rvEmail` | Y | varchar 100 | 店到店包裹送達時寄取件通知 |
|
|
193
|
+
| `rvMobile` | Y | varchar 10 | 店到店發台灣手機簡訊;店到宅供配送聯絡;店港澳發港澳手機簡訊 |
|
|
194
|
+
| `stCode` | 條件 | varchar 9 | **通路別 + 門市代號**(電子地圖回傳的 `stCate` + `stCode`,如 `TFM0038`);`A01`–`A04`、`A11`、`A12` 必填 |
|
|
195
|
+
| `rvAddr` | 條件 | varchar 120 | `A05`、`A06` 必填 |
|
|
196
|
+
| `rvZip` | 條件 | varchar 10 | `A05`、`A06` 必填 |
|
|
197
|
+
| `rtURL` | Y | varchar 100 | 回傳網址 |
|
|
198
|
+
| `webPara` | N | varchar 100 | 原值回傳;勿含 `' : @ % & * $ "` |
|
|
199
|
+
|
|
200
|
+
**商品明細 `<Detail>`**(可重複,非必要;有傳才可在便利配列印寄件單與撿貨報表)
|
|
201
|
+
|
|
202
|
+
| 標籤 | 型態/長度 | 說明 |
|
|
203
|
+
|---|---|---|
|
|
204
|
+
| `prodItem` | number 3 | 商品序號,**必須從 1 開始依序遞增** |
|
|
205
|
+
| `prodNo` | varchar 30 | 商品編號 |
|
|
206
|
+
| `prodName` | varchar 120 | 商品名稱 |
|
|
207
|
+
| `prodPrice` | number 5 | 價格 |
|
|
208
|
+
| `prodQty` | number 5 | 數量 |
|
|
209
|
+
| `prodSpec` | varchar 120 | 規格 |
|
|
210
|
+
|
|
211
|
+
有傳 `<Detail>` 時 `prodItem`、`prodName` 必須有值。含特殊符號的欄位以 `<![CDATA[...]]>` 包起來。
|
|
212
|
+
|
|
213
|
+
```xml
|
|
214
|
+
<ORDER>
|
|
215
|
+
<suID>service@ezship.com.tw</suID>
|
|
216
|
+
<orderID>20140318154002</orderID>
|
|
217
|
+
<orderStatus>A01</orderStatus>
|
|
218
|
+
<orderType>1</orderType>
|
|
219
|
+
<orderAmount>1680</orderAmount>
|
|
220
|
+
<rvName><![CDATA[謝無忌]]></rvName>
|
|
221
|
+
<rvEmail>123@ezship.com.tw</rvEmail>
|
|
222
|
+
<rvMobile>0987654321</rvMobile>
|
|
223
|
+
<stCode>TFM0038</stCode>
|
|
224
|
+
<rtURL>http://yourdomain.domain/direct/program.php</rtURL>
|
|
225
|
+
<webPara>20140318154002-xxx</webPara>
|
|
226
|
+
<Detail>
|
|
227
|
+
<prodItem>1</prodItem>
|
|
228
|
+
<prodNo>A2769-1</prodNo>
|
|
229
|
+
<prodName><![CDATA[格子口袋襯衫]]></prodName>
|
|
230
|
+
<prodPrice>860</prodPrice>
|
|
231
|
+
<prodQty>1</prodQty>
|
|
232
|
+
<prodSpec><![CDATA[白]]></prodSpec>
|
|
233
|
+
</Detail>
|
|
234
|
+
</ORDER>
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
回傳(snake_case):`order_id`、`sn_id`、`order_status`、`webPara`;代碼同參數版,另有 `E98` XML 無法載入、`E99` 系統錯誤。
|
|
238
|
+
|
|
157
239
|
## 3. 申請流程
|
|
158
240
|
|
|
159
241
|
1. 進入 ezShip 後台
|
|
@@ -165,22 +247,21 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
|
|
|
165
247
|
|
|
166
248
|
## 4. 技術文件
|
|
167
249
|
|
|
168
|
-
> ✅ **上一輪標記的 404 已查明**:社群流傳的是**無版號檔名** `ezship_WebOrder_HttpRequest.pdf`,實際檔名帶版本後綴。官網 `service_doc` 當時回「系統忙碌中」是暫時性的,現已可正常存取。
|
|
169
|
-
|
|
170
250
|
| 文件 | 網址 |
|
|
171
251
|
|---|---|
|
|
172
252
|
| 欄位定義(參數版)| `http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest_v15.pdf` |
|
|
173
253
|
| 欄位定義(XML 版)| `http://www.ezship.com.tw/file/ezship_WebOrder_XML_v15s.pdf` |
|
|
254
|
+
| 貨況(依店到店編號)| `http://www.ezship.com.tw/file/ezship_status_api.pdf` |
|
|
255
|
+
| 貨況(依訂單編號)| `http://www.ezship.com.tw/file/ezship_status_api_byorder.pdf` |
|
|
174
256
|
| 文件站首頁 | `https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=1702` |
|
|
175
257
|
|
|
176
|
-
|
|
258
|
+
文件站內容由 `service_doc/1702NN_doc.jsp` 載入(`04`–`09` 參數版、`10`–`16` XML 版、`17`–`18` 簡易版、`19`–`22` 貨況串接)。
|
|
177
259
|
|
|
178
260
|
官方另提供 PHP/JSP 的 BIG5 與 UTF-8 兩種版本程式碼範例。
|
|
179
261
|
|
|
180
|
-
|
|
262
|
+
`webPara` 官方定義為「網站所需額外判別資料,ezShip 將原值回傳」,是原值透傳的識別欄位(類似其他 provider 的 `ExtraData`),沒有驗證或簽章語意。ezShip **沒有簽章機制**,安全性倚賴 `su_id` 帳號綁定與 HTTPS。
|
|
181
263
|
|
|
182
|
-
-
|
|
183
|
-
- 開源實作可參考:https://github.com/recca0120/payum-ezship(PHP,`src/Api.php`)
|
|
264
|
+
開源實作可參考:https://github.com/recca0120/payum-ezship(PHP,`src/Api.php`)
|
|
184
265
|
|
|
185
266
|
> 已知的踩雷點:OpenCart 等平台串 ezShip 時會遇到 **SameSite cookie** 問題(導轉回站時 session 遺失)。若採導轉式串接,須設定 `SameSite=None; Secure`。
|
|
186
267
|
|
|
@@ -208,16 +289,11 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
|
|
|
208
289
|
|
|
209
290
|
## 7. 待補
|
|
210
291
|
|
|
211
|
-
參數版三支端點(電子地圖/傳送訂單/貨況查詢)的欄位已完整。
|
|
212
|
-
|
|
213
292
|
| 項目 | 狀態 |
|
|
214
293
|
|---|---|
|
|
215
|
-
|
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
| 大宗直寄/店退店的串接方式 | 服務存在,是否走同一組 API 未確認 |
|
|
219
|
-
|
|
220
|
-
> `webPara` 先前被記為「token 驗證欄位」,**這是誤解**。官方定義為「網站所需額外判別資料,ezShip 將原值回傳」——它是**原值透傳的識別欄位**(類似其他 provider 的 `ExtraData`/`CustomField`),沒有任何驗證或簽章語意。ezShip 的參數版**沒有簽章機制**,安全性倚賴 `su_id` 帳號綁定與 HTTPS。
|
|
294
|
+
| 大宗直寄 | 欄位定義的金額說明把「直寄店配/直寄宅配」與店到店、店到宅並列,顯示直寄訂單走同一組建單 API;開通條件與是否另有參數未載明 |
|
|
295
|
+
| 店退店(逆物流) | 串接文件未提及,應為後台操作;是否有 API 需洽 ezShip |
|
|
296
|
+
| XML 版批次多筆 | 比較表標示 XML 版可「批次多筆」,但欄位定義與範例只有單一 `<ORDER>`,批次格式未載明 |
|
|
221
297
|
|
|
222
298
|
## 8. 來源
|
|
223
299
|
|
|
@@ -228,6 +304,7 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
|
|
|
228
304
|
- 程式碼說明:連結電子地圖 — `…/2017_service_doc_home.jsp?vDocNo=1702&vDefPage=07`
|
|
229
305
|
- 程式碼說明:傳送訂單 — `…&vDefPage=08`
|
|
230
306
|
- 貨況串接(依訂單編號查詢)— `…&vDefPage=22`
|
|
307
|
+
- 欄位定義 PDF — `ezship_WebOrder_HttpRequest_v15.pdf`、`ezship_WebOrder_XML_v15s.pdf`、`ezship_status_api.pdf`、`ezship_status_api_byorder.pdf`(見 §4)
|
|
231
308
|
- 欄位定義 PDF(參數版)— http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest_v15.pdf
|
|
232
309
|
- 欄位定義 PDF(XML 版)— http://www.ezship.com.tw/file/ezship_WebOrder_XML_v15s.pdf
|
|
233
310
|
- 開源 PHP 實作 — https://github.com/recca0120/payum-ezship
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
|---|---|---|
|
|
14
14
|
| 報價 | 費率表固定,可預先算 | **必須先呼叫 API 取得即時報價**,且報價有效期短 |
|
|
15
15
|
| 建單時機 | 出貨當下 | 消費者下單當下或稍後派遣 |
|
|
16
|
-
| 取消 | 出貨前可取消 |
|
|
16
|
+
| 取消 | 出貨前可取消 | **司機接單後取消多半要付費**(見 §5) |
|
|
17
17
|
| 追蹤 | 貨態代碼(數小時~數日更新)| **司機即時座標** |
|
|
18
18
|
| 失敗處理 | 退回寄件人 | 需重新派遣或人工介入 |
|
|
19
19
|
| 服務範圍 | 全台 | **限同城/特定半徑** |
|
|
@@ -28,10 +28,12 @@
|
|
|
28
28
|
| 台灣可用 | ✅ 官方文件列台灣 | ✅ **官方 API 文件列 `tw`** | ⚠️ 見 §4 |
|
|
29
29
|
| 文件公開 | ✅ 免登入 | ✅ 免登入(Delivery Hero ODR)| ✅ 免登入 |
|
|
30
30
|
| 認證 | HMAC-SHA256 自簽 | **OAuth 2.0 + RSA 簽的 JWT assertion** | OAuth 2.0 client_credentials |
|
|
31
|
-
| 取得憑證 | 開發者後台 | **須洽
|
|
32
|
-
| 報價 | 先報價後下單,效期 5 分鐘 | `POST /orders/fee` 與 `/orders/time` 分開 |
|
|
33
|
-
| 司機座標 | ✅ | ✅ `GET /orders/{id}/coordinates` | ✅ |
|
|
34
|
-
| 尺寸限制 | 依車型 |
|
|
31
|
+
| 取得憑證 | 開發者後台 | **須洽 ODR 窗口申請** | 商家後台 |
|
|
32
|
+
| 報價 | 先報價後下單,效期 5 分鐘 | `POST /orders/fee` 與 `/orders/time` 分開 | `POST .../delivery_quotes`,回傳 `expires` |
|
|
33
|
+
| 司機座標 | ✅ | ✅ `GET /orders/{id}/coordinates` | ✅ `courier.location` |
|
|
34
|
+
| 尺寸限制 | 依車型 | **保溫箱 34×34×36 cm、前踏板 30×20×27 cm,合計 ≤ 20 kg** | 依方案 |
|
|
35
|
+
| 貨到收款 | — | `CASH_ON_DELIVERY`/`CARD_ON_DELIVERY` | — |
|
|
36
|
+
| 取消 | 媒合後 6 分鐘寬限期 | **外送夥伴接單後不能用 API 取消** | 隨時可取消,費用依階段 |
|
|
35
37
|
|
|
36
38
|
## 2. pandago(foodpanda)
|
|
37
39
|
|
|
@@ -41,25 +43,18 @@ pandago 屬 Delivery Hero 的 **On Demand Rider(ODR)API**,同一套 API
|
|
|
41
43
|
|
|
42
44
|
| 環境 | Base URL |
|
|
43
45
|
|---|---|
|
|
44
|
-
| 台灣正式 | **`https://pandago-api-apse.deliveryhero.io/tw`** |
|
|
45
|
-
|
|
|
46
|
+
| 台灣正式 | **`https://pandago-api-apse.deliveryhero.io/tw/api/v1`** |
|
|
47
|
+
| 台灣 Stage | `https://api-infra-ap-southeast-1.stg.ondemandrider.net/tw/api/v1` |
|
|
48
|
+
| 公開 Sandbox | `https://pandago-api-sandbox.deliveryhero.io/sg/api/v1`(新加坡) |
|
|
46
49
|
|
|
47
|
-
>
|
|
50
|
+
> 公開 Sandbox 只有新加坡,地址、費率、涵蓋範圍都是新加坡的;台灣的服務範圍與計價要在台灣 Stage 或正式環境驗證。
|
|
48
51
|
|
|
49
52
|
### 認證
|
|
50
53
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
2. 以私鑰簽出 JWT assertion
|
|
56
|
-
3. POST /oauth2/token
|
|
57
|
-
grant_type = client_credentials
|
|
58
|
-
client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer
|
|
59
|
-
client_assertion = <簽好的 JWT>
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
需向 pandago account manager 索取 **Client ID、Key ID、Scope**;私鑰自行產生。
|
|
54
|
+
1. 自行產生 RSA 2048 金鑰對,公鑰交給 ODR 窗口
|
|
55
|
+
2. ODR 窗口提供 `ClientID`、`KeyID`、`Scope`(格式 `pandago.api.{國碼}.*`,台灣為 `pandago.api.tw.*`)
|
|
56
|
+
3. 以私鑰簽 JWT(RS256):header `kid` = KeyID;payload `iss`、`sub` = ClientID,`jti` 隨機 UUID,`exp` 未來時間,`aud` **固定 `https://sts.deliveryhero.io`**(測試與正式皆同)
|
|
57
|
+
4. `POST /oauth2/token`:`grant_type=client_credentials`、`client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer`、`client_assertion=<JWT>`
|
|
63
58
|
|
|
64
59
|
> ⚠️ 這是 14 家 provider 中**唯一使用 JWT assertion(private_key_jwt)**的。既有的 HMAC 或 API Key 程式碼完全不能沿用。
|
|
65
60
|
|
|
@@ -67,20 +62,58 @@ OAuth 2.0,但不是常見的 client_secret 模式:
|
|
|
67
62
|
|
|
68
63
|
| 操作 | Method | 路徑 |
|
|
69
64
|
|---|---|---|
|
|
65
|
+
| 建立/更新門市(Outlet) | PUT/PATCH | `/outlets/{client_vendor_id}` |
|
|
66
|
+
| 查詢門市 | GET | `/outlets/{client_vendor_id}`、`/outletList` |
|
|
67
|
+
| 費用估算 | POST | `/orders/fee` |
|
|
68
|
+
| 時間估算 | POST | `/orders/time` |
|
|
70
69
|
| 建立訂單 | POST | `/orders` |
|
|
71
70
|
| 查詢訂單 | GET | `/orders/{order_id}` |
|
|
71
|
+
| 更新訂單 | PUT | `/orders/{order_id}` |
|
|
72
72
|
| 取消訂單 | DELETE | `/orders/{order_id}` |
|
|
73
|
-
| 費用估算 | POST | `/orders/fee` |
|
|
74
|
-
| 時間估算 | POST | `/orders/time` |
|
|
75
73
|
| 司機座標 | GET | `/orders/{order_id}/coordinates` |
|
|
74
|
+
| 取件/送達/退回證明 | GET | `/orders/proof_of_pickup/{order_id}`、`proof_of_delivery`、`proof_of_return` |
|
|
75
|
+
| 報價後確認 | POST | `/quotes`、`/quotes/{quoteId}` |
|
|
76
76
|
|
|
77
77
|
> 費用與時間是**兩支獨立端點**,跟 Lalamove 一次回傳報價+預計時間不同。要同時顯示兩者需呼叫兩次。
|
|
78
|
+
> 所有訂單都應從 Outlet 發出:`sender.client_vendor_id` 帶 Outlet ID 為建議做法;同時提供 Outlet 與寄件人明細時以 Outlet 為準。
|
|
79
|
+
|
|
80
|
+
### 建立訂單 `POST /orders`
|
|
81
|
+
|
|
82
|
+
| 欄位 | 必填 | 說明 |
|
|
83
|
+
|---|:---:|---|
|
|
84
|
+
| `client_order_id` | | 商家訂單編號 |
|
|
85
|
+
| `sender.client_vendor_id` | | Outlet ID(建議);或改帶 `sender.name`/`phone_number`/`location` |
|
|
86
|
+
| `recipient.name`、`recipient.phone_number` | ● | 電話為 E.164(`+886…`) |
|
|
87
|
+
| `recipient.location.address`/`latitude`/`longitude` | ● | 台灣可只用座標或只用地址;地址依郵政格式、不含樓層與店名,例如 `5 Lane 80 Taiyuen Road, Datong District, Taipei City 10349` |
|
|
88
|
+
| `recipient.notes`、`sender.notes` | | 給外送夥伴的取件/送件說明 |
|
|
89
|
+
| `payment_method` | ● | `PAID` 已付款/`CASH_ON_DELIVERY` 外送夥伴收現金/`CARD_ON_DELIVERY` 送達刷卡 |
|
|
90
|
+
| `amount` | | 訂單金額 |
|
|
91
|
+
| `description` | ● | 商品描述 |
|
|
92
|
+
| `coldbag_needed` | | 是否需要保冷袋 |
|
|
93
|
+
| `preordered_for` | | 預約**送達**時間(unix timestamp),45 分鐘~7 天後;立即派送請給 `null`,不要給 `0` |
|
|
94
|
+
| `packaging.size`/`weight` | | `small` 鞋盒/`medium` 背包/`large` 汽車;重量公斤 |
|
|
95
|
+
| `pickup_tasks.pickup_code` | | 取件時外送夥伴需報出的代碼 |
|
|
96
|
+
| `delivery_tasks.age_validation_required` | | 送達時驗年齡(需先與窗口確認開通) |
|
|
97
|
+
| `delivery_tasks.handover_confirmation.drop_off` | | `PIN`/`NONE`(Beta,部分國家) |
|
|
98
|
+
| `products[]` | | `name`、`external_id`、`price_amount`(貨幣最小單位);可用於部分退款 |
|
|
99
|
+
| `currency_code` | | ISO 4217 |
|
|
78
100
|
|
|
79
|
-
|
|
101
|
+
回應 `201`:`order_id`、`status`、`delivery_fee`、`distance`(公尺)、`timeline.estimated_pickup_time`/`estimated_delivery_time`、`driver`。`GET /orders/{id}` 另有 `tracking_link`、`status_history`、`proof_of_*_url`,取消時有 `cancellation.source`/`reason`。
|
|
80
102
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
103
|
+
錯誤:`400` 參數錯誤、`401` 未授權、`404` Outlet 不存在、`422` 違反業務規則。
|
|
104
|
+
|
|
105
|
+
### 訂單狀態
|
|
106
|
+
|
|
107
|
+
`NEW` → `RECEIVED` → `WAITING_FOR_TRANSPORT` → `ASSIGNED_TO_TRANSPORT` → `COURIER_ACCEPTED_DELIVERY` → `NEAR_VENDOR` → `PICKED_UP` → `COURIER_LEFT_VENDOR` → `NEAR_CUSTOMER` → `DELIVERED`;另有 `DELAYED`(預計送達時間已更新)、`CANCELLED`、`RETURNED_TO_VENDOR`。
|
|
108
|
+
|
|
109
|
+
### 取消 `DELETE /orders/{order_id}`
|
|
110
|
+
|
|
111
|
+
- **外送夥伴接單後就不能取消**,會回 `409 Uncancellable`;成功回 `204`
|
|
112
|
+
- body `reason`:`DELIVERY_ETA_TOO_LONG`、`MISTAKE_ERROR`、`REASON_UNKNOWN`
|
|
113
|
+
|
|
114
|
+
### 狀態回呼
|
|
115
|
+
|
|
116
|
+
ODR 會 POST 到商家設定的 callback URL,內容含 `order_id`、`status`、`timeline`、`driver`(有外送夥伴時含座標)、取消時的 `cancellation`。可向營運窗口申請簽章:header `X-Signature-SHA256` = hex(HMAC-SHA256(secret, 原始 body))。
|
|
84
117
|
|
|
85
118
|
## 3. Uber Direct
|
|
86
119
|
|
|
@@ -91,15 +124,63 @@ OAuth 2.0,但不是常見的 client_secret 模式:
|
|
|
91
124
|
| Token 端點 | `https://auth.uber.com/oauth/v2/token` |
|
|
92
125
|
| grant_type | `client_credentials` |
|
|
93
126
|
| scope | **`eats.deliveries`** |
|
|
94
|
-
| API Base | `https://api.uber.com
|
|
127
|
+
| API Base | `https://api.uber.com/v1` |
|
|
95
128
|
|
|
96
129
|
Token 請求用 `application/x-www-form-urlencoded`;後續 API 呼叫用 `application/json`,以 Bearer token 帶入 Authorization header。
|
|
97
130
|
|
|
98
131
|
> 💡 **Token 有效期 30 天(2,592,000 秒)**,官方明文建議快取而非每次重新產生。這與 Lalamove(每次請求都簽章)、pandago(JWT assertion)的模式都不同——Uber Direct 這邊反而要注意**別把 token 當短期憑證反覆申請**。
|
|
99
132
|
|
|
100
|
-
### API
|
|
133
|
+
### Direct API 端點
|
|
134
|
+
|
|
135
|
+
`customer_id` 為組織 ID(UUID 或 `cus_` 開頭),`delivery_id` 以 `del_` 開頭。
|
|
101
136
|
|
|
102
|
-
|
|
137
|
+
| 操作 | Method | 路徑 |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| 建立報價 | POST | `/customers/{customer_id}/delivery_quotes` |
|
|
140
|
+
| 建立配送 | POST | `/customers/{customer_id}/deliveries` |
|
|
141
|
+
| 列出配送 | GET | `/customers/{customer_id}/deliveries` |
|
|
142
|
+
| 查詢配送 | GET | `/customers/{customer_id}/deliveries/{delivery_id}` |
|
|
143
|
+
| 更新配送 | POST | `/customers/{customer_id}/deliveries/{delivery_id}` |
|
|
144
|
+
| 取消配送 | POST | `/customers/{customer_id}/deliveries/{delivery_id}/cancel` |
|
|
145
|
+
| 送達證明 | POST | `/customers/{customer_id}/deliveries/{delivery_id}/proof-of-delivery` |
|
|
146
|
+
|
|
147
|
+
### 建立報價
|
|
148
|
+
|
|
149
|
+
必填 `pickup_address`、`dropoff_address`(**JSON 字串**,例如 `"{\"street_address\":[\"…\"],\"city\":\"…\",\"zip_code\":\"…\",\"country\":\"…\"}"`);選填座標、`pickup_ready_dt`/`pickup_deadline_dt`/`dropoff_ready_dt`/`dropoff_deadline_dt`(RFC 3339)、電話、`manifest_total_value`(貨幣最小單位)、`external_store_id`。
|
|
150
|
+
|
|
151
|
+
回應:`id`(`dqt_` 開頭)、`fee`、`currency`、`expires`、`dropoff_eta`、`duration`、`pickup_duration`。
|
|
152
|
+
|
|
153
|
+
### 建立配送
|
|
154
|
+
|
|
155
|
+
| 欄位 | 必填 | 說明 |
|
|
156
|
+
|---|:---:|---|
|
|
157
|
+
| `pickup_name`、`pickup_address`、`pickup_phone_number` | ● | 電話格式 `^\+[0-9]+$` |
|
|
158
|
+
| `dropoff_name`、`dropoff_address`、`dropoff_phone_number` | ● | 同上 |
|
|
159
|
+
| `manifest_items` | ● | 品項清單,會顯示在外送夥伴 App |
|
|
160
|
+
| `quote_id` | | 先前報價的 ID |
|
|
161
|
+
| `pickup_latitude`/`longitude`、`dropoff_latitude`/`longitude` | | 建議提供,提高定位精準度 |
|
|
162
|
+
| `pickup_notes`、`dropoff_notes`、`dropoff_seller_notes` | | 各 ≤ 280 字 |
|
|
163
|
+
| `pickup_verification`、`dropoff_verification`、`return_verification` | | 拍照、掃條碼、簽名、身分驗證等 |
|
|
164
|
+
| `deliverable_action` | | `deliverable_action_meet_at_door`(預設)/`deliverable_action_leave_at_door` |
|
|
165
|
+
| `undeliverable_action` | | `return`(預設)/`leave_at_door`/`discard` |
|
|
166
|
+
| `pickup_ready_dt` | | 須在 30 天內 |
|
|
167
|
+
| `pickup_deadline_dt` | | 比 `pickup_ready_dt` 晚至少 10 分鐘,且距現在至少 20 分鐘 |
|
|
168
|
+
| `dropoff_ready_dt` | | ≤ `pickup_deadline_dt` |
|
|
169
|
+
| `dropoff_deadline_dt` | | 比 `dropoff_ready_dt` 晚至少 20 分鐘,且 ≥ `pickup_deadline_dt` |
|
|
170
|
+
| `manifest_reference` | | 與 `external_id` 的組合須唯一 |
|
|
171
|
+
| `idempotency_key` | | 防重複建單,預設保留 60 分鐘 |
|
|
172
|
+
| `tip` | | 貨幣最小單位;回應的 `fee` 已含小費 |
|
|
173
|
+
| `external_store_id` | | 建單有用時,報價也必須帶 |
|
|
174
|
+
|
|
175
|
+
錯誤:`402 customer_suspended`、`403 customer_blocked`、`409 duplicate_delivery`、`429 customer_limited`。
|
|
176
|
+
|
|
177
|
+
### 狀態與查詢
|
|
178
|
+
|
|
179
|
+
列出配送的 `filter`:`pending`、`pickup`、`pickup_complete`、`dropoff`、`delivered`、`canceled`、`returned`、`ongoing`。查詢結果含 `status`、`courier`(姓名、車種、電話、座標)、`tracking_url`、`undeliverable_action`/`undeliverable_reason`。
|
|
180
|
+
|
|
181
|
+
### 取消
|
|
182
|
+
|
|
183
|
+
`POST .../cancel`,選填 `cancelation_reason`(區分大小寫):`out_of_items`、`store_closed`、`customer_called_to_cancel`、`store_too_busy`、`courier_delayed_en_route_to_pickup`、`too_expensive`、`delivery_vehicle_too_small`、`no_courier_assigned`、`other`(需搭配 `additional_description`)。
|
|
103
184
|
|
|
104
185
|
### 服務範圍
|
|
105
186
|
|
|
@@ -114,38 +195,83 @@ Direct API、Organizations API、Courier Pick & Pack API、Refund API、Business
|
|
|
114
195
|
|
|
115
196
|
**缺乏的證據:**
|
|
116
197
|
- Uber 官方**沒有**逐一列出支援國家的清單,台灣未被點名
|
|
117
|
-
-
|
|
198
|
+
- 開發者文件未標示市場代碼或區域端點;範例地址全是美國
|
|
118
199
|
|
|
119
|
-
**結論**:可用性高度可能,但**本 skill 不將其標為已確認**。與 pandago 不同——pandago 的官方 API 文件直接列出 `tw`
|
|
200
|
+
**結論**:可用性高度可能,但**本 skill 不將其標為已確認**。與 pandago 不同——pandago 的官方 API 文件直接列出 `tw` 的正式與 Stage 端點,那是明確的一手證據。
|
|
120
201
|
|
|
121
202
|
實務建議:導入前先向 Uber 業務確認貴公司所在區域是否在服務範圍內,不要依賴行銷頁的在地化路徑判斷。
|
|
122
203
|
|
|
123
|
-
## 5.
|
|
204
|
+
## 5. 取消規則與費用
|
|
205
|
+
|
|
206
|
+
### Lalamove(台灣官方 FAQ)
|
|
207
|
+
|
|
208
|
+
| 情境 | 規則 |
|
|
209
|
+
|---|---|
|
|
210
|
+
| 尚未媒合司機 | 可直接取消 |
|
|
211
|
+
| 即時訂單 | 媒合後 **6 分鐘**內可取消 |
|
|
212
|
+
| 預約訂單 | 預定取貨時間前 **45 分鐘**內可取消 |
|
|
213
|
+
| 司機已接單並前往、或已抵達 | 收取該訂單**起始價 50%** 作為取消費 |
|
|
214
|
+
| 超過寬限期 | 須聯繫客服,可能收取取消費 |
|
|
215
|
+
|
|
216
|
+
> 以上為 Lalamove 台灣 FAQ 對一般下單的說明;API 下單是否適用同一規則需向 Lalamove 確認。
|
|
217
|
+
|
|
218
|
+
### pandago(foodpanda 商家專區「責任規範與費用收取/補償」)
|
|
219
|
+
|
|
220
|
+
API 層面:外送夥伴接單後不能取消(`409`)。依原因的費用:
|
|
221
|
+
|
|
222
|
+
| 取消原因 | 說明 | 運費收取 | 返送運費收取 | 訂單補償 |
|
|
223
|
+
|---|---|:---:|:---:|:---:|
|
|
224
|
+
| 商家失誤 | 媒合前商家取消,原因「錯誤的訂單資訊」 | 否 | 否 | 否 |
|
|
225
|
+
| 其他原因 | 媒合前商家取消,原因「顧客取消訂單」 | 否 | 否 | 否 |
|
|
226
|
+
| 商家認為媒合時間過長 | 媒合前商家取消,原因「有其他交貨方式可用」 | 否 | 否 | 否 |
|
|
227
|
+
| 商家已打烊或因任何原因需求取消 | **媒合到外送夥伴後**商家取消 | 是 | 是 | 否 |
|
|
228
|
+
| 錯誤收件地址 | 商家輸入地址錯誤或實際地址在範圍外 | 是 | 是 | 否 |
|
|
229
|
+
| 聯繫不到客戶 | 抵達後聯繫不到客戶超過 10 分鐘 | 是 | 是 | 否 |
|
|
230
|
+
| 客戶問題 | 客戶聯絡商家取消 | 是 | 是 | 否 |
|
|
231
|
+
| 客戶無法付款 | 客戶現金不足 | 是 | 是 | 否 |
|
|
232
|
+
| 送件錯誤訂單 | 交給外送夥伴的訂單錯誤,客戶拒收 | 是 | 是 | 否 |
|
|
233
|
+
| 商家已閉店 | 外送夥伴提供證明 | 是 | 是 | 否 |
|
|
234
|
+
| 訂單延遲交付 | 比承諾時間晚 30 分鐘以上,客戶拒收 | 否 | 否 | 否 |
|
|
235
|
+
| 外送夥伴失聯 | 接單後失聯,客戶不願等待 | 否 | 否 | 是 |
|
|
236
|
+
| 灑餐 | 客戶因溢漏拒收 | 否 | 否 | 是 |
|
|
237
|
+
| 遭遇事故 | 外送夥伴途中事故,客戶不願等待 | 否 | 否 | 是 |
|
|
238
|
+
| 超出運送範圍 | 外送夥伴接單後拒單 | 否 | 否 | 否 |
|
|
239
|
+
| 技術問題/超出營業時間/天氣問題/無法媒合外送夥伴 | | 否 | 否 | 否 |
|
|
240
|
+
|
|
241
|
+
### Uber Direct(Uber Help「Issues with deliveries: Uber Direct」)
|
|
242
|
+
|
|
243
|
+
- 可隨時取消(Dashboard 或 API)
|
|
244
|
+
- 需要把商品送回的餐廳,必須透過 Uber Direct 支援團隊取消,讓外送夥伴有退回的行程
|
|
245
|
+
- 該文章的非台灣版本另列:尚無外送夥伴接單時不收取消或退回費用;取件階段取消不收取消費,但收取件費補償外送夥伴;配送途中取消會收費;配送途中取消並要求退回,收配送費與退回費。**從台灣存取的版本未列費用**,台灣的實際收費需向 Uber 確認
|
|
246
|
+
|
|
247
|
+
## 6. 選型
|
|
124
248
|
|
|
125
249
|
| 情境 | 建議 |
|
|
126
250
|
|---|---|
|
|
127
|
-
| 需要明確的台灣官方端點與文件 | **pandago**(`/tw`
|
|
251
|
+
| 需要明確的台灣官方端點與文件 | **pandago**(`/tw` 正式與 Stage 端點有官方文件背書)|
|
|
128
252
|
| 已有 HMAC 簽章經驗、想快速上線 | **Lalamove**(自簽 HMAC,開發者後台自助取得憑證)|
|
|
129
253
|
| 需要多車型/路線最佳化/換司機 | **Lalamove** |
|
|
130
|
-
|
|
|
254
|
+
| 小件、標準箱體、需要貨到收款 | **pandago**(≤ 20 kg,`CASH_ON_DELIVERY`)|
|
|
131
255
|
| 已在用 Uber Eats 生態 | **Uber Direct**(但先確認台灣服務範圍)|
|
|
132
256
|
|
|
133
|
-
>
|
|
257
|
+
> 三家都**不是批次物流的替代品**。單日出貨量大、跨縣市、需要超取的情境,仍應走 ECPay/ezShip 等聚合商。即時配送適合的是同城、急件、生鮮這類批次物流做不到的需求。
|
|
134
258
|
|
|
135
|
-
##
|
|
259
|
+
## 7. 待補
|
|
136
260
|
|
|
137
261
|
| 項目 | 說明 |
|
|
138
262
|
|---|---|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
| 三家的取消政策與費用 | 即時配送的取消多半收費,各家規則未確認 |
|
|
263
|
+
| Uber Direct 台灣可用性與收費 | 官方未列支援國家;台灣版說明頁未列取消費 |
|
|
264
|
+
| pandago 台灣運費表 | 官方 API 文件與商家專區皆未列,運費以 `/orders/fee` 即時估算 |
|
|
142
265
|
|
|
143
|
-
##
|
|
266
|
+
## 8. 來源
|
|
144
267
|
|
|
145
|
-
- Delivery Hero On Demand Rider API
|
|
268
|
+
- Delivery Hero On Demand Rider API(端點、欄位、狀態、取消、回呼簽章)— https://on-demand-rider-docs.deliveryhero.io/
|
|
269
|
+
- foodpanda 商家專區 pandago(尺寸重量、責任規範與費用收取/補償)— https://vendor.foodpanda.com.tw/pandago
|
|
146
270
|
- pandago 台灣 — https://pandago.tw/
|
|
147
|
-
- foodpanda pandago 介紹 — https://www.foodpanda.com.tw/contents/pandago
|
|
148
271
|
- Uber Direct API 總覽 — https://developer.uber.com/docs/deliveries/overview
|
|
272
|
+
- Uber Direct API Reference(Direct API)— https://developer.uber.com/docs/deliveries/api-reference/daas
|
|
149
273
|
- Uber Direct 認證 — https://developer.uber.com/docs/deliveries/guides/authentication
|
|
274
|
+
- Uber Help:Issues with deliveries: Uber Direct — https://help.uber.com/en/merchants-and-restaurants/article/issues-with-deliveries-uber-direct-?nodeId=1d5914c7-b638-4d4b-8a18-d2e3cb29217a
|
|
150
275
|
- Uber Direct 商家頁(台灣在地化)— https://merchants.ubereats.com/tw/zh-tw/
|
|
151
|
-
- Lalamove
|
|
276
|
+
- Lalamove 台灣 FAQ(取消規則)— https://www.lalamove.com/zh-tw/faq
|
|
277
|
+
- Lalamove API — [lalamove-logistics-api.md](lalamove-logistics-api.md)
|
package/dist/index.js
CHANGED
|
@@ -16364,7 +16364,7 @@ async function listCommand() {
|
|
|
16364
16364
|
var import_chalk5 = __toESM(require_source());
|
|
16365
16365
|
|
|
16366
16366
|
// src/version.ts
|
|
16367
|
-
var VERSION = "1.4.
|
|
16367
|
+
var VERSION = "1.4.5";
|
|
16368
16368
|
|
|
16369
16369
|
// src/commands/info.ts
|
|
16370
16370
|
async function infoCommand() {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "taiwan-logistics-skill",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.5",
|
|
4
4
|
"description": "AI-powered Taiwan Logistics toolkit. Supports 7 aggregators (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow, ezShip), HCT direct carrier API, and on-demand delivery (Lalamove, pandago, Uber Direct).",
|
|
5
5
|
"bin": {
|
|
6
6
|
"taiwan-logistics": "./dist/index.js"
|