e首發票 API 說明與開發注意事項

建議從這裡開始：Swagger UI

Product.EInvoice.WebApi — 對外服務 API（Swagger） — 完整端點、參數與線上測試。

下方 §1 有端點一覽與環境說明；簽章與開發注意事項見 §2 起；JSON 欄位說明與三支核心 API 單支說明見本章「JSON 欄位說明」「POST /Append/Invoices」等。機器可讀規格檔（JSON）僅供工具匯入，見 §1 末「進階」區塊。

English documentation for integrators

Non–Chinese readers: API integration guide (English) — Swagger UI first, signing, environments, JSON field glossary. F0401 field mapping (English, full table) · Invoice issuance validation (English) · F0401 key fields (English). Hub: Technical docs (English).

---

本頁摘要

API 技術文件入口：Swagger UI、開通申請、簽章認證、開發注意事項、情境與 API 對應。供工程與資訊團隊串接開立、作廢、折讓等 API 時依循。

---

---

API 申請與開通（串接前必讀）

API 測試與串接需先完成開通，方可取得串接用 KEY。

項目	說明
開通申請	請填寫 「e首發票 API 測試申辦與開通使用同意書」，填寫正確之公司名稱、統編、聯絡人等資料；我們將依此為您辦理申請與開通服務。申請書連結
取得 KEY	開通完成後，將提供串接所需之 API KEY（含簽章用加密 KEY）；正式環境之 KEY 依服務商管理後台或合約取得。
測試開通效期	每次測試開通帳號有效期限為 30 天（依申請書與當時公告為準）；正式環境依合約。
客服引導	若不清楚開通流程或需要協助，客服會引導您完成開通。可透過 LINE@、客服 07-7190888、業務 0800-800-402 或 Email：service@einv.tw 聯繫。
申請書與規範	API 申請使用請依照規範共同維護資訊安全；填寫前請詳細了解申請書所示內容。開通申請書與最新表單以 e首發票官網或客服提供 為準；連結若失效請洽客服。

串接步驟概覽：① 填寫開通申請書並取得 KEY → ② 以 Swagger UI 查閱 API 並閱讀簽章認證（§1、§2）→ ③ 確認情境（發票版／訂單版）與導入前檢查（§3）→ ④ 於 Stage 環境開發與測試 → ⑤ 上線前確認錯誤處理與稽核行為（§4、§5）。

---

1. 互動式 API 文件（Swagger UI）

完整端點清單、請求／回應結構與線上測試，請使用 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 簽章與認證）。

常用路徑（精簡）

方法	路徑	說明
POST	/Append/Order	新增單筆訂單轉發票（訂單版）
POST	/Append/Invoices	新增已開立發票資料（發票版：營業人取號後送交）
POST	/Update/CancelInvoices	批次作廢發票
POST	/Update/AllowanceInvoice	新增發票折讓單

其餘 Append / Inquire / Update 端點請於 Swagger 查閱。

OpenAPI JSON 與 Swagger UI 對照

來源	數量	說明
OpenAPI JSON 已收錄	3 支	POST /Append/Invoices、POST /Update/CancelInvoices、POST /Update/AllowanceInvoice — 見 einvoice-api-openapi.json 與下方 JSON 欄位說明
Swagger UI 延伸端點	18 支	見下方 Swagger-only 端點；已裁決為 public（對外公開）。OpenAPI JSON 尚未收錄，將分階段補齊；補齊前請以 Swagger UI 互動文件與合約約定為準。

對外服務 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-only 端點（OpenAPI JSON 尚未收錄）

以下 18 支 Swagger-only API 已裁決為對外公開（public）。OpenAPI JSON 尚未收錄，將分階段補齊；在補齊前，請以 Swagger UI 互動文件與合約約定為準。三支核心 API（已收錄 OpenAPI JSON 並有單支說明）見上方完整表與 核心 API 單支說明。

分組	API 路徑	用途摘要	可見性	OpenAPI JSON 狀態	文件狀態	備註
Append	POST /Append/Order	新增單筆訂單轉發票	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	訂單版
Append	POST /Append/Orders	批次新增多筆訂單轉發票	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	訂單版
Append	POST /Append/Invoice	新增已開立發票資料	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	單筆；批次見 /Append/Invoices
Append	POST /Append/PrintInvoices	訂單版開立並加入雲端熱感列印佇列	public	尚未收錄，將分階段補齊	見 POST /Append/PrintInvoices	訂單版＋雲端列印
Append	POST /Append/BlankCancel	作廢空白發票	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Append	POST /Append/TrackBlank	新增空白發票號	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Append	POST /Append/InvoiceWithCancel	新增發票並作廢	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Inquire	POST /Inquire/GetInvoiceIDList	查詢發票號碼清單	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Inquire	POST /Inquire/GetInvoicesStatus	批次查詢發票處理狀態	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Inquire	POST /Inquire/GetInvoicesAppendStatus	批次查詢發票新增狀態	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Update	POST /Update/Invoices	批次更新發票資料	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Update	POST /Update/SetBlankInvoiceID	上傳空白發票號碼資料	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Update	POST /Update/SplitInvoiceID	設定發票號碼分割規則	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Update	POST /Update/AllowanceInvoices	批次新增發票折讓單	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	單筆見 POST /Update/AllowanceInvoice
Update	POST /Update/CancelAllowances	批次作廢折讓單	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Update	POST /Update/CancelAllowance	作廢折讓單	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Update	POST /Update/RePrint	發票重新列印	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—
Update	POST /Update/SecPrint	發票補列印	public	尚未收錄，將分階段補齊	Swagger UI 可查；單支文件待補	—

環境

• Swagger UI（Stage）：對外服務 API Swagger — Base URL 為同網址根、API Version: v1
• 測試環境（依方案）：實際 Base URL 與路徑以服務商提供為準（例：https://webapi.systemlead.com/terpapi 或 Swagger 所示根網址）
• 正式環境：依服務商管理後台或合約取得 URL 與加密 KEY

進階：機器可讀 OpenAPI 規格檔（工具匯入用）

e首發票應用 API 亦提供 OpenAPI 3.0 JSON 規格檔，供 Postman、程式產碼或 CI 匯入。一般查閱 API 請使用上方 Swagger UI。

項目	說明
規格檔（JSON）	einvoice-api-openapi.json
規格檔（英文 JSON）	einvoice-api-openapi.en.json — 境外串接；敘述為英文
涵蓋範圍	3 支核心 API：開立發票（發票版）、作廢發票、折讓電子發票（其餘 Swagger 端點見上方對照表）
版本	2025.03（依 Inbox 來源文件整理）

---

2. 簽章與認證

• 驗證方式：SHA256 簽章。
• 計算方式：統編（CompanyID）與加密 KEY、時間序（Timestamp） 計算簽章；過期時間請注意，勿重複使用同一 Timestamp 提交多筆。
• 加密 KEY：正式環境依服務商提供之管理後台取得。

---

3. 導入前請先確認（降低返工）

1. 欄位對照表：來源系統欄位對應到發票欄位的規則（含 B2B/B2C、稅別、載具）。
2. 開立時點：依業態決定（付款成功／出貨／完成服務），避免跨期開立之稅務風險。
3. 錯誤處理策略：開立失敗時重試、告警、補送與人工介入流程；務必處理開立失敗訊息，避免漏開發票。
4. 異動策略：退貨、折讓、作廢的責任與流程，與帳務一致。

---

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 天內需完成上傳。
訂單變更與取消	出貨後取消訂單時，需及時作廢或開立折讓；跨期無法作廢時須以折讓處理，請預留流程與人力。
折讓與退貨	折讓單金額需與實際退貨／交易一致；建議定期檢查系統產生之折讓單與實際金額是否正確。
開立失敗與漏開	未處理開立失敗回傳將導致漏開發票；建議記錄每筆開立結果（成功／失敗、錯誤原因）並建立補開流程。
資料同步與備份	建議定期備份發票與折讓資料，並監控同步狀況，以利稅務申報與稽核。
異常與監控	建立訂單異常檢查流程，密切監控系統通知，及時作廢或折讓，避免稽核風險。
稅務合規與留痕	開立、作廢、折讓須符合國稅局規範；保存相關記錄以便稽核。

---

JSON 欄位說明

適用範圍

本章欄位說明以目前 OpenAPI JSON 已收錄的三支核心 API 為準。Swagger UI 中其他端點若尚未收錄於 OpenAPI JSON，請先以 Swagger UI 互動文件與合約約定為準。

欄位定義依 einvoice-api-openapi.json 之 components.schemas；英文對照見 API integration guide §7。必填與型別僅取自 OpenAPI schema；範例僅取自 OpenAPI examples 或 schema example；未載明之檢核規則標 TODO：待工程確認。

共用外層欄位（Wrapper）

所有三支 API 之 Request Body 外層結構相同（SignedPayload + Data）。

欄位名稱	中文說明	必填	型別	範例	說明	備註
CompanyID	賣方統編	是	string	12345678	賣方統一編號（統一編號）	maxLength: 8；用於簽章計算
Timestamp	時間序	是	string	1677585655	用於簽章計算，有過期時間	勿重複使用同一 Timestamp 提交多筆
Signature	簽章	是	string	4754A5FE41749DE99E82FC5502348C69781E1026064ADF7AC	SHA256 簽章	範例簽章僅供格式參考，不可重用
Data	業務資料	是	object	—	各 API 承載之業務內容	結構見下方各節

開立發票欄位（Issue Invoice）

對應 POST /Append/Invoices；Data 為 InvoiceData 物件；明細為 Details 陣列，元素為 InvoiceDetailItem。

InvoiceData（發票主檔）

欄位名稱	中文說明	必填	型別	範例	說明	備註
InvoiceID	發票字軌號碼	是	string	NX25780488	發票字軌號碼（字母+數字）	maxLength: 10；分批傳入避免重複
InvoiceDateTime	開立日期時間	是	string	2025-03-17T19:43:37	開立日期時間	format: date-time；YYYY-MM-DDTHH:mm:ss
BillingNo	訂單編號	否	string	—	訂單編號，需唯一	maxLength: 30
InvoiceFor	發票對象	是	string	B	B=B2B，C=B2C	enum: B, C
BuyerID	買方統編	是	string	87654321	買方統一編號	maxLength: 10；B2C 固定 0000000000
BuyerInvoiceTitle	買方抬頭	否	string	—	買方抬頭	maxLength: 60；B2B 必填（依 OpenAPI description）
BuyerName	買受人名稱	是	string	企業買家	買受人名稱	maxLength: 60
BuyerTelNo	買方電話	否	string	—	買方電話，簡訊通知用	maxLength: 26
BuyerEmailAddress	買方電子郵件	是	string	einv@einv.tw	買方電子郵件	maxLength: 80；格式錯誤將清空並可能列入黑名單
CheckNumber	發票檢查碼	否	string	—	發票檢查碼	maxLength: 4；B2C 固定 9999
RandomNumber	發票隨機碼	否	string	—	發票隨機碼	maxLength: 4；B2C 固定 9999
PrintMark	證明聯列印標記	否	string	—	C 類證明聯已列印標記	enum: Y, N
TaxType	稅別	是	string	1	1=應稅，2=零稅，3=免稅，9=混稅（僅 C 類）	enum: 1, 2, 3, 9
SalesAmount	應稅銷售額	是	integer	5000	應稅銷售額（四捨五入整數）	—
FreeTaxSalesAmount	免稅銷售額	否	integer	0	免稅銷售額合計	default: 0
ZeroTaxSalesAmount	零稅銷售額	否	integer	0	零稅銷售額合計	default: 0
TaxAmount	稅額	是	integer	250	稅額	B 類為 SalesAmount×5% 四捨五入；C 類為 0
TotalAmount	含稅總金額	是	integer	5250	含稅總金額	—
CarrierType	載具類型	否	string	3J0002	載具類型，如手機條碼	—
CarrierId	載具編號	否	string	—	載具編號	maxLength: 64；手機條碼為 / + 7 碼
NPOBAN	愛心碼	否	string	—	愛心碼（捐贈）	minLength: 3；maxLength: 10
Note	系統紀錄	否	string	—	系統紀錄	maxLength: 250；可含 cc*email*cc* 格式 CC 收件者
Details	明細	是	array	—	發票明細陣列	元素為 InvoiceDetailItem

InvoiceDetailItem（發票明細）

欄位名稱	中文說明	必填	型別	範例	說明	備註
DetailID	明細序號	是	string	001	明細序號	maxLength: 4
ProductName	品名	是	string	商品A	品名	maxLength: 256
Quantity	數量	是	number	1	數量	format: double
UnitPrice	單價	是	number	5000	單價	format: double
SubTotal	小計	是	number	5000	小計	Quantity × UnitPrice
ItemTaxType	明細稅別	是	string	1	1=應稅，2=零稅，3=免稅	enum: 1, 2, 3

作廢發票欄位（Void Invoice）

對應 POST /Update/CancelInvoices；Data 可為單筆 CancelInvoiceData 物件，或 CancelInvoiceData 陣列（批次作廢）。

CancelInvoiceData（作廢資料）

欄位名稱	中文說明	必填	型別	範例	說明	備註
SellerID	賣方統編	是	string	—	賣方統一編號	maxLength: 8
InvoiceNumber	發票號碼	是	string	—	要作廢的發票號碼	maxLength: 10
CancelDate	作廢日期時間	是	string	2024-12-13T14:30:00	作廢日期時間	format: date-time
CancelReason	作廢原因	是	string	—	作廢原因	maxLength: 20；例：退貨、交易取消

折讓發票欄位（Allowance Invoice）

對應 POST /Update/AllowanceInvoice；Data 為 AllowanceData 物件；明細為 Details 陣列，元素為 AllowanceDetailItem。

AllowanceData（折讓主檔）

欄位名稱	中文說明	必填	型別	範例	說明	備註
AllowanceNumberPrefix	折讓單號	是	string	—	折讓單號，不可重複	maxLength: 16；建議時間序流水號
SellerID	賣方統編	是	string	—	賣方統一編號	maxLength: 8
BuyerID	買方統編	是	string	—	買方統一編號	maxLength: 10；B2B 為統編，B2C 為 0000000000
AllowanceType	折讓類型	是	string	—	固定 2（賣方傳送）	enum: 2
TaxAmount	折讓稅額	是	number	—	折讓稅額	應為應稅明細 Tax 加總
TotalAmount	折讓總額	是	number	—	折讓總額	應為所有明細 Amount 加總
Details	明細	是	array	—	折讓明細陣列	元素為 AllowanceDetailItem

AllowanceDetailItem（折讓明細）

欄位名稱	中文說明	必填	型別	範例	說明	備註
InvoiceNumber	原發票號碼	是	string	—	原發票號碼（字軌+8 碼數字）	maxLength: 10
SequenceNumber	明細序號	是	string	0001	明細序號	maxLength: 4
Amount	金額	是	number	—	折讓金額	—
Quantity	數量	是	number	—	數量	—
UnitPrice	單價	是	number	—	單價	—
ItemTaxType	明細稅別	是	string	—	1=應稅，2=零稅，3=免稅	enum: 1, 2, 3
Tax	稅額	是	number	—	明細稅額	ItemTaxType=1 時為 Amount×0.05 四捨五入

回應欄位（Response）

三支 API 皆以 HTTP 200 回傳 JSON；業務成敗以 StatusCode、ResultMessage 判斷（1=成功，0=失敗）。

開立發票回應（InvoiceIssueResponse）

欄位名稱	中文說明	必填	型別	範例	說明	備註
InvoiceID	發票字軌號碼	否	string	—	發票字軌號碼	—
InvoiceNumber	發票號碼	否	string	—	發票號碼	—
InvoiceDateTime	開立日期時間	否	string	—	開立日期時間	format: date-time
StatusCode	處理結果	否	integer	—	1=成功，0=失敗	失敗時須依 ResultMessage 處理，避免漏開
ResultMessage	結果訊息	否	string	—	成功或錯誤原因	TODO：待工程確認 業務錯誤訊息對照表

作廢發票回應（CancelInvoiceResponse）

單筆作廢回傳單一物件；批次作廢回傳物件陣列。

欄位名稱	中文說明	必填	型別	範例	說明	備註
SellerID	賣方統編	否	string	—	賣方統一編號	—
InvoiceNumber	發票號碼	否	string	—	作廢之發票號碼	—
StatusCode	處理結果	否	integer	—	1=成功，0=失敗	—
ResultMessage	結果訊息	否	string	—	成功或錯誤原因	TODO：待工程確認 業務錯誤訊息對照表

折讓發票回應（AllowanceInvoiceResponse）

欄位名稱	中文說明	必填	型別	範例	說明	備註
SellerID	賣方統編	否	string	—	賣方統一編號	—
AllowanceNumber	折讓單號	否	string	—	折讓單號	—
StatusCode	處理結果	否	integer	—	1=成功，0=失敗	—
ResultMessage	結果訊息	否	string	—	成功或錯誤原因	TODO：待工程確認 業務錯誤訊息對照表

---

核心 API 單支說明

以下為 OpenAPI JSON 已收錄之 三支核心 API 用途、流程與範例；欄位細節請見上方 JSON 欄位說明，互動測試請用 Swagger UI。

---

POST /Append/Invoices

API 用途

發票版開立：營業人系統已自行取號後，將發票主檔與明細以 JSON 送交 e首發票，完成開立、存證與後續上傳流程之起點。

使用時機

• 發票版情境：POS、ERP 或自建系統已配置字軌並產生 InvoiceID
• 交易完成（或依合約開立時點）且開立資料已備妥（買受人、稅別、金額、明細）
• 需以 API 批次或系統自動化開立，而非訂單版 Excel／訂單 API

不適合使用的情境

• 訂單版：應由 e首發票協助取號 — 請用 Swagger 之 /Append/Order、/Append/Orders 等（OpenAPI JSON 尚未收錄），或 Excel 匯入
• 尚未完成 API 開通、未取得簽章用 KEY
• 同一 InvoiceID 並行重複提交（應分批、確認前筆結果後再送）
• 僅需查詢狀態 — 請用 Inquire 相關端點（見 §1 Swagger 表）

呼叫流程

1. 完成開通並取得 KEY（見 §API 申請與開通）
2. 由來源系統組好 InvoiceData 與 Details
3. 計算 SHA256 簽章，組成外層 CompanyID、Timestamp、Signature、Data
4. POST /Append/Invoices
5. 解析回應：StatusCode、ResultMessage；成功時記錄 InvoiceID／InvoiceNumber；失敗須記錄並補送

flowchart LR
    A[準備開立資料] --> B[組裝 JSON Data]
    B --> C[計算簽章]
    C --> D[POST /Append/Invoices]
    D --> E{StatusCode}
    E -->|1| F[記錄成功並續送下一筆]
    E -->|0| G[記錄 ResultMessage 並補送]

Request 欄位

• 外層 Wrapper：見 共用外層欄位
• 業務內容 Data（InvoiceData）與明細 InvoiceDetailItem：見 開立發票欄位（Issue Invoice）

Response 欄位

重點欄位	說明
StatusCode	1 成功、0 失敗
ResultMessage	成功或錯誤原因；失敗必處理，避免漏開
InvoiceID	發票字軌號碼
InvoiceNumber	發票號碼
InvoiceDateTime	開立日期時間

完整欄位見 開立發票回應（InvoiceIssueResponse）。

範例

以下取自 einvoice-api-openapi.json 之 examples（簽章為格式範例，不可重用）。

B2B

{
  "CompanyID": "12345678",
  "Timestamp": "1677585655",
  "Signature": "4754A5FE41749DE99E82FC5502348C69781E1026064ADF7AC",
  "Data": {
    "InvoiceID": "NX25780488",
    "InvoiceDateTime": "2025-03-17T19:43:37",
    "InvoiceFor": "B",
    "BuyerID": "87654321",
    "BuyerName": "企業買家",
    "BuyerEmailAddress": "einv@einv.tw",
    "TaxType": "1",
    "SalesAmount": 5000,
    "FreeTaxSalesAmount": 0,
    "ZeroTaxSalesAmount": 0,
    "TaxAmount": 250,
    "TotalAmount": 5250,
    "Details": [
      {
        "DetailID": "001",
        "ProductName": "商品A",
        "ItemTaxType": "1",
        "Quantity": 1,
        "UnitPrice": 5000,
        "SubTotal": 5000
      }
    ]
  }
}

B2C

{
  "CompanyID": "12345678",
  "Timestamp": "1677585655",
  "Signature": "4754A5FE41749DE99E82FC5502348C69781E1026064ADF7AC",
  "Data": {
    "InvoiceID": "NX25780489",
    "InvoiceDateTime": "2025-03-17T19:45:00",
    "InvoiceFor": "C",
    "BuyerID": "0000000000",
    "BuyerEmailAddress": "einv@einv.tw",
    "TaxType": "1",
    "SalesAmount": 2000,
    "FreeTaxSalesAmount": 0,
    "ZeroTaxSalesAmount": 0,
    "TaxAmount": 0,
    "TotalAmount": 2000,
    "Details": [
      {
        "DetailID": "001",
        "ProductName": "商品B",
        "ItemTaxType": "1",
        "Quantity": 1,
        "UnitPrice": 2000,
        "SubTotal": 2000
      }
    ]
  }
}

錯誤處理

• HTTP 200 仍可能 StatusCode = 0（業務拒絕）；請依 ResultMessage 修正後重送
• StatusCode：1 成功、0 失敗（見 OpenAPI schema）
• 完整 ResultMessage 業務錯誤對照表：TODO：待工程 Errors SSOT

相關文件

• JSON 欄位說明
• 發票開立檢核作業
• F0401 欄位對應表
• FAQ：API 與串接
• 發票版開立發票流程
• 取號管理差異與選型

---

POST /Update/CancelInvoices

API 用途

作廢已開立發票：將指定發票標記作廢，支援單筆或批次（Data 為物件或陣列）。

使用時機

• 交易取消、退貨且仍於可作廢期間內
• 開立錯誤需撤銷該張發票（依稅務與合約規範）
• 需一次作廢多張發票（Data 陣列）

不適合使用的情境

• 跨期無法作廢 — 應改以 折讓（POST /Update/AllowanceInvoice）
• 發票尚未成功開立 — 不應呼叫作廢
• 僅需部分金額調整 — 應使用折讓而非作廢
• 訂單版尚未轉開立完成 — 請先確認發票狀態（Inquire 端點，見 Swagger）

呼叫流程

1. 確認目標發票號碼與作廢原因
2. 組裝 CancelInvoiceData（單筆或陣列）放入 Data
3. 計算簽章並組成完整 Request Body
4. POST /Update/CancelInvoices
5. 檢查 StatusCode、ResultMessage；批次時回應可能為陣列

flowchart LR
    A[確認可作廢] --> B[組裝 CancelInvoiceData]
    B --> C[計算簽章]
    C --> D[POST /Update/CancelInvoices]
    D --> E{StatusCode}
    E -->|1| F[記錄作廢成功]
    E -->|0| G[記錄 ResultMessage 並人工處理]

Request 欄位

• 外層 Wrapper：見 共用外層欄位
• Data（CancelInvoiceData 或陣列）：見 作廢發票欄位（Void Invoice）

Response 欄位

重點欄位	說明
StatusCode	1 成功、0 失敗
ResultMessage	成功或錯誤原因
SellerID	賣方統編
InvoiceNumber	作廢之發票號碼

單筆回傳物件；批次回傳物件陣列。完整欄位見 作廢發票回應（CancelInvoiceResponse）。

範例

TODO：待工程提供範例 payload（OpenAPI JSON 目前無作廢 Request／Response examples）。欄位結構請見 作廢發票欄位 或 Swagger UI Try it out。

錯誤處理

• StatusCode：1 成功、0 失敗
• 作廢失敗請保留 ResultMessage 供客服或補送流程使用
• 完整 ResultMessage 對照表：TODO：待工程 Errors SSOT

相關文件

• JSON 欄位說明
• F0401 欄位對應表
• FAQ：API 與串接
• 發票版開立發票流程（作廢時點）

---

POST /Update/AllowanceInvoice

API 用途

開立折讓單（電子發票折讓）：針對已開立發票進行金額或品項折讓，產生折讓證明單資料。

使用時機

• 退貨、部分退款、價格調整需開立折讓
• 跨期無法作廢時，以折讓處理稅務差異
• B2B／B2C 已開立發票需減讓金額（含應稅、零稅、免稅、混稅明細）

不適合使用的情境

• 整張發票應撤銷且仍在作廢期間 — 優先評估 作廢 API
• 原發票尚未成功開立或號碼錯誤
• 折讓金額與實際退貨不一致（將遭稽核拒絕）
• 需批次多張折讓單 — Swagger 另有 /Update/AllowanceInvoices（OpenAPI JSON 尚未收錄）

呼叫流程

1. 確認原發票號碼、折讓金額與明細稅別
2. 組裝 AllowanceData 與 Details（AllowanceDetailItem）
3. 計算簽章並組成 Request Body
4. POST /Update/AllowanceInvoice
5. 檢查 StatusCode、ResultMessage；成功時記錄 AllowanceNumber

flowchart LR
    A[確認原發票與折讓金額] --> B[組裝 AllowanceData]
    B --> C[計算簽章]
    C --> D[POST /Update/AllowanceInvoice]
    D --> E{StatusCode}
    E -->|1| F[記錄 AllowanceNumber]
    E -->|0| G[記錄 ResultMessage 並修正]

Request 欄位

• 外層 Wrapper：見 共用外層欄位
• Data（AllowanceData）與 AllowanceDetailItem：見 折讓發票欄位（Allowance Invoice）

Response 欄位

重點欄位	說明
StatusCode	1 成功、0 失敗
ResultMessage	成功或錯誤原因
SellerID	賣方統編
AllowanceNumber	折讓單號

完整欄位見 折讓發票回應（AllowanceInvoiceResponse）。

範例

TODO：待工程提供範例 payload（OpenAPI JSON 目前無折讓 Request／Response examples）。欄位結構請見 折讓發票欄位 或 Swagger UI Try it out。

錯誤處理

• StatusCode：1 成功、0 失敗
• 稅額與總計須與明細一致（見 OpenAPI AllowanceData description）；拒絕時請依 ResultMessage 處理
• 完整 ResultMessage 對照表：TODO：待工程 Errors SSOT

相關文件

• JSON 欄位說明
• 發票開立檢核作業（稅別與金額檢核概念）
• F0401 欄位對應表
• FAQ：API 與串接
• 發票版開立發票流程

---

POST /Append/PrintInvoices

OpenAPI JSON 狀態：Swagger-only（public）；規格細節以 Swagger UI 為準。
適用情境：訂單版（系統取號開立）＋雲端熱感紙列印。

API 用途

在 e首發票代為取號並開立發票（訂單版）後，由雲端依熱感紙格式組好列印資料，透過本 API 一併寫入雲端待列印佇列。門市或據點安裝的 印表伺服器（輪詢程式）自佇列取得任務後，將資料送至後台已設定之 熱感紙印表機（依設備 IP／印表機編號）輸出證明聯。

與僅開立不列印的 POST /Append/Order 相較，本 API 在開立成功後自動觸發列印佇列（系統邏輯：PrintMark 自動為 Y，並清空載具相關欄位；詳見 列印與證明聯 FAQ）。

使用時機

• 訂單版 POS、門市、便利商店：交易完成後需同時開立並印出紙本證明聯（多為 C 類）
• 已於 e首發票後台完成 雲端列印、熱感式印表機（例：EINV990／PRT 設備管理）與 印表伺服器 設定
• 多台熱感印表機並列，需以 印表機編號 指定輸出設備
• 多台印表機需共用同一組取號切本序號時，可選填 切本本號（見下方欄位）

不適合使用的情境

• 發票版（營業人自行取號）— 請用 POST /Append/Invoices 開立；僅補印／重印請用 POST /Update/RePrint、POST /Update/SecPrint
• 僅需電子載具、不需紙本證明聯 — 請用 POST /Append/Order 或 POST /Append/Orders
• 尚未完成印表機與印表伺服器設定，或門市無法連線雲端
• 僅查詢開立／列印狀態 — 請用 Inquire 相關端點（見 §1）

雲端列印架構

sequenceDiagram
    participant SRC as 來源系統<br/>（POS／訂單）
    participant API as e首發票 API<br/>/Append/PrintInvoices
    participant SIV as 開立與取號
    participant QUEUE as 雲端待列印佇列<br/>（PRT130）
    participant AGENT as 印表伺服器<br/>（門市端輪詢）
    participant PRINTER as 熱感紙印表機<br/>（依 IP／編號）

    SRC->>API: 訂單資料 ＋ PrinterNo（＋選填切本本號）
    API->>SIV: 稽核通過後取號開立
    SIV->>QUEUE: 組好列印格式並入佇列
    API-->>SRC: StatusCode／ResultMessage／發票號
    AGENT->>QUEUE: 輪詢取得待印任務
    QUEUE-->>AGENT: 列印 payload
    AGENT->>PRINTER: 送至指定印表機輸出

印表伺服器安裝需求（EPSON／STAR 等）見 常見問題：列印與證明聯。

呼叫流程

1. 完成 API 開通與簽章 KEY（見 §API 申請與開通）
2. 於後台設定熱感印表機與 印表機編號（PrinterNo），並於門市主機部署 印表伺服器 輪詢程式
3. 組裝請求：頂層為 JSON 陣列（可含一筆或多筆訂單）；每筆含 CompanyID、Timestamp、Signature、Data（訂單／發票主檔，不需預先帶 InvoiceID）
4. 在 Data 中帶入 PrinterNo（指定輸出印表機）；若多台印表機要共用同一切本序號，可選填 SalesID（切本本號）
5. POST /Append/PrintInvoices
6. 解析回應：StatusCode、ResultMessage；成功後由印表伺服器自動列印；失敗須記錄並補送

flowchart LR
    A[交易完成] --> B[組裝訂單 Data<br/>+ PrinterNo]
    B --> C[簽章 POST PrintInvoices]
    C --> D{StatusCode}
    D -->|1| E[雲端入列印佇列]
    E --> F[印表伺服器輪詢]
    F --> G[熱感紙輸出]
    D -->|0| H[依 ResultMessage 補送]

與其他開立 API 對照

項目	/Append/Order	/Append/PrintInvoices	/Append/Invoices（發票版）
取號	e首發票代為取號	e首發票代為取號	營業人自行取號
紙本證明聯	依 PrintMark；通常不列印	開立後入雲端列印佇列	依 PrintMark
PrintMark	呼叫端指定	系統自動 Y	呼叫端指定
PrinterNo	非雲端列印主路徑	建議必填（指定印表機）	非本 API 主用途
Request 頂層	單一 object 或依 Swagger	JSON array（見 Swagger）	單一 object（策展 OAS3）

Request 欄位重點（雲端列印）

除訂單版開立所需之買受人、稅別、金額、明細等欄位外，雲端列印請特別注意（欄位名稱依 Stage Swagger；細部型別以 Swagger UI 為準）：

欄位名稱	中文說明	必填	說明	備註
PrinterNo	印表機編號	是（雲端列印）	指定輸出之熱感印表機；須與後台／設備管理已設定之編號一致	Swagger InvoiceMain；補印 API 亦使用
SalesID	切本本號	否	指定取號所使用之切本（本號）；選填。多台印表機若需共用同一組發票序號，可帶相同本號	語意依產品／工程約定；Swagger 欄位名為 SalesID
PrintMark	證明聯列印標記	—	呼叫本 API 時系統邏輯自動 Y	與一般雲端列印相同，載具欄位將被清空
InvoiceID	發票字軌號碼	否	訂單版不需預先傳入；開立時由系統取號	同 /Append/Order

外層簽章欄位（CompanyID、Timestamp、Signature）與 §2 簽章規則相同。

Response 與錯誤處理

• HTTP 200 時仍以 StatusCode（1 成功、0 失敗）與 ResultMessage 判斷業務結果
• 開立成功不代表實體紙張已印出；紙張輸出依印表伺服器輪詢與印表機狀態。佇列查詢見後台 PRT130／雲端待列印發票查詢（內部模組規劃）
• 完整 ResultMessage 對照：TODO：待工程 Errors SSOT

範例（結構示意）

以下為結構示意；實際欄位與檢核以 Swagger UI 為準。簽章為格式範例，不可重用。

[
  {
    "CompanyID": "12345678",
    "Timestamp": "1677585655",
    "Signature": "<SHA256>",
    "Data": {
      "CompanyID": "12345678",
      "BillingNo": "ORD-20250610-001",
      "InvoiceFor": "C",
      "BuyerID": "0000000000",
      "BuyerEmailAddress": "buyer@example.com",
      "TaxType": "1",
      "SalesAmount": 2000,
      "TaxAmount": 0,
      "TotalAmount": 2000,
      "PrinterNo": "01",
      "SalesID": "A01",
      "Details": [
        {
          "DetailID": "001",
          "ProductName": "商品A",
          "Quantity": 1,
          "UnitPrice": 2000,
          "SubTotal": 2000,
          "ItemTaxType": "1"
        }
      ]
    }
  }
]

相關文件

• 訂單版開立發票流程（含雲端熱感列印分支）
• 取號管理差異與選型
• 常見問題：列印與證明聯
• 字軌管理常見錯誤與預防（切本概念）
• 已開立後補印／重印：POST /Update/RePrint、POST /Update/SecPrint（見 §1 Swagger 表）

---

6. 情境與 API 對應一覽（歸檔）

以下對應不同使用情境應使用的開立方式與 API；作廢、折讓為各情境共用。

情境	開立方式	對應 API 或介接	作廢／折讓
發票版	營業人系統取號後送交	POST /terpapi/Append/Invoices（本 OpenAPI 規格）	POST CancelInvoices、POST AllowanceInvoice
訂單版	e首發票取號；Excel 或訂單版介接	Excel 匯入（EINV111）或 POST /Append/Order、/Append/Orders	同上
訂單版＋雲端熱感列印	取號開立後入雲端列印佇列，印表伺服器輪詢輸出	POST /Append/PrintInvoices（見 單支說明）	同上
機台／繳款設備	訂單版 ＋ 機台號、冪等鍵	依服務商訂單版介接規範；需熱感列印時可用 PrintInvoices	同上
混合使用	依通路分流	POS 發票版 → Append/Invoices；門市熱感列印 → PrintInvoices；電商／機台 → 訂單版介接	同上

情境說明頁（含本情境 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	專案負責人	開通申請書補充申請書連結。
v1.3	2026-05-15	SystemLead	英文技術文件連結；OpenAPI 英文版 YAML／JSON。
v1.4	2026-05-15	SystemLead	英文提示增 F0401 完整表、發票開立檢核（英）連結。
v1.5	2026-06-08	SystemLead	Swagger UI 優先；OpenAPI 檔收至進階區；移除英文 YAML。
v1.6	2026-06-08	SystemLead	移除中文 YAML；OpenAPI 僅保留 JSON（中／英）。
v1.7	2026-06-08	AI	新增 JSON 欄位說明（三支核心 API）；§1 補 OpenAPI JSON／Swagger 對照註記。
v1.8	2026-06-08	AI	API-P1：三支核心 API 單支說明（用途、時機、流程、範例、錯誤處理）。
v1.9	2026-06-08	AI	API-P2a：18 支 Swagger-only 端點摘要表（OpenAPI JSON 狀態／文件狀態）。
v1.10	2026-06-08	AI	API-P2b：18 支 Swagger-only 已裁決 public；OpenAPI JSON 分階段補齊說明。
v1.11	2026-06-10	AI	PrintInvoices：雲端熱感列印用途、架構、PrinterNo／切本本號、情境對照與單支說明。