taiwan-logistics-skill 1.4.4 → 1.4.6

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/README.md CHANGED
@@ -118,7 +118,7 @@ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Co
118
118
  | ECPay | B2C(含冷凍)+ C2C | B2C + C2C | B2C + C2C | C2C | 常溫/冷藏/冷凍 | 中華郵政 |
119
119
  | NewebPay | B2C + C2C | C2C | C2C | C2C | — | — |
120
120
  | PAYUNi | B2C + C2C(常溫/冷凍) | — | — | — | 常溫/冷凍/冷藏 | — |
121
- | SmilePay | B2C + C2C | B2C + C2C | — | — | 含逆物流 | — |
121
+ | SmilePay | B2C + C2C | C2C | — | — | 含逆物流 | — |
122
122
  | PChomePay | 取貨付款 | 取貨付款 | 取貨付款 | — | — | — |
123
123
  | PayNow | B2C + C2C(含冷凍) | B2C + C2C(含冷凍) | C2C | C2C | 宅配、到店 | 7-11 海外 |
124
124
  | ezShip | — | C2C | C2C | C2C | — | 宅配、店港澳 |
@@ -118,7 +118,7 @@ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Co
118
118
  | ECPay | B2C(含冷凍)+ C2C | B2C + C2C | B2C + C2C | C2C | 常溫/冷藏/冷凍 | 中華郵政 |
119
119
  | NewebPay | B2C + C2C | C2C | C2C | C2C | — | — |
120
120
  | PAYUNi | B2C + C2C(常溫/冷凍) | — | — | — | 常溫/冷凍/冷藏 | — |
121
- | SmilePay | B2C + C2C | B2C + C2C | — | — | 含逆物流 | — |
121
+ | SmilePay | B2C + C2C | C2C | — | — | 含逆物流 | — |
122
122
  | PChomePay | 取貨付款 | 取貨付款 | 取貨付款 | — | — | — |
123
123
  | PayNow | B2C + C2C(含冷凍) | B2C + C2C(含冷凍) | C2C | C2C | 宅配、到店 | 7-11 海外 |
124
124
  | ezShip | — | C2C | C2C | C2C | — | 宅配、店港澳 |
@@ -20,11 +20,11 @@ CVS,LgsType=C2C ShipType=1 GoodsType=1,7-11 店到店(常溫),payuni,cvs_c2c
20
20
  CVS,LgsType=C2C ShipType=1 GoodsType=2,7-11 店到店(冷凍),payuni,cvs_c2c,true,,,冷凍,Ship=1 取貨付款、ShipTag=1 啟用物流;冷凍門市地圖 MapType 固定 2
21
21
  HOME,LgsType=HOME ShipType=2 GoodsType=1/2/3,黑貓宅配,payuni,home,,,,常溫/冷凍/冷藏,GoodsType 1 常溫/2 冷凍/3 冷藏;ConsigneeAddress、DeliveryTimeTag 必填
22
22
  CVS,Pay_zg=55/56 Pay_subzg=7NET,7-11 大宗寄倉(B2C),smilepay,cvs_b2c,true,,,常溫,55 取貨付款/56 純取貨
23
- CVS,Pay_zg=55/56 Pay_subzg=FAMI,全家 大宗寄倉(B2C),smilepay,cvs_b2c,true,,,常溫,55 取貨付款/56 純取貨
24
23
  CVS,Pay_zg=51/52 Pay_subzg=7NET,7-11 店到店(C2C),smilepay,cvs_c2c,true,,,常溫,51 取貨付款/52 純取貨
25
24
  CVS,Pay_zg=51/52 Pay_subzg=FAMI,全家 店到店(C2C),smilepay,cvs_c2c,true,,,常溫,51 取貨付款/52 純取貨
26
25
  HOME,Pay_zg=81/82 Pay_subzg=TCAT,黑貓宅配,smilepay,home,true,,,常溫/冷藏/冷凍,81 取貨付款/82 純取貨;溫層由 ezcatGetTrackNum.asp 的 temperature 0001/0002/0003 決定
27
26
  HOME,Pay_zg=83 Pay_subzg=TCAT,黑貓逆物流(退貨),smilepay,return,false,,,常溫,退貨用
27
+ CVS,Pay_zg=57/58,超商 C2B 退貨便,smilepay,return,false,,,常溫,57 消費者付運費/58 商家付運費;通知另帶 Classif R/S 與 Classif_sub
28
28
  CVS,pay_type=IPL7,7-11 超商取貨付款,pchomepay,cvs_c2c,true,20000,,常溫,金額 65–20000;物流單由金流訂單派生;不提供 OK/宅配
29
29
  CVS,pay_type=IPLFM,全家 超商取貨付款,pchomepay,cvs_c2c,true,20000,,常溫,金額 65–20000;物流單由金流訂單派生;不提供 OK/宅配
30
30
  CVS,pay_type=IPLHL,萊爾富 超商取貨付款,pchomepay,cvs_c2c,true,20000,,常溫,金額 65–20000;物流單由金流訂單派生;不提供 OK/宅配
@@ -47,9 +47,12 @@ CVS,Logistic_service=12,7-11 大宗退貨便,paynow,return,false,,,常溫,退貨
47
47
  CVS,stCate=TFM,全家 店到店,ezship,cvs_c2c,true,10000,,常溫,order_status A01–A04;order_type 1 取貨付款(代收 10–10000)/3 取貨不付款;不含 7-11
48
48
  CVS,stCate=TLF,萊爾富 店到店,ezship,cvs_c2c,true,10000,,常溫,order_status A01–A04;order_type 1 取貨付款(代收 10–10000)/3 取貨不付款;不含 7-11
49
49
  CVS,stCate=TOK,OK 店到店,ezship,cvs_c2c,true,10000,,常溫,order_status A01–A04;order_type 1 取貨付款(代收 10–10000)/3 取貨不付款;不含 7-11
50
+ CVS,stCate=TFM(B2C 寄件),全家 大宗寄倉,ezship,cvs_b2c,true,10000,,常溫,後台開啟「自動要號」後網站建單一律為 B2C 寄件;包裹送超商物流中心;長寬高合計 < 105 cm、< 5 kg
51
+ CVS,stCate=TLF(B2C 寄件),萊爾富 大宗寄倉,ezship,cvs_b2c,true,10000,,常溫,後台開啟「自動要號」後網站建單一律為 B2C 寄件;包裹送超商物流中心;長寬高合計 < 105 cm、< 5 kg
52
+ CVS,stCate=TOK(B2C 寄件),OK 大宗寄倉,ezship,cvs_b2c,true,10000,,常溫,後台開啟「自動要號」後網站建單一律為 B2C 寄件;包裹送超商物流中心;長寬高合計 < 105 cm、< 5 kg
50
53
  HOME,order_status=A05/A06,ezShip 宅配,ezship,home,true,8000,,常溫,order_type 1 取貨付款(代收 10–8000);rv_addr、rv_zip 必填
51
54
  CROSS_BORDER,stCate=TSF,店港澳,ezship,cross_border,false,,,常溫,order_status A11/A12;無代收
52
55
  HOME,eprdcl2=001/003/008,新竹物流(直連),hct_direct,home,true,,,常溫/冷凍/冷藏,eprdcl2 001 一般/003 冷凍/008 冷藏;eqmny 代收貨款
53
56
  ONDEMAND,LALAMOVE,Lalamove 即時配送,lalamove,ondemand,false,依方案,依車型,常溫,先報價後下單;報價效期5分鐘;同城/當日;可換司機;非批次物流
54
- ONDEMAND,PANDAGO,pandago 即時配送,pandago,ondemand,false,依報價,34x34x36cm/20kg,常溫,費用與時間為兩支獨立端點;Sandbox僅新加坡;不需成為foodpanda餐廳夥伴
57
+ ONDEMAND,PANDAGO,pandago 即時配送,pandago,ondemand,false,依報價,34x34x36cm/20kg,常溫,費用與時間為兩支獨立端點;公開Sandbox僅新加坡(台灣另有Stage環境);不需成為foodpanda餐廳夥伴
55
58
  ONDEMAND,UBER_DIRECT,Uber Direct 即時配送,uber_direct,ondemand,false,依報價,依方案,常溫,配送半徑約10英里;可預約最多30天;台灣可用性未經官方確認
@@ -7,16 +7,16 @@ pchomepay,拍錢包物流,PChomePay Logistics,payment_aggregator,true,請至後
7
7
  paynow,立吉富物流,PayNow Logistics,payment_aggregator,true,請至後台申請,請至後台申請,12345678,https://test.paynow.com.tw/service/etopm.aspx,https://www.paynow.com.tw/service/etopm.aspx,"11產品線(7-11/全家/黑貓/海外),3DES/ECB/Zero-Padding加密",全台,apply,https://owlting.github.io/paynow-guideline/,2026-08-08
8
8
  ezship,ezShip 台灣便利配,ezShip,aggregator,true,請至後台申請,無簽章機制,,https://map.ezship.com.tw/ezship_map_web.jsp,https://www.ezship.com.tw/emap/ezship_request_order_api_ex.jsp,"非金流商的超取聚合商,OK/萊爾富/全家(不含7-11),店到店/取貨付款/大宗直寄/店到宅/店退店,支援店港澳A11/A12,參數版無簽章倚賴su_id綁定與HTTPS,送出BIG5但回傳UTF-8,電子地圖用camelCase而訂單用snake_case,sn_id回八個零代表建單失敗,貨況查詢須間隔3秒否則中斷串接權利,代收服務需商務會員,簡易版官方已凍結不再開發,WooCommerce/OpenCart/EasyStore/CYBERBIZ/meepShop 模組",全台及港澳,public,https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=1702,2026-08-08
9
9
  lalamove,Lalamove,Lalamove,ondemand,true,請至 Lalamove 申請,請至 Lalamove 申請,,https://rest.sandbox.lalamove.com/v3,https://rest.lalamove.com/v3,"即時/同城配送,先報價後下單(報價5分鐘效期),HMAC-SHA256 CRLF簽章,可查詢/更換司機,加價priority-fee,路線最佳化,POD",台灣及13個市場,public,https://developers.lalamove.com/,2026-08-08
10
- sunpay,紅陽物流,SunPay Logistics,payment_aggregator,false,,,,https://www.sunpay.com.tw,https://www.sunpay.com.tw,"超商便利送,宅配通(少數可取得宅配通的聚合路徑),參數層待補",全台,public,https://www.sunpay.com.tw/developers/,2026-08-08
10
+ sunpay,紅陽物流,SunPay Logistics,payment_aggregator,false,,,,https://www.sunpay.com.tw,https://www.sunpay.com.tw,"官網物流頁列全家大宗貨運與 C2C 7-11/全家/萊爾富,金流 card_type=09 超商取貨付款,宅配通僅見於舊文件站 doc.esafe.com.tw,無公開物流 API 規格",全台,public,https://www.sunpay.com.tw/developers/,2026-09-24
11
11
  hct_direct,新竹物流(直連),HCT Direct API,carrier,true,test,,,https://hctapiweb.hct.com.tw,https://hctapiweb.hct.com.tw,"查貨服務+出貨API,XML/JSON/DataSet,加密金鑰申請後提供,TransReport須18:00前呼叫",全台,apply,https://www.hct.com.tw,2026-08-08
12
- unimart,7-11 交貨便,7-11 ibon,cvs,false,,,,,https://emap.pcsc.com.tw,"店到店;無對外商家API;交貨便/賣貨便為賣家自助平台;須經 ECPay/SmilePay/PayNow/PChomePay 聚合商",全台 5000+ 門市,none,https://myship.7-11.com.tw/MyShip/Index,2026-08-08
13
- fami,全家店到店,FamilyMart,cvs,false,,,,,https://www.famiport.com.tw,"店到店;無對外商家API;好賣+為賣家自助平台;須經聚合商",全台 3500+ 門市,none,https://www.famiport.com.tw,2026-08-08
14
- hilife,萊爾富,Hi-Life,cvs,false,,,,,https://www.hilife.com.tw,"店到店;無獨立對外API;須經 ECPay/ezShip 等聚合商",全台 1500+ 門市,none,https://www.hilife.com.tw,2026-08-08
15
- okmart,OK 便利商店,OK Mart,cvs,false,,,,,,"店到店;無獨立對外API;須經 ECPay/ezShip 等聚合商",全台 900+ 門市,none,,2026-08-08
16
- tcat,黑貓宅急便,t-cat,home,false,,,,https://www.t-cat.com.tw,https://www.t-cat.com.tw,"常溫/冷藏/冷凍;無公開API規格;官方為 ezcat 印單軟體+契約客戶 iCat/API 授權;建議走 SmilePay(Pay_zg 81/82/83) 或 ECPay",全台,contract,https://www.t-cat.com.tw/contract/ezcat.aspx,2026-08-08
17
- pelican,宅配通,Pelican Express,home,false,,,,https://www.pelican.com.tw,https://www.pelican.com.tw,"常溫;無公開API規格;可經紅陽 SunPay 等聚合商取得",全台,contract,https://www.pelican.com.tw,2026-08-08
12
+ unimart,7-11 交貨便,7-11 ibon,cvs,false,,,,,https://emap.pcsc.com.tw,店到店;無對外商家API;交貨便/賣貨便為賣家自助平台;須經 ECPay/SmilePay/PayNow/PChomePay 聚合商,全台 5000+ 門市,none,https://myship.7-11.com.tw/MyShip/Index,2026-08-08
13
+ fami,全家店到店,FamilyMart,cvs,false,,,,,https://www.famiport.com.tw,店到店;無對外商家API;好賣+為賣家自助平台;須經聚合商,全台 3500+ 門市,none,https://www.famiport.com.tw,2026-08-08
14
+ hilife,萊爾富,Hi-Life,cvs,false,,,,,https://www.hilife.com.tw,店到店;無獨立對外API;須經 ECPay/ezShip 等聚合商,全台 1500+ 門市,none,https://www.hilife.com.tw,2026-08-08
15
+ okmart,OK 便利商店,OK Mart,cvs,false,,,,,,店到店;無獨立對外API;須經 ECPay/ezShip 等聚合商,全台 900+ 門市,none,,2026-08-08
16
+ tcat,黑貓宅急便,t-cat,home,false,,,,https://www.t-cat.com.tw,https://www.t-cat.com.tw,常溫/冷藏/冷凍;無公開API規格;官方為 ezcat 印單軟體+契約客戶 iCat/API 授權;建議走 SmilePay(Pay_zg 81/82/83) 或 ECPay,全台,contract,https://www.t-cat.com.tw/contract/ezcat.aspx,2026-08-08
17
+ pelican,宅配通,Pelican Express,home,false,,,,https://www.pelican.com.tw,https://www.pelican.com.tw,"常溫;無公開API規格;紅陽舊文件站曾列宅配通,官網物流頁已未列;可用的聚合路徑需向業者確認",全台,contract,https://www.pelican.com.tw,2026-09-24
18
18
  kerrytj,嘉里大榮,Kerry TJ Logistics,home,false,,,,https://www.kerrytj.com,https://www.kerrytj.com,"常溫;官網僅貨態查詢頁,無公開API規格;須簽約洽業務",全台,contract,https://www.kerrytj.com/zh/checking,2026-08-08
19
19
  post,中華郵政,Chunghwa Post,home,false,,,,https://www.post.gov.tw,https://www.post.gov.tw,"注意:中華郵政 Open API 僅開放金融類(存款/ATM/匯率/餘額),物流面完全無 API;郵政宅配須經 ECPay 等聚合商;流傳的包裹查詢API為非官方逆向",全台,none,https://www.post.gov.tw/post/internet/Message/index.jsp?ID=1584329354372,2026-08-08
20
- shopee_store,蝦皮店到店,Shopee Store-to-Store,cvs,false,,,,,,"無對外商家API;僅蝦皮生態內可用;無替代路徑",全台,none,,2026-08-08
20
+ shopee_store,蝦皮店到店,Shopee Store-to-Store,cvs,false,,,,,,無對外商家API;僅蝦皮生態內可用;無替代路徑,全台,none,,2026-08-08
21
21
  pandago,pandago 熊貓速配,pandago (Delivery Hero),ondemand,true,請洽 account manager,RSA私鑰自行產生,,https://pandago-api-sandbox.deliveryhero.io/sg,https://pandago-api-apse.deliveryhero.io/tw,"即時/同城配送,Delivery Hero On Demand Rider API 同套服務Glovo與Talabat,OAuth2以RSA簽的JWT assertion(private_key_jwt)為14家中唯一,費用與時間為兩支獨立端點,司機即時座標,包裹限34x34x36cm與20kg,零售商家不需成為foodpanda餐廳夥伴,Sandbox僅有新加坡sg無台灣沙箱",台灣(正式端點官方列tw),public,https://on-demand-rider-docs.deliveryhero.io/,2026-08-08
22
22
  uber_direct,Uber Direct,Uber Direct,ondemand,true,請至商家後台申請,client_credentials,,https://api.uber.com,https://api.uber.com,"即時/同城配送,OAuth2 client_credentials scope為eats.deliveries,token有效30天官方建議快取,配送半徑約10英里,可選2小時內/當日/最多預約30天,另有Organizations與Courier Pick&Pack與Refund等API,台灣可用性僅有間接證據官方未點名見references/ondemand-delivery.md",⚠️台灣可用性未經官方確認,public,https://developer.uber.com/docs/deliveries/overview,2026-08-08
@@ -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,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
930
- ezship,A02,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
931
- ezship,A03,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
932
- ezship,A04,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
933
- ezship,A05,宅配,Home Delivery,order_type,建單時的訂單狀態分組 宅配類 須帶 rv_addr 與 rv_zip,
934
- ezship,A06,宅配,Home Delivery,order_type,建單時的訂單狀態分組 宅配類 須帶 rv_addr 與 rv_zip,
935
- ezship,A11,店港澳,HK/Macau Store,order_type,建單時的訂單狀態分組 店港澳類 須帶 st_code,
936
- ezship,A12,店港澳,HK/Macau Store,order_type,建單時的訂單狀態分組 店港澳類 須帶 st_code,
937
- ezship,S05,包裹退貨,Package Returned,returned,貨況查詢回傳 此狀態無法呈現最終貨況,登入 ezShip 系統查詢最終貨況
938
- ezship,S06,包裹配送異常,Delivery Exception,error,貨況查詢回傳 此狀態無法呈現最終貨況,登入 ezShip 系統查詢最終貨況
939
- ezship,00000000,建單失敗,Order Creation Failed,error,傳送訂單回傳的 sn_id 為八個零即代表建單失敗 無獨立錯誤碼欄位,檢查必填欄位與帳號是否已開通網站串接
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')
@@ -47,7 +47,7 @@
47
47
 
48
48
  **現況**:無公開 API 規格。已列於 `providers.csv` 是因為它是**可用的配送通路**(部分聚合商支援),不是因為可直連。
49
49
 
50
- **已知**:紅陽科技(SunPay)的物流服務項目中列有「宅配通」,代表可經由該聚合商使用。
50
+ **已知**:紅陽科技(SunPay)舊文件站 doc.esafe.com.tw 列有「宅配通」,但官網物流頁(sunpay.com.tw/logistics,2026-09-24 查核)已未列,也沒有對應的 API 規格;可用的聚合路徑需向業者確認。
51
51
 
52
52
  ## 4. 中華郵政 ⚠️ 常見誤解
53
53
 
@@ -30,12 +30,25 @@
30
30
 
31
31
  ### 物流相關端點
32
32
 
33
- | 功能 | 測試環境 | 正式環境 |
34
- |------|----------|----------|
35
- | 建立物流訂單 | `/Express/Create` | `/Express/Create` |
36
- | 超商電子地圖 | `/Express/map` | `/Express/map` |
37
- | 列印託運單 | `/helper/printTradeDocument` | `/helper/printTradeDocument` |
38
- | 查詢訂單 | `/Helper/QueryLogisticsTradeInfo/V2` | `/Helper/QueryLogisticsTradeInfo/V2` |
33
+ | 功能 | 路徑 | 官方頁 |
34
+ |------|------|--------|
35
+ | 門市電子地圖 | `/Express/map` | /8795 |
36
+ | 取得門市清單 | `/Helper/GetStoreList` | /47496 |
37
+ | 建立物流訂單(超商、宅配) | `/Express/Create` | /8809、/7414 |
38
+ | 產生測試標籤資料(B2C) | `/Express/CreateTestData` | /7402 |
39
+ | 列印託運單:B2C(含測標)、宅配 | `/helper/printTradeDocument` | /8875 |
40
+ | 列印託運單:C2C 7-ELEVEN | `/Express/PrintUniMartC2COrderInfo` | /7406 |
41
+ | 列印託運單:C2C 全家 | `/Express/PrintFAMIC2COrderInfo` | /8848 |
42
+ | 列印託運單:C2C 萊爾富 | `/Express/PrintHILIFEC2COrderInfo` | /8858 |
43
+ | 列印託運單:C2C OK | `/Express/PrintOKMARTC2COrderInfo` | 綠界官方 ecpay-api-skill guides/06 |
44
+ | 逆物流:B2C 7-ELEVEN/全家/萊爾富 | `/express/ReturnUniMartCVS`、`/express/ReturnCVS`、`/express/ReturnHilifeCVS` | /7408、/8894、/8896 |
45
+ | 逆物流:宅配 | `/Express/ReturnHome` | /7416 |
46
+ | 異動訂單:B2C 7-ELEVEN | `/Helper/UpdateShipmentInfo` | /7410 |
47
+ | 異動門市:C2C 7-ELEVEN | `/Express/UpdateStoreInfo` | /8907 |
48
+ | 取消訂單:C2C 7-ELEVEN | `/Express/CancelC2COrder` | /7412 |
49
+ | 查詢物流訂單 | `/Helper/QueryLogisticsTradeInfo/V5` | /7418 |
50
+
51
+ 2024-11-25 起查詢 API 版本為 **V5**(/36099 更新歷程)。
39
52
 
40
53
  ---
41
54
 
@@ -182,62 +195,53 @@ POST /Express/Create
182
195
 
183
196
  | 參數 | 類型 | 必填 | 說明 |
184
197
  |------|------|------|------|
185
- | `MerchantID` | String(10) | ● | 商店代號 |
186
- | `MerchantTradeNo` | String(20) | ● | 訂單編號 (唯一) |
187
- | `MerchantTradeDate` | String(20) | ● | 訂單日期 `yyyy/MM/dd HH:mm:ss` |
188
- | `LogisticsType` | String(20) | ● | 物流類型 `CVS`/`HOME` |
189
- | `LogisticsSubType` | String(20) | ● | 物流子類型 |
190
- | `GoodsAmount` | Integer | ● | 商品金額 |
191
- | `GoodsName` | String(50) | ● | 商品名稱 |
192
- | `SenderName` | String(10) | ● | 寄件人姓名 |
193
- | `SenderPhone` | String(20) | ● | 寄件人電話 |
194
- | `SenderCellPhone` | String(20) | 否 | 寄件人手機 |
195
- | `ReceiverName` | String(10) | ● | 收件人姓名 |
196
- | `ReceiverPhone` | String(20) | ● | 收件人電話 |
197
- | `ReceiverCellPhone` | String(20) | 否 | 收件人手機 |
198
+ | `MerchantID` | String(10) | ● | 廠商編號 |
199
+ | `MerchantTradeNo` | String(20) | ● | 廠商交易編號,唯一 |
200
+ | `MerchantTradeDate` | String(20) | ● | `yyyy/MM/dd HH:mm:ss` |
201
+ | `LogisticsType` | String(20) | ● | `CVS`/`HOME` |
202
+ | `LogisticsSubType` | String(20) | ● | 見「物流類型」 |
203
+ | `GoodsAmount` | Int | ● | 超商 1–20,000;宅配 1 元以上(黑貓代收時上限 20,000) |
204
+ | `GoodsName` | String(50) | 條件 | 超商 `UNIMARTC2C`、`HILIFEC2C`、`OKMARTC2C` 必填 |
205
+ | `SenderName` | String(10) | ● | 4–10 字元(中文 2–5 字),不可含數字、特殊符號、emoji;C2C 退件須憑證件領取,勿填公司名 |
206
+ | `ReceiverName` | String(10) | ● | 同上 |
198
207
  | `ServerReplyURL` | String(200) | ● | 物流狀態通知網址 |
199
- | `CheckMacValue` | String | ● | 檢查碼 |
208
+ | `ClientReplyURL` | String(200) | | Client 端回傳網址 |
209
+ | `ReceiverEmail` | String(50) | | 收件人 email |
210
+ | `TradeDesc` | String(200) | | 交易描述 |
211
+ | `Remark` | String(200) | | 備註 |
212
+ | `PlatformID` | String(10) | | 平台商代號 |
213
+ | `CheckMacValue` | String | ● | 檢查碼(MD5) |
200
214
 
201
- ### 超商取貨專用參數
215
+ ### 超商專用參數(/8809)
202
216
 
203
217
  | 參數 | 類型 | 必填 | 說明 |
204
218
  |------|------|------|------|
205
- | `ReceiverStoreID` | String(6) | ● | 收件門市代號 |
206
- | `ReturnStoreID` | String(6) | 否 | 退貨門市代號 |
207
- | `IsCollection` | String(1) | 否 | 是否代收貨款 `Y`/`N` |
208
- | `CollectionAmount` | Integer | 否 | 代收金額 |
219
+ | `ReceiverStoreID` | String(6) | ● | 收件門市代碼 |
220
+ | `ReturnStoreID` | String(6) | | 退貨門市;僅 7-ELEVEN C2C 適用,未帶則退回原寄件門市 |
221
+ | `SenderPhone` | String(20) | | 寄件人電話 |
222
+ | `SenderCellPhone` | String(10) | 條件 | `UNIMARTC2C`、`HILIFEC2C`、`OKMARTC2C` 必填;09 開頭 10 碼;`FAMIC2C` 空值時帶入後台設定 |
223
+ | `ReceiverPhone` | String(20) | | 允許數字與 `()-#` |
224
+ | `ReceiverCellPhone` | String(10) | ● | 09 開頭 10 碼 |
225
+ | `IsCollection` | String(1) | | `Y` 代收貨款、`N` 不代收(預設) |
226
+ | `CollectionAmount` | Int | 條件 | `UNIMARTC2C`、`UNIMART`、`UNIMARTFREEZE` 須等於 `GoodsAmount` |
209
227
 
210
- ### 宅配專用參數
228
+ ### 宅配專用參數(/7414)
211
229
 
212
230
  | 參數 | 類型 | 必填 | 說明 |
213
231
  |------|------|------|------|
214
- | `SenderZipCode` | String(5) | ● | 寄件人郵遞區號 |
215
- | `SenderAddress` | String(200) | ● | 寄件人地址 |
216
- | `ReceiverZipCode` | String(5) | ● | 收件人郵遞區號 |
217
- | `ReceiverAddress` | String(200) | ● | 收件人地址 |
218
- | `Temperature` | String(4) | 否 | 溫層 `0001`常溫 `0002`冷藏 `0003`冷凍 |
219
- | `Distance` | String(2) | 否 | 距離 `00`同縣市 `01`外縣市 `02`離島 |
220
- | `Specification` | String(4) | 否 | 規格 (見下表) |
221
- | `ScheduledDeliveryTime` | String(1) | 否 | 預定送達時段 |
222
- | `ScheduledDeliveryDate` | String(10) | 否 | 預定送達日期 |
223
-
224
- ### Specification 規格代碼
225
-
226
- | 代碼 | 尺寸 |
227
- |------|------|
228
- | `0001` | 60cm |
229
- | `0002` | 90cm |
230
- | `0003` | 120cm |
231
- | `0004` | 150cm |
232
-
233
- ### ScheduledDeliveryTime 時段代碼
234
-
235
- | 代碼 | 時段 |
236
- |------|------|
237
- | `1` | 13:00 前 |
238
- | `2` | 14:00-18:00 |
239
- | `3` | 不限時 |
240
- | `4` | 任何時間 (黑貓夜配) |
232
+ | `SenderPhone`/`SenderCellPhone` | String(20) | 擇一 | |
233
+ | `ReceiverPhone`/`ReceiverCellPhone` | String(20) | 擇一 | |
234
+ | `SenderZipCode` | String(6) | ● | 寄件人郵遞區號 |
235
+ | `SenderAddress` | String(60) | ● | 6–60 字元;中華郵政僅台灣本島 |
236
+ | `ReceiverZipCode` | String(6) | ● | 收件人郵遞區號 |
237
+ | `ReceiverAddress` | String(60) | ● | 收件人地址 |
238
+ | `IsCollection` | String(1) | | `Y` 代收(僅 `TCAT`,商品金額上限 20,000);中華郵政勿填 |
239
+ | `GoodsWeight` | Number | 條件 | `POST` 必填,公斤,上限 20、小數 3 位 |
240
+ | `Temperature` | String(4) | | `0001` 常溫(預設)、`0002` 冷藏、`0003` 冷凍;`POST` 只能 `0001` |
241
+ | `Distance` | String(2) | | `00` 同縣市(預設)、`01` 外縣市、`02` 離島;`POST` 忽略 |
242
+ | `Specification` | String(4) | | `0001` 60cm(預設)、`0002` 90cm、`0003` 120cm、`0004` 150cm;冷藏冷凍不可用 150cm;`POST` 忽略 |
243
+ | `ScheduledPickupTime` | String(1) | | 固定帶 `4`(不限時);`POST` 忽略 |
244
+ | `ScheduledDeliveryTime` | String(2) | | `1` 13 點前、`2` 14–18 點、`4` 不限時(官方表另列 `3` 亦為 14–18 點) |
241
245
 
242
246
  ### PHP 範例 - 超商取貨
243
247
 
@@ -349,23 +353,19 @@ HTML;
349
353
 
350
354
  ## 列印託運單
351
355
 
352
- ### 端點
353
-
354
- ```
355
- POST /helper/printTradeDocument
356
- ```
357
-
358
- ### 參數
356
+ ### B2C(含測標)、宅配 `POST /helper/printTradeDocument`(/8875)
359
357
 
360
358
  | 參數 | 類型 | 必填 | 說明 |
361
359
  |------|------|------|------|
362
- | `MerchantID` | String(10) | ● | 商店代號 |
363
- | `AllPayLogisticsID` | String(20) | ● | ECPay 物流編號 |
360
+ | `MerchantID` | String(10) | ● | 廠商編號 |
361
+ | `AllPayLogisticsID` | String | ● | 物流交易編號,批次列印以半形逗號分隔 |
362
+ | `PlatformID` | String(10) | | 平台商代號 |
363
+ | `PrintMode` | Int | | `1` 一般 A4、`2` 熱感應標籤 A6 |
364
364
  | `CheckMacValue` | String | ● | 檢查碼 |
365
365
 
366
- ### 回應
366
+ 回傳 HTML 頁面(`Accept: text/html`)。**不可放在 iframe**,導向超商時會被阻擋。
367
367
 
368
- 成功時會回傳 PDF 檔案內容。
368
+ C2C 各超商另有列印端點(見上方端點表),需帶 `CVSPaymentNo`(7-11 另帶 `CVSValidationNo`)。
369
369
 
370
370
  ---
371
371
 
@@ -374,33 +374,23 @@ POST /helper/printTradeDocument
374
374
  ### 端點
375
375
 
376
376
  ```
377
- POST /Helper/QueryLogisticsTradeInfo/V2
377
+ POST /Helper/QueryLogisticsTradeInfo/V5
378
378
  ```
379
379
 
380
- ### 參數
380
+ ### 參數(/7418)
381
381
 
382
382
  | 參數 | 類型 | 必填 | 說明 |
383
383
  |------|------|------|------|
384
- | `MerchantID` | String(10) | ● | 商店代號 |
385
- | `AllPayLogisticsID` | String(20) | ● | ECPay 物流編號 |
384
+ | `MerchantID` | String(10) | ● | 廠商編號 |
385
+ | `AllPayLogisticsID` | String(20) | 擇一 | 綠界物流交易編號 |
386
+ | `MerchantTradeNo` | String(20) | 擇一 | 廠商交易編號 |
387
+ | `TimeStamp` | Int | ● | Unix 時間,3 分鐘內有效 |
388
+ | `PlatformID` | String(10) | | 平台商代號 |
386
389
  | `CheckMacValue` | String | ● | 檢查碼 |
387
390
 
388
391
  ### 回應參數
389
392
 
390
- | 參數 | 說明 |
391
- |------|------|
392
- | `MerchantID` | 商店代號 |
393
- | `MerchantTradeNo` | 訂單編號 |
394
- | `AllPayLogisticsID` | ECPay 物流編號 |
395
- | `LogisticsType` | 物流類型 |
396
- | `LogisticsSubType` | 物流子類型 |
397
- | `LogisticsStatus` | 物流狀態碼 |
398
- | `GoodsAmount` | 商品金額 |
399
- | `UpdateStatusDate` | 狀態更新時間 |
400
- | `ReceiverName` | 收件人姓名 |
401
- | `ReceiverPhone` | 收件人電話 |
402
- | `ReceiverStoreID` | 收件門市代號 |
403
- | `TradeDate` | 交易時間 |
393
+ `MerchantID`、`MerchantTradeNo`、`AllPayLogisticsID`、`LogisticsType`(如 `CVS_UNIMARTC2C`)、`LogisticsStatus`(代碼見 /7440)、`GoodsAmount`、`GoodsName`、`GoodsWeight`、`ActualWeight`、`HandlingCharge`、`CollectionAmount`、`CollectionChargeFee`、`CollectionAllocateAmount`、`CollectionAllocateDate`、`CVSPaymentNo`、`CVSValidationNo`、`ShipmentNo`、`ShipChargeDate`、`BookingNote`、`TradeDate`、`SenderName`、`SenderPhone`、`SenderCellPhone`、`CheckMacValue`。
404
394
 
405
395
  ---
406
396
 
@@ -21,7 +21,7 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
21
21
  |---|---|
22
22
  | 超商取貨 | 店到店,買家至指定門市取件 |
23
23
  | 超商取貨付款 | 貨到付款(COD) |
24
- | 大宗直寄 | 大量出貨直送門市 |
24
+ | B2C 寄件(大宗寄倉)| 包裹依超商分箱送至各超商物流中心再轉運門市,只收店配,見 §2.3 |
25
25
  | 店到宅 | 門市寄件、宅配到府 |
26
26
  | 店退店 | 逆物流 |
27
27
  | 臉書店 | 社群電商賣場 |
@@ -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`)是先前未收錄的能力——ezShip 是本 skill 少數支援港澳店配的聚合商。
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`、`rtn_url`、`web_para`。
142
+ 送出:`su_id`、`sn_id`(依店到店編號)或 `order_no`(依訂單編號,≤25)、`rtn_url`、`web_para`。
143
143
 
144
- 回傳:`sn_id`、`order_no`、`order_status`、`webPara`,另有三個時序欄位:
144
+ 回傳:`sn_id`、`order_no`(僅依訂單編號查詢)、`order_status`、`webPara`,另有三個時序欄位:
145
145
 
146
146
  | 參數 | 說明 |
147
147
  |---|---|
@@ -149,11 +149,169 @@ 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
+
239
+ ## 2.3 B2C 寄件(大宗寄倉)與寄件單下載 API
240
+
241
+ 來源:服務說明 `service_home_w18v1.jsp?vDocNo=2501`(內容頁 `service_doc/2501NN_doc.jsp`,`NN`=01–23)。
242
+
243
+ **服務**:賣家把包裹依取件超商分箱,自行以貨運/宅配/郵局送到該超商物流中心,由物流中心轉運至門市(p.01–02)。只收「店配–取貨付款」與「店配–取貨不付款」(p.02)。
244
+
245
+ | 超商 | 物流中心 | 收貨時間(當日轉運)| 材積 |
246
+ |---|---|---|---|
247
+ | 全家 | 日翊物流大溪倉,桃園市大溪區仁善里15鄰新光東路76巷22-2號 | 08:30–14:00;14:01–16:30 隔日;需先在全家「廠商進貨預約平台」預約(7 家指定貨運商免預約)| 長+寬+高 < 105 cm、最長邊 < 45 cm、< 5 kg |
248
+ | 萊爾富 | 新北市樹林區味王街1-25號(38號碼頭)| 08:00–14:00;14:01–15:00 隔日 | 同上 |
249
+ | OK | 來來物流,桃園市大溪區仁善里9鄰新光東路63巷88號(42-43碼頭)| 08:00–14:00;14:01–17:00 隔日 | 長+寬+高 < 105 cm、最長邊 45 cm、其餘兩邊 ≤ 30 cm、< 5 kg |
250
+
251
+ (p.05–07)當日轉運者次日中午前送達門市。取貨付款每筆代收上限 10,000 元(p.08)。
252
+
253
+ **啟用**(p.03、p.19):限 ezShip 商務會員且合約有效。後台「我的便利配 → 設定 → 配送服務 → B2C寄件設定」:
254
+
255
+ - **自動要號**:開啟後,以網站串接(§2.1/§2.2 的建單 API)建立的寄件資料**一律視為 B2C 寄件**並自動取號。若部分訂單仍要門市寄件(店到店),不可開啟
256
+ - **來源 IP**:登錄呼叫寄件單 API 的對外 IP
257
+
258
+ 也就是**建單沒有另一組 API**,B2C 與店到店的差別由帳號設定決定。
259
+
260
+ ### 單筆寄件單下載(p.20)
261
+
262
+ `https://www.ezship.com.tw/emap/ezship_request_order_label_api.jsp`,Form submit 或 URL 參數。
263
+
264
+ | 參數 | 說明 |
265
+ |---|---|
266
+ | `suID` | ezShip 帳號(需開通網站串接)|
267
+ | `sn_id` | 店到店編號 |
268
+
269
+ 成功直接輸出寄件單 PDF。錯誤以文字輸出:
270
+
271
+ | 訊息 | 原因 |
272
+ |---|---|
273
+ | `Error: The requested header does not contain a valid source IP address.` | 來源 IP 未設定 |
274
+ | `Error: The requested file with sn_id : … was not found.` | `sn_id` 不存在 |
275
+ | `Error: The requested file was not found.` | `suID` 錯誤或未開自動要號 |
276
+
277
+ ### 多筆寄件單下載(p.21)
278
+
279
+ 兩步驟,皆 `POST` JSON(UTF-8),需先設定來源 IP。
280
+
281
+ **步驟一** `https://www.ezship.com.tw/myezship_label/myezship_order_print_api.jsp` — 建立批次表單
282
+
283
+ | 欄位 | 說明 |
284
+ |---|---|
285
+ | `ezship_id` | ezShip 帳號 |
286
+ | `label_for` | 固定 `4` |
287
+ | `label_printer` | `A` A4 四格;`B` 標籤機 10×15 |
288
+ | `label_printtype` | `A` 只印寄件單;`B` 寄件單+明細 |
289
+ | `label_merge` | `A` 三家超商合併;`B` 各超商分開檔案 |
290
+ | `sn_list[].sn_id` | 店到店編號 |
291
+
292
+ 回應:`errorCode`、`ezship_id`、`file_id`(步驟二使用)、`success_count`、`fail_count`、`fail_list[].sn_id`、`total`、`request_id`。
293
+
294
+ **步驟二** `https://www.ezship.com.tw/myezship_label/myezship_order_label_api.jsp` — 取得 PDF 網址
295
+
296
+ 請求 `ezship_id`、`file_id`;回應 `errorCode`、`file_list[].file_url`、`file_count`、`request_id`。每 100 筆切一個檔案,製作約 1 分鐘/百筆。
297
+
298
+ | `errorCode` | 意義 |
299
+ |---|---|
300
+ | `000` | 成功 |
301
+ | `001` | 新增失敗 |
302
+ | `002` | JSON 格式有誤 |
303
+ | `003` | 會員權限異常 |
304
+ | `004` | 製作中(步驟二)|
305
+ | `005` | 製作失敗(步驟二)|
306
+ | `006` | 尚未製作(步驟二)|
307
+ | `007` | 非允許 IP |
308
+ | `008` | 禁止一分鐘內多次傳送(步驟一)|
309
+ | `999` | 傳送失敗 |
310
+
311
+ > ⚠️ 步驟一一分鐘內不可重送(`008`);步驟二回 `004` 時稍後再查,不要重跑步驟一。
312
+
313
+ **逾期未領**(p.10):貨到門市 7 天未取即退回超商物流中心,依「B2C寄件設定」的退貨週期整箱待領,**由寄件人自行委託物流業者取回**,超過 30 日未處理將捐贈或回收。沒有退貨 API。
314
+
157
315
  ## 3. 申請流程
158
316
 
159
317
  1. 進入 ezShip 後台
@@ -165,22 +323,21 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
165
323
 
166
324
  ## 4. 技術文件
167
325
 
168
- > ✅ **上一輪標記的 404 已查明**:社群流傳的是**無版號檔名** `ezship_WebOrder_HttpRequest.pdf`,實際檔名帶版本後綴。官網 `service_doc` 當時回「系統忙碌中」是暫時性的,現已可正常存取。
169
-
170
326
  | 文件 | 網址 |
171
327
  |---|---|
172
328
  | 欄位定義(參數版)| `http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest_v15.pdf` |
173
329
  | 欄位定義(XML 版)| `http://www.ezship.com.tw/file/ezship_WebOrder_XML_v15s.pdf` |
330
+ | 貨況(依店到店編號)| `http://www.ezship.com.tw/file/ezship_status_api.pdf` |
331
+ | 貨況(依訂單編號)| `http://www.ezship.com.tw/file/ezship_status_api_byorder.pdf` |
174
332
  | 文件站首頁 | `https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=1702` |
175
333
 
176
- 文件站以 `vDefPage` 參數分頁(`04`–`09` 參數版、`10`–`16` XML 版、`17`–`18` 簡易版、`19`–`23` 貨況串接)。
334
+ 文件站內容由 `service_doc/1702NN_doc.jsp` 載入(`04`–`09` 參數版、`10`–`16` XML 版、`17`–`18` 簡易版、`19`–`22` 貨況串接)。
177
335
 
178
336
  官方另提供 PHP/JSP 的 BIG5 與 UTF-8 兩種版本程式碼範例。
179
337
 
180
- ### 已知欄位線索
338
+ `webPara` 官方定義為「網站所需額外判別資料,ezShip 將原值回傳」,是原值透傳的識別欄位(類似其他 provider 的 `ExtraData`),沒有驗證或簽章語意。ezShip **沒有簽章機制**,安全性倚賴 `su_id` 帳號綁定與 HTTPS。
181
339
 
182
- - 傳遞參數中有預留的 **`webPara`** 欄位,用於**令牌驗證(token)**功能——這是把 ezShip 回傳對回自家訂單的關鍵欄位,設計上類似其他 provider 的 `MerchantTradeNo` 或 `ExtraData`
183
- - 開源實作可參考:https://github.com/recca0120/payum-ezship(PHP,`src/Api.php`)
340
+ 開源實作可參考:https://github.com/recca0120/payum-ezship(PHP,`src/Api.php`)
184
341
 
185
342
  > 已知的踩雷點:OpenCart 等平台串 ezShip 時會遇到 **SameSite cookie** 問題(導轉回站時 session 遺失)。若採導轉式串接,須設定 `SameSite=None; Secure`。
186
343
 
@@ -208,16 +365,10 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
208
365
 
209
366
  ## 7. 待補
210
367
 
211
- 參數版三支端點(電子地圖/傳送訂單/貨況查詢)的欄位已完整。
212
-
213
368
  | 項目 | 狀態 |
214
369
  |---|---|
215
- | 貨況代碼 | 建單的 `A`/`S01`/`E` 代碼已依 PDF 補齊;貨況查詢回傳的 `S05`/`S06` 等完整對照待補 |
216
- | XML 版欄位 | 端點與能力差異已確認,欄位定義在 `ezship_WebOrder_XML_v15s.pdf` |
217
- | 商品資料結構 | XML 版獨有(可列印含商品明細寄件單),欄位待補 |
218
- | 大宗直寄/店退店的串接方式 | 服務存在,是否走同一組 API 未確認 |
219
-
220
- > `webPara` 先前被記為「token 驗證欄位」,**這是誤解**。官方定義為「網站所需額外判別資料,ezShip 將原值回傳」——它是**原值透傳的識別欄位**(類似其他 provider 的 `ExtraData`/`CustomField`),沒有任何驗證或簽章語意。ezShip 的參數版**沒有簽章機制**,安全性倚賴 `su_id` 帳號綁定與 HTTPS。
370
+ | 店退店(逆物流) | 串接文件與 B2C 寄件說明都未提供 API;B2C 逾期件由寄件人自行至物流中心取回。是否有 API 需洽 ezShip |
371
+ | XML 版批次多筆 | 比較表標示 XML 版可「批次多筆」,但欄位定義與範例只有單一 `<ORDER>`,批次格式未載明 |
221
372
 
222
373
  ## 8. 來源
223
374
 
@@ -228,6 +379,8 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
228
379
  - 程式碼說明:連結電子地圖 — `…/2017_service_doc_home.jsp?vDocNo=1702&vDefPage=07`
229
380
  - 程式碼說明:傳送訂單 — `…&vDefPage=08`
230
381
  - 貨況串接(依訂單編號查詢)— `…&vDefPage=22`
382
+ - B2C 寄件服務說明 — https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=2501&vDefPage=19(內容頁 `service_doc/250101_doc.jsp`–`250123_doc.jsp`,2026-09-24 查核)
383
+ - 欄位定義 PDF — `ezship_WebOrder_HttpRequest_v15.pdf`、`ezship_WebOrder_XML_v15s.pdf`、`ezship_status_api.pdf`、`ezship_status_api_byorder.pdf`(見 §4)
231
384
  - 欄位定義 PDF(參數版)— http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest_v15.pdf
232
385
  - 欄位定義 PDF(XML 版)— http://www.ezship.com.tw/file/ezship_WebOrder_XML_v15s.pdf
233
386
  - 開源 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
- | 取得憑證 | 開發者後台 | **須洽 account manager 申請** | 商家後台 |
32
- | 報價 | 先報價後下單,效期 5 分鐘 | `POST /orders/fee` 與 `/orders/time` 分開 | quote 端點 |
33
- | 司機座標 | ✅ | ✅ `GET /orders/{id}/coordinates` | ✅ |
34
- | 尺寸限制 | 依車型 | **34×34×36 cm、20 kg**(foodpanda 外送箱)| 依方案 |
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
- | Sandbox | `https://pandago-api-sandbox.deliveryhero.io/sg` |
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
- > ⚠️ **Sandbox 只有 `sg`(新加坡)**,沒有台灣沙箱。測試時的地址、費率、涵蓋範圍都是新加坡的,**不能用來驗證台灣的服務範圍或計價**。
50
+ > 公開 Sandbox 只有新加坡,地址、費率、涵蓋範圍都是新加坡的;台灣的服務範圍與計價要在台灣 Stage 或正式環境驗證。
48
51
 
49
52
  ### 認證
50
53
 
51
- OAuth 2.0,但不是常見的 client_secret 模式:
52
-
53
- ```
54
- 1. 產生 RSA 金鑰對
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
- - 包裹須放得進 foodpanda 外送箱:**34 × 34 × 36 cm**
82
- - **上限 20 公斤**
83
- - 零售商家**不需成為 foodpanda 餐廳夥伴**即可使用,可直接填單叫車
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
- Direct API、Organizations API、Courier Pick & Pack API、Refund API、Business Location Management API。
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
- | 小件、標準箱體、不需成為餐飲夥伴 | **pandago**(34×34×36 cm / 20 kg 內)|
254
+ | 小件、標準箱體、需要貨到收款 | **pandago**(≤ 20 kg,`CASH_ON_DELIVERY`)|
131
255
  | 已在用 Uber Eats 生態 | **Uber Direct**(但先確認台灣服務範圍)|
132
256
 
133
- > 三家都**不是批次物流的替代品**。單日出貨量大、跨縣市、需要超取或貨到付款的情境,仍應走 ECPay/ezShip 等聚合商。即時配送適合的是同城、急件、生鮮這類批次物流做不到的需求。
257
+ > 三家都**不是批次物流的替代品**。單日出貨量大、跨縣市、需要超取的情境,仍應走 ECPay/ezShip 等聚合商。即時配送適合的是同城、急件、生鮮這類批次物流做不到的需求。
134
258
 
135
- ## 6. 待補
259
+ ## 7. 待補
136
260
 
137
261
  | 項目 | 說明 |
138
262
  |---|---|
139
- | pandago `/orders` 逐欄 | 端點與認證已確認,request/response 欄位待擷取 |
140
- | Uber Direct 端點逐欄 | 認證已確認;API reference 為 SPA,需以瀏覽器取得 |
141
- | 三家的取消政策與費用 | 即時配送的取消多半收費,各家規則未確認 |
263
+ | Uber Direct 台灣可用性與收費 | 官方未列支援國家;台灣版說明頁未列取消費 |
264
+ | pandago 台灣運費表 | 官方 API 文件與商家專區皆未列,運費以 `/orders/fee` 即時估算 |
142
265
 
143
- ## 7. 來源
266
+ ## 8. 來源
144
267
 
145
- - Delivery Hero On Demand Rider API — https://on-demand-rider-docs.deliveryhero.io/
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 — [lalamove-logistics-api.md](lalamove-logistics-api.md)
276
+ - Lalamove 台灣 FAQ(取消規則)— https://www.lalamove.com/zh-tw/faq
277
+ - Lalamove API — [lalamove-logistics-api.md](lalamove-logistics-api.md)
@@ -6,8 +6,10 @@
6
6
  > SmilePay 物流 API 與金流 API **共用同一個帳號** (`Dcvc` + `Verify_key`)。
7
7
  > 你不會再看到「物流商代號」之類的東西 — SmilePay 是「金物流整合服務商」,
8
8
  > 它在背後再串接 7-11、全家、黑貓 (TCAT) 等實際物流業者。
9
- > 對開發者而言,所有物流產品都透過「**SmilePay 同一組 API + 不同的 `Pay_zg` / `Pay_subzg` 編碼**」
10
- > 來路由。掌握這個矩陣是整合 SmilePay 物流的祖傳秘方。
9
+ > 所有物流產品都透過同一組 API,以 `Pay_zg`/`Pay_subzg` 編碼路由。
10
+ >
11
+ > 來源:速買配官方 WooCommerce 外掛 **1.1.23**(`smilepay-module-for-woocommerce`)與 **4.3.3**(各功能分檔,
12
+ > 附 ReadMe 修訂日期 2023/03/31)。兩版不一致處逐項註明。
11
13
 
12
14
  ---
13
15
 
@@ -41,10 +43,11 @@ SmilePay 物流 API 支援 **三大物流體系,共 7 種物流產品**:
41
43
  | 7-11 超商取貨 | C2C 店到店 | 個人/小商家取貨;走 7-11 交貨便系統 |
42
44
  | 7-11 超商取貨 | B2C 大宗寄倉 | 商家大量寄倉;走大智通配送中心 |
43
45
  | 全家 超商取貨 | C2C 店到店 | 個人/小商家取貨;走全家店到店系統 |
44
- | 全家 超商取貨 | B2C 大宗寄倉 | 商家大量寄倉 (走全家專屬配送) |
45
- | 黑貓宅急便 | 常溫 | TCAT 室溫宅配 |
46
- | 黑貓宅急便 | 冷藏 | TCAT 0~7°C 冷藏宅配 |
47
- | 黑貓宅急便 | 冷凍 | TCAT -18°C 冷凍宅配 |
46
+ | 全家 超商取貨 | B2C 大宗寄倉 | 兩版外掛都未實作,見下方編碼表註記 |
47
+ | 黑貓宅急便 | 常溫 | |
48
+ | 黑貓宅急便 | 冷藏 | |
49
+ | 黑貓宅急便 | 冷凍 | |
50
+ | 7-11 退貨便 | C2B | 消費者寄回商家;4.3.3 ReadMe 標為 B2C 商家限定 |
48
51
 
49
52
  ### 整合方式
50
53
 
@@ -236,8 +239,7 @@ WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
236
239
 
237
240
  ## Pay_zg / Pay_subzg 編碼矩陣
238
241
 
239
- > **這是 SmilePay 物流的祖傳秘方** — 所有物流產品都從同一支 `SPPayment.asp`
240
- > 進入,靠 `Pay_zg`(主要分類)+ `Pay_subzg`(副分類)來路由到實際物流業者。
242
+ 所有物流產品都從 `SPPayment.asp`(或 `mtmk_utf.asp` 結帳頁)進入,靠 `Pay_zg`(主要分類)+ `Pay_subzg`(副分類)路由到實際物流業者。
241
243
 
242
244
  ### Pay_zg(物流主分類)
243
245
 
@@ -250,7 +252,8 @@ WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
250
252
  | `TCAT_COD_PAY_ZG` | `81` | 黑貓宅配 **取貨付款** |
251
253
  | `TCAT_PICKUP_PAY_ZG` | `82` | 黑貓宅配 **純取貨** |
252
254
  | `RETCAT_PAY_ZG` | `83` | 黑貓 **逆物流(退貨)** |
253
- | `c2b_payzg` | (商家自訂) | C2B 退貨便(由商家後台設定,常見值依超商而異) |
255
+ | — | `57` | C2B 退貨便,運費由消費者付 |
256
+ | — | `58` | C2B 退貨便,運費由商家付(1.1.23 設定預設值) |
254
257
 
255
258
  ### Pay_subzg(物流副分類)
256
259
 
@@ -270,15 +273,19 @@ WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
270
273
  | 7-11 B2C 大宗寄倉 | 純取貨 | `56` | `7NET` |
271
274
  | 全家 C2C 店到店 | 取貨付款 | `51` | `FAMI` |
272
275
  | 全家 C2C 店到店 | 純取貨 | `52` | `FAMI` |
273
- | 全家 B2C 大宗寄倉 | 取貨付款 | `55` | `FAMI` |
274
- | 全家 B2C 大宗寄倉 | 純取貨 | `56` | `FAMI` |
276
+ | 全家 B2C 大宗寄倉 | 取貨付款 | `55`? | `FAMI`? |
277
+ | 全家 B2C 大宗寄倉 | 純取貨 | `56`? | `FAMI`? |
275
278
  | 黑貓常溫 / 冷藏 / 冷凍 | 取貨付款 | `81` | `TCAT` |
276
279
  | 黑貓常溫 / 冷藏 / 冷凍 | 純取貨 | `82` | `TCAT` |
277
280
  | 黑貓逆物流(退貨) | — | `83` | `TCAT` |
281
+ | 7-11 退貨便(C2B) | 運費消費者付/商家付 | `57`/`58` | `7NET` |
278
282
 
279
- **注意**:黑貓的「常溫 / 冷藏 / 冷凍」差異**不是**靠 `Pay_zg` 區分,
280
- 而是走第二支 API `ezcatGetTrackNum.asp` 時的 `temperature` 參數
281
- (`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍)。
283
+ > **全家 B2C 未經證實**:1.1.23 只有 `FAMIB2C` 的電子地圖網址,建單分支沒有全家 B2C;
284
+ > 4.3.3 的全家 B2C 整段被註解掉,ReadMe 也只列 7-11 B2C。實際代碼以速買配規格書為準。
285
+
286
+ **注意**:黑貓的「常溫 / 冷藏 / 冷凍」差異**不是**靠 `Pay_zg` 區分,而是 `temperature` 參數
287
+ (`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍)。兩版外掛送的位置不同:
288
+ 1.1.23 送在第二階段 `ezcatGetTrackNum.asp`;4.3.3 送在第一階段 `SPPayment.asp`(`Pay_zg=81/82`),第二階段不再送。
282
289
 
283
290
  ### 路由邏輯(PHP 範例)
284
291
 
@@ -304,11 +311,7 @@ function determine_pay_codes(string $typesserver, string $payment_method): array
304
311
  'pay_zg' => $is_cod ? 51 : 52,
305
312
  'pay_subzg' => 'FAMI',
306
313
  ];
307
- case 'FAMIB2C':
308
- return [
309
- 'pay_zg' => $is_cod ? 55 : 56,
310
- 'pay_subzg' => 'FAMI',
311
- ];
314
+ // FAMIB2C:兩版外掛都沒有建單分支,未確認代碼
312
315
  }
313
316
  throw new InvalidArgumentException("Unknown typesserver: {$typesserver}");
314
317
  }
@@ -353,6 +356,7 @@ POST https://ssl.smse.com.tw/api/SPPayment.asp
353
356
  | `Logistics_Roturl` | String(URL) | ● | **物流貨況通知網址** |
354
357
  | `Roturl_status` | String | △ | 回傳狀態識別碼(如 `woook1.1.23`) |
355
358
  | `Remark` | String | △ | 備註(取自買家結帳備註) |
359
+ | `Logistics_MapType` | String | △ | `M`=行動版電子地圖;4.3.3 偵測到 Android/iPad/iPhone 時帶入 |
356
360
 
357
361
  #### 回應(XML)
358
362
 
@@ -383,6 +387,20 @@ POST https://ssl.smse.com.tw/api/SPPayment.asp
383
387
  - HTTP body 含 `<SmilePay>`
384
388
  - `<Status>` 等於 `1`
385
389
 
390
+ **兩版外掛的建單方式差異**
391
+
392
+ | 產品 | 1.1.23 | 4.3.3 |
393
+ |------|--------|-------|
394
+ | C2C 取貨付款 `51` | 後端 POST `SPPayment.asp` | 同左(`smilepayc2c.php`) |
395
+ | B2C 取貨付款 `55` | 後端 POST `SPPayment.asp` | **瀏覽器轉址到 `mtmk_utf.asp`**,帶 `MapRoturl`;有預選門市才帶 `Logistics_store`(`smilepayb2c.php`) |
396
+ | C2C/B2C 純取貨 `52`/`56` | 後端 POST `SPPayment.asp` | 同左,商家在後台開啟訂單時才建單(`smilepayc2cup.php`、`smilepayb2cup.php`) |
397
+ | 黑貓 `81`/`82` | 後端 POST `SPPayment.asp` | 同左,`temperature` 在此階段送出(`smilepayezcatp.php`、`smilepayezcatup.php`) |
398
+
399
+ 取貨付款的**款項通知**走金流的 `Roturl`,以 `Classif` 區分:`T` 超商 C2C、`V` 超商 B2C、`O` 黑貓(4.3.3 `smilepay_respond.php`;1.1.23 對 `T`、`O` 將訂單設為 completed)。
400
+ 貨況通知另走 `Logistics_Roturl`(見[通知與貨況](#通知與貨況))。
401
+
402
+ 4.3.3 ReadMe:交貨便服務單產生後須於 7 日內出貨,逾期失效;黑貓與純取貨的物流單要由商家在後台訂單頁觸發才會建立。
403
+
386
404
  ### 第二階段:取得實際物流編號
387
405
 
388
406
  依物流產品分為三條路徑:
@@ -452,12 +470,12 @@ POST https://ssl.smse.com.tw/api/ezcatGetTrackNum.asp
452
470
  | `Dcvc` | ● | 商家代號 |
453
471
  | `Verify_key` | ● | 共享密鑰 |
454
472
  | `smseid` | ● | 第一階段拿到的 `SmilePayNO` |
455
- | `package_size` | ● | 包裹尺寸(60/90/120/150 cm) |
456
- | `temperature` | ● | 溫層:`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍 |
457
- | `delivery_date` | △ | 預定送達日 (`YYYY/MM/DD`) |
458
- | `delivery_timezone` | △ | 預定送達時段(`1`/`2`/`4`) |
459
- | `is_protect` | △ | 易碎品保護(`1` 啟用;`0` 不送出此參數) |
460
- | `shipment_type` | △ | 出貨類型 |
473
+ | `package_size` | ● | `0001` 60 cm/`0002` 90 cm/`0003` 120 cm/`0004` 150 cm(150 僅常溫;冷藏、冷凍上限 120) |
474
+ | `temperature` | △ | 溫層:`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍(4.3.3 改在第一階段送) |
475
+ | `delivery_date` | △ | 預定送達日 `YYYY-MM-DD`(兩版外掛都送此格式;4.3.3 預設隔日,遇週日延一天) |
476
+ | `delivery_timezone` | △ | `1` 13 時前/`2` 14–18 時/`4` 不指定(4.3.3 固定送 `4`) |
477
+ | `is_protect` | △ | `Y` 使用/`N` 不使用;選「預設」時不送 |
478
+ | `shipment_type` | △ | `1` 手動出貨/`2` 黑貓派工;選「預設」時不送 |
461
479
  | `receiver_address` | △ | 收件地址(逆物流時用) |
462
480
 
463
481
  回應:
@@ -840,7 +858,7 @@ echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應
840
858
 
841
859
  > 黑貓只回 `1/3/5/7/8` 這幾個狀態,沒有 `2/4/6`。
842
860
 
843
- #### DetailStatus 異常代碼(節錄)
861
+ #### DetailStatus 異常代碼
844
862
 
845
863
  | 代碼 | 異常類型 |
846
864
  |------|---------|
@@ -869,11 +887,21 @@ echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應
869
887
  | `009` | 超大 |
870
888
  | `010` | 人不在 |
871
889
  | `011` | 已收走 |
890
+ | `012` | 暫不退 |
891
+ | `013` | 電話暫停使用 |
872
892
  | `014` | 商品送達時已拒收退回 |
873
893
  | `015` | 地址有誤 |
894
+ | `016` | 無件可退 |
874
895
  | `017` | PCHOME 通知取消 |
896
+ | `018` | 不知回收何物,自行與廠商聯絡 |
897
+ | `019` | 要換貨,需廠商再聯繫 |
898
+ | `020` | 僅需索取說明書,需廠商聯繫 |
899
+ | `021` | 多日聯絡不到,需廠商再聯繫 |
900
+ | `022` | 改住址 |
901
+ | `023` | 區號錯誤 |
875
902
  | `024` | 其他 |
876
903
  | `025` | 已集貨 |
904
+ | `026` | 廠商通知取消 |
877
905
  | `999` | 訂單復原 |
878
906
  | `P26` | 另約時間 |
879
907
  | `P27` | 電聯不上 |
@@ -886,6 +914,7 @@ echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應
886
914
 
887
915
  > **處理順序**:通知進來時先檢查 `DetailStatus`,**有值就優先記錄異常**,
888
916
  > 然後直接回應 `<Roturlstatus>接收到配送異常XXX</Roturlstatus>` 結束 (不再處理 `Shipstatus`)。
917
+ > 4.3.3(`smilepay_logistic_status.php` `ezcat_logistic_callback`)有 `DetailStatus` 時只寫訂單備註就結束,**不回應任何字串**;兩版代碼表相同。
889
918
 
890
919
  #### 回應格式
891
920
 
@@ -974,8 +1003,8 @@ GET https://ssl.smse.com.tw/ezpos/mtmk_utf.asp
974
1003
  | `Rvg2c` | ● | 簽章驗證代碼 |
975
1004
  | `Verify_key` | ● | 共享密鑰 |
976
1005
  | `Od_sob` | ● | 訂單編號(會原樣回傳) |
977
- | `Pay_zg` | ● | C2B 退貨便用值(商家後台設定的 `c2b_payzg`,依超商不同) |
978
- | `Pay_subzg` | ● | `7NET` 或 `FAMI` |
1006
+ | `Pay_zg` | ● | `57` 運費由消費者付/`58` 運費由商家付(兩版相同) |
1007
+ | `Pay_subzg` | ● | 4.3.3 固定 `7NET`;1.1.23 沿用原 B2C 訂單的值,且只允許 B2C 訂單建立退貨便 |
979
1008
  | `Data_id` | ● | 訂單編號 |
980
1009
  | `Amount` | ● | 退款金額 |
981
1010
  | `Pur_name` | ● | 退貨人姓名 |
@@ -999,6 +1028,8 @@ GET https://ssl.smse.com.tw/ezpos/mtmk_utf.asp
999
1028
 
1000
1029
  完整退貨便代碼 = `Paymentno` + `Validationno`
1001
1030
 
1031
+ 4.3.3(`smilepayc2b.php` `c2b_recv_order_process`)另讀 `Classif`(`R` 或 `S` 才視為成功)與 `Classif_sub`,並以 Form 自動送出到 `mtmk_utf.asp`(欄位名寫成小寫 `verify_key`,未帶 `Tel_number`、`Logistics_Roturl`)。
1032
+
1002
1033
  #### PHP 範例
1003
1034
 
1004
1035
  ```php
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.4";
16367
+ var VERSION = "1.4.6";
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.4",
3
+ "version": "1.4.6",
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"