發票開立 API¶
本文對應 Swagger 中 Append 分組之開立／匯入端點。請求欄位、必填條件、稅別與明細結構請以 Swagger UI 之 Schema 為準；本頁說明情境選擇與合規注意，不複製完整模型以免與版本漂移。
先確認取號與列印責任¶
本頁介紹標準 API 的開立與匯入。POS 已自行取號時，請走發票版存檔；希望系統直接透過雲端送至指定印表機，請確認標準 API 的雲端列印流程。
若是自動販賣機、繳款機或 POS，希望取得設備列印資訊，或提供現成捐贈／歸戶頁面，請先讀 POS／自助設備 API 選用情境。不要先開立，再呼叫另一套 Append 取得列印或綁定資訊。
與標準 API Swagger 對應之端點¶
| 情境（概念） | HTTP | 路徑 | 說明 |
|---|---|---|---|
| 訂單版（由系統依訂單取號開立） | POST | /Append/Order |
單筆訂單轉發票 |
| 訂單版（批次） | POST | /Append/Orders |
多筆訂單；建議留意每筆結果與失敗訊息 |
| 發票版（營業人已取號，匯入已開立資料） | POST | /Append/Invoice |
單筆 |
| 發票版（批次） | POST | /Append/Invoices |
多筆 |
| 訂單開立並雲端列印 | POST | /Append/PrintInvoices |
依 Swagger 說明 |
| 其他 | POST | /Append/InvoiceWithCancel 等 |
見 Swagger Append 標籤 |
發票版 vs. 訂單版
誰負責發票號取號決定路徑與資料必填差異。請併讀 API 串接流程與例外設計，並以本頁端點表與當期 Swagger 確認實作。
認證與請求包裝¶
- Header：
apiKey（見 Swagger securityDefinitions）。 - Body：多為
InvoiceModel，含CompanyID、Timestamp、Signature、Data；簽章算法見 認證與金鑰管理 與 Swagger 欄位說明。
Data（發票主檔） 內含買賣方、明細、稅別、載具等；訂單版與發票版對「發票號碼、日期時間是否必填」等規則不同，以 Swagger description 為準（例如：Append Order 與 Append Invoices 之欄位限制差異）。
請求範例（結構示意）¶
以下僅示意 包裝層；Data 內欄位請勿抄寫本範例即上線，請自 Swagger 產生或對照 definitions。
POST https://{您的BaseURL}/Append/Order
apiKey: {開通後取得之KEY}
Content-Type: application/json
{
"CompanyID": "您的公司識別",
"Timestamp": "1700000000",
"Signature": "依Timestamp與HashSalt計算之SHA256十六進位字串",
"Data": {
"...": "請展開 Swagger 內 Product.EInvoice.Model.Append.InvoiceMain 等定義"
}
}
成功與失敗處理¶
實際回應模型請看 Swagger（例如 ResponseAppendInvoiceModel 等）。工程實務上請至少：
- 記錄 HTTP 狀態碼 與 回應 Body（含業務狀態／訊息欄位，名稱以 Swagger 為準）。
- 開立失敗必須進入補救流程；未處理失敗回傳可能造成 漏開發票。
- 重試前先以 Inquire 查狀態，避免重複開立。
稅別與稽核（摘要）¶
- B2B／B2C、應稅／零稅／免稅／混稅 等規則與欄位組合，以 Swagger 與 稽核／導入文件 為準。
- 訂單編號（BillingNo） 等唯一性要求，請依開通文件與 Swagger 註解。
責任邊界¶
API 可自動化開立，但串接方仍須對資料來源、授權、重試與法規適用負責。
相關文件¶
- 電子發票 API 串接指南
- API 端點與契約來源
- 發票查詢 API（Inquire）
- 認證與金鑰管理
- 常見錯誤代碼