ezpay-einvoicelisted

# ezPay 電子發票串接 協助在任何專案／語言實作 ezPay（簡單行動支付）電子發票串接，並提供可實機驗證的工具。 這份 skill 把「手冊不會明講、或前後矛盾、踩過才知道」的知識濃縮下來，讓你不必重新考古。 ## 整合模型速覽 - **傳輸**：HTTP 標準 Form POST，UTF-8，平台以 Web Service 回應。 - **環境**：測試 `https://cinv.ezpay.com.tw`、正式 `https://inv.ezpay.com.tw`（同一套 API、換網址與金鑰）。 - **加密**：商業欄位組成 query string → **AES-256-CBC（PKCS7）** → 小寫 hex，放入 `PostData_`。 - **簽章**：`CheckValue`（送出，BDV 才需要）與 `CheckCode`（驗回應）皆 SHA256 大寫，但**夾 Key/IV 的順序相反**。 - **雙金鑰**：發票/BDV 用「商店金鑰」搭 `MerchantID_`；字軌用「會員金鑰」搭 `CompanyID_`，**兩把不同**。 - **回應**：發票/字軌類 `Result` 是明文 JSON；BDV 類 `Result` 是 AES 加密 hex，需解密。 > ⚠️ 機敏資訊：本 skill **不含任何真實金鑰／商店代號**。所有密鑰一律由使用者填入專案的 `.env`， > 程式只從環境讀取、絕不寫死、絕不進版控。唯一出現的金鑰是手冊「公開範例向量」，僅供離線自我測試。 ## 來源與版本時效性（務必先確認） - **官方文件下載頁（唯一權威來源）**：https://inv.ezpay.com.tw/Invoice_index/download ezPay 會不定期改版手冊，**本 skill 的規格不保證永遠最新**。 - **本 skill 依據的手冊版本**（驗證日期 **2026-06-03**，測試環境實機跑綠）： - 開立／作廢／折讓／查詢：`EZP_INVI_1.2.2`（最後異動 2024-04-22） - 字軌管理：`EZP_Track_1.0.0`（2018-10-03） - 手機條碼／捐贈碼驗證：`EZP_BDV_1.0.0`（2021-02） - **動手前先做版本檢查**：到上方下載頁取得最新手冊、比對文件版號。 - 版號相同 → 可直接信任本 skill。 - 版號較新 → **切勿照舊規格開發**。先看手冊開頭「版本異動」表，針對變動章節重新核對 端點／Version／參數，更新 `reference/` 後再進行。 - 加解密與簽章邏輯（`crypto.md`）歷來穩定，`selftest` 仍可先驗；但**端點與參數最易隨版本變動**。 - 詳細的版本對照與漂移檢查清單見 `reference/source-and-versioning.md`。 ## 建置工作流 照這個順序走，能最快做出可驗證的串接： 1. **確認範圍**：問清楚要哪些功能（開立？作廢？折讓？查詢？條碼/捐贈碼驗證？字軌？）與目標語言/框架。 各功能的端點、版本號、必填參數見 `reference/api-reference.md`。 2. **備妥金鑰到 `.env`**（請使用者提供，勿寫死）。最多會用到這 6 個值： ``` EZPAY_BASE_URL=https://cinv.ezpay.com.tw