moksa1123/taiwan-ecommerce-toolkit

Taiwan E-Commerce Integration Toolkit

台灣電商整合開發工具包

電子發票 · 金流串接 · 物流整合

---

專案概覽

Taiwan E-Commerce Toolkit 是專為台灣電商生態系統設計的企業級整合開發工具包，提供完整的電子發票、金流串接、物流整合解決方案。本工具包收錄台灣三大領域共 34 個服務商（9 家發票 + 14 家金流 + 11 家可串接物流），另收錄 10 家無法直接串接的物流業者與其替代路徑，搭配智能開發工具與生產級程式碼範例，協助開發團隊快速完成電商系統整合。

最新版本（請以 npm 為準）：

• [email protected]+ — 9 家發票（ECPay / SmilePay / Amego / ezPay / PayNow / O’Pay / SunPay / 財政部大平台 / 關貿）
• [email protected]+ — 14 家金流（ECPay / NewebPay / PAYUNi / SmilePay / PChomePay / ezPay / PayNow / Shopline / LINE Pay / TapPay / O’Pay / 街口 / 紅陽 / GoMyPay）
• [email protected]+ — 11 家可串接物流（7 aggregator + HCT 直連 + 3 家即時配送）＋ 10 家僅供查詢

發票的兩個例外：財政部大平台是上游，只做查詢／驗證（手機條碼、載具、捐贈碼），不能開立發票；關貿網路已收錄於資料層，但文件需簽約，尚無 reference。

物流的「僅供查詢」是什麼：黑貓、嘉里大榮、宅配通、中華郵政、7-11 交貨便、全家好賣+、萊爾富、OK、蝦皮店到店都沒有對外商家 API，只能經聚合商。這些在 providers.csv 標為 api_available=false 並附替代路徑，避免誤以為可直連；紅陽物流的參數規格尚未公開，同樣標為 false。

狀態: Production Ready · MIT 授權

安裝舊版會看到 npm deprecation 提示（55 個舊版已 deprecated）— 請以 npm shield 上的 latest 版本為準。

---

快速開始

Step 1: 安裝 CLI 工具

# 依需求選擇安裝 (擇一或全裝)
npm install -g taiwan-invoice-skill     # 電子發票
npm install -g taiwan-payment-skill     # 金流串接
npm install -g taiwan-logistics-skill   # 物流整合

Step 2: 初始化專案

# 進入你的專案目錄
cd /path/to/your/project

Step 3: 開始使用

初始化完成後，啟動你的 AI 助手，直接用自然語言描述需求：

使用綠界測試環境產生 B2C 發票開立程式碼，金額 1050 元

建立 ECPay 信用卡付款訂單，交易金額 2500 元

查詢台北市信義區的 7-11 超商取貨點資訊

---

核心特色

企業級程式碼標準

所有程式碼範例均達到生產環境品質標準：

• 完整型別定義 - Python Dataclass 搭配 Literal、Optional、Dict 型別提示
• 專業文件規範 - 詳細的 Docstring 文件 (Args/Returns/Raises/Example)
• 嚴謹錯誤處理 - 系統化錯誤分類與自動重試機制
• 實戰測試憑證 - 包含測試環境憑證，可直接執行驗證
• 可維護架構 - 遵循 SOLID 原則，易於擴展與維護

BM25 智能搜尋引擎

採用 BM25 演算法實作的語義搜尋系統，支援跨領域智能查詢：

# 錯誤碼查詢
python scripts/search.py "10000009" --domain error

# 欄位映射搜尋
python scripts/search.py "CheckMacValue" --domain field

# 稅務規則查詢
python scripts/search.py "B2B 稅額計算" --domain tax

智能推薦系統

基於關鍵字權重與 BM25 評分的服務商推薦引擎：

# 發票加值中心推薦
python taiwan-invoice/scripts/recommend.py "電商平台 高交易量 系統穩定"

# 金流平台推薦
python taiwan-payment/scripts/recommend.py "整合簡單 快速上線 多元支付"

# 物流服務推薦
python taiwan-logistics/scripts/recommend.py "超商取貨 溫控配送 冷凍宅配"

自動化程式碼生成器

支援 TypeScript 與 Python 雙語言輸出的程式碼生成工具：

# 生成發票服務模組
python taiwan-invoice/scripts/generate-invoice-service.py ECPay --lang typescript --output ./services

# 生成物流服務模組
python taiwan-logistics/scripts/generate-logistics-service.py PAYUNi --output ts

資料驅動架構

採用 CSV 檔案管理核心數據，便於維護與更新：

• providers.csv - 服務商比較資訊
• operations.csv - API 端點定義
• error-codes.csv - 錯誤碼對照表
• field-mappings.csv - 欄位映射關係
• tax-rules.csv - 稅務計算規則

系統化錯誤處理

完整的錯誤處理機制與自動重試策略：

• 錯誤分類 - 6 大類別 (驗證/認證/權限/業務邏輯/網路/伺服器)
• 自動重試 - 4 種重試策略 (NO_RETRY/IMMEDIATE/EXPONENTIAL_BACKOFF/LINEAR_BACKOFF)
• 智能建議 - 針對性錯誤解決方案
• 詳細日誌 - 完整的錯誤追蹤記錄

---

專案結構

taiwan-ecommerce-toolkit/
├── README.md                      # 本文件 (總覽)
├── LICENSE                        # MIT 授權
├── CLAUDE.md                      # Claude Code 專案指引
│
├── taiwan-invoice/                # 電子發票核心內容 (Source of Truth)
│   ├── README.md                  # 發票專案說明
│   ├── SKILL.md                   # AI 技能文檔
│   ├── EXAMPLES.md                # 程式碼範例
│   ├── references/                # API 文件
│   ├── examples/                  # 生產級 Python 範例
│   ├── scripts/                   # Python 智能工具
│   └── data/                      # CSV 數據檔
│
├── taiwan-payment/                # 金流整合核心內容 (Source of Truth)
│   ├── README.md                  # 金流專案說明
│   ├── SKILL.md                   # AI 技能文檔
│   ├── EXAMPLES.md                # 程式碼範例
│   ├── references/                # API 文件
│   ├── examples/                  # 生產級 Python 範例
│   ├── scripts/                   # Python 智能工具
│   └── data/                      # CSV 數據檔
│
├── taiwan-logistics/              # 物流串接核心內容 (Source of Truth)
│   ├── README.md                  # 物流專案說明
│   ├── SKILL.md                   # AI 技能文檔
│   ├── EXAMPLES.md                # 程式碼範例
│   ├── references/                # API 文件
│   ├── examples/                  # 生產級 Python 範例
│   ├── scripts/                   # Python 智能工具
│   └── data/                      # CSV 數據檔
│
├── invoice-cli/                   # 發票 CLI (npm: taiwan-invoice-skill)
│   ├── src/                       # TypeScript 源碼
│   ├── assets/                    # 打包資源
│   └── dist/                      # 編譯輸出
│
├── payment-cli/                   # 金流 CLI (npm: taiwan-payment-skill)
│   ├── src/                       # TypeScript 源碼
│   ├── assets/                    # 打包資源
│   └── dist/                      # 編譯輸出
│
└── logistics-cli/                 # 物流 CLI (npm: taiwan-logistics-skill)
    ├── src/                       # TypeScript 源碼
    ├── assets/                    # 打包資源
    └── dist/                      # 編譯輸出

---

廠商整合支援

電子發票 (7 家加值中心 + 財政部大平台)

金流串接平台 (14 家)

物流串接服務 (11 家：7 aggregator + HCT 直連 + 3 即時配送)

---

多平台支援

支援 14 種 AI 編碼助手平台，涵蓋主流開發工具：

---

CLI 指令

共通指令

# 列出支援平台
taiwan-invoice list
taiwan-payment list
taiwan-logistics list

# 顯示技能資訊
taiwan-invoice info
taiwan-payment info
taiwan-logistics info

# 檢查更新
taiwan-invoice update
taiwan-payment update
taiwan-logistics update

# 覆蓋安裝
taiwan-invoice init --force
taiwan-payment init --force
taiwan-logistics init --force

---

Python 範例程式

電子發票範例

生產級 ECPay 發票整合實作：

• ecpay-invoice-example.py
  • B2C 二聯式發票開立
  • B2B 三聯式發票開立
  • 發票作廢 (void_invoice)
  • 發票折讓 (issue_allowance)
  • AES-128-CBC 完整加解密
  • B2B 金額自動計算 (含稅轉未稅+稅額)

金流串接範例

完整的金流整合實作，遵循企業級開發規範：

• ecpay-payment-example.py - ECPay 金流整合 (信用卡、ATM、超商代碼)
• newebpay-payment-example.py - NewebPay MPG 整合 (多元支付)
• payuni-payment-example.py - PAYUNi 統一金流 (RESTful API)

物流串接範例

完整的超商物流 (CVS) 與宅配整合實作：

• ecpay-logistics-cvs-example.py - 綠界 C2C 物流
• newebpay-logistics-cvs-example.py - 藍新超商物流
• payuni-logistics-cvs-example.py - 統一超商物流
• store-map-integration-example.html - 門市地圖整合

程式碼規範

所有範例皆包含：

• 完整的 Dataclass 資料結構定義
• 詳細的型別提示 (Literal, Optional, Dict[str, any])
• 專業的 Docstring 說明文件
• 完善的錯誤處理機制與中文錯誤訊息
• 測試環境憑證與使用範例
• 可直接用於生產環境的程式碼品質

---

智能開發工具

所有工具皆採用純 Python 實作，無需安裝外部依賴套件。

BM25 搜尋引擎

# 電子發票錯誤碼查詢
python taiwan-invoice/scripts/search.py "10000009" --domain error

# 金流欄位映射查詢
python taiwan-payment/scripts/search.py "CheckMacValue" --domain field

# 物流 API 端點查詢
python taiwan-logistics/scripts/search.py "查詢物流狀態" --domain operation

服務商推薦系統

# 電子發票加值中心推薦
python taiwan-invoice/scripts/recommend.py "電商平台 高交易量 系統穩定"

# 金流平台推薦
python taiwan-payment/scripts/recommend.py "整合簡單 快速上線"

# 物流服務推薦
python taiwan-logistics/scripts/recommend.py "超商取貨 溫控配送"

程式碼生成器

# 產生發票服務模組
python taiwan-invoice/scripts/generate-invoice-service.py ECPay --lang typescript --output ./services

# 產生物流服務模組
python taiwan-logistics/scripts/generate-logistics-service.py PAYUNi --output ts

系統化錯誤處理

from error_handler import InvoiceErrorHandler, retry_on_error

# 查詢錯誤資訊
handler = InvoiceErrorHandler(provider='ecpay')
info = handler.get_error_info('10000009')
print(info.suggestion)

# 自動重試裝飾器
@retry_on_error(max_retries=3, backoff_factor=2)
def issue_invoice(data):
    # 失敗時自動重試 3 次 (1s, 2s, 4s 間隔)
    pass

---

常見問題

---

技術規格

系統需求

• Node.js: >= 18.0.0 (CLI 工具)
• Python: >= 3.8 (範例程式與智能工具)
• TypeScript: >= 5.0 (程式碼生成器輸出)

Python 依賴

# 範例程式所需依賴
pip install pycryptodome requests

# 智能工具無需外部依賴 (純 Python 標準庫)

支援的加密方式

---

開發與貢獻

Git 工作流程

# 1. Clone 專案
git clone https://github.com/Moksa1123/taiwan-ecommerce-toolkit.git
cd taiwan-ecommerce-toolkit

# 2. 建立功能分支
git checkout -b feat/your-feature

# 3. 修改對應的核心內容目錄
# - taiwan-invoice/     (發票相關)
# - taiwan-payment/     (金流相關)
# - taiwan-logistics/   (物流相關)

# 4. 同步到 CLI assets (發布前)
cp -r taiwan-invoice/* invoice-cli/assets/taiwan-invoice/
cp -r taiwan-payment/* payment-cli/assets/taiwan-payment/
cp -r taiwan-logistics/* logistics-cli/assets/taiwan-logistics/

# 5. 提交變更
git add .
git commit -m "feat: description"
git push -u origin feat/your-feature

# 6. 建立 Pull Request
gh pr create

發布流程 (維護者)

發布由 GitHub Actions 於 tag 推送時觸發，不需手動 npm publish。完整說明見 RELEASING.md。

# 1. 更新版本號（assets 同步已由 build 自動處理，不需手動 cp）
cd payment-cli && npm version minor --no-git-tag-version && cd ..

# 2. 本機驗證
node scripts/sync-assets.mjs          # 同步 assets
python scripts/validate-data.py       # CSV 完整性
python taiwan-payment/scripts/test_recommend.py

# 3. commit 後打 tag 觸發發布
git add -A && git commit -m "chore(payment): bump to 1.4.0" && git push
git tag payment-v1.4.0 && git push origin payment-v1.4.0

tag 前綴決定發布哪個套件：invoice-v* / payment-v* / logistics-v*。 workflow 會驗證 tag 版號與 package.json 一致、assets 已同步、資料檔完整、回歸測試通過，任一不過即中止發布。

使用者安裝流程

# 1. 全域安裝 CLI 工具
npm install -g taiwan-invoice-skill
npm install -g taiwan-payment-skill
npm install -g taiwan-logistics-skill

# 2. 進入專案目錄
cd /path/to/your/project

# 3. 初始化技能檔案 (選擇 AI 平台)
taiwan-invoice init --ai claude
taiwan-payment init --ai claude
taiwan-logistics init --ai claude

# 4. 啟動 AI 助手，開始使用
# Claude Code: 直接描述需求或使用 /taiwan-invoice
# Cursor: 使用 /taiwan-invoice 斜線命令
# Windsurf: 自動載入，直接描述需求

---

授權

MIT License

---

相關連結

• Taiwan Invoice Skill - 電子發票完整文件
• Taiwan Payment Skill - 金流整合完整文件
• Taiwan Logistics Skill - 物流串接完整文件
• NPM: taiwan-invoice-skill
• NPM: taiwan-payment-skill
• NPM: taiwan-logistics-skill
• GitHub Repository

---

Made by Moksa [email protected]