電子發票 API 選用指南¶
一般電子發票整合，請優先評估標準 API。標準 API 可依需求處理訂單版、發票版、列印、不列印及雲端列印，大部分 POS 系統也能使用。
POS／自助設備 API 是為簡化硬體串接而設計的特定應用介面。 雖然技術名稱是 POS API，也適用於自動販賣機、繳款機、自助結帳機等設備；請先了解需要簡化的流程，再決定是否使用。
依您的需求選擇¶
| 您的情境 | 建議選擇 |
|---|---|
| 自行安排一般開票、列印或載具流程 | 標準 API |
| POS 已自行取號，傳送已開立發票存檔 | 標準 API：發票版存檔模式 |
| 希望系統直接送到指定印表機 | 標準 API 搭配雲端列印 |
| 設備要自行送印，希望取得系統整理好的列印資訊 | POS／自助設備 API：開立發票並取得前端列印資訊 |
| 希望消費者使用現成頁面辦理捐贈／歸戶 | POS／自助設備 API：開立發票並取得捐贈／歸戶入口 |
| 設備本次不需要取得列印資料 | POS／自助設備 API：開立發票，不取得列印資料；雲端發票處理方式需確認 |
標準 API：一般整合的優先選擇¶
若您需要自行控制開票資料、交易流程與消費者操作，可使用標準 API。這也包括 POS、電商、ERP 及其他業務系統。
- 訂單版：由系統依傳入訂單取號開立。
- 發票版存檔：POS 已自行取號開立，再傳送既有發票資料，不重新取號。
- 列印或不列印：依選用介面與開通設定安排。
POS 已取號的發票，不論已列印或作載具處理，都應選擇相應存檔流程。請參閱 標準 API 開立與存檔說明。
雲端列印與設備前端列印有何不同？¶
雲端列印：由系統直接透過雲端，將列印內容傳送到指定印表機。 前端不必先接收列印資訊再轉送。
設備前端列印：由系統產生列印資訊，回傳 POS／設備，再由設備端銜接印表機輸出。
| 比較項目 | 雲端列印 | 設備前端列印 |
|---|---|---|
| 列印資訊由誰準備 | 系統 | 系統 |
| 誰負責送至印表機 | 系統經雲端直接送印 | POS／設備前端 |
| 適合需求 | 指定印表機由系統直接送印 | 設備自行控制本地印表機 |
| 導入前確認 | 支援的印表機、網路及指定印表機設定 | 回傳資料格式、印表機相容性及設備輸出方式 |
雲端列印流程：前端送出資料 → 系統開票並準備列印內容 → 雲端送至指定印表機 → 印表機輸出。
「雲端發票」描述開票情境；「雲端列印」描述送印方式，兩者不是同一件事。
POS／自助設備 API 的三種情境¶
這組 API 主要減少硬體廠商與設備開發商的工作：由系統依設定協助補足傳入資訊、產生列印資訊，或提供現成的捐贈／歸戶頁面。
簡化傳入資訊不代表可任意省略欄位。必填資料與可補足範圍，仍須依商家、設備設定及 API 文件確認。
1. 開立發票並取得前端列印資訊¶
POS API：POST /Append/Order
適用於 POS、自動販賣機或繳款機，在完成需要開票的交易後，由設備內建或連接的印表機印出發票。
傳送訂單 → 系統補足資訊並取號開立 → 回傳 PrintDataString → 設備送至印表機。
系統協助將發票資料轉成列印資訊，開發商只需依格式完成設備與印表機的輸出銜接。PrintDataString 是列印內容資料，不是可直接送印的命令，也不是 QR 圖片；其處理方式請依技術文件。
開立成功不保證每次都有列印資訊。若缺少資料，先核對結果，不重新開票。
2. 開立發票並取得捐贈／歸戶入口¶
POS API：POST /Append/OrderReturnQKey
適用於自助設備完成交易後，讓消費者用手機掃碼，或在設備畫面按鈕進入現成的雲端頁面，辦理捐贈／歸戶。
| 回傳欄位 | 前端用途 |
|---|---|
QKey |
使用當次回傳的綁定碼 |
QrCodeUrl |
製作 QR Code，或作為「捐贈／歸戶」按鈕的連結 |
傳送訂單 → 系統開票並回傳綁定資訊 → 顯示 QR Code 或按鈕 → 消費者進入頁面辦理捐贈／歸戶。
設備開發商不必另行開發完整的捐贈／歸戶頁面。必須直接使用當次回傳的連結，不拿綁定碼自行拼接網址，也不使用範例值代替。
成功開立不保證每次都有綁定資訊；缺少有效連結時，不顯示可操作入口。取得連結也不等於消費者已完成捐贈／歸戶。
3. 開立發票，不取得列印資料¶
POS API：POST /Append/OrderWithoutPrint
適用於 POS 或自助設備需要由系統取號開立，但本次不需要取得列印資料的情境。若設備未配置印表機，或希望一律開立雲端發票，須先確認雲端發票處理方式。
傳送訂單 → 系統取號開立 → 不取得列印資料 → 確認開立結果。
先確認雲端發票處理方式
此介面不產生列印資料，但目前技術文件仍指出它不保證最終不走紙本處理。若需求是「一律開立雲端發票」，導入前須由技術窗口確認商家設定與實際結果，不能只靠介面名稱或 PrintMark 判斷。
此介面不是既有發票存檔，也不提供前一種情境的捐贈／歸戶入口。若要讓消費者掃碼操作，請選用 OrderReturnQKey。
避免選錯與重複開立¶
- 同一筆交易選定一條開立流程。 不要先用標準 API 開立，再呼叫 POS Append 取得列印或綁定資訊；POS 三支 Append 都是開立操作。
- 相同路徑不代表相同介面。 標準 API 與 POS API 都可能出現
/Append/Order，請同時核對所屬服務、開通網址、認證及請求格式。 - 認證、查詢與回應不能混用。 標準 API 的認證及 Inquire 查詢不能直接套用至 POS API。
- HTTP 200 不等於業務成功。 應依所選 API 檢查回傳狀態與必要資料，分別記錄開立、送印及捐贈／歸戶結果。
- 逾時先核對，不自動重送。 保留原訂單編號與交易紀錄。POS 文件未提供依訂單編號查開立結果的專用操作，需先與技術窗口確認核對入口；不可把 Append 當作查詢或任意改單號重送。
選定情境後查看技術文件¶
- 標準 API：端點與契約來源 — 查看標準 API 文件、環境與開通依據。
- POS／自助設備 API 技術文件 — 查看欄位、回傳條件、列印格式與例外處理。
正式串接以服務開通時交付的環境、Swagger／OpenAPI 契約及開通文件為準。技術文件中的測試操作可能實際開票或列印，請使用已確認的測試環境。
需要整理觸發時點、例外處理與上線檢查，請回到 電子發票 API 串接指南。