e首發票 API 說明與開發注意事項
本頁摘要
API 技術文件入口：OpenAPI 規格、開通申請、簽章認證、開發注意事項、情境與 API 對應。供工程與資訊團隊串接開立、作廢、折讓等 API 時依循。
API 申請與開通（串接前必讀）
API 測試與串接需先完成開通，方可取得串接用 KEY。
| 項目 | 說明 |
|---|---|
| 開通申請 | 請填寫 「e首發票 API 測試申辦與開通使用同意書」，填寫正確之公司名稱、統編、聯絡人等資料；我們將依此為您辦理申請與開通服務。申請書連結 |
| 取得 KEY | 開通完成後，將提供串接所需之 API KEY（含簽章用加密 KEY）；正式環境之 KEY 依服務商管理後台或合約取得。 |
| 測試開通效期 | 每次測試開通帳號有效期限為 30 天（依申請書與當時公告為準）；正式環境依合約。 |
| 客服引導 | 若不清楚開通流程或需要協助，客服會引導您完成開通。可透過 LINE@、客服 07-7190888、業務 0800-800-402 或 Email：service@ieinv.com 聯繫。 |
| 申請書與規範 | API 申請使用請依照規範共同維護資訊安全；填寫前請詳細了解申請書所示內容。開通申請書與最新表單以 e首發票官網或客服提供 為準；連結若失效請洽客服。 |
串接步驟概覽：① 填寫開通申請書並取得 KEY → ② 閱讀 OpenAPI 規格與簽章認證（§1、§2）→ ③ 確認情境（發票版／訂單版）與導入前檢查（§3）→ ④ 開發與測試（Swagger UI／Stage 環境）→ ⑤ 上線前確認錯誤處理與稽核行為（§4、§5）。
1. API 規格（OpenAPI 格式）
e首發票應用 API 已以 OpenAPI 3.0 格式撰寫，便於工具鏈與文件生成使用。
| 項目 | 說明 |
|---|---|
| 規格檔（YAML） | einvoice-api-openapi.yaml |
| 規格檔（JSON） | einvoice-api-openapi.json — 若 YAML 在瀏覽器中文顯示亂碼，請改用 JSON 版（內容相同） |
| 涵蓋範圍 | 開立發票（發票版）、作廢發票、折讓電子發票 |
| 版本 | 2025.03（依 Inbox 來源文件整理） |
主要路徑（常用）
| 方法 | 路徑 | 說明 |
|---|---|---|
| POST | /Append/Order |
新增單筆訂單轉發票（訂單版） |
| POST | /Append/Invoices |
新增已開立發票資料（發票版：營業人取號後送交） |
| POST | /Update/CancelInvoices |
批次作廢發票 |
| POST | /Update/AllowanceInvoice |
新增發票折讓單 |
Swagger UI 互動文件（對外服務 API）
完整端點清單、請求／回應結構與線上測試，請使用 Swagger UI：
| 項目 | 說明 |
|---|---|
| Swagger UI | Product.EInvoice.WebApi - 對外服務 API（Swagger） |
| API 名稱 | Product.EInvoice.WebApi - 對外服務 API |
| Base URL（Stage） | https://jpe-sl-einvoice-erpapi-stage.azurewebsites.net（Swagger 頁面之根網址） |
| API 版本 | v1 |
| 認證 | Swagger 介面可輸入 api_key；實際呼叫請依服務商提供之簽章與 KEY 為準（見下方 §2 簽章與認證）。 |
對外服務 API 端點一覽（依 Swagger 分組）
以下對應 Swagger UI 之 Append / Inquire / Update 分組，便於與互動文件對照。請求參數與回應格式請於 Swagger 查閱。
| 方法 | 路徑 | 說明 |
|---|---|---|
| Append | ||
| POST | /Append/Order |
新增單筆訂單轉發票 |
| POST | /Append/Orders |
批次新增多筆訂單轉發票 |
| POST | /Append/Invoice |
新增已開立發票資料 |
| POST | /Append/Invoices |
批次新增已開立發票資料 |
| POST | /Append/PrintInvoices |
傳入訂單開立發票並加入雲端列印 |
| POST | /Append/BlankCancel |
作廢空白發票 |
| POST | /Append/TrackBlank |
新增空白發票號 |
| POST | /Append/InvoiceWithCancel |
新增發票並作廢 |
| Inquire | ||
| POST | /Inquire/GetInvoiceIDList |
查詢發票號碼清單 |
| POST | /Inquire/GetInvoicesStatus |
批次查詢發票處理狀態 |
| POST | /Inquire/GetInvoicesAppendStatus |
批次查詢發票新增狀態 |
| Update | ||
| POST | /Update/Invoices |
批次更新發票資料 |
| POST | /Update/SetBlankInvoiceID |
上傳空白發票號碼資料 |
| POST | /Update/SplitInvoiceID |
設定發票號碼分割規則 |
| POST | /Update/CancelInvoices |
批次作廢發票 |
| POST | /Update/AllowanceInvoices |
批次新增發票折讓單 |
| POST | /Update/AllowanceInvoice |
新增發票折讓單 |
| POST | /Update/CancelAllowances |
批次作廢折讓單 |
| POST | /Update/CancelAllowance |
作廢折讓單 |
| POST | /Update/RePrint |
發票重新列印 |
| POST | /Update/SecPrint |
發票補列印 |
環境
- Swagger UI（Stage）：對外服務 API Swagger — Base URL 為同網址根、API Version: v1
- 測試環境（依方案）：實際 Base URL 與路徑以服務商提供為準（例：
https://webapi.systemlead.com/terpapi或 Swagger 所示根網址） - 正式環境：依服務商管理後台或合約取得 URL 與加密 KEY
2. 簽章與認證
- 驗證方式：SHA256 簽章。
- 計算方式：統編（CompanyID）與加密 KEY、時間序（Timestamp） 計算簽章；過期時間請注意，勿重複使用同一 Timestamp 提交多筆。
- 加密 KEY：正式環境依服務商提供之管理後台取得。
3. 導入前請先確認（降低返工）
- 欄位對照表：來源系統欄位對應到發票欄位的規則（含 B2B/B2C、稅別、載具）。
- 開立時點：依業態決定（付款成功／出貨／完成服務），避免跨期開立之稅務風險。
- 錯誤處理策略：開立失敗時重試、告警、補送與人工介入流程；務必處理開立失敗訊息，避免漏開發票。
- 異動策略：退貨、折讓、作廢的責任與流程，與帳務一致。
4. 開立與稽核行為（開發必讀）
- 稽核不通過即拒絕開立：系統依發票成立條件稽核，若有錯誤會拒絕開立並回覆錯誤原因，避免違規開立。
- 營業人須注意開立失敗訊息：API 回傳之
StatusCode、ResultMessage需記錄並處理；未處理失敗筆數將導致漏開發票，影響客戶與稅務。 - B2B/B2C 與稅別：B 類單身為未稅、單頭需加計 5% 稅額；C 類為含稅、單頭稅額為 0。混稅僅 C 類，單頭 TaxType＝9，單身 ItemTaxType 填 1（應稅）、2（零稅）、3（免稅）；API 架構支援單身不同稅別的拋入紀錄。混稅時系統可自動完成稅額分列與稽核。詳見 OpenAPI 內 schema 與範例。
- 訂單編號（BillingNo）：不可重複；發票號碼（InvoiceID） 請分批傳入、成功後再傳下一筆，避免並行重複提交。
5. 開發注意事項（風險與合規）
以下整理自 Inbox 注意事項與稽核規則，串接時請一併考量。
| 項目 | 說明 |
|---|---|
| 稅務與開立時點 | 遵守 API 設定的開立時點，避免跨期開立之稅務風險；C 類 48 小時、B 類 7 天內需完成上傳。 |
| 訂單變更與取消 | 出貨後取消訂單時，需及時作廢或開立折讓；跨期無法作廢時須以折讓處理，請預留流程與人力。 |
| 折讓與退貨 | 折讓單金額需與實際退貨／交易一致；建議定期檢查系統產生之折讓單與實際金額是否正確。 |
| 開立失敗與漏開 | 未處理開立失敗回傳將導致漏開發票；建議記錄每筆開立結果（成功／失敗、錯誤原因）並建立補開流程。 |
| 資料同步與備份 | 建議定期備份發票與折讓資料，並監控同步狀況，以利稅務申報與稽核。 |
| 異常與監控 | 建立訂單異常檢查流程，密切監控系統通知，及時作廢或折讓，避免稽核風險。 |
| 稅務合規與留痕 | 開立、作廢、折讓須符合國稅局規範；保存相關記錄以便稽核。 |
6. 情境與 API 對應一覽（歸檔）
以下對應不同使用情境應使用的開立方式與 API；作廢、折讓為各情境共用。
| 情境 | 開立方式 | 對應 API 或介接 | 作廢／折讓 |
|---|---|---|---|
| 發票版 | 營業人系統取號後送交 | POST /terpapi/Append/Invoices（本 OpenAPI 規格） | POST CancelInvoices、POST AllowanceInvoice |
| 訂單版 | e首發票取號；Excel 或訂單版介接 | Excel 匯入（EINV111）或依服務商提供之訂單版 API | 同上 |
| 機台／繳款設備 | 訂單版 ＋ 機台號、冪等鍵 | 依服務商訂單版介接規範 | 同上 |
| 混合使用 | 依通路分流 | POS → Append/Invoices；電商／機台 → 訂單版介接 | 同上 |
情境說明頁（含本情境 API 使用區塊）
- 取號管理差異與選型 → 情境與 API 說明對應表
- 發票版開立發票流程 → 本情境對應 API 使用
- 訂單版開立發票流程 → 本情境對應 API 使用
- 機台與繳款設備流程 → 本情境對應 API 使用
- 混合使用情境 → 各通路 API 對應
7. 情境選型與相關文件
- 發票版 vs 訂單版：先判斷「誰負責發票號取號」。發票版為營業人系統取號後送本開立 API；訂單版為 e首發票協助取號，請依情境選型再選擇對應流程。→ 情境流程：取號管理差異與選型
- 逾期稽核：上傳時限、暫停區、處理方式。→ 逾期稽核與預防處置措施
- 字軌管理：常見錯誤與預防。→ 字軌管理常見錯誤與預防
8. 來源說明與版本
- 本 API 說明與 OpenAPI 規格係依 Inbox 內 e首發票應用 API 相關文件整理，包含：API 技術文件（入口）、2025-發票版-開立發票 API、2024-作廢發票 API、2025-折讓電子發票 API、JSON 稽核規則、注意事項等。
- Swagger UI 整合：對外服務 API 之 Swagger UI 連結與 Append／Inquire／Update 端點一覽已納入 §1，供開發者對照互動文件與本頁說明；實際 Base URL、路徑前綴與認證以服務商提供為準。
- 正式規格與合約以 e首發票公告與雙方合約 為準；若有版本更新，依服務商通知與版本管理方式（依法規盡可能向下相容，重大變更另通知並有緩衝期）為準。
版本紀錄
| 版本 | 日期 | 修改者 | 修改內容 |
|---|---|---|---|
| v1.0 | 2025-02-10 | 專案負責人 | 依 Inbox API 文件整理；Swagger、OpenAPI、端點一覽、簽章、注意事項、情境對應。 |
| v1.1 | 2025-02-10 | 專案負責人 | 新增「API 申請與開通（串接前必讀）」；新增串接步驟概覽。 |
| v1.2 | 2025-02-10 | 專案負責人 | 開通申請書補充申請書連結。 |