發票開立 API¶
本文對應 Swagger 中 Append 分組之開立／匯入端點。請求欄位、必填條件、稅別與明細結構請以 Swagger UI 之 Schema 為準；本頁說明情境選擇與合規注意，不複製完整模型以免與版本漂移。
與 Swagger 對應之端點¶
| 情境（概念） | HTTP | 路徑 | 說明 |
|---|---|---|---|
| 訂單版（由系統依訂單取號開立） | POST | /Append/Order |
單筆訂單轉發票 |
| 訂單版（批次） | POST | /Append/Orders |
多筆訂單；建議留意每筆結果與失敗訊息 |
| 發票版（營業人已取號，匯入已開立資料） | POST | /Append/Invoice |
單筆 |
| 發票版（批次） | POST | /Append/Invoices |
多筆 |
| 訂單開立並雲端列印 | POST | /Append/PrintInvoices |
依 Swagger 說明 |
| 其他 | POST | /Append/InvoiceWithCancel 等 |
見 Swagger Append 標籤 |
發票版 vs. 訂單版
誰負責發票號取號決定路徑與資料必填差異。請併讀 systemlead-einvoice docs/tech/API說明與開發注意事項.md §6 情境表。
認證與請求包裝¶
- 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 可自動化開立，但串接方仍須對資料來源、授權、重試與法規適用負責。