無人化設備專屬電子發票API整合服務
POS／自助設備 API（POSAPI）技術說明：開立情境、列印流程、欄位、作廢與串接注意事項
e首發票（矽聯科技）｜更新日期：
無人化設備以 http Post 傳送 Json 訂單給 e首發票 POSAPI，即可開立電子發票並取得列印命令。
本文為 e首發票提供給營業人與設備廠商的 POS／自助設備 API（POSAPI）技術說明，適用販賣機、繳款機、收銀設備等無人化設備。實際欄位、驗證規則與環境網址，請以 POSAPI 技術文件 及服務開通時提供的文件為準。
無人化設備電子發票 API 服務特色
- 設備交易開立消費者電子發票，課稅別可設定應稅、零稅率、免稅或特種稅額
- 支援雲端發票、載具與捐贈碼，並可提供消費者捐贈／歸戶 QR Code 入口
- 採用 http Post 傳遞 Json 格式資料
- 回傳大寫 Hex 列印命令，設備可直接送至印表機列印，或由系統排入列印佇列
- 提供手機條碼、捐贈碼驗證與字軌使用狀態查詢等輔助 API
POSAPI 與標準 API 不可混用
POSAPI 是為簡化硬體串接而設計的專屬介面，認證、查詢與回應格式都與標準 API 不同。同一筆交易請只選一條開立流程；POSAPI 的三支 Append 都是開立操作，不要先用標準 API 開立後再呼叫 POSAPI。若需自行控制開票流程，請參考 API 選用指南。
POSAPI 有哪三種開立情境？
依設備是否需要列印、是否提供捐贈／歸戶頁面，可選擇三種開立端點：
設備以 http Post 傳送 Json 訂單資料
設備需要哪種開立結果？
開立並取得前端列印資訊
POST /Append/Order
系統取號開立發票
回傳發票號碼、列印命令 PrintCode 與 PrintDataString
設備現場列印電子發票證明聯
開立並取得捐贈／歸戶入口
POST /Append/OrderReturnQKey
系統開票並回傳 QKey 與 QrCodeUrl
設備顯示 QR Code
消費者掃碼辦理捐贈／歸戶
開立不回傳列印資訊
POST /Append/OrderWithoutPrint
系統取號開立（PrintMark 固定為 N）
回傳開立結果，PrintStatus 為 NotRequested
POSAPI 三種開立情境（依 e首發票 POSAPI 技術文件）
QrCodeUrl 為不透明網址，請直接使用當次回傳的連結，不要自行解密或組合網址。- 三支 Append 都會實際開立發票，不可把 Append 當作查詢使用。
POSAPI 的列印流程怎麼運作？
使用 /Append/Order 或重新列印時，系統會以 PrintStatus 告知列印處理方式：
系統開立發票並回傳 PrintStatus
PrintStatus 狀態？
Ready
回傳大寫 Hex 列印命令 PrintCode
設備將 Hex 字串轉為 Byte 陣列
透過 TCP/IP 傳送至印表機列印
Queued
系統將發票排入列印佇列
由列印服務處理輸出
Failed
列印資料產生失敗
依 PrintMessage 說明處理，需要時呼叫重新列印
POSAPI 列印流程（依 e首發票 POSAPI 技術文件）
PrintCode：大寫 Hex 列印命令（例如 1B40），設備轉為 Byte 後送至印表機。PrintDataString：以 | 分隔的十段顯示／條碼資料，保留空白；它不是列印命令，也不是 QR 圖片。/Printer/RePrint：取得重新列印資料，重複呼叫可能造成重複列印。/Printer/Status：查詢列印服務狀態；回傳成功只代表服務正常，不代表某張發票已印出。
POSAPI 驗證方式與主要欄位
驗證欄位
POSAPI 端點需帶入以下三個驗證欄位，驗證金鑰於服務開通後提供：
| 欄位 | 說明 |
|---|
CompanyIdentifier | 賣方統一編號 |
DeviceNo | POS／設備裝置編號 |
Key | 驗證金鑰 |
開立請求主要欄位
| 欄位 | 說明 |
|---|
RelateNumber | 交易識別碼，建議必填且固定不變，用於辨識重複訂單 |
SalesAmount、TaxAmount、TotalAmount | 銷售額、稅額、總計（整數金額） |
TaxType | 課稅別：1 應稅、2 零稅率、3 免稅、4 特種稅額 |
UseFor | 用途代碼（依商家設定，例如 P1） |
Details | 商品明細，至少一筆 |
CarrierType、CarrierId1、CarrierId2 | 載具資訊（選填） |
NPOBAN | 捐贈碼（選填） |
開立回應主要欄位
| 欄位 | 說明 |
|---|
StatusCode | 1 成功、0 失敗；成功只代表同步開立成功，不代表已上傳財政部或已實體列印 |
InvoiceNumber | 發票號碼（2 碼英文＋8 碼數字） |
PrintStatus | Ready、Queued、Failed 或 NotRequested |
PrintCode | 大寫 Hex 列印命令 |
PrintDataString | 十段 | 分隔的顯示／條碼資料 |
QKey、QrCodeUrl | 捐贈／歸戶短碼與入口網址（OrderReturnQKey） |
MessageCode | 業務代碼，例如 DUPLICATE_ORDER（重複訂單） |
POSAPI 端點一覽
| 分類 | 端點 | 用途 |
|---|
| 開立 | /Append/Order | 開立發票並取得前端列印資訊 |
| 開立 | /Append/OrderReturnQKey | 開立發票並取得捐贈／歸戶入口 |
| 開立 | /Append/OrderWithoutPrint | 開立發票，不回傳前端列印資訊 |
| 作廢 | /Invoice/Cancel | 作廢電子發票 |
| 列印 | /Printer/RePrint | 取得發票重新列印資料 |
| 列印 | /Printer/Status | 查詢列印服務狀態 |
| 字軌 | /AssignNo/UseState | 查詢指定用途與期別的字軌使用狀態（不保留號碼） |
| 驗證 | /PhoneBarCodeCheck | 驗證手機條碼 |
| 驗證 | /PreservCodeCheck | 驗證捐贈碼 |
所有端點皆採 POST。POSAPI 未提供依訂單編號查詢開立結果的專用端點，如需核對開立結果，請先與 e首發票技術窗口確認核對方式。
如何作廢 POSAPI 開立的電子發票？
呼叫 /Invoice/Cancel，帶入以下欄位：
InvoiceNumber：發票號碼（必填）CancelDate：作廢日期（預設為台灣時間 UTC+08）CancelReason：作廢原因（最長 20 字，預設「訂單作廢」）ReturnTaxDocumentNumber：專案作廢核准文號（最長 60 字，選填）BlankCancel：是否為空白作廢，Y 或 N（預設 N）
作廢請勿自動重試
作廢可能在連線中斷前就已生效，請勿自動重試；請先確認發票狀態再決定下一步。
錯誤處理與重試原則
- 判斷結果看 StatusCode：
StatusCode 為 1 才是開立成功；0 為失敗，需進入補救流程，以免漏開發票。
- 重複訂單：同一筆交易重複送出時，會回傳
MessageCode: DUPLICATE_ORDER 與既有的 InvoiceNumber，請以既有發票號碼為準。
- 逾時：保留原請求內容、時間與
RelateNumber，核對原交易，不可任意改單號重送。
- 作廢與列印：不自動重試；重新列印可能造成重複列印。
- 輔助驗證 API：手機條碼與捐贈碼驗證以 HTTP 200／Status 1 表示有效，HTTP 400／Status 0 表示無效。
無人化設備需要開發哪些程式？
| 步驟 | 開發項目 | 說明 | 相關欄位／端點 |
|---|
| 1 | 交易資料轉 Json | 將交易資料轉換為 Json 格式，並能處理 Json 格式回應 | RelateNumber、Details 等 |
| 2 | 呼叫 API | 透過 http Post 呼叫 POSAPI，帶入驗證欄位並傳送與接收 Json 資料 | /Append/Order 等開立端點 |
| 3 | 判斷結果 | 處理成功、重複訂單與失敗情境 | StatusCode、MessageCode、PrintStatus |
| 4 | Hex 字串轉換 | 將回傳的 Hex 列印命令轉換為 Byte 陣列 | PrintCode |
| 5 | 傳送至印表機 | 將 Byte 陣列透過 TCP/IP 傳送到印表機（需配合設備上的印表機 IP） | 設備印表機 IP |
電子發票的開立、上傳等作業都由 e首發票處理，設備端只需依規範傳送交易資料並處理回傳結果。
測試提醒
技術文件中的「Test Request」會呼叫真實 API，可能實際開立、作廢或列印發票；請使用測試環境，切勿使用正式金鑰測試。文件範例皆為測試資料，不能當作正式憑證或交易結果。
POSAPI 技術文件與申請諮詢
無人化設備 API 的串接方案與費用，請洽 e首發票業務人員洽談。
無人化設備電子發票 API 常見問題
無人化設備如何開立電子發票？
設備將交易資料轉為 Json，以 http Post 呼叫 e首發票 POSAPI 的開立端點，即可開立電子發票，並依需求取得列印命令、捐贈／歸戶 QR Code 入口，或不回傳列印資訊。
POSAPI 回傳的 PrintCode 和 PrintDataString 有什麼不同？
PrintCode 是大寫 Hex 列印命令，設備轉為 Byte 後透過 TCP/IP 送至印表機；PrintDataString 是以 | 分隔的十段顯示／條碼資料，不是列印命令，也不是 QR 圖片。
StatusCode 回傳 1 代表發票已上傳財政部嗎？
不是。StatusCode 為 1 只代表同步開立成功，不代表已上傳財政部或已實體列印完成。
同一筆交易重複送出會重複開立發票嗎？
系統會回傳 MessageCode「DUPLICATE_ORDER」與既有的發票號碼，因此建議 RelateNumber 固定不變；逾時時請核對原交易，不要改單號重送。
作廢發票失敗可以自動重試嗎？
不建議。作廢可能在連線中斷前就已生效，請先確認發票狀態，再決定是否重新作廢。
