taiwan-logistics-skill 1.4.2 → 1.4.4

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.
Files changed (49) hide show
  1. package/README.md +39 -28
  2. package/assets/taiwan-logistics/CLAUDE.md +18 -17
  3. package/assets/taiwan-logistics/EXAMPLES.md +43 -66
  4. package/assets/taiwan-logistics/README.md +40 -29
  5. package/assets/taiwan-logistics/SKILL.md +70 -78
  6. package/assets/taiwan-logistics/data/logistics-types.csv +54 -30
  7. package/assets/taiwan-logistics/data/operations.csv +11 -11
  8. package/assets/taiwan-logistics/data/status-codes.csv +496 -6
  9. package/assets/taiwan-logistics/examples/ecpay-logistics-cvs-example.py +6 -6
  10. package/assets/taiwan-logistics/examples/ezship-logistics-example.py +52 -30
  11. package/assets/taiwan-logistics/examples/hct-logistics-example.py +6 -9
  12. package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py +0 -1
  13. package/assets/taiwan-logistics/examples/paynow-logistics-cvs-example.py +1 -1
  14. package/assets/taiwan-logistics/examples/payuni-logistics-cvs-example.py +110 -196
  15. package/assets/taiwan-logistics/examples/pchomepay-logistics-cvs-example.py +1 -2
  16. package/assets/taiwan-logistics/examples/smilepay-logistics-cvs-example.py +0 -1
  17. package/assets/taiwan-logistics/examples/store-map-integration-example.html +3 -3
  18. package/assets/taiwan-logistics/references/NEWEBPAY_LOGISTICS_REFERENCE.md +1 -7
  19. package/assets/taiwan-logistics/references/carrier-direct-access.md +2 -3
  20. package/assets/taiwan-logistics/references/ecpay-logistics-api.md +18 -17
  21. package/assets/taiwan-logistics/references/ezship-logistics-api.md +20 -10
  22. package/assets/taiwan-logistics/references/hct-logistics-api.md +1 -4
  23. package/assets/taiwan-logistics/references/lalamove-logistics-api.md +1 -1
  24. package/assets/taiwan-logistics/references/ondemand-delivery.md +0 -1
  25. package/assets/taiwan-logistics/references/paynow-logistics-api.md +2 -5
  26. package/assets/taiwan-logistics/references/payuni-logistics-api.md +126 -212
  27. package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +0 -3
  28. package/assets/taiwan-logistics/references/smilepay-logistics-api.md +0 -3
  29. package/assets/taiwan-logistics/scripts/core.py +3 -4
  30. package/assets/taiwan-logistics/scripts/generate-logistics-service.py +70 -1231
  31. package/assets/taiwan-logistics/scripts/test_logistics.py +108 -262
  32. package/assets/templates/base/quick-reference.md +41 -33
  33. package/assets/templates/base/skill-content.md +64 -78
  34. package/assets/templates/platforms/agent.json +2 -2
  35. package/assets/templates/platforms/claude.json +2 -2
  36. package/assets/templates/platforms/cline.json +3 -3
  37. package/assets/templates/platforms/codebuddy.json +2 -2
  38. package/assets/templates/platforms/codex.json +2 -2
  39. package/assets/templates/platforms/continue.json +2 -2
  40. package/assets/templates/platforms/copilot.json +3 -3
  41. package/assets/templates/platforms/cursor.json +2 -2
  42. package/assets/templates/platforms/gemini.json +2 -2
  43. package/assets/templates/platforms/kiro.json +3 -3
  44. package/assets/templates/platforms/opencode.json +2 -2
  45. package/assets/templates/platforms/qoder.json +2 -2
  46. package/assets/templates/platforms/trae.json +2 -2
  47. package/assets/templates/platforms/windsurf.json +2 -2
  48. package/dist/index.js +20 -13
  49. package/package.json +2 -2
package/README.md CHANGED
@@ -3,17 +3,17 @@
3
3
  <h3 align="center">台灣物流 AI 開發技能包</h3>
4
4
 
5
5
  <p align="center">
6
- <strong>6 家物流 aggregator + HCT 新竹物流直連 carrier API</strong>
6
+ <strong>7 家物流 aggregator + HCT 新竹物流直連 + 3 家即時配送</strong>
7
7
  </p>
8
8
 
9
9
  <p align="center">
10
- ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · PayNow · HCT 直連
10
+ ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · PayNow · ezShip · HCT 直連 · Lalamove · pandago · Uber Direct
11
11
  </p>
12
12
 
13
13
  <p align="center">
14
14
  <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/v/taiwan-logistics-skill?style=flat-square&logo=npm" alt="npm version"></a>
15
15
  <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/dm/taiwan-logistics-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
16
- <img src="https://img.shields.io/badge/providers-7-success?style=flat-square" alt="7 Providers">
16
+ <img src="https://img.shields.io/badge/providers-11-success?style=flat-square" alt="11 Providers">
17
17
  <img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
18
18
  <a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
19
19
  </p>
@@ -52,17 +52,21 @@ HCT 直連 API 傳入託運資料,逆物流單獨處理
52
52
 
53
53
  ---
54
54
 
55
- ## 7 家物流服務商
55
+ ## 物流服務商
56
56
 
57
57
  | 服務商 | 類型 | 加密 / 認證 | 特色 |
58
58
  |---|---|---|---|
59
- | **ECPay 綠界** | aggregator | MD5 CheckMacValue | 市佔率最高、SDK 完整、7-11/全家/萊爾富/OK/黑貓/宅配通/HCT |
60
- | **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | 7-11/全家/萊爾富/OK/黑貓 |
59
+ | **ECPay 綠界** | aggregator | MD5 CheckMacValue | B2C 7-11(含冷凍)/全家/萊爾富;C2C 四大超商;宅配黑貓/中華郵政 |
60
+ | **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | B2C 僅 7-11;C2C 四大超商;無宅配 |
61
61
  | **PAYUNi 統一** | aggregator | AES-256-GCM + SHA256 | 7-11 常溫/冷凍 + T-Cat 常溫/冷藏/冷凍(溫控配送最完整) |
62
62
  | **SmilePay 速買配** | aggregator | Verify_key + 加權檢核碼 | Pay_zg 矩陣 51/52/55/56/81/82/83,含逆物流 |
63
- | **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、Notify IP 113.196.231.190、4 大超商 |
63
+ | **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、7-11/全家/萊爾富取貨付款 |
64
64
  | **PayNow 立吉富** | aggregator | **3DES/ECB/Zero-Padding** | 11 條產品線(含海外配送);不同於金流端 AES |
65
- | **HCT 新竹物流** | **direct carrier API** | 申請後提供金鑰 | 直連 carrier API(vs 透過 aggregator) |
65
+ | **ezShip 台灣便利配** | aggregator | 無簽章(`su_id` 帳號綁定) | 全家/萊爾富/OK、宅配、店港澳;不含 7-11 |
66
+ | **HCT 新竹物流** | **direct carrier API** | 申請後提供金鑰 | 收錄的聚合商都沒有新竹物流選項,只能直連 |
67
+ | **Lalamove** | 即時配送 | HMAC-SHA256 自簽 | 先報價後下單(報價 5 分鐘效期) |
68
+ | **pandago** | 即時配送 | OAuth 2.0 + RSA 簽 JWT assertion | 同城即時配送 |
69
+ | **Uber Direct** | 即時配送 | OAuth 2.0 client_credentials | 台灣可用性未經官方確認 |
66
70
 
67
71
  ## 技能包內容
68
72
 
@@ -70,19 +74,23 @@ HCT 直連 API 傳入託運資料,逆物流單獨處理
70
74
  taiwan-logistics/
71
75
  ├── SKILL.md # AI 技能主文檔
72
76
  ├── EXAMPLES.md # 實戰範例集
73
- ├── references/ # 7 份 API 規格 (~10,300 行)
77
+ ├── references/ # 各服務商 API 規格
74
78
  │ ├── ecpay-logistics-api.md
75
79
  │ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
76
80
  │ ├── payuni-logistics-api.md
77
- │ ├── smilepay-logistics-api.md # 1,332 行 / Pay_zg 矩陣
78
- │ ├── pchomepay-logistics-api.md # 1,154 行 / NDJSON 對帳 parser
79
- │ ├── paynow-logistics-api.md # 1,670 行 / 11 產品線
80
- │ └── hct-logistics-api.md # 1,102 行 / 直連 HCT
81
+ │ ├── smilepay-logistics-api.md # Pay_zg 矩陣
82
+ │ ├── pchomepay-logistics-api.md # NDJSON 對帳 parser
83
+ │ ├── paynow-logistics-api.md # Logistic_service 產品線
84
+ │ ├── ezship-logistics-api.md
85
+ │ ├── hct-logistics-api.md # 直連 HCT
86
+ │ ├── lalamove-logistics-api.md
87
+ │ ├── ondemand-delivery.md # Lalamove / pandago / Uber Direct
88
+ │ └── carrier-direct-access.md # 無公開 API 的物流業者與替代路徑
81
89
  ├── examples/ # Python 範例
82
- └── data/ # 5 份 CSV
83
- ├── providers.csv # 7 服務商
84
- ├── operations.csv # 30+ API 操作
85
- ├── logistics-types.csv # CVS / Home / 溫控
90
+ └── data/ # search / recommend 使用的 CSV
91
+ ├── providers.csv # 可串接 + 僅供查詢
92
+ ├── operations.csv
93
+ ├── logistics-types.csv # 各家實際參數值(子類型/溫層/代收上限)
86
94
  ├── status-codes.csv # 跨服務商狀態碼
87
95
  └── field-mappings.csv # 欄位對照
88
96
  ```
@@ -103,22 +111,25 @@ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Co
103
111
 
104
112
  ## 物流類型支援矩陣
105
113
 
106
- | 取貨方式 | 7-11 | 全家 | 萊爾富 | OK | 黑貓 | 海外 | HCT |
107
- |---|---|---|---|---|---|---|---|
108
- | ECPay | ✅ | ✅ | ✅ | ✅ | ✅(常溫) | — | ✅ |
109
- | NewebPay | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
110
- | PAYUNi | ✅ | — | — | — | ✅(常溫/冷凍/冷藏) | — | — |
111
- | SmilePay | ✅ C2C+B2C | ✅ C2C+B2C | — | — | ✅(COD/PICKUP/逆物流) | — | — |
112
- | PChomePay | ✅ | ✅ | ✅ | ✅ | — | — | — |
113
- | PayNow | ✅(含冷凍) | ✅(含冷凍) | ✅ | ✅ | ✅(宅配 + 店到店) | ✅(7-11) | — |
114
- | HCT 直連 | — | — | — | — | — | — | ✅(直連) |
114
+ 依各家官方規格整理,實際參數值見 `data/logistics-types.csv`。
115
+
116
+ | 服務商 | 7-11 | 全家 | 萊爾富 | OK | 黑貓 | 其他 |
117
+ |---|---|---|---|---|---|---|
118
+ | ECPay | B2C(含冷凍)+ C2C | B2C + C2C | B2C + C2C | C2C | 常溫/冷藏/冷凍 | 中華郵政 |
119
+ | NewebPay | B2C + C2C | C2C | C2C | C2C | — | — |
120
+ | PAYUNi | B2C + C2C(常溫/冷凍) | — | — | — | 常溫/冷凍/冷藏 | — |
121
+ | SmilePay | B2C + C2C | B2C + C2C | — | — | 含逆物流 | — |
122
+ | PChomePay | 取貨付款 | 取貨付款 | 取貨付款 | — | — | — |
123
+ | PayNow | B2C + C2C(含冷凍) | B2C + C2C(含冷凍) | C2C | C2C | 宅配、到店 | 7-11 海外 |
124
+ | ezShip | — | C2C | C2C | C2C | — | 宅配、店港澳 |
125
+ | HCT 直連 | — | — | — | — | — | 新竹物流 |
115
126
 
116
127
  ## 相關套件
117
128
 
118
129
  本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
119
130
 
120
- - [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 5 家電子發票
121
- - [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) — 10 家金流
131
+ - [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 7 家電子發票加值中心 + 財政部大平台查詢
132
+ - [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) — 14 家金流
122
133
 
123
134
  ## 授權
124
135
 
@@ -21,11 +21,11 @@ python3 taiwan-logistics/scripts/search.py "<query>" [--domain <domain>]
21
21
  # Recommend logistics provider
22
22
  python3 taiwan-logistics/scripts/recommend.py "<requirements>"
23
23
 
24
- # Test API connectivity
25
- python3 taiwan-logistics/scripts/test_logistics.py [--platform <platform>]
24
+ # 簽章已知答案 + 測試環境連線(ecpay 另可 --create / --query)
25
+ python3 taiwan-logistics/scripts/test_logistics.py [ecpay|newebpay|payuni]
26
26
 
27
- # Generate logistics service code
28
- python3 taiwan-logistics/scripts/generate-logistics-service.py <Platform> --output <ts|py>
27
+ # 輸出已驗證的服務實作(py:examples/;ts:EXAMPLES.md 的 verify 片段)
28
+ python3 taiwan-logistics/scripts/generate-logistics-service.py <Provider> --output <ts|py>
29
29
  ```
30
30
 
31
31
  ## Architecture
@@ -38,22 +38,26 @@ taiwan-logistics/ # Source of Truth
38
38
  │ ├── ecpay-logistics-api.md
39
39
  │ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
40
40
  │ ├── payuni-logistics-api.md
41
- │ ├── smilepay-logistics-api.md # NEW (Phase 4): Pay_zg matrix
42
- │ ├── pchomepay-logistics-api.md # NEW (Phase 4): 金物流二合一
43
- │ ├── paynow-logistics-api.md # NEW (Phase 4): 11 product lines, 3DES/ECB
44
- │ └── hct-logistics-api.md # NEW (Phase 4): HCT 直連 carrier API
45
- ├── examples/ # Python examples per provider
41
+ │ ├── smilepay-logistics-api.md # Pay_zg matrix
42
+ │ ├── pchomepay-logistics-api.md # 金物流二合一
43
+ │ ├── paynow-logistics-api.md # Logistic_service 產品線, 3DES/ECB
44
+ │ ├── ezship-logistics-api.md
45
+ │ ├── hct-logistics-api.md # HCT 直連 carrier API
46
+ │ ├── lalamove-logistics-api.md
47
+ │ ├── ondemand-delivery.md
48
+ │ └── carrier-direct-access.md # 無公開 API 的物流業者
49
+ ├── examples/ # 可執行範例(CI 以官方測試向量驗證)
46
50
  └── data/ # Data-driven CSVs
47
- ├── providers.csv # 9 可串接 + 10 僅供查詢(含 doc_access 分級)
51
+ ├── providers.csv # 11 可串接 + 10 僅供查詢(含 doc_access 分級)
48
52
  ├── operations.csv # cross-provider API operations
49
- ├── logistics-types.csv # CVS/Home/temp variants
53
+ ├── logistics-types.csv # 各家實際參數值(子類型/溫層/代收上限)
50
54
  ├── status-codes.csv # vendor-specific status codes
51
- └── field-mappings.csv # 22 欄位 × 11 家 provider 對照(含即時配送)
55
+ └── field-mappings.csv # 跨 provider 欄位對照(含即時配送)
52
56
 
53
57
  logistics-cli/ # CLI installer (taiwan-logistics-skill on npm)
54
58
  ├── src/
55
59
  │ ├── commands/init.ts # Install command with template generation
56
- │ ├── utils/template.ts # Template rendering engine
60
+ │ └── utils/template.ts # Template rendering engine
57
61
  └── assets/ # Bundled assets
58
62
  ├── taiwan-logistics/ # Copy of taiwan-logistics/
59
63
  └── templates/
@@ -141,9 +145,6 @@ Never push directly to `main`. Always:
141
145
 
142
146
  ## Related Projects
143
147
 
144
- - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow)
148
+ - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow, O'Pay, SunPay)
145
149
  - **Taiwan Payment Skill** - Payment integration (14 providers: ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline, LINE Pay, TapPay, O'Pay, JKOPAY, SunPay, GoMyPay)
146
150
 
147
- ---
148
-
149
- **Last Updated**: 2026-05-07 (Phase 4: +4 logistics providers — SmilePay, PChomePay, PayNow, HCT direct)
@@ -1267,12 +1267,8 @@ if __name__ == '__main__':
1267
1267
 
1268
1268
  ## PAYUNi Logistics Examples
1269
1269
 
1270
- > 端點、欄位、代碼依 wpbr-payuni-shipping 1.6.4(正式上架外掛);加解密由 CI 以統一金流官方外掛與
1271
- > 官方 PHP SDK 產生的標準答案驗證。規格細節見 `references/payuni-logistics-api.md`,
1272
- > 完整 Python 版見 `examples/payuni-logistics-cvs-example.py`。
1273
- >
1274
- > 舊版範例中的 `/logistics/create`、`LogisticsType`、`GoodsAmount`、`Receiver*`、`LogisticsID`
1275
- > 皆不存在於 PAYUNi 物流 API,請勿沿用。
1270
+ > 依 PAYUNi 官方文件(docs.payuni.com.tw/web/#/7);加解密由 CI 以官方外掛與官方 PHP SDK 的標準答案驗證。
1271
+ > 規格見 `references/payuni-logistics-api.md`,Python 版見 `examples/payuni-logistics-cvs-example.py`。
1276
1272
 
1277
1273
  ### 1. Encryption Helper (TypeScript)
1278
1274
 
@@ -1299,49 +1295,47 @@ export function decryptPAYUNi(encryptInfo: string, hashKey: string, hashIV: stri
1299
1295
  }
1300
1296
  ```
1301
1297
 
1302
- ### 2. Create Shipment
1298
+ ### 2. Create Shipment(在交易 API 內建立)
1303
1299
 
1304
1300
  ```typescript
1305
1301
  const BASE = 'https://sandbox-api.payuni.com.tw/api';
1306
1302
 
1307
- async function payuniPost(path: string, info: Record<string, any>, version = '1.1') {
1303
+ async function payuniPost(path: string, info: Record<string, any>, version: string) {
1308
1304
  const { EncryptInfo, HashInfo } = encryptPAYUNi(info, HASH_KEY, HASH_IV);
1309
1305
  const res = await fetch(`${BASE}${path}`, {
1310
1306
  method: 'POST',
1311
- headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
1307
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'User-Agent': 'payuni' },
1312
1308
  body: new URLSearchParams({ MerID: MER_ID, Version: version, EncryptInfo, HashInfo }),
1313
1309
  });
1314
1310
  const body = await res.json();
1315
- if (!body.EncryptInfo) return body; // 外層錯誤(例如 API00003)
1311
+ if (!body.EncryptInfo) return body;
1316
1312
  const expected = crypto.createHash('sha256').update(HASH_KEY + body.EncryptInfo + HASH_IV).digest('hex').toUpperCase();
1317
1313
  if (expected !== body.HashInfo) throw new Error('HashInfo 驗證失敗');
1318
1314
  return decryptPAYUNi(body.EncryptInfo, HASH_KEY, HASH_IV);
1319
1315
  }
1320
1316
 
1321
- // 7-11 店到店,取貨不付款(StoreID 來自門市地圖 /logistics/ship_map 的回傳)
1322
- const created = await payuniPost('/logistics/trade', {
1317
+ // 超商代碼幕後交易 + 7-11 店到店取貨不付款(StoreID 來自門市地圖)
1318
+ const created = await payuniPost('/cvs', {
1323
1319
  MerID: MER_ID,
1320
+ MerTradeNo: `ORD${Date.now()}`,
1321
+ TradeAmt: 500,
1324
1322
  Timestamp: Math.floor(Date.now() / 1000),
1325
- MerTradeNo: `LOG${Date.now()}`,
1326
- GoodsType: '1', // 1=常溫 2=冷凍
1327
- LgsType: 'C2C', // C2C / B2C
1328
- ShipType: '1', // 1=7-ELEVEN
1329
- TradeAmt: 500, // 取貨不付款時為報值金額
1330
- ServiceType: '3', // 1=取貨付款 3=取貨不付款
1331
- StoreID: '123456',
1323
+ ProdDesc: '商品',
1324
+ UsrMail: 'buyer@example.com', // 有物流時必填,視為收件人信箱
1325
+ ServiceType: '3', // 幕後 API 只支援取貨不付款
1326
+ LgsType: 'C2C', // B2C / C2C / HOME
1327
+ ShipType: '1', // 1=7-ELEVEN 2=黑貓
1328
+ GoodsType: '1', // 1=常溫 2=冷凍 3=冷藏(僅黑貓)
1332
1329
  Consignee: '王小明',
1333
- ConsigneeMail: 'buyer@example.com',
1334
1330
  ConsigneeMobile: '0987654321',
1335
- RefundStoreID: '',
1336
- SenderName: '測試商家',
1337
- SenderMobile: '0912345678',
1338
- NotifyURL: 'https://your-site.com/payuni/shipping-notify',
1339
- });
1340
- // 黑貓宅配改呼叫 /home_delivery/trade,ShipType='2'、LgsType='HOME'、StoreID='',
1341
- // 並加上 ConsigneeAddress、ProdDesc(≤20 字)、DeliveryTimeTag(01 / 02 / 04)
1331
+ StoreID: '916712',
1332
+ }, '1.3');
1333
+ // 黑貓改 LgsType='HOME'、ShipType='2',並帶 ConsigneeAddress、DeliveryTimeTag(01 / 02 / 04)
1342
1334
  console.log(created.Status, created.ShipTradeNo); // ShipTradeNo 是後續查詢、列印、通知的鍵
1343
1335
  ```
1344
1336
 
1337
+ UPP 則在 EncryptInfo 帶 `ShipTag=1`(取貨付款另帶 `Ship=1`)及 `LgsType`、`ShipType`、`GoodsType`、`Consignee`、`ConsigneeMobile`,門市由消費者在支付頁選。
1338
+
1345
1339
  ### 3. Query Shipment
1346
1340
 
1347
1341
  ```typescript
@@ -1350,21 +1344,19 @@ const status = await payuniPost('/logistics/query', {
1350
1344
  Timestamp: Math.floor(Date.now() / 1000),
1351
1345
  LgsType: 'C2C',
1352
1346
  ShipTradeNo: created.ShipTradeNo,
1353
- });
1354
- // status.ShipStatus: 21 待出貨 / 22 物流中心驗收 / 92 寄件門市已收件 / 31 配送中 / 32 待取貨 / 11 已取貨
1347
+ }, '1.1');
1348
+ // ShipStatus 見官方貨態碼:91 未處理、21 待出貨、31 配送中、32 待取貨、11 已取貨、52 買家未取、81 門市關轉…
1355
1349
  console.log(status.ShipStatus, status.ShipStatusDesc, status.Odno);
1356
1350
  ```
1357
1351
 
1358
1352
  ### 4. Status Notification Callback
1359
1353
 
1360
1354
  ```typescript
1355
+ // Notify URL 於 PAYUNi 後台「物流設定」填寫
1361
1356
  app.post('/payuni/shipping-notify', express.urlencoded({ extended: false }), (req, res) => {
1362
1357
  const { EncryptInfo, HashInfo } = req.body;
1363
- // 先驗 HashInfo(官方外掛沒驗,這是疏漏,不要照抄)
1364
- if (HashInfo !== undefined) {
1365
- const expected = crypto.createHash('sha256').update(HASH_KEY + EncryptInfo + HASH_IV).digest('hex').toUpperCase();
1366
- if (expected !== HashInfo) return res.status(400).end();
1367
- }
1358
+ const expected = crypto.createHash('sha256').update(HASH_KEY + EncryptInfo + HASH_IV).digest('hex').toUpperCase();
1359
+ if (expected !== HashInfo) return res.status(400).end();
1368
1360
  const info = decryptPAYUNi(EncryptInfo, HASH_KEY, HASH_IV);
1369
1361
  if (info.Status === 'SUCCESS' && info.ApiType === 'ShipStatus') {
1370
1362
  updateShipment(info.ShipTradeNo, info.ShipStatus, info.ShipStatusDesc, info.ShipStatusTime);
@@ -1515,7 +1507,7 @@ import axios from 'axios';
1515
1507
 
1516
1508
  interface CreateCVSShipmentRequest {
1517
1509
  merTradeNo: string;
1518
- logisticsSubType: 'FAMI' | 'UNIMART' | 'UNIMARTFREEZE' | 'HILIFE' | 'OKMART';
1510
+ logisticsSubType: 'FAMIC2C' | 'UNIMARTC2C' | 'HILIFEC2C' | 'OKMARTC2C';
1519
1511
  goodsAmount: number;
1520
1512
  goodsName: string;
1521
1513
  senderName: string;
@@ -1596,9 +1588,9 @@ class ECPayCVSLogistics extends ECPayLogistics {
1596
1588
 
1597
1589
  // Usage Example
1598
1590
  const logistics = new ECPayCVSLogistics({
1599
- merchantId: '2000132',
1600
- hashKey: '5294y06JbISpM5x9',
1601
- hashIV: 'v77hoKGq4kWxNNIS',
1591
+ merchantId: '2000933', // C2C 測試特店(B2C/宅配為 2000132)
1592
+ hashKey: 'XBERn1YOvpM9nfZc',
1593
+ hashIV: 'h1ONHk4P4yqbl5LK',
1602
1594
  isProduction: false,
1603
1595
  });
1604
1596
 
@@ -1626,11 +1618,7 @@ export { ECPayCVSLogistics };
1626
1618
 
1627
1619
  ```python
1628
1620
  #!/usr/bin/env python3
1629
- """
1630
- Create CVS C2C Shipment - ECPay Python Example
1631
-
1632
- 依照 taiwan-logistics-skill 嚴格規範撰寫
1633
- """
1621
+ """Create CVS C2C Shipment - ECPay Python Example"""
1634
1622
 
1635
1623
  import requests
1636
1624
  import urllib.parse
@@ -1644,7 +1632,7 @@ from dataclasses import dataclass
1644
1632
  class CVSShipmentData:
1645
1633
  """CVS C2C 物流訂單資料"""
1646
1634
  mer_trade_no: str
1647
- logistics_sub_type: Literal['FAMI', 'UNIMART', 'UNIMARTFREEZE', 'HILIFE', 'OKMART']
1635
+ logistics_sub_type: Literal['FAMIC2C', 'UNIMARTC2C', 'HILIFEC2C', 'OKMARTC2C']
1648
1636
  goods_amount: int
1649
1637
  goods_name: str
1650
1638
  sender_name: str
@@ -1673,12 +1661,11 @@ class ECPayCVSLogistics(ECPayLogistics):
1673
1661
  """
1674
1662
  ECPay CVS 超商物流服務
1675
1663
 
1676
- 支援超商類型:
1677
- - FAMI: FamilyMart 全家便利商店
1678
- - UNIMART: 7-ELEVEN 統一超商 (常溫)
1679
- - UNIMARTFREEZE: 7-ELEVEN 統一超商 (冷凍)
1680
- - HILIFE: Hi-Life 萊爾富便利商店
1681
- - OKMART: OK Mart OK 便利商店
1664
+ C2C 店到店子類型(B2C 合約改用 FAMI / UNIMART / UNIMARTFREEZE / HILIFE):
1665
+ - FAMIC2C: 全家店到店
1666
+ - UNIMARTC2C: 7-11 交貨便
1667
+ - HILIFEC2C: 萊爾富店到店
1668
+ - OKMARTC2C: OK 店到店(OK 只有 C2C)
1682
1669
 
1683
1670
  回傳碼:
1684
1671
  - 300: 訂單建立成功 (尚未寄貨)
@@ -1789,9 +1776,9 @@ class ECPayCVSLogistics(ECPayLogistics):
1789
1776
  if __name__ == '__main__':
1790
1777
  # 初始化物流服務 (使用測試環境)
1791
1778
  logistics = ECPayCVSLogistics(
1792
- merchant_id='2000132', # ECPay 測試商店代號
1793
- hash_key='5294y06JbISpM5x9', # ECPay 測試 HashKey
1794
- hash_iv='v77hoKGq4kWxNNIS', # ECPay 測試 HashIV
1779
+ merchant_id='2000933', # ECPay C2C 測試特店(B2C/宅配為 2000132)
1780
+ hash_key='XBERn1YOvpM9nfZc',
1781
+ hash_iv='h1ONHk4P4yqbl5LK',
1795
1782
  is_production=False, # 使用測試環境
1796
1783
  )
1797
1784
 
@@ -1837,7 +1824,7 @@ if __name__ == '__main__':
1837
1824
  ```typescript
1838
1825
  interface CreateHomeShipmentRequest {
1839
1826
  merTradeNo: string;
1840
- logisticsSubType: 'TCAT' | 'ECAN' | 'POST';
1827
+ logisticsSubType: 'TCAT' | 'POST';
1841
1828
  goodsAmount: number;
1842
1829
  goodsName: string;
1843
1830
  senderName: string;
@@ -2538,12 +2525,6 @@ try {
2538
2525
 
2539
2526
  ---
2540
2527
 
2541
- **Total Lines**: 1400+
2542
-
2543
- This comprehensive guide covers all major NewebPay Logistics integration scenarios with production-ready code examples.
2544
-
2545
- ---
2546
-
2547
2528
  ## SmilePay 速買配物流範例
2548
2529
 
2549
2530
  SmilePay 透過 `Pay_zg` 矩陣編碼涵蓋 7-11/全家 + 黑貓三大配送:
@@ -2601,8 +2582,8 @@ SmilePay 透過 `Pay_zg` 矩陣編碼涵蓋 7-11/全家 + 黑貓三大配送:
2601
2582
  ## HCT 新竹物流(直連 carrier API)範例
2602
2583
 
2603
2584
  ⚠️ **先確認你需要的是直連還是 aggregator**:
2604
- - **透過 ECPay/PayNow/SmilePay** 走 HCT 配送 → 用 aggregator 的 `LogisticsType=HCT`,不需要本範例
2605
- - **直接打 HCT 自家系統**(大量出貨、自備站所對接)→ 用本範例,需向 HCT 申請
2585
+ - 本 skill 收錄的聚合商官方規格都沒有新竹物流選項,要用 HCT 只能直連
2586
+ - 直連需向 HCT 申請帳號與金鑰
2606
2587
 
2607
2588
  完整範例見 [`examples/hct-logistics-example.py`](examples/hct-logistics-example.py)。
2608
2589
 
@@ -2644,7 +2625,3 @@ SmilePay 透過 `Pay_zg` 矩陣編碼涵蓋 7-11/全家 + 黑貓三大配送:
2644
2625
  ### 門市代碼
2645
2626
 
2646
2627
  可能四碼或五碼(如 `TFM9771`),且**與門市服務代號不一定相同**。直接把 ezShip 給的值原封回傳即可,不要自行轉換。
2647
-
2648
- ---
2649
-
2650
- **更多範例持續更新中...**
@@ -3,17 +3,17 @@
3
3
  <h3 align="center">台灣物流 AI 開發技能包</h3>
4
4
 
5
5
  <p align="center">
6
- <strong>6 家物流 aggregator + HCT 新竹物流直連 carrier API</strong>
6
+ <strong>7 家物流 aggregator + HCT 新竹物流直連 + 3 家即時配送</strong>
7
7
  </p>
8
8
 
9
9
  <p align="center">
10
- ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · PayNow · HCT 直連
10
+ ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · PayNow · ezShip · HCT 直連 · Lalamove · pandago · Uber Direct
11
11
  </p>
12
12
 
13
13
  <p align="center">
14
14
  <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/v/taiwan-logistics-skill?style=flat-square&logo=npm" alt="npm version"></a>
15
15
  <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/dm/taiwan-logistics-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
16
- <img src="https://img.shields.io/badge/providers-7-success?style=flat-square" alt="7 Providers">
16
+ <img src="https://img.shields.io/badge/providers-11-success?style=flat-square" alt="11 Providers">
17
17
  <img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
18
18
  <a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
19
19
  </p>
@@ -52,17 +52,21 @@ HCT 直連 API 傳入託運資料,逆物流單獨處理
52
52
 
53
53
  ---
54
54
 
55
- ## 7 家物流服務商
55
+ ## 物流服務商
56
56
 
57
57
  | 服務商 | 類型 | 加密 / 認證 | 特色 |
58
58
  |---|---|---|---|
59
- | **ECPay 綠界** | aggregator | MD5 CheckMacValue | 市佔率最高、SDK 完整、7-11/全家/萊爾富/OK/黑貓/宅配通/HCT |
60
- | **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | 7-11/全家/萊爾富/OK/黑貓 |
59
+ | **ECPay 綠界** | aggregator | MD5 CheckMacValue | B2C 7-11(含冷凍)/全家/萊爾富;C2C 四大超商;宅配黑貓/中華郵政 |
60
+ | **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | B2C 僅 7-11;C2C 四大超商;無宅配 |
61
61
  | **PAYUNi 統一** | aggregator | AES-256-GCM + SHA256 | 7-11 常溫/冷凍 + T-Cat 常溫/冷藏/冷凍(溫控配送最完整) |
62
62
  | **SmilePay 速買配** | aggregator | Verify_key + 加權檢核碼 | Pay_zg 矩陣 51/52/55/56/81/82/83,含逆物流 |
63
- | **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、Notify IP 113.196.231.190、4 大超商 |
63
+ | **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、7-11/全家/萊爾富取貨付款 |
64
64
  | **PayNow 立吉富** | aggregator | **3DES/ECB/Zero-Padding** | 11 條產品線(含海外配送);不同於金流端 AES |
65
- | **HCT 新竹物流** | **direct carrier API** | 申請後提供金鑰 | 直連 carrier API(vs 透過 aggregator) |
65
+ | **ezShip 台灣便利配** | aggregator | 無簽章(`su_id` 帳號綁定) | 全家/萊爾富/OK、宅配、店港澳;不含 7-11 |
66
+ | **HCT 新竹物流** | **direct carrier API** | 申請後提供金鑰 | 收錄的聚合商都沒有新竹物流選項,只能直連 |
67
+ | **Lalamove** | 即時配送 | HMAC-SHA256 自簽 | 先報價後下單(報價 5 分鐘效期) |
68
+ | **pandago** | 即時配送 | OAuth 2.0 + RSA 簽 JWT assertion | 同城即時配送 |
69
+ | **Uber Direct** | 即時配送 | OAuth 2.0 client_credentials | 台灣可用性未經官方確認 |
66
70
 
67
71
  ## 技能包內容
68
72
 
@@ -70,19 +74,23 @@ HCT 直連 API 傳入託運資料,逆物流單獨處理
70
74
  taiwan-logistics/
71
75
  ├── SKILL.md # AI 技能主文檔
72
76
  ├── EXAMPLES.md # 實戰範例集
73
- ├── references/ # 7 份 API 規格 (~10,300 行)
77
+ ├── references/ # 各服務商 API 規格
74
78
  │ ├── ecpay-logistics-api.md
75
79
  │ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
76
80
  │ ├── payuni-logistics-api.md
77
- │ ├── smilepay-logistics-api.md # 1,332 行 / Pay_zg 矩陣
78
- │ ├── pchomepay-logistics-api.md # 1,154 行 / NDJSON 對帳 parser
79
- │ ├── paynow-logistics-api.md # 1,670 行 / 11 產品線
80
- │ └── hct-logistics-api.md # 1,102 行 / 直連 HCT
81
+ │ ├── smilepay-logistics-api.md # Pay_zg 矩陣
82
+ │ ├── pchomepay-logistics-api.md # NDJSON 對帳 parser
83
+ │ ├── paynow-logistics-api.md # Logistic_service 產品線
84
+ │ ├── ezship-logistics-api.md
85
+ │ ├── hct-logistics-api.md # 直連 HCT
86
+ │ ├── lalamove-logistics-api.md
87
+ │ ├── ondemand-delivery.md # Lalamove / pandago / Uber Direct
88
+ │ └── carrier-direct-access.md # 無公開 API 的物流業者與替代路徑
81
89
  ├── examples/ # Python 範例
82
- └── data/ # 5 份 CSV
83
- ├── providers.csv # 7 服務商
84
- ├── operations.csv # 30+ API 操作
85
- ├── logistics-types.csv # CVS / Home / 溫控
90
+ └── data/ # search / recommend 使用的 CSV
91
+ ├── providers.csv # 可串接 + 僅供查詢
92
+ ├── operations.csv
93
+ ├── logistics-types.csv # 各家實際參數值(子類型/溫層/代收上限)
86
94
  ├── status-codes.csv # 跨服務商狀態碼
87
95
  └── field-mappings.csv # 欄位對照
88
96
  ```
@@ -99,26 +107,29 @@ taiwan-logistics init --global # 全域安裝
99
107
 
100
108
  ## 14 個 AI 平台支援
101
109
 
102
- Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Roo Code · Gemini · Trae · OpenCode · Continue · CodeBuddy
110
+ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Cline · Gemini · Trae · OpenCode · Continue · CodeBuddy
103
111
 
104
112
  ## 物流類型支援矩陣
105
113
 
106
- | 取貨方式 | 7-11 | 全家 | 萊爾富 | OK | 黑貓 | 海外 | HCT |
107
- |---|---|---|---|---|---|---|---|
108
- | ECPay | ✅ | ✅ | ✅ | ✅ | ✅(常溫) | — | ✅ |
109
- | NewebPay | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
110
- | PAYUNi | ✅ | — | — | — | ✅(常溫/冷凍/冷藏) | — | — |
111
- | SmilePay | ✅ C2C+B2C | ✅ C2C+B2C | — | — | ✅(COD/PICKUP/逆物流) | — | — |
112
- | PChomePay | ✅ | ✅ | ✅ | ✅ | — | — | — |
113
- | PayNow | ✅(含冷凍) | ✅(含冷凍) | ✅ | ✅ | ✅(宅配 + 店到店) | ✅(7-11) | — |
114
- | HCT 直連 | — | — | — | — | — | — | ✅(直連) |
114
+ 依各家官方規格整理,實際參數值見 `data/logistics-types.csv`。
115
+
116
+ | 服務商 | 7-11 | 全家 | 萊爾富 | OK | 黑貓 | 其他 |
117
+ |---|---|---|---|---|---|---|
118
+ | ECPay | B2C(含冷凍)+ C2C | B2C + C2C | B2C + C2C | C2C | 常溫/冷藏/冷凍 | 中華郵政 |
119
+ | NewebPay | B2C + C2C | C2C | C2C | C2C | — | — |
120
+ | PAYUNi | B2C + C2C(常溫/冷凍) | — | — | — | 常溫/冷凍/冷藏 | — |
121
+ | SmilePay | B2C + C2C | B2C + C2C | — | — | 含逆物流 | — |
122
+ | PChomePay | 取貨付款 | 取貨付款 | 取貨付款 | — | — | — |
123
+ | PayNow | B2C + C2C(含冷凍) | B2C + C2C(含冷凍) | C2C | C2C | 宅配、到店 | 7-11 海外 |
124
+ | ezShip | — | C2C | C2C | C2C | — | 宅配、店港澳 |
125
+ | HCT 直連 | — | — | — | — | — | 新竹物流 |
115
126
 
116
127
  ## 相關套件
117
128
 
118
129
  本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
119
130
 
120
- - [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 5 家電子發票
121
- - [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) — 10 家金流
131
+ - [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 7 家電子發票加值中心 + 財政部大平台查詢
132
+ - [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) — 14 家金流
122
133
 
123
134
  ## 授權
124
135