電子發票 API 串接指南¶
本區協助開發與產品團隊規劃 e首發票 API（應用程式介面）串接、找到技術文件，並在上線前準備例外處理與驗證項目。
契約與審核邊界
API 路徑、欄位、認證、環境網址、錯誤回應與限制，須以服務開通時交付的 Swagger／OpenAPI（API 契約文件）及正式開通文件為準。本網站是閱讀導覽，不是正式 API 契約；技術內容發布前須經工程負責人審核。
先選擇 API 與列印方式¶
一般電子發票整合，請優先評估標準 API。需要系統直接透過雲端送至指定印表機時，可搭配雲端列印。
POS／自助設備 API 不只適用於收銀系統，也為自動販賣機、繳款機、自助結帳機等設備提供簡化串接方式。是否選用取決於需要簡化的流程，不是設備名稱。
- 已自行取號：使用標準 API 的發票版存檔模式。
- 需要設備列印資訊、現成捐贈／歸戶頁面，或開立後不取得列印資料：先確認 POS／自助設備的適用情境。
查看 API 選用指南｜查看 POS／自助設備 API 技術文件
依任務開始¶
| 任務 | 文件 | 完成標誌 |
|---|---|---|
| 選擇 API 與列印方式 | 標準 API 與自助設備選用指南 | 已確認取號、送印及消費者操作由誰負責 |
| 評估串接範圍與主要流程 | 串接流程與例外設計 | 已確認開立、查詢、異動及失敗補救的責任 |
| 查看端點與資料結構 | API 端點與契約來源 | 已找到目前 Swagger／OpenAPI 與開通交付內容，並排定工程核對 |
| 設定認證與金鑰 | 認證與金鑰管理 | 測試環境可通過認證，且機密值未寫入程式碼或文件 |
| 實作開立 | 發票開立 API | 可由業務識別鍵追查一次請求及其結果 |
| 實作查詢與異動 | 發票查詢 API | 可在逾時或狀態不明時先查詢，再決定是否重送 |
| 處理錯誤 | 常見錯誤代碼 | 已定義記錄、告警、人工介入與補救方式 |
上線前最低檢查¶
- 使用開通交付的環境網址、帳號與金鑰，不從範例推測正式設定。
- 為每筆交易保留可追溯的業務識別資料與處理結果，但不將金鑰或完整敏感資料寫入紀錄。
- 驗證成功、失敗、逾時、狀態不明、重複送出及退貨退款等情境。
- 明確指定由哪個系統與角色決定重試、人工補送、作廢或折讓。
- 在正式上線前，以目前 Swagger／OpenAPI 完成工程審查與測試證據留存。
有文件差異或需要開通資訊¶
若網站內容與開通交付內容不同，停止依網站範例實作，先由工程窗口確認契約版本。需要申請或技術協助時，請依 聯絡客服 準備環境、發生時間、請求識別資訊與去識別化錯誤內容。