taiwan-logistics-skill 1.4.5 → 1.4.7

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 | — | 宅配、店港澳 |
@@ -108,7 +108,7 @@ When modifying files:
108
108
  | Antigravity | `.agent` | full |
109
109
  | Copilot | `.github` | full |
110
110
  | Kiro | `.kiro` | full |
111
- | Codex | `.codex` | full |
111
+ | Codex | `.agents` | full |
112
112
  | Qoder | `.qoder` | full |
113
113
  | Cline | `.cline` | full |
114
114
  | Gemini | `.gemini` | full |
@@ -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 | — | 宅配、店港澳 |
@@ -19,12 +19,12 @@ CVS,LgsType=B2C ShipType=1 GoodsType=2,7-11 大宗寄倉(冷凍),payuni,cvs_
19
19
  CVS,LgsType=C2C ShipType=1 GoodsType=1,7-11 店到店(常溫),payuni,cvs_c2c,true,,,常溫,Ship=1 取貨付款、ShipTag=1 啟用物流
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
- 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
- CVS,Pay_zg=51/52 Pay_subzg=7NET,7-11 店到店(C2C),smilepay,cvs_c2c,true,,,常溫,51 取貨付款/52 純取貨
25
- CVS,Pay_zg=51/52 Pay_subzg=FAMI,全家 店到店(C2C),smilepay,cvs_c2c,true,,,常溫,51 取貨付款/52 純取貨
26
- HOME,Pay_zg=81/82 Pay_subzg=TCAT,黑貓宅配,smilepay,home,true,,,常溫/冷藏/冷凍,81 取貨付款/82 純取貨;溫層由 ezcatGetTrackNum.asp 的 temperature 0001/0002/0003 決定
27
- HOME,Pay_zg=83 Pay_subzg=TCAT,黑貓逆物流(退貨),smilepay,return,false,,,常溫,退貨用
22
+ CVS,Pay_zg=55/56 Pay_subzg=7NET,7-11 大宗寄倉(B2C),smilepay,cvs_b2c,true,,,常溫,55 取貨付款/56 純取貨;通知 Classif V 取貨付款/W 純取貨
23
+ CVS,Pay_zg=51/52 Pay_subzg=7NET,7-11 店到店(C2C),smilepay,cvs_c2c,true,,,常溫,51 取貨付款/52 純取貨;通知 Classif T 取貨付款/U 純取貨
24
+ CVS,Pay_zg=51/52 Pay_subzg=FAMI,全家 店到店(C2C),smilepay,cvs_c2c,true,,,常溫,51 取貨付款/52 純取貨;通知 Classif T 取貨付款/U 純取貨;全家 B2C 速買配目前未提供(客服回覆 2026-09-30)
25
+ HOME,Pay_zg=81/82 Pay_subzg=TCAT,黑貓宅配,smilepay,home,true,,,常溫/冷藏/冷凍,81 取貨付款/82 純取貨;溫層由 ezcatGetTrackNum.asp 的 temperature 0001/0002/0003 決定;通知 Classif O 貨到收現/P 宅配
26
+ HOME,Pay_zg=83 Pay_subzg=TCAT,黑貓逆物流(退貨),smilepay,return,false,,,常溫,退貨用;通知 Classif Q
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,6 +47,9 @@ 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 代收貨款
@@ -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,"官方確認目前無物流 API(紅陽客服回覆 2026-09-29),官網物流頁列全家大宗貨運與 C2C 7-11/全家/萊爾富,金流 card_type=09 超商取貨付款(不支援 OK),宅配通僅見於舊文件站 doc.esafe.com.tw",全台,public,https://www.sunpay.com.tw/developers/,2026-09-29
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.e-can.com.tw,https://www.e-can.com.tw,"常溫;無公開API規格;紅陽舊文件站曾列宅配通,官網物流頁已未列;可用的聚合路徑需向業者確認",全台,contract,https://www.e-can.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
@@ -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 規格;可用的聚合路徑需向業者確認。紅陽也確認目前不支援物流 API 串接(紅陽客服回覆 2026-09-29)。
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
  | 臉書店 | 社群電商賣場 |
@@ -39,13 +39,15 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
39
39
  |---|---|---|---|
40
40
  | 費用 | 免費 | 免費 | 免費 |
41
41
  | 包裹類別 | 店配(付款/不付款)+ 宅配(貨到付款/純配送)| 同參數版 | **僅店配,無宅配** |
42
- | 串接類型 | 單次單筆 | **單次單筆或批次多筆** | 單次單筆 |
42
+ | 串接類型 | 單次單筆 | 比較表寫「單次單筆或批次多筆」,**實際一次只能傳一筆**(見下) | 單次單筆 |
43
43
  | 電子地圖與取件人資訊 | 獨立串接傳遞 | 獨立串接傳遞 | **同時完成** |
44
44
  | 串接商品資料 | 無 | **有** | 無 |
45
45
  | 列印商品明細寄件單 | 無 | **可** | 無 |
46
46
  | 異常處理 | 提供錯誤狀態碼 | 提供錯誤狀態碼 | **無** |
47
47
  | 配送狀態 | API 查詢 | API 查詢 | API 查詢 |
48
48
 
49
+ > ⚠️ **網站串接一次只能傳一筆訂單**(ezShip 客服回覆 2026-09-29)。要批次上傳時,拆成多筆、每筆間隔幾秒依序送出;XML 版也一樣。
50
+
49
51
  > ⚠️ **簡易版官方已凍結**:原文「請使用(參數版)或(XML版),(簡易版)僅提供系統正常運作,不再開發新功能」。新專案不應採用。
50
52
  > ⚠️ **代收服務(取貨付款/貨到付款)需 ezShip 商務會員資格**,且須在合約期間內。一般會員只能做「取貨不付款/純配送」。
51
53
 
@@ -236,6 +238,82 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
236
238
 
237
239
  回傳(snake_case):`order_id`、`sn_id`、`order_status`、`webPara`;代碼同參數版,另有 `E98` XML 無法載入、`E99` 系統錯誤。
238
240
 
241
+ ## 2.3 B2C 寄件(大宗寄倉)與寄件單下載 API
242
+
243
+ 來源:服務說明 `service_home_w18v1.jsp?vDocNo=2501`(內容頁 `service_doc/2501NN_doc.jsp`,`NN`=01–23)。
244
+
245
+ **服務**:賣家把包裹依取件超商分箱,自行以貨運/宅配/郵局送到該超商物流中心,由物流中心轉運至門市(p.01–02)。只收「店配–取貨付款」與「店配–取貨不付款」(p.02)。
246
+
247
+ | 超商 | 物流中心 | 收貨時間(當日轉運)| 材積 |
248
+ |---|---|---|---|
249
+ | 全家 | 日翊物流大溪倉,桃園市大溪區仁善里15鄰新光東路76巷22-2號 | 08:30–14:00;14:01–16:30 隔日;需先在全家「廠商進貨預約平台」預約(7 家指定貨運商免預約)| 長+寬+高 < 105 cm、最長邊 < 45 cm、< 5 kg |
250
+ | 萊爾富 | 新北市樹林區味王街1-25號(38號碼頭)| 08:00–14:00;14:01–15:00 隔日 | 同上 |
251
+ | OK | 來來物流,桃園市大溪區仁善里9鄰新光東路63巷88號(42-43碼頭)| 08:00–14:00;14:01–17:00 隔日 | 長+寬+高 < 105 cm、最長邊 45 cm、其餘兩邊 ≤ 30 cm、< 5 kg |
252
+
253
+ (p.05–07)當日轉運者次日中午前送達門市。取貨付款每筆代收上限 10,000 元(p.08)。
254
+
255
+ **啟用**(p.03、p.19):限 ezShip 商務會員且合約有效。後台「我的便利配 → 設定 → 配送服務 → B2C寄件設定」:
256
+
257
+ - **自動要號**:開啟後,以網站串接(§2.1/§2.2 的建單 API)建立的寄件資料**一律視為 B2C 寄件**並自動取號。若部分訂單仍要門市寄件(店到店),不可開啟
258
+ - **來源 IP**:登錄呼叫寄件單 API 的對外 IP
259
+
260
+ 也就是**建單沒有另一組 API**,B2C 與店到店的差別由帳號設定決定。
261
+
262
+ ### 單筆寄件單下載(p.20)
263
+
264
+ `https://www.ezship.com.tw/emap/ezship_request_order_label_api.jsp`,Form submit 或 URL 參數。
265
+
266
+ | 參數 | 說明 |
267
+ |---|---|
268
+ | `suID` | ezShip 帳號(需開通網站串接)|
269
+ | `sn_id` | 店到店編號 |
270
+
271
+ 成功直接輸出寄件單 PDF。錯誤以文字輸出:
272
+
273
+ | 訊息 | 原因 |
274
+ |---|---|
275
+ | `Error: The requested header does not contain a valid source IP address.` | 來源 IP 未設定 |
276
+ | `Error: The requested file with sn_id : … was not found.` | `sn_id` 不存在 |
277
+ | `Error: The requested file was not found.` | `suID` 錯誤或未開自動要號 |
278
+
279
+ ### 多筆寄件單下載(p.21)
280
+
281
+ 兩步驟,皆 `POST` JSON(UTF-8),需先設定來源 IP。
282
+
283
+ **步驟一** `https://www.ezship.com.tw/myezship_label/myezship_order_print_api.jsp` — 建立批次表單
284
+
285
+ | 欄位 | 說明 |
286
+ |---|---|
287
+ | `ezship_id` | ezShip 帳號 |
288
+ | `label_for` | 固定 `4` |
289
+ | `label_printer` | `A` A4 四格;`B` 標籤機 10×15 |
290
+ | `label_printtype` | `A` 只印寄件單;`B` 寄件單+明細 |
291
+ | `label_merge` | `A` 三家超商合併;`B` 各超商分開檔案 |
292
+ | `sn_list[].sn_id` | 店到店編號 |
293
+
294
+ 回應:`errorCode`、`ezship_id`、`file_id`(步驟二使用)、`success_count`、`fail_count`、`fail_list[].sn_id`、`total`、`request_id`。
295
+
296
+ **步驟二** `https://www.ezship.com.tw/myezship_label/myezship_order_label_api.jsp` — 取得 PDF 網址
297
+
298
+ 請求 `ezship_id`、`file_id`;回應 `errorCode`、`file_list[].file_url`、`file_count`、`request_id`。每 100 筆切一個檔案,製作約 1 分鐘/百筆。
299
+
300
+ | `errorCode` | 意義 |
301
+ |---|---|
302
+ | `000` | 成功 |
303
+ | `001` | 新增失敗 |
304
+ | `002` | JSON 格式有誤 |
305
+ | `003` | 會員權限異常 |
306
+ | `004` | 製作中(步驟二)|
307
+ | `005` | 製作失敗(步驟二)|
308
+ | `006` | 尚未製作(步驟二)|
309
+ | `007` | 非允許 IP |
310
+ | `008` | 禁止一分鐘內多次傳送(步驟一)|
311
+ | `999` | 傳送失敗 |
312
+
313
+ > ⚠️ 步驟一一分鐘內不可重送(`008`);步驟二回 `004` 時稍後再查,不要重跑步驟一。
314
+
315
+ **逾期未領**(p.10):貨到門市 7 天未取即退回超商物流中心,依「B2C寄件設定」的退貨週期整箱待領,**由寄件人自行委託物流業者取回**,超過 30 日未處理將捐贈或回收。沒有退貨 API。
316
+
239
317
  ## 3. 申請流程
240
318
 
241
319
  1. 進入 ezShip 後台
@@ -291,9 +369,7 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
291
369
 
292
370
  | 項目 | 狀態 |
293
371
  |---|---|
294
- | 大宗直寄 | 欄位定義的金額說明把「直寄店配/直寄宅配」與店到店、店到宅並列,顯示直寄訂單走同一組建單 API;開通條件與是否另有參數未載明 |
295
- | 店退店(逆物流) | 串接文件未提及,應為後台操作;是否有 API 需洽 ezShip |
296
- | XML 版批次多筆 | 比較表標示 XML 版可「批次多筆」,但欄位定義與範例只有單一 `<ORDER>`,批次格式未載明 |
372
+ | 店退店(逆物流) | 串接文件與 B2C 寄件說明都未提供 API;B2C 逾期件由寄件人自行至物流中心取回。2026-09-25 已詢問 ezShip 客服,回覆未提及店退店 API |
297
373
 
298
374
  ## 8. 來源
299
375
 
@@ -304,6 +380,7 @@ ezShip 是本 skill 收錄的**唯一非金流商的超商取貨聚合商**。
304
380
  - 程式碼說明:連結電子地圖 — `…/2017_service_doc_home.jsp?vDocNo=1702&vDefPage=07`
305
381
  - 程式碼說明:傳送訂單 — `…&vDefPage=08`
306
382
  - 貨況串接(依訂單編號查詢)— `…&vDefPage=22`
383
+ - 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 查核)
307
384
  - 欄位定義 PDF — `ezship_WebOrder_HttpRequest_v15.pdf`、`ezship_WebOrder_XML_v15s.pdf`、`ezship_status_api.pdf`、`ezship_status_api_byorder.pdf`(見 §4)
308
385
  - 欄位定義 PDF(參數版)— http://www.ezship.com.tw/file/ezship_WebOrder_HttpRequest_v15.pdf
309
386
  - 欄位定義 PDF(XML 版)— http://www.ezship.com.tw/file/ezship_WebOrder_XML_v15s.pdf
@@ -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
 
@@ -210,7 +213,6 @@ SmilePay 物流可由「**寄送方式**」與「**金流方式**」兩個維度
210
213
  | 7-11 C2C 店到店 | `typesserver = 711C2C` |
211
214
  | 7-11 B2C 大宗寄倉 | `typesserver = 711B2C` |
212
215
  | 全家 C2C 店到店 | `typesserver = FAMIC2C` |
213
- | 全家 B2C 大宗寄倉 | `typesserver = FAMIB2C`(部分商家可選用) |
214
216
  | 黑貓 常溫 | TCAT (溫層 `0001`) |
215
217
  | 黑貓 冷藏 | TCAT (溫層 `0002`) |
216
218
  | 黑貓 冷凍 | TCAT (溫層 `0003`) |
@@ -236,8 +238,7 @@ WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
236
238
 
237
239
  ## Pay_zg / Pay_subzg 編碼矩陣
238
240
 
239
- > **這是 SmilePay 物流的祖傳秘方** — 所有物流產品都從同一支 `SPPayment.asp`
240
- > 進入,靠 `Pay_zg`(主要分類)+ `Pay_subzg`(副分類)來路由到實際物流業者。
241
+ 所有物流產品都從 `SPPayment.asp`(或 `mtmk_utf.asp` 結帳頁)進入,靠 `Pay_zg`(主要分類)+ `Pay_subzg`(副分類)路由到實際物流業者。
241
242
 
242
243
  ### Pay_zg(物流主分類)
243
244
 
@@ -250,7 +251,8 @@ WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
250
251
  | `TCAT_COD_PAY_ZG` | `81` | 黑貓宅配 **取貨付款** |
251
252
  | `TCAT_PICKUP_PAY_ZG` | `82` | 黑貓宅配 **純取貨** |
252
253
  | `RETCAT_PAY_ZG` | `83` | 黑貓 **逆物流(退貨)** |
253
- | `c2b_payzg` | (商家自訂) | C2B 退貨便(由商家後台設定,常見值依超商而異) |
254
+ | — | `57` | C2B 退貨便,運費由消費者付 |
255
+ | — | `58` | C2B 退貨便,運費由商家付(1.1.23 設定預設值) |
254
256
 
255
257
  ### Pay_subzg(物流副分類)
256
258
 
@@ -270,15 +272,16 @@ WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
270
272
  | 7-11 B2C 大宗寄倉 | 純取貨 | `56` | `7NET` |
271
273
  | 全家 C2C 店到店 | 取貨付款 | `51` | `FAMI` |
272
274
  | 全家 C2C 店到店 | 純取貨 | `52` | `FAMI` |
273
- | 全家 B2C 大宗寄倉 | 取貨付款 | `55` | `FAMI` |
274
- | 全家 B2C 大宗寄倉 | 純取貨 | `56` | `FAMI` |
275
275
  | 黑貓常溫 / 冷藏 / 冷凍 | 取貨付款 | `81` | `TCAT` |
276
276
  | 黑貓常溫 / 冷藏 / 冷凍 | 純取貨 | `82` | `TCAT` |
277
277
  | 黑貓逆物流(退貨) | — | `83` | `TCAT` |
278
+ | 7-11 退貨便(C2B) | 運費消費者付/商家付 | `57`/`58` | `7NET` |
278
279
 
279
- **注意**:黑貓的「常溫 / 冷藏 / 冷凍」差異**不是**靠 `Pay_zg` 區分,
280
- 而是走第二支 API `ezcatGetTrackNum.asp` 時的 `temperature` 參數
281
- (`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍)。
280
+ > **全家 B2C(大宗寄倉)目前沒有提供**(SmilePay 客服回覆 2026-09-30)。1.1.23 雖有 `FAMIB2C` 電子地圖網址,但兩版外掛都沒有建單分支。
281
+
282
+ **注意**:黑貓的「常溫 / 冷藏 / 冷凍」差異**不是**靠 `Pay_zg` 區分,而是 `temperature` 參數
283
+ (`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍)。兩版外掛送的位置不同:
284
+ 1.1.23 送在第二階段 `ezcatGetTrackNum.asp`;4.3.3 送在第一階段 `SPPayment.asp`(`Pay_zg=81/82`),第二階段不再送。
282
285
 
283
286
  ### 路由邏輯(PHP 範例)
284
287
 
@@ -304,11 +307,7 @@ function determine_pay_codes(string $typesserver, string $payment_method): array
304
307
  'pay_zg' => $is_cod ? 51 : 52,
305
308
  'pay_subzg' => 'FAMI',
306
309
  ];
307
- case 'FAMIB2C':
308
- return [
309
- 'pay_zg' => $is_cod ? 55 : 56,
310
- 'pay_subzg' => 'FAMI',
311
- ];
310
+ // 全家 B2C(大宗寄倉)速買配目前未提供
312
311
  }
313
312
  throw new InvalidArgumentException("Unknown typesserver: {$typesserver}");
314
313
  }
@@ -353,6 +352,7 @@ POST https://ssl.smse.com.tw/api/SPPayment.asp
353
352
  | `Logistics_Roturl` | String(URL) | ● | **物流貨況通知網址** |
354
353
  | `Roturl_status` | String | △ | 回傳狀態識別碼(如 `woook1.1.23`) |
355
354
  | `Remark` | String | △ | 備註(取自買家結帳備註) |
355
+ | `Logistics_MapType` | String | △ | `M`=行動版電子地圖;4.3.3 偵測到 Android/iPad/iPhone 時帶入 |
356
356
 
357
357
  #### 回應(XML)
358
358
 
@@ -383,6 +383,34 @@ POST https://ssl.smse.com.tw/api/SPPayment.asp
383
383
  - HTTP body 含 `<SmilePay>`
384
384
  - `<Status>` 等於 `1`
385
385
 
386
+ **兩版外掛的建單方式差異**
387
+
388
+ | 產品 | 1.1.23 | 4.3.3 |
389
+ |------|--------|-------|
390
+ | C2C 取貨付款 `51` | 後端 POST `SPPayment.asp` | 同左(`smilepayc2c.php`) |
391
+ | B2C 取貨付款 `55` | 後端 POST `SPPayment.asp` | **瀏覽器轉址到 `mtmk_utf.asp`**,帶 `MapRoturl`;有預選門市才帶 `Logistics_store`(`smilepayb2c.php`) |
392
+ | C2C/B2C 純取貨 `52`/`56` | 後端 POST `SPPayment.asp` | 同左,商家在後台開啟訂單時才建單(`smilepayc2cup.php`、`smilepayb2cup.php`) |
393
+ | 黑貓 `81`/`82` | 後端 POST `SPPayment.asp` | 同左,`temperature` 在此階段送出(`smilepayezcatp.php`、`smilepayezcatup.php`) |
394
+
395
+ 物流相關通知走金流的 `Roturl`,以 `Classif` 區分(SmilePay 客服回覆 2026-09-30):
396
+
397
+ | `Classif` | 交易方式 |
398
+ |---|---|
399
+ | `T` | C2C 取貨付款 |
400
+ | `U` | C2C 純取貨 |
401
+ | `V` | B2C 取貨付款 |
402
+ | `W` | B2C 純取貨 |
403
+ | `O` | 黑貓貨到收現 |
404
+ | `P` | 黑貓宅配 |
405
+ | `Q` | 黑貓逆物流 |
406
+ | `R` | C2B 客付 |
407
+ | `S` | C2B 場付 |
408
+
409
+ 4.3.3 外掛(`smilepay_respond.php`)只處理 `T`、`V`、`O`;1.1.23 對 `T`、`O` 將訂單設為 completed。
410
+ 貨況通知另走 `Logistics_Roturl`(見[通知與貨況](#通知與貨況))。
411
+
412
+ 4.3.3 ReadMe:交貨便服務單產生後須於 7 日內出貨,逾期失效;黑貓與純取貨的物流單要由商家在後台訂單頁觸發才會建立。
413
+
386
414
  ### 第二階段:取得實際物流編號
387
415
 
388
416
  依物流產品分為三條路徑:
@@ -452,12 +480,12 @@ POST https://ssl.smse.com.tw/api/ezcatGetTrackNum.asp
452
480
  | `Dcvc` | ● | 商家代號 |
453
481
  | `Verify_key` | ● | 共享密鑰 |
454
482
  | `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` | △ | 出貨類型 |
483
+ | `package_size` | ● | `0001` 60 cm/`0002` 90 cm/`0003` 120 cm/`0004` 150 cm(150 僅常溫;冷藏、冷凍上限 120) |
484
+ | `temperature` | △ | 溫層:`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍(4.3.3 改在第一階段送) |
485
+ | `delivery_date` | △ | 預定送達日 `YYYY-MM-DD`(兩版外掛都送此格式;4.3.3 預設隔日,遇週日延一天) |
486
+ | `delivery_timezone` | △ | `1` 13 時前/`2` 14–18 時/`4` 不指定(4.3.3 固定送 `4`) |
487
+ | `is_protect` | △ | `Y` 使用/`N` 不使用;選「預設」時不送 |
488
+ | `shipment_type` | △ | `1` 手動出貨/`2` 黑貓派工;選「預設」時不送 |
461
489
  | `receiver_address` | △ | 收件地址(逆物流時用) |
462
490
 
463
491
  回應:
@@ -601,7 +629,7 @@ GET https://ssl.smse.com.tw/api/LogisticsEmap.asp
601
629
  | `711C2C` | 7-11 C2C 店到店 |
602
630
  | `711B2C` | 7-11 B2C 大宗寄倉 |
603
631
  | `FAMIC2C` | 全家 C2C 店到店 |
604
- | `FAMIB2C` | 全家 B2C 大宗寄倉 |
632
+ | `FAMIB2C` | 全家 B2C 大宗寄倉(電子地圖網址存在,但速買配目前未提供此服務) |
605
633
 
606
634
  ### TypesInterface 對照
607
635
 
@@ -840,7 +868,7 @@ echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應
840
868
 
841
869
  > 黑貓只回 `1/3/5/7/8` 這幾個狀態,沒有 `2/4/6`。
842
870
 
843
- #### DetailStatus 異常代碼(節錄)
871
+ #### DetailStatus 異常代碼
844
872
 
845
873
  | 代碼 | 異常類型 |
846
874
  |------|---------|
@@ -869,11 +897,21 @@ echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應
869
897
  | `009` | 超大 |
870
898
  | `010` | 人不在 |
871
899
  | `011` | 已收走 |
900
+ | `012` | 暫不退 |
901
+ | `013` | 電話暫停使用 |
872
902
  | `014` | 商品送達時已拒收退回 |
873
903
  | `015` | 地址有誤 |
904
+ | `016` | 無件可退 |
874
905
  | `017` | PCHOME 通知取消 |
906
+ | `018` | 不知回收何物,自行與廠商聯絡 |
907
+ | `019` | 要換貨,需廠商再聯繫 |
908
+ | `020` | 僅需索取說明書,需廠商聯繫 |
909
+ | `021` | 多日聯絡不到,需廠商再聯繫 |
910
+ | `022` | 改住址 |
911
+ | `023` | 區號錯誤 |
875
912
  | `024` | 其他 |
876
913
  | `025` | 已集貨 |
914
+ | `026` | 廠商通知取消 |
877
915
  | `999` | 訂單復原 |
878
916
  | `P26` | 另約時間 |
879
917
  | `P27` | 電聯不上 |
@@ -886,6 +924,7 @@ echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應
886
924
 
887
925
  > **處理順序**:通知進來時先檢查 `DetailStatus`,**有值就優先記錄異常**,
888
926
  > 然後直接回應 `<Roturlstatus>接收到配送異常XXX</Roturlstatus>` 結束 (不再處理 `Shipstatus`)。
927
+ > 4.3.3(`smilepay_logistic_status.php` `ezcat_logistic_callback`)有 `DetailStatus` 時只寫訂單備註就結束,**不回應任何字串**;兩版代碼表相同。
889
928
 
890
929
  #### 回應格式
891
930
 
@@ -974,8 +1013,8 @@ GET https://ssl.smse.com.tw/ezpos/mtmk_utf.asp
974
1013
  | `Rvg2c` | ● | 簽章驗證代碼 |
975
1014
  | `Verify_key` | ● | 共享密鑰 |
976
1015
  | `Od_sob` | ● | 訂單編號(會原樣回傳) |
977
- | `Pay_zg` | ● | C2B 退貨便用值(商家後台設定的 `c2b_payzg`,依超商不同) |
978
- | `Pay_subzg` | ● | `7NET` 或 `FAMI` |
1016
+ | `Pay_zg` | ● | `57` 運費由消費者付/`58` 運費由商家付(兩版相同) |
1017
+ | `Pay_subzg` | ● | 4.3.3 固定 `7NET`;1.1.23 沿用原 B2C 訂單的值,且只允許 B2C 訂單建立退貨便 |
979
1018
  | `Data_id` | ● | 訂單編號 |
980
1019
  | `Amount` | ● | 退款金額 |
981
1020
  | `Pur_name` | ● | 退貨人姓名 |
@@ -999,6 +1038,8 @@ GET https://ssl.smse.com.tw/ezpos/mtmk_utf.asp
999
1038
 
1000
1039
  完整退貨便代碼 = `Paymentno` + `Validationno`
1001
1040
 
1041
+ 4.3.3(`smilepayc2b.php` `c2b_recv_order_process`)另讀 `Classif`(`R` 或 `S` 才視為成功)與 `Classif_sub`,並以 Form 自動送出到 `mtmk_utf.asp`(欄位名寫成小寫 `verify_key`,未帶 `Tel_number`、`Logistics_Roturl`)。
1042
+
1002
1043
  #### PHP 範例
1003
1044
 
1004
1045
  ```php
@@ -1276,7 +1317,7 @@ WC 端記得**禁用「貨到付款」金流**避免重複扣款。
1276
1317
  | 列印 API | 自帶 (`types=Web`) | `B2C_MultiplePrint.asp` |
1277
1318
  | 適合對象 | 個人 / 小批量出貨 | 商家大量出貨 |
1278
1319
  | 號碼格式 | `paymentno` + `validationno` | `766` + `EshopOrderNo` |
1279
- | 可選店 | 7-11 / 全家 | 7-11(全家 B2C 較少見) |
1320
+ | 可選店 | 7-11 / 全家 | 僅 7-11(全家 B2C 目前未提供) |
1280
1321
 
1281
1322
  ### Q10:能否 B2C 與 C2C 同時開?
1282
1323
 
@@ -3,10 +3,10 @@
3
3
  "displayName": "Codex CLI",
4
4
  "installType": "full",
5
5
  "folderStructure": {
6
- "root": ".codex",
6
+ "root": ".agents",
7
7
  "skillPath": "skills/taiwan-logistics",
8
8
  "filename": "SKILL.md",
9
- "globalRoot": "~/.codex"
9
+ "globalRoot": "~/.agents"
10
10
  },
11
11
  "scriptPath": "skills/taiwan-logistics/scripts",
12
12
  "frontmatter": {
package/dist/index.js CHANGED
@@ -16037,7 +16037,7 @@ function getAITypeDescription(aiType) {
16037
16037
  case "kiro":
16038
16038
  return "Kiro (.kiro/skills/)";
16039
16039
  case "codex":
16040
- return "Codex CLI (.codex/skills/)";
16040
+ return "Codex CLI (.agents/skills/)";
16041
16041
  case "qoder":
16042
16042
  return "Qoder (.qoder/skills/)";
16043
16043
  case "cline":
@@ -16331,7 +16331,7 @@ async function listCommand() {
16331
16331
  { key: "antigravity", path: ".agent/skills/taiwan-logistics/" },
16332
16332
  { key: "copilot", path: ".github/skills/taiwan-logistics/" },
16333
16333
  { key: "kiro", path: ".kiro/skills/taiwan-logistics/" },
16334
- { key: "codex", path: ".codex/skills/taiwan-logistics/" },
16334
+ { key: "codex", path: ".agents/skills/taiwan-logistics/" },
16335
16335
  { key: "qoder", path: ".qoder/skills/taiwan-logistics/" },
16336
16336
  { key: "cline", path: ".cline/skills/taiwan-logistics/" },
16337
16337
  { key: "gemini", path: ".gemini/skills/taiwan-logistics/" },
@@ -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.5";
16367
+ var VERSION = "1.4.7";
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.5",
3
+ "version": "1.4.7",
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"