API 串接總覽¶
若貴公司的系統已有訂單、出貨或金流事件，下一步通常是：何時觸發開立、失敗如何重試、退貨如何對應折讓或作廢，且日後仍查得到當時的請求與回應。本頁是開發與產品共同的快速導覽；路徑與 Schema 請以官方 Swagger 為準。
這頁適合誰¶
- 要把電子發票接進電商、OMS、ERP 的後端或整合工程師。
- 要先評估時程、環境與例外處理，再開技術細節會議的產品或技術主管。
契約真相來源（必讀）¶
正式契約應以服務開通時交付的 Swagger／OpenAPI 與開通文件為準。若倉儲內檔案、本頁或公開範例與開通交付內容不一致，請先停止實作並請工程窗口確認契約版本。完整契約對照見 API 概覽。
| 項目 | 連結／說明 |
|---|---|
| Swagger UI | Product.EInvoice.WebApi - 對外服務 API |
| OpenAPI／Swagger JSON（v1） | https://jpe-sl-einvoice-erpapi-stage.azurewebsites.net/swagger/docs/v1（Stage） |
| 倉儲內 YAML（協作主檔） | einvoice-api-openapi.yaml（systemlead-einvoice） |
請以 Swagger 校對端點
若範例出現 /v1/invoices、純 Bearer、Webhook 等描述，請以 Swagger 宣告為準再實作。
發布前須經工程審核
本頁尚未標記為 OpenAPI 已驗證。端點、認證、環境與範例在對外發布或交付客戶前，須由工程負責人依目前契約完成審核。
串接原則¶
- 合規優先：流程需符合電子發票作業規範。
- 營運不中斷：逾時、失敗、重試、重複送出需有補救劇本。
- 可追溯可稽核：保存 apiKey 以外之業務鍵、回應狀態與訊息欄位（名稱以 Swagger／實際回應為準）。
認證方式（摘要）¶
- Header
apiKey（見 Swagger securityDefinitions）。 - Body 內
CompanyID、Timestamp、Signature（SHA256，細節見 認證與金鑰管理 與 Swagger）。
主要端點（與 Swagger 分組對齊）¶
以下皆為 POST；完整清單見 API 概覽 或 Swagger。
| 功能（概念） | 路徑 | 延伸閱讀 |
|---|---|---|
| 訂單版開立（單筆） | /Append/Order |
發票開立 API |
| 訂單版開立（批次） | /Append/Orders |
同上 |
| 發票版匯入（批次） | /Append/Invoices |
同上 |
| 查詢號碼清單 | /Inquire/GetInvoiceIDList |
發票查詢 API |
| 查詢處理狀態 | /Inquire/GetInvoicesStatus |
同上 |
| 查詢新增狀態 | /Inquire/GetInvoicesAppendStatus |
同上 |
| 作廢發票 | /Update/CancelInvoices |
發票查詢 API（Update 一節） |
| 折讓 | /Update/AllowanceInvoice（等） |
同上 |
例外情境（上線前務必對齊）¶
- API 逾時或錯誤時是否重試、由誰批准重送。
- 重試是否可能造成重複開立（請與訂單狀態機一併設計；並善用 Inquire 查狀態）。
- 訂單取消、退貨、折讓、作廢如何與發票狀態對齊。
- 內部系統與加值中心狀態不同步時的補救與對帳 SOP。
環境網址¶
| 環境 | 說明 |
|---|---|
| Stage（對照 Swagger） | https://jpe-sl-einvoice-erpapi-stage.azurewebsites.net |
| 測試／正式 | Base URL 與金鑰以 API 開通／合約 為準 |
錯誤與狀態碼¶
HTTP 層與業務層欄位請以 實際回應 與 Swagger Schema 為準；一般性說明見 常見錯誤代碼。
主動通知¶
Swagger v1 未提供 Webhook；若需即時性，請以 Inquire 主動查詢為主，或向服務商確認是否有契約外之通知機制。
責任邊界¶
API 可協助自動化，但串接方仍須確認訂單資料、交易事實、授權控管、重試策略與例外處理。法規判斷以主管機關公告與專業意見為準。