taiwan-logistics-skill 1.3.0 → 1.4.0

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
@@ -99,7 +99,7 @@ taiwan-logistics init --global # 全域安裝
99
99
 
100
100
  ## 14 個 AI 平台支援
101
101
 
102
- Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Roo Code · Gemini · Trae · OpenCode · Continue · CodeBuddy
102
+ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Cline · Gemini · Trae · OpenCode · Continue · CodeBuddy
103
103
 
104
104
  ## 物流類型支援矩陣
105
105
 
@@ -6,7 +6,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
6
6
 
7
7
  Taiwan Logistics Skill is an AI-powered toolkit for Taiwan logistics integration, providing API documentation, code examples, and scripts for major logistics platforms. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8
8
 
9
- **Supported Providers:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `paynow`, `ezship`, `lalamove`, `hct_direct`
9
+ **Supported Providers:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `paynow`, `ezship`, `lalamove`, `pandago`, `uber_direct`, `hct_direct`
10
+
11
+ **即時/同城配送(`ondemand`):** `lalamove`、`pandago`、`uber_direct` 三家。此分類與批次物流(超取/宅配)的資料模型不同——報價有效期短、以「趟」為單位、司機有即時座標。見 `references/ondemand-delivery.md`。⚠️ Uber Direct 的台灣可用性僅有間接證據,官方未點名確認。
10
12
 
11
13
  **No public API(僅列於 providers.csv 供查詢,`api_available=false`):** 黑貓 t-cat、嘉里大榮、宅配通、中華郵政、7-11 交貨便/賣貨便、全家好賣+、萊爾富、OK、蝦皮店到店。原因與替代路徑見 `references/carrier-direct-access.md`。
12
14
 
@@ -46,7 +48,7 @@ taiwan-logistics/ # Source of Truth
46
48
  ├── operations.csv # cross-provider API operations
47
49
  ├── logistics-types.csv # CVS/Home/temp variants
48
50
  ├── status-codes.csv # vendor-specific status codes
49
- └── field-mappings.csv # cross-provider field mapping
51
+ └── field-mappings.csv # 22 欄位 × 11 家 provider 對照(含即時配送)
50
52
 
51
53
  logistics-cli/ # CLI installer (taiwan-logistics-skill on npm)
52
54
  ├── src/
@@ -104,7 +106,7 @@ When modifying files:
104
106
  | Kiro | `.kiro` | full |
105
107
  | Codex | `.codex` | full |
106
108
  | Qoder | `.qoder` | full |
107
- | Roo Code | `.roo` | full |
109
+ | Cline | `.cline` | full |
108
110
  | Gemini | `.gemini` | full |
109
111
  | Trae | `.trae` | full |
110
112
  | OpenCode | `.opencode` | full |
@@ -3253,6 +3253,38 @@ SmilePay 透過 `Pay_zg` 矩陣編碼涵蓋 7-11/全家 + 黑貓三大配送:
3253
3253
  3. **JSON / XML / DataSet 三種變體**:建議用 JSON 變體,避開 .NET DataSet 跨語言難題。
3254
3254
  4. **逆物流只有 JSON**:`R_TransData` 沒有 XML 或 DataSet 版本。
3255
3255
 
3256
+ ## ezShip 台灣便利配範例
3257
+
3258
+ ### 完整 Python 範例
3259
+ 請見 [`examples/ezship-logistics-example.py`](examples/ezship-logistics-example.py) — 涵蓋電子地圖、傳送訂單、貨況查詢三步驟,並內建自我驗證。
3260
+
3261
+ ### ⚠️ 兩個跨端點的不一致
3262
+
3263
+ 1. **參數命名風格不同**:電子地圖用 camelCase(`suID` / `rtURL` / `webPara`),傳送訂單與貨況查詢用 snake_case(`su_id` / `rtn_url` / `web_para`)。同一次串接要寫兩種。
3264
+ 2. **編碼方向不對稱**:以 URL 方式送出時中文需 **BIG5** 編碼,但 ezShip **回傳一律 UTF-8**。官方建議優先用 FORM SUBMIT 可避開這問題。
3265
+
3266
+ ### ⚠️ 建單失敗的唯一訊號是 `sn_id` 八個零
3267
+
3268
+ 沒有獨立的錯誤碼欄位。`sn_id` 回 `00000000` 即失敗;非八個零即成功,且**必須把 `sn_id` 存起來**,後續寄件與追蹤貨況都靠它。
3269
+
3270
+ ### 三個會被打回或被停權的點
3271
+
3272
+ | 限制 | 後果 |
3273
+ |---|---|
3274
+ | `rv_name` 超過四個中英文字 | 超商取貨單印不完整,可能無法取貨 |
3275
+ | 貨況查詢間隔 < 3 秒 | 官方明文將「**中斷其網路串接之權利**」 |
3276
+ | 電子地圖嵌入 iframe 或 CSS | 官方明文禁止 |
3277
+
3278
+ ### 通路與涵蓋
3279
+
3280
+ - **不含 7-ELEVEN**:只有 OK(`TOK`)、萊爾富(`TLF`)、全家(`TFM`)。客群以 7-11 為主者,ezShip 不能單獨滿足需求。
3281
+ - **支援店港澳**:`order_status` 的 `A11` / `A12` 是香港與澳門店配。
3282
+ - 代收服務(取貨付款/貨到付款)需 ezShip **商務會員**資格。
3283
+
3284
+ ### 門市代碼
3285
+
3286
+ 可能四碼或五碼(如 `TFM9771`),且**與門市服務代號不一定相同**。直接把 ezShip 給的值原封回傳即可,不要自行轉換。
3287
+
3256
3288
  ---
3257
3289
 
3258
3290
  **更多範例持續更新中...**
@@ -1,23 +1,23 @@
1
- field_name,field_zh,ecpay_name,newebpay_name,payuni_name,smilepay_name,pchomepay_name,paynow_name,hct_name,type,required,notes
2
- merchant_id,商店代號,MerchantID,uid,MerID,Dcvc,APP_ID (Basic Auth),merID,CustomerNo,string,true,HCT 直連用 CustomerNo;PChomePay 用 Basic Auth → token
3
- order_id,訂單編號,MerchantTradeNo,merchant_order_no,MerTradeNo,Data_id,order_id,(自選),epino,string,true,HCT 必須 esdate+epino 唯一組合
4
- order_date,訂單日期,MerchantTradeDate,create_time,TradeTime,(系統決定),(系統決定),(系統決定),esdate (YYYY/MM/DD),string,true,HCT esdate 是「出貨日期」格式為 yyyy/MM/dd
5
- logistics_type,物流類型,LogisticsType,lgs_type,LogisticsType,Pay_zg,pay_type,LogisticServiceID,(N/A — HCT 直連碳貓),string,true,SmilePay 用 Pay_zg 編碼;PayNow 用 ServiceID 區分 11 條產品線
6
- logistics_sub_type,物流子類型,LogisticsSubType,lgs_sub_type,LogisticsSubType,Pay_subzg,logistic_type,(內含於 ServiceID),(N/A),string,true,SmilePay Pay_subzg=7NET/FAMI;PChomePay logistic_type=PL711/PLFMI/PLHIL/PLOK
7
- logistics_id,物流編號,AllPayLogisticsID,logistics_id,PayUniLogisticsID,Smseid,(returned in data),LogisticTradeNo,edelno,string,false,廠商回傳;HCT 在 100 天內唯一
8
- goods_amount,代收金額,GoodsAmount,goods_amount,GoodsAmount,Amount,(via金流),Amount,eamtcod,integer,true,COD 才填;HCT 用 eamtcod (epaytype=2)
9
- goods_name,商品名稱,GoodsName,goods_name,GoodsName,od_sob,(無),GoodsName,eprdcl1,string,true,SmilePay 用 od_sob
10
- sender_name,寄件人姓名,SenderName,sender_name,SenderName,(無 — 商家固定),(後台設定),SenderName,epname,string,true,
11
- sender_phone,寄件人電話,SenderPhone,sender_tel,SenderPhone,(無),(後台設定),SenderPhone,eptel,string,true,
12
- sender_address,寄件人地址,SenderAddress,sender_address,SenderAddress,(無),(後台設定),SenderAddress,eaddr2,string,false,宅配必填
13
- receiver_name,收件人姓名,ReceiverName,receiver_name,ReceiverName,Pur_name,name,ReceiverName,epdcl1,string,true,
14
- receiver_phone,收件人電話,ReceiverPhone,receiver_tel,ReceiverPhone,Pur_telno,phone,ReceiverPhone,epdcl2,string,true,
15
- receiver_address,收件人地址,ReceiverAddress,receiver_address,ReceiverAddress,Address,address,ReceiverAddress,eaddr1,string,false,宅配必填
16
- receiver_store_id,收件門市代號,ReceiverStoreID,receiver_store_code,ReceiverStoreID,(透過 Emap 選店回傳),store_id,ReceiverStoreID,(N/A),string,false,超商必填;SmilePay/PayNow/PChomePay 透過電子地圖選店 callback 回傳
17
- return_store_id,退貨門市代號,ReturnStoreID,return_store_code,ReturnStoreID,(無),return_store_id,(無),(N/A),string,false,
18
- is_collection,是否代收,IsCollection,is_collection,N/A,(由 Pay_zg 決定),(由 pay_type 決定),(由 IsCOD/Y/N 決定),epaytype=2,string,false,SmilePay 從 Pay_zg 51/55/81 (COD) vs 52/56/82 (PICKUP) 判斷
19
- collection_amount,代收金額,CollectionAmount,collection_amount,N/A,Amount,(via 金流),Amount,eamtcod,integer,false,
20
- temperature,溫層,Temperature,temperature,Temperature,Temperature (1/2/3),(透過 logistic_type),(內含於 ServiceID),eshipment,string,false,1常溫 2冷藏 3冷凍;PayNow 透過產品線細分
21
- weight,重量,(N/A),(N/A),(N/A),(N/A),(N/A),(N/A),eweight,integer,false,HCT 直連必填;其他 aggregator 通常自動分箱
22
- package_count,件數,(N/A),(N/A),(N/A),(N/A),(N/A),(N/A),eqmny,integer,false,HCT 必填
23
- server_reply_url,通知網址,ServerReplyURL,notify_url,NotifyURL,Roturl,(後台設定),ReturnURL,(N/A — 用 webhook),string,true,HCT 直連靠主動查詢,無 push notify
1
+ field_name,field_zh,ecpay_name,newebpay_name,payuni_name,smilepay_name,pchomepay_name,paynow_name,hct_name,ezship_name,lalamove_name,pandago_name,uber_direct_name,type,required,notes
2
+ merchant_id,商店代號,MerchantID,uid,MerID,Dcvc,APP_ID (Basic Auth),merID,CustomerNo,su_id,(無;走 API key),clientId,(無;走 OAuth),string,true,HCT 直連用 CustomerNo;PChomePay 用 Basic Auth → token
3
+ order_id,訂單編號,MerchantTradeNo,merchant_order_no,MerTradeNo,Data_id,order_id,(自選),epino,order_id,ref (自訂),client_order_id,external_id,string,true,HCT 必須 esdate+epino 唯一組合
4
+ order_date,訂單日期,MerchantTradeDate,create_time,TradeTime,(系統決定),(系統決定),(系統決定),esdate (YYYY/MM/DD),(系統決定),(系統決定),(系統決定),(系統決定),string,true,HCT esdate 是「出貨日期」格式為 yyyy/MM/dd
5
+ logistics_type,物流類型,LogisticsType,lgs_type,LogisticsType,Pay_zg,pay_type,LogisticServiceID,(N/A — HCT 直連碳貓),order_status (A01-A06/A11-A12),(單一;即時配送),(單一),(單一),string,true,SmilePay 用 Pay_zg 編碼;PayNow 用 ServiceID 區分 11 條產品線
6
+ logistics_sub_type,物流子類型,LogisticsSubType,lgs_sub_type,LogisticsSubType,Pay_subzg,logistic_type,(內含於 ServiceID),(N/A),(由 stCate 決定 TOK/TLF/TFM),serviceType (車型),(無),(無),string,true,SmilePay Pay_subzg=7NET/FAMI;PChomePay logistic_type=PL711/PLFMI/PLHIL/PLOK
7
+ logistics_id,物流編號,AllPayLogisticsID,logistics_id,PayUniLogisticsID,Smseid,(returned in data),LogisticTradeNo,edelno,sn_id (八個零=建單失敗),orderId,order_id,id,string,false,廠商回傳;HCT 在 100 天內唯一
8
+ goods_amount,代收金額,GoodsAmount,goods_amount,GoodsAmount,Amount,(via金流),Amount,eamtcod,order_amount,item 價值,(無),manifest_total_value,integer,true,COD 才填;HCT 用 eamtcod (epaytype=2)
9
+ goods_name,商品名稱,GoodsName,goods_name,GoodsName,od_sob,(無),GoodsName,eprdcl1,(無),remarks,description,manifest_items[].name,string,true,SmilePay 用 od_sob
10
+ sender_name,寄件人姓名,SenderName,sender_name,SenderName,(無 — 商家固定),(後台設定),SenderName,epname,(由帳號決定),sender.name,sender.name,pickup_name,string,true,
11
+ sender_phone,寄件人電話,SenderPhone,sender_tel,SenderPhone,(無),(後台設定),SenderPhone,eptel,(由帳號決定),sender.phone,sender.phone_number,pickup_phone_number,string,true,
12
+ sender_address,寄件人地址,SenderAddress,sender_address,SenderAddress,(無),(後台設定),SenderAddress,eaddr2,(由帳號決定),stops[0].address,sender.location,pickup_address,string,false,宅配必填
13
+ receiver_name,收件人姓名,ReceiverName,receiver_name,ReceiverName,Pur_name,name,ReceiverName,epdcl1,rv_name (超過四字印不完整),recipient.name,recipient.name,dropoff_name,string,true,
14
+ receiver_phone,收件人電話,ReceiverPhone,receiver_tel,ReceiverPhone,Pur_telno,phone,ReceiverPhone,epdcl2,rv_mobile,recipient.phone,recipient.phone_number,dropoff_phone_number,string,true,
15
+ receiver_address,收件人地址,ReceiverAddress,receiver_address,ReceiverAddress,Address,address,ReceiverAddress,eaddr1,rv_addr + rv_zip (A05/A06),stops[1].address,recipient.location,dropoff_address,string,false,宅配必填
16
+ receiver_store_id,收件門市代號,ReceiverStoreID,receiver_store_code,ReceiverStoreID,(透過 Emap 選店回傳),store_id,ReceiverStoreID,(N/A),st_code (四或五碼),(無;即時配送無門市),(無),(無),string,false,超商必填;SmilePay/PayNow/PChomePay 透過電子地圖選店 callback 回傳
17
+ return_store_id,退貨門市代號,ReturnStoreID,return_store_code,ReturnStoreID,(無),return_store_id,(無),(N/A),(店退店服務;欄位待補),(無),(無),(無),string,false,
18
+ is_collection,是否代收,IsCollection,is_collection,N/A,(由 Pay_zg 決定),(由 pay_type 決定),(由 IsCOD/Y/N 決定),epaytype=2,order_type (1代收/3一般),(無;不支援代收),payment_method,(無),string,false,SmilePay 從 Pay_zg 51/55/81 (COD) vs 52/56/82 (PICKUP) 判斷
19
+ collection_amount,代收金額,CollectionAmount,collection_amount,N/A,Amount,(via 金流),Amount,eamtcod,order_amount,(無),amount,(無),integer,false,
20
+ temperature,溫層,Temperature,temperature,Temperature,Temperature (1/2/3),(透過 logistic_type),(內含於 ServiceID),eshipment,(無;常溫),(無),(無),(無),string,false,1常溫 2冷藏 3冷凍;PayNow 透過產品線細分
21
+ weight,重量,(N/A),(N/A),(N/A),(N/A),(N/A),(N/A),eweight,(無),(依車型),(限20kg),(無),integer,false,HCT 直連必填;其他 aggregator 通常自動分箱
22
+ package_count,件數,(N/A),(N/A),(N/A),(N/A),(N/A),(N/A),eqmny,(無),(無),(無),(無),integer,false,HCT 必填
23
+ server_reply_url,通知網址,ServerReplyURL,notify_url,NotifyURL,Roturl,(後台設定),ReturnURL,(N/A — 用 webhook),rtn_url,webhook (後台設定),callback (後台設定),webhook,string,true,HCT 直連靠主動查詢,無 push notify
@@ -27,3 +27,5 @@ CVS,EZSHIP_OK,OK 店到店 (ezShip),ezship,cvs_c2c,true,20000,45x30x30cm,常溫,
27
27
  CVS,EZSHIP_HILIFE,萊爾富店到店 (ezShip),ezship,cvs_c2c,true,20000,45x30x30cm,常溫,ezShip 不含 7-11
28
28
  CVS,EZSHIP_FAMI,全家店到店 (ezShip),ezship,cvs_c2c,true,20000,45x30x30cm,常溫,ezShip 不含 7-11
29
29
  Ondemand,LALAMOVE,Lalamove 即時配送,lalamove,ondemand,false,依方案,依車型,常溫,先報價後下單;報價效期5分鐘;同城/當日;可換司機;非批次物流
30
+ Ondemand,PANDAGO,pandago 即時配送,pandago,ondemand,false,依報價,34x34x36cm/20kg,常溫,費用與時間為兩支獨立端點;Sandbox僅新加坡;不需成為foodpanda餐廳夥伴
31
+ Ondemand,UBER_DIRECT,Uber Direct 即時配送,uber_direct,ondemand,false,依報價,依方案,常溫,配送半徑約10英里;可預約最多30天;台灣可用性未經官方確認
@@ -5,7 +5,7 @@ payuni,統一物流,PAYUNi Logistics,payment_aggregator,true,請至後台申請,
5
5
  smilepay,速買配物流,SmilePay Logistics,payment_aggregator,true,1111,174A02F97A95F72CE301137B3F98D128,,https://ssl.smse.com.tw/api,https://ssl.smse.com.tw/api,"7-11/全家 C2C+B2C,黑貓 COD/PICKUP/逆物流,Pay_zg矩陣 51/52/55/56/81/82/83",全台,public,https://www.smilepay.net/,2026-08-08
6
6
  pchomepay,拍錢包物流,PChomePay Logistics,payment_aggregator,true,請至後台申請,請至後台申請,,https://sandbox-api.pchomepay.com.tw,https://api.pchomepay.com.tw,"金物流二合一,7-11/全家/萊爾富/OK,Notify IP白名單113.196.231.190",全台,apply,https://www.pchomepay.com.tw/,2026-08-08
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
- ezship,ezShip 台灣便利配,ezShip,aggregator,true,請至後台申請,請至後台申請,,https://www.ezship.com.tw,https://www.ezship.com.tw,"非金流商的超取聚合商,OK/萊爾富/全家(不含7-11),店到店/取貨付款/大宗直寄/店到宅/店退店,webPara token,WooCommerce/OpenCart/EasyStore/CYBERBIZ/meepShop 模組",全台,apply,https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=1702,2026-08-08
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
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
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
@@ -18,3 +18,5 @@ pelican,宅配通,Pelican Express,home,false,,,,https://www.pelican.com.tw,https
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
20
  shopee_store,蝦皮店到店,Shopee Store-to-Store,cvs,false,,,,,,"無對外商家API;僅蝦皮生態內可用;無替代路徑",全台,none,,2026-08-08
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
+ 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
@@ -87,3 +87,14 @@ hct,址誤,Address Error,Address Error,error,地址錯誤無法配送,聯繫商
87
87
  hct,拒收退回,Refused,Refused Return,returned,收件人拒收,包裹退回,
88
88
  hct,商品保留不退,Hold No Return,Held No Return,on_hold,商品保留不退回,聯繫商家
89
89
  hct,公司行號休息,Office Closed,Office Closed,error,公司行號休息日無法配送,延後重新配送
90
+ ezship,A01,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
91
+ ezship,A02,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
92
+ ezship,A03,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
93
+ ezship,A04,超商取貨,CVS Pickup,order_type,建單時的訂單狀態分組 超商取貨類 須帶 st_code,
94
+ ezship,A05,宅配,Home Delivery,order_type,建單時的訂單狀態分組 宅配類 須帶 rv_addr 與 rv_zip,
95
+ ezship,A06,宅配,Home Delivery,order_type,建單時的訂單狀態分組 宅配類 須帶 rv_addr 與 rv_zip,
96
+ ezship,A11,店港澳,HK/Macau Store,order_type,建單時的訂單狀態分組 店港澳類 須帶 st_code,
97
+ ezship,A12,店港澳,HK/Macau Store,order_type,建單時的訂單狀態分組 店港澳類 須帶 st_code,
98
+ ezship,S05,包裹退貨,Package Returned,returned,貨況查詢回傳 此狀態無法呈現最終貨況,登入 ezShip 系統查詢最終貨況
99
+ ezship,S06,包裹配送異常,Delivery Exception,error,貨況查詢回傳 此狀態無法呈現最終貨況,登入 ezShip 系統查詢最終貨況
100
+ ezship,00000000,建單失敗,Order Creation Failed,error,傳送訂單回傳的 sn_id 為八個零即代表建單失敗 無獨立錯誤碼欄位,檢查必填欄位與帳號是否已開通網站串接
@@ -0,0 +1,336 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ ezShip 台灣便利配 物流 Python 範例(參數版)
4
+
5
+ 依照 taiwan-logistics-skill 規範撰寫。
6
+
7
+ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**——
8
+ 對「只要物流不要金流」的商家,不必為了超取去開一個金流帳號。
9
+
10
+ ⚠️ 通路只有 OK、萊爾富、全家,**不含 7-ELEVEN**。
11
+ 若客群以 7-11 為主,ezShip 不能單獨滿足需求。
12
+
13
+ 流程三步:電子地圖 -> 傳送訂單 -> 貨況查詢
14
+
15
+ ⚠️ 兩個跨端點的不一致,實作前務必知道:
16
+ 1. 參數命名風格不同 —— 電子地圖是 camelCase(suID/rtURL/webPara),
17
+ 傳送訂單與貨況查詢是 snake_case(su_id/rtn_url/web_para)
18
+ 2. 編碼方向不對稱 —— 以 URL 方式送出時中文需 BIG5 編碼,
19
+ 但 ezShip 回傳一律 UTF-8
20
+
21
+ API 文件: 參見 references/ezship-logistics-api.md
22
+
23
+ 依賴:
24
+ pip install requests
25
+
26
+ 直接執行本檔會跑內建驗證,不會發出任何網路請求:
27
+ python ezship-logistics-example.py
28
+ """
29
+
30
+ import urllib.parse
31
+ from dataclasses import dataclass
32
+ from typing import Dict, Optional
33
+
34
+ import requests
35
+
36
+
37
+ MAP_URL = 'https://map.ezship.com.tw/ezship_map_web.jsp'
38
+ # 舊端點(無 _ex)已於 2017 年底停用
39
+ ORDER_URL = 'https://www.ezship.com.tw/emap/ezship_request_order_api_ex.jsp'
40
+ STATUS_BY_SN_URL = 'https://www.ezship.com.tw/emap/ezship_request_order_status_api.jsp'
41
+ STATUS_BY_ORDER_URL = 'https://www.ezship.com.tw/emap/ezship_request_order_status_api_byorder.jsp'
42
+
43
+ # 建單失敗的唯一訊號 —— 沒有獨立的錯誤碼欄位
44
+ SN_ID_FAILED = '00000000'
45
+
46
+ # 電子地圖回傳的通路代號
47
+ STORE_CHANNELS = {
48
+ 'TOK': 'OK 便利商店',
49
+ 'TLF': '萊爾富',
50
+ 'TFM': '全家',
51
+ }
52
+
53
+ # order_status 分組
54
+ ORDER_STATUS_GROUPS = {
55
+ 'cvs': ['A01', 'A02', 'A03', 'A04'], # 超商取貨,須帶 st_code
56
+ 'home': ['A05', 'A06'], # 宅配,須帶 rv_addr + rv_zip
57
+ 'hk_mo': ['A11', 'A12'], # 店港澳,須帶 st_code
58
+ }
59
+
60
+ # 貨況查詢的 times 欄位
61
+ DELIVERY_TIMES = {
62
+ '1': '第一次配送',
63
+ '2': '第二次配送',
64
+ '8': '退還給寄件人',
65
+ '9': '非常規配送',
66
+ }
67
+
68
+ # 這兩個狀態無法呈現最終貨況,需登入 ezShip 系統查詢
69
+ NEEDS_MANUAL_CHECK = {'S05': '包裹退貨', 'S06': '包裹配送異常'}
70
+
71
+
72
+ # ============================================================================
73
+ # 編碼
74
+ # ============================================================================
75
+
76
+ def encode_big5_params(params: Dict[str, str]) -> str:
77
+ """以 URL 方式傳遞時,中文需以 **BIG5** 字集做 URL 編碼。
78
+
79
+ ⚠️ 這是送出方向。ezShip **回傳一律 UTF-8**,兩邊不對稱。
80
+ ⚠️ 官方建議優先用 FORM SUBMIT(方式一)而非 URL 傳參,
81
+ 可避開這個編碼問題;本函式供必須用 URL 時使用。
82
+ """
83
+ parts = []
84
+ for k, v in params.items():
85
+ parts.append(f'{k}={urllib.parse.quote(str(v).encode("big5"), safe="")}')
86
+ return '&'.join(parts)
87
+
88
+
89
+ def check_no_special_chars(value: str, field_name: str) -> None:
90
+ """web_para / webPara 不可含特殊字元(官方明列)。"""
91
+ for ch in "':@%&*$\"":
92
+ if ch in value:
93
+ raise ValueError(f'{field_name} 不可包含特殊字元 {ch!r}')
94
+
95
+
96
+ # ============================================================================
97
+ # 步驟一:電子地圖(只有超商取貨需要)
98
+ # ============================================================================
99
+
100
+ def build_map_form(su_id: str, process_id: str, rt_url: str, web_para: str = '') -> Dict[str, str]:
101
+ """組出導向 ezShip 電子地圖的表單欄位。
102
+
103
+ ⚠️ 這一支用 **camelCase**(suID / rtURL / webPara),
104
+ 與後續兩支的 snake_case 不同。
105
+
106
+ ⚠️ 官方明文**禁止把電子地圖嵌入 iframe 或以 CSS 內嵌**。
107
+ """
108
+ if web_para:
109
+ check_no_special_chars(web_para, 'webPara')
110
+ return {
111
+ 'suID': su_id,
112
+ 'processID': process_id,
113
+ 'stCate': '',
114
+ 'stCode': '',
115
+ 'rtURL': rt_url,
116
+ 'webPara': web_para,
117
+ }
118
+
119
+
120
+ def parse_map_result(query: Dict[str, str]) -> Dict[str, str]:
121
+ """解析電子地圖導回的參數(UTF-8)。
122
+
123
+ ⚠️ 門市代碼可能四碼或五碼(如 TFM9771),
124
+ 且**與門市服務代號不一定相同**。
125
+ 直接把 ezShip 給的值原封回傳即可,不要自行轉換。
126
+ """
127
+ return {
128
+ 'process_id': query.get('processID', ''),
129
+ 'st_cate': query.get('stCate', ''),
130
+ 'st_cate_name': STORE_CHANNELS.get(query.get('stCate', ''), '未知通路'),
131
+ 'st_code': query.get('stCode', ''),
132
+ 'st_name': query.get('stName', ''),
133
+ 'st_addr': query.get('stAddr', ''),
134
+ 'st_tel': query.get('stTel', ''),
135
+ 'web_para': query.get('webPara', ''),
136
+ }
137
+
138
+
139
+ # ============================================================================
140
+ # 步驟二:傳送訂單
141
+ # ============================================================================
142
+
143
+ @dataclass
144
+ class EzshipConfig:
145
+ su_id: str # 賣家 ezShip 帳號,需開通網站串接
146
+ rtn_url: str # 回傳網址
147
+
148
+
149
+ def build_order_form(
150
+ config: EzshipConfig,
151
+ order_id: str,
152
+ order_status: str,
153
+ order_type: str,
154
+ order_amount: int,
155
+ rv_name: str,
156
+ rv_mobile: str,
157
+ *,
158
+ rv_email: str = '',
159
+ st_code: str = '',
160
+ rv_addr: str = '',
161
+ rv_zip: str = '',
162
+ web_para: str = '',
163
+ ) -> Dict[str, str]:
164
+ """組出建單表單。
165
+
166
+ order_status: A01-A04 超商取貨 / A05-A06 宅配 / A11-A12 店港澳
167
+ order_type: 1 代收(取貨付款/貨到付款)/ 3 一般配送
168
+
169
+ ⚠️ 代收服務需 ezShip **商務會員**資格且在合約期間內,
170
+ 一般會員只能做「取貨不付款/純配送」。
171
+ """
172
+ validate_order(order_status, st_code, rv_addr, rv_zip, rv_name)
173
+ if order_type not in ('1', '3'):
174
+ raise ValueError('order_type 只能是 1(代收)或 3(一般配送)')
175
+ if web_para:
176
+ check_no_special_chars(web_para, 'web_para')
177
+
178
+ return {
179
+ 'su_id': config.su_id,
180
+ 'order_id': order_id,
181
+ 'order_status': order_status,
182
+ 'order_type': order_type,
183
+ 'order_amount': str(order_amount),
184
+ 'rv_name': rv_name,
185
+ 'rv_email': rv_email,
186
+ 'rv_mobile': rv_mobile,
187
+ 'st_code': st_code,
188
+ 'rv_addr': rv_addr,
189
+ 'rv_zip': rv_zip,
190
+ 'rtn_url': config.rtn_url,
191
+ 'web_para': web_para,
192
+ }
193
+
194
+
195
+ def validate_order(order_status: str, st_code: str, rv_addr: str, rv_zip: str, rv_name: str) -> None:
196
+ """依 order_status 檢查必填欄位。"""
197
+ if order_status in ORDER_STATUS_GROUPS['cvs'] + ORDER_STATUS_GROUPS['hk_mo']:
198
+ if not st_code:
199
+ raise ValueError(f'{order_status} 為門市取貨,st_code 必填')
200
+ elif order_status in ORDER_STATUS_GROUPS['home']:
201
+ if not rv_addr or not rv_zip:
202
+ raise ValueError(f'{order_status} 為宅配,rv_addr 與 rv_zip 皆必填')
203
+ else:
204
+ raise ValueError(f'未知的 order_status: {order_status}')
205
+
206
+ # ⚠️ 超商取貨單的姓名欄位長度有限,超過四個中英文字會印不完整,
207
+ # 可能造成取貨問題。官方特別提醒。
208
+ if len(rv_name) > 4:
209
+ raise ValueError(
210
+ f'rv_name「{rv_name}」超過四個字,超商取貨單會印不完整而可能無法取貨'
211
+ )
212
+
213
+
214
+ def parse_order_result(query: Dict[str, str]) -> Dict[str, str]:
215
+ """解析建單導回的參數。
216
+
217
+ ⚠️ **sn_id 回傳八個零代表建單失敗**——這是唯一的失敗訊號,
218
+ 沒有獨立的錯誤碼欄位。非八個零即成功,
219
+ 且**必須把 sn_id 存起來**,後續寄件與追蹤貨況都靠它。
220
+ """
221
+ sn_id = query.get('sn_id', '')
222
+ return {
223
+ 'order_id': query.get('order_id', ''),
224
+ 'sn_id': sn_id,
225
+ 'order_status': query.get('order_status', ''),
226
+ 'web_para': query.get('webPara', ''),
227
+ 'success': sn_id != '' and sn_id != SN_ID_FAILED,
228
+ }
229
+
230
+
231
+ # ============================================================================
232
+ # 步驟三:貨況查詢
233
+ # ============================================================================
234
+
235
+ MIN_QUERY_INTERVAL_SECONDS = 3
236
+ """⚠️ 官方明文:大量反覆查詢結案資料導致系統忙碌者,
237
+ ezShip 將「中斷其網路串接之權利」。建議每筆查詢間隔 3 秒以上,
238
+ 已結案貨件勿重複查詢,也不要做整批預先輪詢。"""
239
+
240
+
241
+ def build_status_form(config: EzshipConfig, order_no: str, web_para: str = '') -> Dict[str, str]:
242
+ """依購物網站訂單編號查詢貨況。
243
+
244
+ ⚠️ 此查法**不適用簡易版**串接的訂單。
245
+ ⚠️ 訂單號碼重複時,以**最後一次上傳**的訂單資料為主。
246
+ """
247
+ if web_para:
248
+ check_no_special_chars(web_para, 'web_para')
249
+ return {
250
+ 'su_id': config.su_id,
251
+ 'order_no': order_no,
252
+ 'rtn_url': config.rtn_url,
253
+ 'web_para': web_para,
254
+ }
255
+
256
+
257
+ def parse_status_result(query: Dict[str, str]) -> Dict[str, str]:
258
+ """解析貨況回傳。"""
259
+ status = query.get('order_status', '')
260
+ times = query.get('times', '')
261
+ return {
262
+ 'sn_id': query.get('sn_id', ''),
263
+ 'order_no': query.get('order_no', ''),
264
+ 'order_status': status,
265
+ 'times': times,
266
+ 'times_desc': DELIVERY_TIMES.get(times, f'未知 {times}'),
267
+ # sdate 由超商或宅配公司提供;udate 是 ezShip 收到該狀態的時間
268
+ 'sdate': query.get('sdate', ''),
269
+ 'udate': query.get('udate', ''),
270
+ 'needs_manual_check': status in NEEDS_MANUAL_CHECK,
271
+ 'manual_check_reason': NEEDS_MANUAL_CHECK.get(status, ''),
272
+ }
273
+
274
+
275
+ # ============================================================================
276
+ # 自我驗證
277
+ # ============================================================================
278
+
279
+ def _self_test() -> int:
280
+ """驗證編碼與欄位規則。ezShip 官方未提供簽章測試向量
281
+ (參數版沒有簽章機制,安全性倚賴 su_id 帳號綁定與 HTTPS)。"""
282
+ failed = 0
283
+ print('ezShip 實作驗證')
284
+
285
+ # BIG5 編碼:中文與 UTF-8 的結果不同
286
+ big5 = encode_big5_params({'rv_name': '王小明'})
287
+ utf8 = f"rv_name={urllib.parse.quote('王小明', safe='')}"
288
+ ok = big5 != utf8 and 'rv_name=' in big5
289
+ failed += not ok
290
+ print(f' [{"PASS" if ok else "FAIL"}] BIG5 編碼與 UTF-8 結果不同')
291
+ print(f' BIG5 {big5}')
292
+ print(f' UTF8 {utf8}')
293
+
294
+ # 建單失敗訊號
295
+ ok = parse_order_result({'sn_id': SN_ID_FAILED})['success'] is False
296
+ failed += not ok
297
+ print(f' [{"PASS" if ok else "FAIL"}] sn_id 八個零判定為建單失敗')
298
+
299
+ ok = parse_order_result({'sn_id': 'SN12345678'})['success'] is True
300
+ failed += not ok
301
+ print(f' [{"PASS" if ok else "FAIL"}] sn_id 非八個零判定為成功')
302
+
303
+ # 必填欄位規則
304
+ cases = [
305
+ ('A01 缺 st_code', dict(order_status='A01', st_code='', rv_addr='', rv_zip='', rv_name='王小明')),
306
+ ('A05 缺 rv_zip', dict(order_status='A05', st_code='', rv_addr='台北市', rv_zip='', rv_name='王小明')),
307
+ ('姓名超過四字', dict(order_status='A01', st_code='TFM9771', rv_addr='', rv_zip='', rv_name='王小明先生')),
308
+ ]
309
+ for label, kw in cases:
310
+ try:
311
+ validate_order(**kw)
312
+ print(f' [FAIL] 應攔下:{label}')
313
+ failed += 1
314
+ except ValueError:
315
+ print(f' [PASS] 正確攔下:{label}')
316
+
317
+ # 港澳
318
+ ok = 'A11' in ORDER_STATUS_GROUPS['hk_mo']
319
+ failed += not ok
320
+ print(f' [{"PASS" if ok else "FAIL"}] A11/A12 歸類為店港澳(ezShip 支援港澳店配)')
321
+
322
+ # 特殊字元
323
+ try:
324
+ check_no_special_chars("order'123", 'web_para')
325
+ print(' [FAIL] 應攔下 web_para 的特殊字元')
326
+ failed += 1
327
+ except ValueError:
328
+ print(' [PASS] 正確攔下 web_para 的特殊字元')
329
+
330
+ print()
331
+ print('全部通過' if failed == 0 else f'{failed} 項失敗')
332
+ return 1 if failed else 0
333
+
334
+
335
+ if __name__ == '__main__':
336
+ raise SystemExit(_self_test())
@@ -2,8 +2,8 @@
2
2
 
3
3
  > 官網: https://www.ezship.com.tw/
4
4
  > 購物網站串接: https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=1702
5
- > Captured: 2026-08-08 · doc_access: **apply**(需後台申請串接;串接文件公開流通但官方直連當下不可達)
6
- > Status: **partial** — 服務矩陣與串接流程已確認,欄位層規格待補
5
+ > Captured: 2026-08-08 · doc_access: **public**(文件站免登入;串接需後台申請開通)
6
+ > Status: **參數版三支端點欄位已完整** — 電子地圖、傳送訂單、貨況查詢;XML 版與欄位定義 PDF 待補
7
7
 
8
8
  ## 0. 定位
9
9
 
@@ -32,9 +32,117 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
32
32
 
33
33
  > ⚠️ 注意:ezShip **不含 7-ELEVEN**。7-11 超取需另走 ECPay/SmilePay/PayNow 等。若你的客群以 7-11 為主,ezShip 不能單獨滿足需求。這是選型時最關鍵的一點。
34
34
 
35
- ## 2. 串接方式
35
+ ## 2. 三種串接方式的差異
36
36
 
37
- 官方提供**三種串接方式**,將金物流服務整合進購物網站。(三者的具體差異待補——推測為:純導轉頁面 / 表單 POST / API 呼叫,需以官方文件確認。)
37
+ 先前推測為「導轉/表單/API」三種,**實際不是**——三者都是表單導轉,差別在批次能力與商品資料:
38
+
39
+ | | 參數版 | XML 版 | 簡易版 |
40
+ |---|---|---|---|
41
+ | 費用 | 免費 | 免費 | 免費 |
42
+ | 包裹類別 | 店配(付款/不付款)+ 宅配(貨到付款/純配送)| 同參數版 | **僅店配,無宅配** |
43
+ | 串接類型 | 單次單筆 | **單次單筆或批次多筆** | 單次單筆 |
44
+ | 電子地圖與取件人資訊 | 獨立串接傳遞 | 獨立串接傳遞 | **同時完成** |
45
+ | 串接商品資料 | 無 | **有** | 無 |
46
+ | 列印商品明細寄件單 | 無 | **可** | 無 |
47
+ | 異常處理 | 提供錯誤狀態碼 | 提供錯誤狀態碼 | **無** |
48
+ | 配送狀態 | API 查詢 | API 查詢 | API 查詢 |
49
+
50
+ > ⚠️ **簡易版官方已凍結**:原文「請使用(參數版)或(XML版),(簡易版)僅提供系統正常運作,不再開發新功能」。新專案不應採用。
51
+ > ⚠️ **代收服務(取貨付款/貨到付款)需 ezShip 商務會員資格**,且須在合約期間內。一般會員只能做「取貨不付款/純配送」。
52
+
53
+ ## 2.1 參數版 — 完整流程與欄位
54
+
55
+ 三個端點依序:**電子地圖 → 傳送訂單 → 貨況查詢**。
56
+
57
+ ### ⚠️ 兩個跨端點的不一致,實作前先知道
58
+
59
+ 1. **參數命名風格不同**:電子地圖用 **camelCase**(`suID`、`rtURL`、`webPara`),傳送訂單與貨況查詢用 **snake_case**(`su_id`、`rtn_url`、`web_para`)。同一次串接要兩種寫法。
60
+ 2. **編碼方向不對稱**:以 URL 方式送出時中文需 **BIG5** 編碼;但 ezShip **回傳一律 UTF-8**。送 BIG5、收 UTF-8。
61
+
62
+ ### 步驟一:電子地圖(只有超商取貨需要)
63
+
64
+ `https://map.ezship.com.tw/ezship_map_web.jsp`
65
+
66
+ | 送出 | 說明 |
67
+ |---|---|
68
+ | `suID` | 賣家 ezShip 帳號,需開通網站串接 |
69
+ | `processID` | 處理序號或訂單編號,自行提供 |
70
+ | `stCate` | 取件門市通路代號 |
71
+ | `stCode` | 取件門市代號 |
72
+ | `rtURL` | 回傳網址(完整路徑)|
73
+ | `webPara` | 自訂識別資料,原值回傳 |
74
+
75
+ | 回傳 | 說明 |
76
+ |---|---|
77
+ | `processID` | 原值回傳 |
78
+ | `stCate` | **`TOK` OK/`TLF` 萊爾富/`TFM` 全家** |
79
+ | `stCode` / `stName` / `stAddr` / `stTel` | 門市代號/名稱/地址/電話 |
80
+ | `webPara` | 原值回傳 |
81
+
82
+ > ⚠️ **官方明文禁止把電子地圖嵌入 iframe 或以 CSS 內嵌**。
83
+ > ⚠️ **門市代碼可能四碼或五碼**(如 `TFM9771`),且**與門市服務代號不一定相同**。直接回傳 ezShip 給的值即可,不要自行轉換。
84
+ > 官方另建議網站啟用 HTTPS——行動裝置對混合內容的限制越來越嚴。
85
+
86
+ ### 步驟二:傳送訂單
87
+
88
+ `https://www.ezship.com.tw/emap/ezship_request_order_api_ex.jsp`
89
+
90
+ > 舊端點 `ezship_request_order_api.jsp`(無 `_ex`)**已於 2017 年底停用**。
91
+
92
+ | 參數 | 說明 |
93
+ |---|---|
94
+ | `su_id` | 賣家帳號。**用代收服務須為商務會員且在合約期間內** |
95
+ | `order_id` | 購物網站自訂訂單編號 |
96
+ | `order_status` | 訂單狀態,見下 |
97
+ | `order_type` | **`1` 代收(取貨付款/貨到付款)/`3` 一般配送(不付款/純配送)** |
98
+ | `order_amount` | 代收金額或報值金額 |
99
+ | `rv_name` | 取件人姓名 |
100
+ | `rv_email` / `rv_mobile` | 取件人信箱/行動電話 |
101
+ | `st_code` | 取件門市。**`A01`–`A04`、`A11`、`A12` 必填** |
102
+ | `rv_addr` / `rv_zip` | 收件地址與郵遞區號。**`A05`、`A06` 必填**(宅配)|
103
+ | `rtn_url` | 回傳網址 |
104
+ | `web_para` | 自訂識別資料 |
105
+
106
+ **`order_status` 分組**:
107
+
108
+ | 代碼 | 類別 |
109
+ |---|---|
110
+ | `A01`–`A04` | 超商取貨 |
111
+ | `A05`、`A06` | 宅配 |
112
+ | `A11`、`A12` | **店港澳**(香港/澳門)|
113
+
114
+ > ⚠️ **`rv_name` 超過四個中英文字,超商取貨單會印不完整**,可能導致取貨問題。官方特別提醒。
115
+ > 💡 **港澳配送**(`A11`/`A12`)是先前未收錄的能力——ezShip 是本 skill 少數支援港澳店配的聚合商。
116
+
117
+ 回傳:`order_id`、`sn_id`、`order_status`、`webPara`。
118
+
119
+ > ⚠️ **`sn_id` 回傳八個零(`00000000`)代表訂單建立失敗**——這是唯一的失敗訊號,沒有獨立的錯誤碼欄位。非八個零即成功,且**必須把 `sn_id` 存起來**,後續寄件與追蹤貨況都靠它。
120
+
121
+ 亦可用 CURL 直接 POST(官方提供 Linux/Windows 兩種引號寫法範例)。
122
+
123
+ ### 步驟三:貨況查詢
124
+
125
+ 兩種查法,端點不同:
126
+
127
+ | 依據 | 端點 |
128
+ |---|---|
129
+ | ezShip 店到店編號 | `.../emap/ezship_request_order_status_api.jsp` |
130
+ | 購物網站訂單編號 | `.../emap/ezship_request_order_status_api_byorder.jsp` |
131
+
132
+ 送出:`su_id`、`order_no`、`rtn_url`、`web_para`。
133
+
134
+ 回傳:`sn_id`、`order_no`、`order_status`、`webPara`,另有三個時序欄位:
135
+
136
+ | 參數 | 說明 |
137
+ |---|---|
138
+ | `times` | **`1` 第一次配送/`2` 第二次配送/`8` 退還寄件人/`9` 非常規配送** |
139
+ | `sdate` | 配送狀態發生日期(`yyyy/mm/dd`),由超商或宅配公司提供 |
140
+ | `udate` | ezShip 接收到該狀態的時間(`yyyy/mm/dd hh24:mi`)|
141
+
142
+ > ⚠️ **有速率限制且會被停權**:官方明文「若因大量反覆查詢結案資料,導致 ezShip 系統忙碌或運行困難,ezShip 將中斷其網路串接之權利」,**建議每筆查詢間隔 3 秒以上**,已結案貨件勿重複查詢。不要做整批預先輪詢。
143
+ > ⚠️ **`order_status` 回傳 `S05`(包裹退貨)或 `S06`(包裹配送異常)時無法呈現最終貨況**,需登入 ezShip 系統查詢。
144
+ > ⚠️ 訂單號碼重複時,**以最後一次上傳的訂單資料為準**。
145
+ > ⚠️ 以訂單編號查詢**不適用簡易版**串接的訂單。
38
146
 
39
147
  ## 3. 申請流程
40
148
 
@@ -47,13 +155,17 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
47
155
 
48
156
  ## 4. 技術文件
49
157
 
50
- 社群與開店平台文件普遍指向:
158
+ > ✅ **上一輪標記的 404 已查明**:社群流傳的是**無版號檔名** `ezship_WebOrder_HttpRequest.pdf`,實際檔名帶版本後綴。官網 `service_doc` 當時回「系統忙碌中」是暫時性的,現已可正常存取。
51
159
 
52
- ```
53
- http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest.pdf
54
- ```
160
+ | 文件 | 網址 |
161
+ |---|---|
162
+ | 欄位定義(參數版)| `http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest_v15.pdf` |
163
+ | 欄位定義(XML 版)| `http://www.ezship.com.tw/file/ezship_WebOrder_XML_v15s.pdf` |
164
+ | 文件站首頁 | `https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=1702` |
165
+
166
+ 文件站以 `vDefPage` 參數分頁(`04`–`09` 參數版、`10`–`16` XML 版、`17`–`18` 簡易版、`19`–`23` 貨況串接)。
55
167
 
56
- ⚠️ **本次驗證時該連結回 404**,官網 `service_doc` 頁面亦回「系統忙碌中」。可能已改版或搬遷。取得方式:登入後台文件區,或洽客服索取。
168
+ 官方另提供 PHP/JSP 的 BIG5 與 UTF-8 兩種版本程式碼範例。
57
169
 
58
170
  ### 已知欄位線索
59
171
 
@@ -84,15 +196,18 @@ http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest.pdf
84
196
  | 要黑貓宅配含逆物流 | SmilePay(`Pay_zg=81/82/83`) |
85
197
  | 要即時配送 | Lalamove(見 [lalamove-logistics-api.md](lalamove-logistics-api.md)) |
86
198
 
87
- ## 7. 待驗證
199
+ ## 7. 待補
88
200
 
89
- | 項目 | 內容 |
201
+ 參數版三支端點(電子地圖/傳送訂單/貨況查詢)的欄位已完整。
202
+
203
+ | 項目 | 狀態 |
90
204
  |---|---|
91
- | 文件本體 | `ezship_WebOrder_HttpRequest.pdf` 的現行有效連結 |
92
- | 三種串接方式 | 各自的技術型態與適用情境 |
93
- | 欄位規格 | 建單、電子地圖、查詢、取消、貨態回傳的完整參數 |
94
- | 驗證機制 | `webPara` token 的產生與驗證規則 |
95
- | 狀態碼 | 貨態代碼表(需併入 `data/status-codes.csv`) |
205
+ | `order_status` 完整代碼表 | 已知分組 `A01`–`A04` 超商取貨、`A05`/`A06` 宅配、`A11`/`A12` 店港澳,以及貨況的 `S05`/`S06`;**完整對照需解析欄位定義 PDF**,之後併入 `data/status-codes.csv` |
206
+ | XML 版欄位 | 端點與能力差異已確認,欄位定義在 `ezship_WebOrder_XML_v15s.pdf` |
207
+ | 商品資料結構 | XML 版獨有(可列印含商品明細寄件單),欄位待補 |
208
+ | 大宗直寄/店退店的串接方式 | 服務存在,是否走同一組 API 未確認 |
209
+
210
+ > `webPara` 先前被記為「token 驗證欄位」,**這是誤解**。官方定義為「網站所需額外判別資料,ezShip 將原值回傳」——它是**原值透傳的識別欄位**(類似其他 provider 的 `ExtraData`/`CustomField`),沒有任何驗證或簽章語意。ezShip 的參數版**沒有簽章機制**,安全性倚賴 `su_id` 帳號綁定與 HTTPS。
96
211
 
97
212
  ## 8. 來源
98
213
 
@@ -100,4 +215,9 @@ http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest.pdf
100
215
  - 購物網站串接 — https://www.ezship.com.tw/service_doc/service_home_w18v1.jsp?vDocNo=1702
101
216
  - EasyStore 串接說明 — https://support.easystore.co/zh-tw/article/ezship-1mchswf/
102
217
  - CYBERBIZ 超商物流教學 — https://www.cyberbiz.io/helpcenter/?p=2524
218
+ - 程式碼說明:連結電子地圖 — `…/2017_service_doc_home.jsp?vDocNo=1702&vDefPage=07`
219
+ - 程式碼說明:傳送訂單 — `…&vDefPage=08`
220
+ - 貨況串接(依訂單編號查詢)— `…&vDefPage=22`
221
+ - 欄位定義 PDF(參數版)— http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest_v15.pdf
222
+ - 欄位定義 PDF(XML 版)— http://www.ezship.com.tw/file/ezship_WebOrder_XML_v15s.pdf
103
223
  - 開源 PHP 實作 — https://github.com/recca0120/payum-ezship
@@ -0,0 +1,152 @@
1
+ # 即時/同城配送(On-demand Delivery)在台灣
2
+
3
+ > Captured: 2026-08-08
4
+ > 涵蓋: Lalamove、pandago(foodpanda)、Uber Direct
5
+ > Lalamove 詳細規格見 [lalamove-logistics-api.md](lalamove-logistics-api.md)
6
+
7
+ ## 0. 這個分類跟其他物流不同在哪
8
+
9
+ 本 skill 收錄的其他物流(超取、宅配)都是**批次型**:建單 → 出貨 → 數日後送達,以「單」為單位。即時配送是**派遣型**:報價 → 立即派車 → 數十分鐘內送達,以「趟」為單位。
10
+
11
+ 差異直接影響串接設計:
12
+
13
+ | 面向 | 批次物流(超取/宅配)| 即時配送 |
14
+ |---|---|---|
15
+ | 報價 | 費率表固定,可預先算 | **必須先呼叫 API 取得即時報價**,且報價有效期短 |
16
+ | 建單時機 | 出貨當下 | 消費者下單當下或稍後派遣 |
17
+ | 取消 | 出貨前可取消 | **司機接單後取消多半要付費** |
18
+ | 追蹤 | 貨態代碼(數小時~數日更新)| **司機即時座標** |
19
+ | 失敗處理 | 退回寄件人 | 需重新派遣或人工介入 |
20
+ | 服務範圍 | 全台 | **限同城/特定半徑** |
21
+
22
+ > ⚠️ 把即時配送套用批次物流的資料模型(先建單再出貨)會不合用——報價會過期、司機座標無處可放。
23
+
24
+ ## 1. 三家對照
25
+
26
+ | | Lalamove | pandago | Uber Direct |
27
+ |---|---|---|---|
28
+ | 母公司 | Lalamove | Delivery Hero(foodpanda)| Uber |
29
+ | 台灣可用 | ✅ 官方文件列台灣 | ✅ **官方 API 文件列 `tw`** | ⚠️ 見 §4 |
30
+ | 文件公開 | ✅ 免登入 | ✅ 免登入(Delivery Hero ODR)| ✅ 免登入 |
31
+ | 認證 | HMAC-SHA256 自簽 | **OAuth 2.0 + RSA 簽的 JWT assertion** | OAuth 2.0 client_credentials |
32
+ | 取得憑證 | 開發者後台 | **須洽 account manager 申請** | 商家後台 |
33
+ | 報價 | 先報價後下單,效期 5 分鐘 | `POST /orders/fee` 與 `/orders/time` 分開 | quote 端點 |
34
+ | 司機座標 | ✅ | ✅ `GET /orders/{id}/coordinates` | ✅ |
35
+ | 尺寸限制 | 依車型 | **34×34×36 cm、20 kg**(foodpanda 外送箱)| 依方案 |
36
+
37
+ ## 2. pandago(foodpanda)
38
+
39
+ pandago 屬 Delivery Hero 的 **On Demand Rider(ODR)API**,同一套 API 也服務 Glovo、Talabat 等品牌。
40
+
41
+ ### 環境
42
+
43
+ | 環境 | Base URL |
44
+ |---|---|
45
+ | 台灣正式 | **`https://pandago-api-apse.deliveryhero.io/tw`** |
46
+ | Sandbox | `https://pandago-api-sandbox.deliveryhero.io/sg` |
47
+
48
+ > ⚠️ **Sandbox 只有 `sg`(新加坡)**,沒有台灣沙箱。測試時的地址、費率、涵蓋範圍都是新加坡的,**不能用來驗證台灣的服務範圍或計價**。
49
+
50
+ ### 認證
51
+
52
+ OAuth 2.0,但不是常見的 client_secret 模式:
53
+
54
+ ```
55
+ 1. 產生 RSA 金鑰對
56
+ 2. 以私鑰簽出 JWT assertion
57
+ 3. POST /oauth2/token
58
+ grant_type = client_credentials
59
+ client_assertion_type = urn:ietf:params:oauth:client-assertion-type:jwt-bearer
60
+ client_assertion = <簽好的 JWT>
61
+ ```
62
+
63
+ 需向 pandago account manager 索取 **Client ID、Key ID、Scope**;私鑰自行產生。
64
+
65
+ > ⚠️ 這是 14 家 provider 中**唯一使用 JWT assertion(private_key_jwt)**的。既有的 HMAC 或 API Key 程式碼完全不能沿用。
66
+
67
+ ### 端點
68
+
69
+ | 操作 | Method | 路徑 |
70
+ |---|---|---|
71
+ | 建立訂單 | POST | `/orders` |
72
+ | 查詢訂單 | GET | `/orders/{order_id}` |
73
+ | 取消訂單 | DELETE | `/orders/{order_id}` |
74
+ | 費用估算 | POST | `/orders/fee` |
75
+ | 時間估算 | POST | `/orders/time` |
76
+ | 司機座標 | GET | `/orders/{order_id}/coordinates` |
77
+
78
+ > 費用與時間是**兩支獨立端點**,跟 Lalamove 一次回傳報價+預計時間不同。要同時顯示兩者需呼叫兩次。
79
+
80
+ ### 服務限制
81
+
82
+ - 包裹須放得進 foodpanda 外送箱:**34 × 34 × 36 cm**
83
+ - **上限 20 公斤**
84
+ - 零售商家**不需成為 foodpanda 餐廳夥伴**即可使用,可直接填單叫車
85
+
86
+ ## 3. Uber Direct
87
+
88
+ ### 認證
89
+
90
+ | 項目 | 值 |
91
+ |---|---|
92
+ | Token 端點 | `https://auth.uber.com/oauth/v2/token` |
93
+ | grant_type | `client_credentials` |
94
+ | scope | **`eats.deliveries`** |
95
+ | API Base | `https://api.uber.com/` |
96
+
97
+ Token 請求用 `application/x-www-form-urlencoded`;後續 API 呼叫用 `application/json`,以 Bearer token 帶入 Authorization header。
98
+
99
+ > 💡 **Token 有效期 30 天(2,592,000 秒)**,官方明文建議快取而非每次重新產生。這與 Lalamove(每次請求都簽章)、pandago(JWT assertion)的模式都不同——Uber Direct 這邊反而要注意**別把 token 當短期憑證反覆申請**。
100
+
101
+ ### API 家族
102
+
103
+ Direct API、Organizations API、Courier Pick & Pack API、Refund API、Business Location Management API。
104
+
105
+ ### 服務範圍
106
+
107
+ 官方行銷頁只說「available in 2 dozen countries」,未逐一列出。配送半徑約 **10 英里**內,時效可選 2 小時內/當日/最多預約 30 天後。
108
+
109
+ ## 4. ⚠️ Uber Direct 的台灣可用性:有間接證據,無官方確認
110
+
111
+ **支持的證據:**
112
+ - 存在台灣在地化的商家頁 `merchants.ubereats.com/tw/zh-tw/`
113
+ - Uber Help 有中文的「Uber Direct 控制台」章節
114
+ - 台灣的系統整合商(如 weiby.tw)公開販售「Uber Eats/Uber Direct/foodpanda/pandago」的 API 串接服務
115
+
116
+ **缺乏的證據:**
117
+ - Uber 官方**沒有**逐一列出支援國家的清單,台灣未被點名
118
+ - 開發者文件未標示市場代碼或區域端點
119
+
120
+ **結論**:可用性高度可能,但**本 skill 不將其標為已確認**。與 pandago 不同——pandago 的官方 API 文件直接列出 `tw` 的正式端點,那是明確的一手證據。
121
+
122
+ 實務建議:導入前先向 Uber 業務確認貴公司所在區域是否在服務範圍內,不要依賴行銷頁的在地化路徑判斷。
123
+
124
+ ## 5. 選型
125
+
126
+ | 情境 | 建議 |
127
+ |---|---|
128
+ | 需要明確的台灣官方端點與文件 | **pandago**(`/tw` 正式端點有官方文件背書)|
129
+ | 已有 HMAC 簽章經驗、想快速上線 | **Lalamove**(自簽 HMAC,開發者後台自助取得憑證)|
130
+ | 需要多車型/路線最佳化/換司機 | **Lalamove** |
131
+ | 小件、標準箱體、不需成為餐飲夥伴 | **pandago**(34×34×36 cm / 20 kg 內)|
132
+ | 已在用 Uber Eats 生態 | **Uber Direct**(但先確認台灣服務範圍)|
133
+
134
+ > 三家都**不是批次物流的替代品**。單日出貨量大、跨縣市、需要超取或貨到付款的情境,仍應走 ECPay/ezShip 等聚合商。即時配送適合的是同城、急件、生鮮這類批次物流做不到的需求。
135
+
136
+ ## 6. 待補
137
+
138
+ | 項目 | 說明 |
139
+ |---|---|
140
+ | pandago `/orders` 逐欄 | 端點與認證已確認,request/response 欄位待擷取 |
141
+ | Uber Direct 端點逐欄 | 認證已確認;API reference 為 SPA,需以瀏覽器取得 |
142
+ | 三家的取消政策與費用 | 即時配送的取消多半收費,各家規則未確認 |
143
+
144
+ ## 7. 來源
145
+
146
+ - Delivery Hero On Demand Rider API — https://on-demand-rider-docs.deliveryhero.io/
147
+ - pandago 台灣 — https://pandago.tw/
148
+ - foodpanda pandago 介紹 — https://www.foodpanda.com.tw/contents/pandago
149
+ - Uber Direct API 總覽 — https://developer.uber.com/docs/deliveries/overview
150
+ - Uber Direct 認證 — https://developer.uber.com/docs/deliveries/guides/authentication
151
+ - Uber Direct 商家頁(台灣在地化)— https://merchants.ubereats.com/tw/zh-tw/
152
+ - Lalamove — [lalamove-logistics-api.md](lalamove-logistics-api.md)
@@ -48,8 +48,10 @@ CSV_CONFIG = {
48
48
  },
49
49
  'field': {
50
50
  'file': 'field-mappings.csv',
51
- 'search_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'notes'],
52
- 'output_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'type', 'required', 'format', 'notes']
51
+ # 逐一列出所有 provider 欄位 —— 原本只涵蓋 3 家,
52
+ # 導致搜尋其餘 provider 的欄位名時完全比對不到
53
+ 'search_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'smilepay_name', 'pchomepay_name', 'paynow_name', 'hct_name', 'ezship_name', 'lalamove_name', 'pandago_name', 'uber_direct_name', 'notes'],
54
+ 'output_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'smilepay_name', 'pchomepay_name', 'paynow_name', 'hct_name', 'ezship_name', 'lalamove_name', 'pandago_name', 'uber_direct_name', 'type', 'required', 'notes']
53
55
  },
54
56
  'status': {
55
57
  'file': 'status-codes.csv',
@@ -1,11 +1,12 @@
1
1
  {
2
- "platform": "roocode",
3
- "displayName": "Roo Code",
2
+ "platform": "cline",
3
+ "displayName": "Cline",
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
- "root": ".roo",
7
- "skillPath": "commands/taiwan-logistics",
8
- "filename": "SKILL.md"
6
+ "root": ".cline",
7
+ "skillPath": "skills/taiwan-logistics",
8
+ "filename": "SKILL.md",
9
+ "globalRoot": "~/.cline"
9
10
  },
10
11
  "scriptPath": "commands/taiwan-logistics/scripts",
11
12
  "frontmatter": {
@@ -4,7 +4,7 @@
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
6
  "root": ".github",
7
- "skillPath": "prompts/taiwan-logistics",
7
+ "skillPath": "skills/taiwan-logistics",
8
8
  "filename": "SKILL.md"
9
9
  },
10
10
  "scriptPath": "prompts/taiwan-logistics/scripts",
@@ -4,7 +4,7 @@
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
6
  "root": ".kiro",
7
- "skillPath": "steering/taiwan-logistics",
7
+ "skillPath": "skills/taiwan-logistics",
8
8
  "filename": "SKILL.md"
9
9
  },
10
10
  "scriptPath": "steering/taiwan-logistics/scripts",
package/dist/index.js CHANGED
@@ -15824,7 +15824,7 @@ var AI_TYPES = [
15824
15824
  "kiro",
15825
15825
  "codex",
15826
15826
  "qoder",
15827
- "roocode",
15827
+ "cline",
15828
15828
  "gemini",
15829
15829
  "trae",
15830
15830
  "opencode",
@@ -15848,7 +15848,7 @@ var AI_TO_PLATFORM = {
15848
15848
  kiro: "kiro",
15849
15849
  codex: "codex",
15850
15850
  qoder: "qoder",
15851
- roocode: "roocode",
15851
+ cline: "cline",
15852
15852
  gemini: "gemini",
15853
15853
  trae: "trae",
15854
15854
  opencode: "opencode",
@@ -15990,8 +15990,8 @@ function detectAIType(cwd = process.cwd()) {
15990
15990
  if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".qoder"))) {
15991
15991
  detected.push("qoder");
15992
15992
  }
15993
- if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".roo"))) {
15994
- detected.push("roocode");
15993
+ if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".cline"))) {
15994
+ detected.push("cline");
15995
15995
  }
15996
15996
  if ((0, import_node_fs.existsSync)((0, import_node_path2.join)(cwd, ".gemini"))) {
15997
15997
  detected.push("gemini");
@@ -16027,15 +16027,15 @@ function getAITypeDescription(aiType) {
16027
16027
  case "antigravity":
16028
16028
  return "Antigravity (.agent/skills/)";
16029
16029
  case "copilot":
16030
- return "GitHub Copilot (.github/prompts/)";
16030
+ return "GitHub Copilot (.github/skills/)";
16031
16031
  case "kiro":
16032
- return "Kiro (.kiro/steering/)";
16032
+ return "Kiro (.kiro/skills/)";
16033
16033
  case "codex":
16034
16034
  return "Codex CLI (.codex/skills/)";
16035
16035
  case "qoder":
16036
- return "Qoder (.qoder/rules/)";
16037
- case "roocode":
16038
- return "Roo Code (.roo/commands/)";
16036
+ return "Qoder (.qoder/skills/)";
16037
+ case "cline":
16038
+ return "Cline (.cline/skills/)";
16039
16039
  case "gemini":
16040
16040
  return "Gemini CLI (.gemini/skills/)";
16041
16041
  case "trae":
@@ -16323,11 +16323,11 @@ async function listCommand() {
16323
16323
  { key: "cursor", path: ".cursor/skills/taiwan-logistics/" },
16324
16324
  { key: "windsurf", path: ".windsurf/skills/taiwan-logistics/" },
16325
16325
  { key: "antigravity", path: ".agent/skills/taiwan-logistics/" },
16326
- { key: "copilot", path: ".github/prompts/taiwan-logistics/" },
16327
- { key: "kiro", path: ".kiro/steering/taiwan-logistics/" },
16326
+ { key: "copilot", path: ".github/skills/taiwan-logistics/" },
16327
+ { key: "kiro", path: ".kiro/skills/taiwan-logistics/" },
16328
16328
  { key: "codex", path: ".codex/skills/taiwan-logistics/" },
16329
- { key: "qoder", path: ".qoder/rules/taiwan-logistics/" },
16330
- { key: "roocode", path: ".roo/commands/taiwan-logistics/" },
16329
+ { key: "qoder", path: ".qoder/skills/taiwan-logistics/" },
16330
+ { key: "cline", path: ".cline/skills/taiwan-logistics/" },
16331
16331
  { key: "gemini", path: ".gemini/skills/taiwan-logistics/" },
16332
16332
  { key: "trae", path: ".trae/skills/taiwan-logistics/" },
16333
16333
  { key: "opencode", path: ".opencode/skills/taiwan-logistics/" },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "taiwan-logistics-skill",
3
- "version": "1.3.0",
3
+ "version": "1.4.0",
4
4
  "description": "AI-powered Taiwan Logistics toolkit. Supports 7 providers: 6 aggregators (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow) plus HCT 新竹物流 direct carrier API.",
5
5
  "bin": {
6
6
  "taiwan-logistics": "./dist/index.js"