電子發票串接
電子發票相關 API 參數有哪些？
電子發票主要 API 參數參考：
| 參數名稱 | 說明/用途 |
|---|---|
| issue_invoice_state | 是否開立發票: 0否/1開立 |
| invoice_input_type | 發票開立類型: 1雲端/2愛心碼/3B2B |
| invoice_ratetype | 稅率別: 0應稅5%，1零稅率，2免稅 |
| invoice_b2b_title | 公司抬頭（B2B時必填） |
| invoice_b2b_id | 公司統編（B2B時必填） |
| invoice_mobile_code | 手機條碼載具 |
| invoice_natural_person | 自然人憑證條碼 |
| invoice_love_code | 愛心碼（捐贈發票） |
| items | 商品明細陣列，建議含折扣、運費項目 |
| invoice_cloud_type | 雲端發票載具類型，如1、2、3（條碼/自然人等） |
* 電子發票串接的相關更新，請以技術文件為準：
發票地址、抬頭可否異動？
發票張數是否有控管？
電子發票開立類型（invoice_input_type）代表什麼？
金流退款時如何處理電子發票？
電子發票怎麼設定折扣或運費資訊？
串接時必填的電子發票參數有哪些？
必填參數視開立類型而定，主要有：
- invoice_input_type（發票開立類型，1: 雲端發票、2:愛心碼、3: B2B發票）
- invoice_ratetype（發票稅率別，0:應稅5%…）
- 發票載具條碼（雲端、愛心碼、自然人憑證、手機條碼等）
- invoice_b2b_title、invoice_b2b_id、invoice_b2b_address（B2B時必填）
- invoice_mobile_code、invoice_natural_person（載具條碼/自然人憑證）
電子發票可否與金流交易同時發動？
如何做發票折讓串接？
發票折讓（部分退貨/退款的電子發票折讓）操作，需走「交易退款」API 模式，並透過適當資料欄位組合來指定折讓明細。折讓的重點是針對原訂單部分金額進行退款並註記折讓，系統將自動處理電子發票折讓流程。
發票折讓串接流程
- 串接路徑：特約商店 Store 模式用 https://ka.usecase.cc/api/init，經銷商 Agent 模式用 https://ka.usecase.cc/api/agent。
- 條件：必須基於原交易訂單，發送「api/refund」命令。
POST資料結構
- 帶入原訂單的 uid（MYPAY 交易流水號）、key（交易驗證碼）。
- 設定 refund 金額（cost，為折讓金額）。
- 設定 invoice_state = 6（狀態：6 表折讓）。
- 在 items 欄位中明確列出本次折讓的商品明細（如部分退款時僅列部分商品或數量）。
工作流程與注意事項
系統接收到退款申請後，判斷 invoice_state=6，將自動執行電子發票折讓作業。若折讓部分商品或金額，items必須僅列出折讓內容（部分退貨時不宜全部商品都列）。折讓紀錄會同步於查詢API中顯示，並可於管理後台查驗折讓結果。如何做發票作廢串接？
發票作廢的串接主要是透過「交易退款」API，並以特定欄位 invoice_state 設值為 4 來表示發票作廢（註銷）。特約商店、經銷商兩種模式發票作廢串接的差異主要在 API 位址及驗證身份欄位，整體流程與欄位結構相似：
兩模式主要差異在參數中是否帶入 agent_uid，以及 API 基本路徑不同，但使用的命令與參數結構一致，均以 api/refund 串接，invoice_state=4 指示發票作廢。
如何作廢發票？
發票作廢操作（即「發票折讓」與「發票註銷」），流程需依照訂單建立後的退款或折讓動作完成。作廢發票的正確步驟是利用「交易退款」API，並在資料結構中設定發票處理參數。
發票作廢操作說明
- 必須針對原交易訂單發動退款，API 路徑特約商店 Store 模式為 https://ka.usecase.cc/api/init，經銷商 Agent 模式為 https://ka.usecase.cc/api/agent，並呼叫 cmd = "api/refund"。
- 在 postData 欄位中，帶入原訂單的「uid」（MYPAY交易流水號）以及「key」（交易驗證碼），並且在退款資料裏設定 invoice_state 或相關欄位，表明此次退款屬於「發票作廢」情境。
- 退款單內容必須包含原發票明細（商品資訊、售價等），否則作廢流程無法完整，目前參考範例可設定成：
- invoice_state = 4（狀態：4 表作廢）
- 退款商品資訊於 items 內正確標明。
注意事項
- 只有成功完成退款動作，才會觸發發票作廢（折讓）流程。
- 若原發票有折讓或其他特殊處理，需依照 API 文件的「發票作廢/折讓」設定所有必要參數，否則系統不會正確註記作廢。
- 作廢僅對「未作廢」發票有效，不得重複註銷同一張發票。
如何發動發票折讓？
發動發票折讓的方式本質上類似，都是透過「交易退款（api/refund）」API發起折讓請求，但特約商店、經銷商兩模式在使用身分、API介接端點、必要參數等細節上有差異：
發票折讓發動方法（共通點）
- 折讓由「交易退款 API」發起，帶入折讓相關參數（invoice_state 指定為折讓狀態，退款商品明細 items 須與原發票相符）
- 送出資料前需以 AES 256 加密，並以 HTTPS POST 送出
- 發票折讓資料由系統送至財政部電子發票平台完成折讓作業
- 折讓金額與商品明細需與交易、發票一致，支持部分折讓
特約商店 vs 經銷商差異點
| 項目 | 特約商店串接 | 經銷商串接 |
|---|---|---|
| API介接網址 | https://ka.mypay.tw/api/init | https://ka.mypay.tw/api/agent |
| 證書授權及金鑰 | 特約商店專屬 | 經銷商專屬，可代特約商店作業 |
| 交易欄位中 | store_uid 等特約商店資訊 | 需有 agent_uid（經銷商商務代號）及 store_uid |
| API請求格式 | POST x-www-form-urlencoded 加密資料 | POST x-www-form-urlencoded 加密資料 |
| 系統身份與權限 | 以特約商店直接發動 | 以經銷商身分代發特約商店訂單交易 |
| 發票折讓細節帶入 | invoice_state、items 等折讓欄位 | 同上，必須指定正確身分參數 |
| 回報與監控 | 交易回報及發票狀態連動通知 | 同上，並可透過經銷商後台管理 |
結論
- 兩者發動折讓流程原理一致，均透過「交易退款 API」帶入折讓資料發起請求，且均需要加密與 HTTPS 連線安全保護
- 經銷商串接多了 agent_uid 欄位，需要使用經銷商身份金鑰與介接端點，且可代替特約商店執行折讓
- 特約商店則直接使用 store_uid 及其金鑰介接官方 API 端點
- 開發時需根據串接身分取用正確API端點與認證資訊，折讓參數與資料格式本質無異
總之，特約商店與經銷商在技術發動發票折讓的方式上是同源的流程，差別在於 API 介接身分與端點配置，發票折讓參數使用方式是一致的。
如何知道剩下幾張電子發票號碼？
可以透過 MYPAY 交易查詢 API，查詢剩餘可用電子發票號碼數量。實際操作是在呼叫「交易查詢」時，系統回傳結果中會包含 invoice_count 欄位，其值即代表目前專戶剩下的可用電子發票張數。
查詢方式與必備欄位
- 特約商店（Store 模式）需以交易查詢 API（api/queryorder）發送查詢，必要參數為「uid」（交易流水號）與「key」（驗證碼）。
- 經銷商（Agent 模式）同樣以交易查詢 API（api/queryorder）查詢，必須帶入「uid」及「key」參數。
回傳資料解析
- 查詢回傳資料中，invoice_count 字段會回傳剩餘電子發票號碼，文件說明：「發票剩餘張數,只有打 ka.usecase.cc 和 ka.mypay.tw 才有」。
- 若發票庫存不足，系統將拒絕開立交易，需確保此欄位值大於零方可順利開立新發票。
注意事項
- invoice_count 僅於指定 MYPAY 交易查詢介面 (ka.usecase.cc 和 ka.mypay.tw) 才會有此欄位。
- 不同帳戶發票庫存獨立管理，請根據歸屬查詢。
只要透過交易查詢 API，解析回傳中的 invoice_count 欄位，即可隨時掌握剩餘電子發票號碼數量。
能只使用電子發票功能，不使用金流嗎？
電子發票僅能在有 MYPAY 金流交易的前提下開立，無法只單獨使用電子發票功能。
更多 MYPAY 提供之服務與格式，應用情境請參閱：
- 經銷商：https://doc.usecase.cc/Payment/Agent/#mypay-link
- 特約商店：https://doc.usecase.cc/Payment/Store/#mypay-link
- 【經銷商】商務代號，尾碼 4 碼 1XXX。
- 【特約商店】商務代號，尾碼 4 碼 0XXX。
高鉅是台灣領先的金融科技公司，專注於提供客製化的金融服務，我們以創新的思維和專業的技術，打造一個安全、便利、高效的支付生態系，搭建起企業、銀行與消費者之間的橋樑，扮演微型商家到大型電商企業最堅實的後盾協助共創三贏。