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.
- package/README.md +39 -28
- package/assets/taiwan-logistics/CLAUDE.md +18 -17
- package/assets/taiwan-logistics/EXAMPLES.md +43 -66
- package/assets/taiwan-logistics/README.md +40 -29
- package/assets/taiwan-logistics/SKILL.md +70 -78
- package/assets/taiwan-logistics/data/logistics-types.csv +54 -30
- package/assets/taiwan-logistics/data/operations.csv +11 -11
- package/assets/taiwan-logistics/data/status-codes.csv +496 -6
- package/assets/taiwan-logistics/examples/ecpay-logistics-cvs-example.py +6 -6
- package/assets/taiwan-logistics/examples/ezship-logistics-example.py +52 -30
- package/assets/taiwan-logistics/examples/hct-logistics-example.py +6 -9
- package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py +0 -1
- package/assets/taiwan-logistics/examples/paynow-logistics-cvs-example.py +1 -1
- package/assets/taiwan-logistics/examples/payuni-logistics-cvs-example.py +110 -196
- package/assets/taiwan-logistics/examples/pchomepay-logistics-cvs-example.py +1 -2
- package/assets/taiwan-logistics/examples/smilepay-logistics-cvs-example.py +0 -1
- package/assets/taiwan-logistics/examples/store-map-integration-example.html +3 -3
- package/assets/taiwan-logistics/references/NEWEBPAY_LOGISTICS_REFERENCE.md +1 -7
- package/assets/taiwan-logistics/references/carrier-direct-access.md +2 -3
- package/assets/taiwan-logistics/references/ecpay-logistics-api.md +18 -17
- package/assets/taiwan-logistics/references/ezship-logistics-api.md +20 -10
- package/assets/taiwan-logistics/references/hct-logistics-api.md +1 -4
- package/assets/taiwan-logistics/references/lalamove-logistics-api.md +1 -1
- package/assets/taiwan-logistics/references/ondemand-delivery.md +0 -1
- package/assets/taiwan-logistics/references/paynow-logistics-api.md +2 -5
- package/assets/taiwan-logistics/references/payuni-logistics-api.md +126 -212
- package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +0 -3
- package/assets/taiwan-logistics/references/smilepay-logistics-api.md +0 -3
- package/assets/taiwan-logistics/scripts/core.py +3 -4
- package/assets/taiwan-logistics/scripts/generate-logistics-service.py +70 -1231
- package/assets/taiwan-logistics/scripts/test_logistics.py +108 -262
- package/assets/templates/base/quick-reference.md +41 -33
- package/assets/templates/base/skill-content.md +64 -78
- package/assets/templates/platforms/agent.json +2 -2
- package/assets/templates/platforms/claude.json +2 -2
- package/assets/templates/platforms/cline.json +3 -3
- package/assets/templates/platforms/codebuddy.json +2 -2
- package/assets/templates/platforms/codex.json +2 -2
- package/assets/templates/platforms/continue.json +2 -2
- package/assets/templates/platforms/copilot.json +3 -3
- package/assets/templates/platforms/cursor.json +2 -2
- package/assets/templates/platforms/gemini.json +2 -2
- package/assets/templates/platforms/kiro.json +3 -3
- package/assets/templates/platforms/opencode.json +2 -2
- package/assets/templates/platforms/qoder.json +2 -2
- package/assets/templates/platforms/trae.json +2 -2
- package/assets/templates/platforms/windsurf.json +2 -2
- package/dist/index.js +20 -13
- 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
|
+
<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-
|
|
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
|
-
##
|
|
55
|
+
## 物流服務商
|
|
56
56
|
|
|
57
57
|
| 服務商 | 類型 | 加密 / 認證 | 特色 |
|
|
58
58
|
|---|---|---|---|
|
|
59
|
-
| **ECPay 綠界** | aggregator | MD5 CheckMacValue |
|
|
60
|
-
| **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | 7-11
|
|
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 | 金物流二合一、
|
|
63
|
+
| **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、7-11/全家/萊爾富取貨付款 |
|
|
64
64
|
| **PayNow 立吉富** | aggregator | **3DES/ECB/Zero-Padding** | 11 條產品線(含海外配送);不同於金流端 AES |
|
|
65
|
-
| **
|
|
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/ #
|
|
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 #
|
|
78
|
-
│ ├── pchomepay-logistics-api.md #
|
|
79
|
-
│ ├── paynow-logistics-api.md #
|
|
80
|
-
│
|
|
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/ #
|
|
83
|
-
├── providers.csv #
|
|
84
|
-
├── operations.csv
|
|
85
|
-
├── logistics-types.csv #
|
|
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
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
|
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) —
|
|
121
|
-
- [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) —
|
|
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
|
-
#
|
|
25
|
-
python3 taiwan-logistics/scripts/test_logistics.py [
|
|
24
|
+
# 簽章已知答案 + 測試環境連線(ecpay 另可 --create / --query)
|
|
25
|
+
python3 taiwan-logistics/scripts/test_logistics.py [ecpay|newebpay|payuni]
|
|
26
26
|
|
|
27
|
-
#
|
|
28
|
-
python3 taiwan-logistics/scripts/generate-logistics-service.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 #
|
|
42
|
-
│ ├── pchomepay-logistics-api.md #
|
|
43
|
-
│ ├── paynow-logistics-api.md #
|
|
44
|
-
│
|
|
45
|
-
├──
|
|
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 #
|
|
51
|
+
├── providers.csv # 11 可串接 + 10 僅供查詢(含 doc_access 分級)
|
|
48
52
|
├── operations.csv # cross-provider API operations
|
|
49
|
-
├── logistics-types.csv #
|
|
53
|
+
├── logistics-types.csv # 各家實際參數值(子類型/溫層/代收上限)
|
|
50
54
|
├── status-codes.csv # vendor-specific status codes
|
|
51
|
-
└── field-mappings.csv #
|
|
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
|
-
│
|
|
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
|
-
>
|
|
1271
|
-
>
|
|
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
|
|
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;
|
|
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
|
|
1322
|
-
const created = await payuniPost('/
|
|
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
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
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
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
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
|
-
//
|
|
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
|
-
|
|
1364
|
-
if (
|
|
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: '
|
|
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: '
|
|
1600
|
-
hashKey: '
|
|
1601
|
-
hashIV: '
|
|
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['
|
|
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
|
-
-
|
|
1678
|
-
-
|
|
1679
|
-
-
|
|
1680
|
-
-
|
|
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='
|
|
1793
|
-
hash_key='
|
|
1794
|
-
hash_iv='
|
|
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' | '
|
|
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
|
-
-
|
|
2605
|
-
-
|
|
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
|
+
<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-
|
|
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
|
-
##
|
|
55
|
+
## 物流服務商
|
|
56
56
|
|
|
57
57
|
| 服務商 | 類型 | 加密 / 認證 | 特色 |
|
|
58
58
|
|---|---|---|---|
|
|
59
|
-
| **ECPay 綠界** | aggregator | MD5 CheckMacValue |
|
|
60
|
-
| **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | 7-11
|
|
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 | 金物流二合一、
|
|
63
|
+
| **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、7-11/全家/萊爾富取貨付款 |
|
|
64
64
|
| **PayNow 立吉富** | aggregator | **3DES/ECB/Zero-Padding** | 11 條產品線(含海外配送);不同於金流端 AES |
|
|
65
|
-
| **
|
|
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/ #
|
|
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 #
|
|
78
|
-
│ ├── pchomepay-logistics-api.md #
|
|
79
|
-
│ ├── paynow-logistics-api.md #
|
|
80
|
-
│
|
|
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/ #
|
|
83
|
-
├── providers.csv #
|
|
84
|
-
├── operations.csv
|
|
85
|
-
├── logistics-types.csv #
|
|
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 ·
|
|
110
|
+
Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Cline · Gemini · Trae · OpenCode · Continue · CodeBuddy
|
|
103
111
|
|
|
104
112
|
## 物流類型支援矩陣
|
|
105
113
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
|
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) —
|
|
121
|
-
- [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) —
|
|
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
|
|