ezpay-invoice

name: ezpay-invoice description: > ezPay 電子發票（藍新金流 NewebPay 旗下品牌）API 完整技術參考，對應官方文件 EZP_INVI_1.2.1「電子發票技術串接手冊（標準版）」（簡單行動支付股份有限公司， 2021-04-01）。台灣電子發票服務商，涵蓋發票全生命週期：開立發票 （即時 / 等待觸發 / 預約自動，B2C / B2B，invoice_issue）、觸發開立發票 （invoice_touch_issue）、作廢發票（invoice_invalid）、開立折讓 （allowance_issue）、觸發確認 / 取消折讓（allowance_touch_issue）、 作廢折讓（allowanceInvalid）、查詢發票（invoice_search）。包含 AES-256-CBC 加密 PostData_（HashKey 32 bytes / HashIV 16 bytes / PKCS#7 padding / hex 輸出）、回應 CheckCode SHA256 驗證機制、載具類別 （手機條碼 0 / 自然人憑證 1 / ezPay 電子發票載具 2）、捐贈碼 LoveCode、 課稅別 TaxType、零稅率報關標記、含稅 / 未稅金額計算邏輯、完整錯誤碼表、 測試與正式環境 endpoint。Use this skill whenever code or tasks involve ezPay、ezpay、藍新電子發票、電子發票、cinv.ezpay.com.tw、inv.ezpay.com.tw、 開立發票、發票作廢、折讓單、開立折讓、作廢折讓、查詢發票、PostData_、 MerchantID_、CheckCode、HashKey、HashIV、CarrierType、載具、LoveCode、 捐贈碼、TaxType、課稅別、invoice_issue、invoice_touch_issue、 invoice_invalid、allowance_issue、allowance_touch_issue、allowanceInvalid、 invoice_search、e-invoice integration、台灣電子發票串接，或在 zenbu-site apps/api-gateway/src/commerce/ 下整合 ezPay 電子發票開立。 本 SKILL 為唯一官方 API reference 來源——不要再去翻 ezpay.com.tw 官網。

ezPay 電子發票 API

ezPay 電子發票加值服務平台由簡單行動支付股份有限公司（藍新金流 NewebPay 集團旗下品牌）提供，串接台灣財政部電子發票。本文件對應官方手冊 EZP_INVI_1.2.1「電子發票技術串接手冊（標準版）」（2021-04-01），適用範圍為 開立、作廢、折讓、作廢折讓、查詢發票。所有 API 採 HTTP POST + 標準 Form Post（application/x-www-form-urlencoded），編碼 UTF-8，本平台以 Web Service 方式回應 JSON 或 String。本專案 zenbu-site 為 NestJS 11 + TypeORM 0.3 後端，金流 / 第三方整合慣例位於 apps/api-gateway/src/commerce/。

文件範圍說明：EZP_INVI_1.2.1「標準版」只涵蓋上述 7 支 API。 任務中可能提及的「發票列表」「中獎發票查詢」「發票通知」「發票檔案下載」 「熱感應機列印」等功能不在此標準版文件內——本 SKILL 不臆造這些端點。 若需要請另查 ezPay 其他版本文件或洽 ezPay 客服。

環境與認證

測試平台：https://cinv.ezpay.com.tw/   （申請測試會員、建立測試商店、取得 Hash Key/IV）
正式平台：https://inv.ezpay.com.tw/    （申請正式會員、建立商店、取得 Hash Key/IV）

• 測試與正式是不同網域（不像某些服務商共用 URL）。測試走 cinv.ezpay.com.tw， 正式走 inv.ezpay.com.tw。切換環境需同時換「網域 + 商店代號 + HashKey + HashIV」。
• 串接前必須在對應平台：① 申請會員並建立商店、取得商店 API 串接金鑰 HashKey 與 HashIV；② 等平台審核啟用電子發票；③ 在【管理設定／發票字軌號碼設定】 新增發票字軌號碼，才能開始開立。
• 發票資料可登入平台於【銷項發票作業／銷項發票查詢】查看。

串接認證的兩個層級

注意底線：MerchantID_ 與 PostData_ 兩個傳輸參數名稱結尾都有底線 _。 漏掉底線是常見錯誤。

PostData_ 加密規則（AES-256-CBC，最容易出錯）

除 MerchantID_ 外，所有業務欄位先組成 query string，再用 AES 加密：

演算法：AES-256-CBC
金鑰  ：HashKey（商店專屬，長度 32 bytes）
IV    ：HashIV（商店專屬，長度 16 bytes）
Padding：PKCS#7（先補 padding，加密時用 ZERO_PADDING 模式 → 等同自行 PKCS#7）
輸出  ：加密結果轉小寫 hex 字串

加密三步驟：

1. 業務參數組成 query string（http_build_query 風格，值需 url encode）。
2. 對該字串補 PKCS#7 padding（blocksize = 32）。
3. 用 HashKey + HashIV 做 AES-256-CBC 加密（zero padding 模式，因 padding 已自行 補好），結果 bin2hex 轉小寫 hex → 即 PostData_ 的值。

關鍵陷阱：官方 PHP 範例 openssl_encrypt(addpadding($str), 'AES-256-CBC', $key, OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING, $iv) —— 先自行 addpadding 補 PKCS#7，再用 OPENSSL_ZERO_PADDING（告訴 openssl 不要再補）。若直接用 openssl 預設 padding 又自行補一次，會多補一個 block 導致解密錯誤（KEY10002）。

NestJS / TypeScript 加密函式與完整呼叫流程見 references/integration.md。

CheckCode 回應驗證（SHA256）

PostData_ 是 request 端加密；CheckCode 是 response 端驗證——平台回傳的 CheckCode 讓你驗證回應確實來自 ezPay。計算規則（見 references/concepts.md）：

1. 取回應 5 個欄位 InvoiceTransNo / MerchantID / MerchantOrderNo / RandomNum / TotalAmt
2. 依參數名稱 A~Z 排序後用 & 串聯成 query string
3. 前後加上 HashIV 與 HashKey：
   "HashIV=<IV>&" + <排序後字串> + "&HashKey=<Key>"
4. 整串做 SHA256，轉大寫 → 與回應的 CheckCode 比對

API 端點總覽

每支 API 測試 / 正式網域不同，路徑相同。所有 API 的 POST body 都是 MerchantID_ + PostData_ 兩欄。

Version 欄位不可亂填：每支 API 的 PostData_ 內含 Version 欄位有固定值 （見上表）。填錯版本可能回 INV10017（版本不支援混合稅率）等錯誤。

完整逐欄位 request / response 參數表見 references/api-reference.md。

三種開立發票方式

開立發票 invoice_issue 的 Status 欄位決定開立時機：

• 只有 Status=1 即時開立，invoice_issue 回應才會帶 InvoiceNumber。
• Status=0 與 Status=3 的發票，發票號碼要等 invoice_touch_issue 觸發後（或預約日到）才會產生。
• 觸發開立用 InvoiceTransNo（開立時回傳的 ezPay 電子發票開立序號）來指定要觸發哪張。

課稅別、零稅率與金額計算

TaxType 課稅別

開立發票 TaxType（發票層級）：

商品層級 ItemTaxType（僅 TaxType=9 時必填）：1=應稅、2=零稅率、3=免稅， 多項商品以 | 分隔。

稅率 TaxRate

• 應稅：一般稅率帶 5；特種稅率帶實際稅率數字（不含 %，例 18% 帶 18）。
• 零稅率 / 免稅：TaxRate 帶 0。

零稅率報關標記 CustomsClearance

TaxType=2（零稅率）時必須帶 CustomsClearance：1=非經海關出口、2=經海關出口。

含稅 / 未稅金額（順序敏感）

核心規則由 Category 決定 ItemPrice / ItemAmt 是含稅或未稅：

開立發票需自行算出並傳入 Amt（銷售額未稅）、TaxAmt（稅額）、TotalAmt（含稅總額）：

TotalAmt = Amt + TaxAmt          # 平台檢核：銷售額 + 稅額 = 發票金額
ItemAmt  = ItemCount * ItemPrice # 平台檢核：數量 × 單價 = 小計

# TaxType=9 混合稅率時：
Amt = AmtSales + AmtZero + AmtFree   # Amt 為三者合計

平台金額檢核範圍（依文件「其他說明」）：

• 開立發票只檢核「商品小計 = 商品數量 × 商品單價」與「發票金額 = 銷售額 + 稅額」。
• 開立折讓只檢核「折讓總金額 = 折讓商品小計 + 折讓商品稅額」。
• 發票金額計算方式請務必與公司財會人員確認——發票資料關係公司稅務。

金額計算的完整範例見 references/api-reference.md「金額計算」章節。

載具與捐贈

開立 B2C 發票（Category=B2C）時，依財政部規定須讓買受人擇一：存載具、捐贈、 或索取紙本。

載具 CarrierType / CarrierNum

• CarrierType 有值時 CarrierNum 必填，且 LoveCode 必為空（載具與捐贈互斥）。
• CarrierNum 須用 rawurlencode() encode，且值前後不得含空白。
• ezPay 電子發票載具（CarrierType=2）不需事先申請，由賣方統編 + 買受人代號 組成載具號碼；同一統編下相同代號視為同一買受人。

捐贈碼 LoveCode

• LoveCode：3~7 碼純數字，受贈單位的愛心碼（財政部清單內有效碼）。
• 僅 Category=B2C 適用；有值時 CarrierType 必為空。

索取紙本 PrintFlag

• PrintFlag=Y 索取紙本（營業人可於平台列印）；PrintFlag=N 不索取。
• Category=B2B → PrintFlag 必填 Y。
• Category=B2C 且 CarrierType、LoveCode 皆空 → PrintFlag 必填 Y。
• PrintFlag=Y 時回應才會帶 BarCode / QRcodeL / QRcodeR。

回應格式

回應格式由 PostData_ 內的 RespondType 決定：

• Status=SUCCESS 代表成功；失敗時 Status 為錯誤代碼（見 references/error-codes.md）。
• JSON 模式：成功業務資料在 Result 欄位（是字串，需 JSON.parse 再取）。
• String 模式：所有欄位平鋪在 query string，必須驗證 EndStr=## 確保傳輸完整。

重要：開立發票回 Status=SUCCESS 只代表「ezPay 平台收件並處理成功」， 不代表已上傳財政部成功。上傳財政部是非同步流程——平台每日 01:00 起上傳 前一日資料，06:00 起更新上傳結果。真正上傳狀態要靠 invoice_search 查 UploadStatus 欄位（0 未上傳 / 1 已上傳成功 / 2 上傳中 / 3 上傳失敗 / 4 上傳逾時）。

重送冪等性

開立發票 MerchantOrderNo（自訂編號）同一商店內不可重覆。若用完全相同的 PostData_ 重送，平台會回傳原本那張發票的 Result（Status=SUCCESS），不會重複 開立——但若 MerchantOrderNo 重覆而其他欄位不同，會回 LIB10003（自訂編號重覆）。

作廢與折讓的業務規則

作廢發票（invoice_invalid）

• 作廢期限：於奇數月 14 日前，可作廢前兩個月開立的發票（例：7/14 前可作廢 5/1–6/30 開立的發票）。超期回 LIB10008。
• 不可作廢的情況：
  • 已開過折讓的發票無法作廢（須先作廢折讓）→ LIB10007。
  • 已開立但尚未上傳財政部的發票無法作廢 → LIB10009。
  • 上傳失敗的發票不得作廢 → INV70002。
  • 已作廢過 → LIB10005。

折讓流程（兩段式）

開立折讓 allowance_issue 的 Status 欄位：

• Status=0 的折讓，營業人與買受人確認後，需再呼叫 allowance_touch_issue：
  • AllowanceStatus=C → 確認折讓（隔日上傳財政部）。
  • AllowanceStatus=D → 取消折讓（折讓狀態變更為取消）。
  • 已確認的折讓無法再取消。
• 作廢折讓 allowanceInvalid 只能作廢已確認的折讓。

折讓金額（ItemTaxAmt 邏輯）

折讓商品單價 ItemPrice 可為未稅或含稅：

• ItemPrice 為未稅金額 → ItemTaxAmt（折讓商品稅額）= 小計 × 稅率。
• ItemPrice 為含稅金額 → ItemTaxAmt = 0（申報時無法扣抵該項營業稅額）。
• 平台檢核：TotalAmt（折讓總金額）= 折讓商品小計合計 + 折讓商品稅額合計。
• 請與會計人員確認採未稅或含稅。

整合工作流程（典型電商）

1. 結帳完成 → 後端組業務參數（ItemName/Count/Unit/Price/Amt 多項用 | 分隔）
2. 算 Amt / TaxAmt / TotalAmt；決定 Category（B2B/B2C）、載具 / 捐贈 / 紙本（互斥）
3. 組 query string → PKCS#7 padding → AES-256-CBC 加密 → hex → PostData_
4. POST {MerchantID_, PostData_} 到 /Api/invoice_issue
5. 回 Status=SUCCESS → parse Result → 存 InvoiceTransNo / InvoiceNumber / RandomNum
6. 驗證回應 CheckCode（SHA256）確認來源
7. （非同步）需要時呼叫 /Api/invoice_search 查 UploadStatus 確認財政部上傳結果
8. 退貨 → /Api/allowance_issue 開折讓（必要時 /Api/allowance_touch_issue 確認）
9. 整張取消 → /Api/invoice_invalid 作廢（須在期限內、未開過折讓、已上傳財政部）

NestJS service pattern、AES 加密實作、輪詢策略見 references/integration.md。

禁止事項與常見陷阱

• ❌ 不要漏掉傳輸參數的底線——是 MerchantID_ 與 PostData_，不是 MerchantID / PostData。
• ❌ 不要混淆測試 / 正式網域——測試 cinv.ezpay.com.tw、正式 inv.ezpay.com.tw。
• ❌ 不要弄錯 AES padding——先自行補 PKCS#7（blocksize 32），加密時用 zero padding 模式； 重複補或不補都會 KEY10002（資料解密錯誤）。
• ❌ 不要填錯 Version——每支 API 的 PostData_ 內 Version 有固定值（issue 1.5 / touch 1.0 / invalid 1.0 / allowance_issue 1.3 / allowance_touch 1.0 / allowanceInvalid 1.0 / search 1.3）。
• ❌ B2C 與 B2B 的 ItemPrice / ItemAmt 金額性質不同——B2C 含稅、B2B 未稅，弄反金額會錯。
• ❌ 載具與捐贈互斥——CarrierType 有值時 LoveCode 必空，反之亦然。
• ❌ Category=B2C 且選紙本時不可帶載具 / 捐贈；PrintFlag 在 B2B 或 B2C 無載具無捐贈時必填 Y。
• ❌ 不要假設 Status=SUCCESS = 財政部上傳成功——要查 invoice_search 的 UploadStatus。
• ❌ MerchantOrderNo 同商店不可重覆——重覆且內容不同回 LIB10003。
• ❌ 不要對已開折讓 / 未上傳財政部 / 跨期的發票作廢（各有專屬錯誤碼）。
• ❌ String 回應模式必須驗 EndStr=##，否則無法確保資料完整。
• ❌ CarrierNum 須 rawurlencode，前後不得有空白。

Reference 檔案導覽