A Claude Code Agent Skill for integrating, building, and debugging Taiwan ezPay（簡單行動支付）e-invoice APIs in any language or framework.
English summary — This repository packages production-verified knowledge for integrating Taiwan's
ezPay (簡單行動支付 / 藍新 NewebPay group) electronic invoice (e-invoice, 電子發票) API into any project,
in any language. It covers invoice issue (B2C/B2B), void, allowance (credit note), query,
mobile-barcode & donation-code carrier verification, and invoice-number-track (字軌) management — plus the
AES-256-CBC encryption, CheckValue/CheckCode signing, the store-vs-member dual-key model, every
endpoint's parameters, common error codes (e.g. KEY10002), and a self-contained Python verifier.
Drop it into .claude/skills/ and Claude auto-loads it whenever you work on ezPay invoices.
把「ezPay 電子發票串接」這件事——加解密、簽章、商店/會員雙金鑰、各端點參數、錯誤碼除錯、實機驗證—— 濃縮成一個可被 Claude 自動觸發的 skill。只要你在專案裡跟 Claude 聊到 ezPay 發票，它就會載入這些知識， 不必再從頭啃手冊、也不必重蹈那些「踩過才知道」的坑。
- 涵蓋全部 API：開立發票（B2C/B2B）、觸發開立、作廢發票、開立折讓、觸發確認/取消折讓、作廢折讓、查詢發票、 手機條碼/捐贈碼驗證、字軌管理。
- 語言無關：規格寫到「任何語言都能照著實作」，附 Python 參考實作，可照翻成 Laravel/PHP、Node、Go…。
- 濃縮踩雷點：商店 vs 會員雙金鑰、CheckValue(Key-first) 與 CheckCode(IV-first) 方向相反、
allowanceInvalidcamelCase、折讓參數InvoiceNo、字軌「每期只能一組啟用」的副作用、KEY10002除錯心法… - 可實機驗證：自包含的
ezpay_verify.py，先離線用公開向量驗加密，再用你的金鑰跑端到端 smoke test。
一次講一件事，一張圖一個重點。
不論開立、作廢、折讓還是查詢，每支 API 都是同一件事：你的系統送出一個加密請求、ezPay 回你一個結果。
把要傳的欄位組成明文字串，用 AES-256-CBC 加密、轉成 hex，就是 PostData_。
ezPay 分「商店」與「會員」兩套金鑰。發票與驗證類用商店金鑰，字軌類用會員金鑰，兩把不同。
CheckValue（送出）把 HashKey 放前面；CheckCode（驗回應）把 HashIV 放前面 —— 位置對調，最常踩雷。
開立後可查詢、作廢，或開立折讓（折讓需先確認，之後還能作廢折讓）。
把 ezpay-einvoice/ 整個資料夾複製到你的 Claude Code skills 目錄：
# 專案層級（只在這個專案生效）
cp -r ezpay-einvoice <your-project>/.claude/skills/
# 或個人層級（所有專案都可觸發）
cp -r ezpay-einvoice ~/.claude/skills/重開 Claude Code session 後，跟它聊 ezPay 發票相關需求即會自動觸發。
直接用自然語言交辦，例如：
- 「幫我在 Laravel 串接 ezPay 開立 B2C 發票」
- 「ezPay 開立一直回
KEY10002 解密錯誤，但查詢正常，怎麼回事？」 - 「寫支腳本確認我手上這組 ezPay 測試金鑰通不通」
內含的驗證工具（需 pip install requests pycryptodome）：
cd ezpay-einvoice/scripts
python ezpay_verify.py selftest # 離線：公開向量驗證加密（免金鑰）
cp .env.example .env # 填入你自己的金鑰（勿提交）
python ezpay_verify.py smoke --env .env # 連線：開立→查詢，端到端
python ezpay_verify.py -h # 全部子指令ezPay 會不定期改版手冊。本 skill 依據以下版本整理（驗證日 2026-06-03）：
| 範圍 | 文件版號 |
|---|---|
| 開立/作廢/折讓/查詢 | EZP_INVI_1.2.2 |
| 字軌管理 | EZP_Track_1.0.0 |
| 條碼/捐贈碼驗證 | EZP_BDV_1.0.0 |
使用前請到官方下載頁確認是否有新版，版本不同切勿照舊規格開發：
- 官方文件下載頁（唯一權威來源）：https://inv.ezpay.com.tw/Invoice_index/download
- 詳細的版本漂移檢查清單見
ezpay-einvoice/reference/source-and-versioning.md。
- 本專案為非官方社群整理，與 ezPay／簡單行動支付股份有限公司／藍新 NewebPay 無任何隸屬或背書關係。
- 規格整理自 ezPay 公開技術手冊，僅供開發參考，請一律以官方最新文件為準；發票資料涉及稅務，上線前請與財會人員確認。
- 本專案不含、也不轉散布 ezPay 的 PDF 手冊（著作權屬 ezPay）；請自官方下載頁取得。
- 程式與文件以「現狀（as-is）」提供，不負任何擔保責任。
- 所有金鑰／商店代號一律由使用者自行填入
.env，本 repo 不含任何真實憑證；文中出現的金鑰皆為官方手冊之公開範例。 - 「ezPay」「簡單行動支付」「NewebPay」「藍新」等商標屬各自所有人。
MIT © 2026 Arthur Lai
Keywords / 關鍵字: ezPay, 簡單行動支付, NewebPay, 藍新金流, Taiwan e-invoice, 電子發票, 電子發票 API, 發票串接, einvoice, electronic invoice, fapiao, invoice API, invoice_issue, allowance, 折讓, 作廢, 字軌, 載具, 手機條碼, B2B/B2C 發票, CheckValue, CheckCode, Hash Key/IV, Claude Code, Claude Code skill, Claude agent skill, Anthropic, Laravel, PHP, Python, Node.js, Go.