API 概覽¶
本頁做什麼：幫開發與整合人員快速建立心智模型—對外服務叫什麼、資料怎麼傳、權威契約去哪裡查、常用功能落在哪些路徑—並指出下一步文件，減少誤接過時範例或錯端點的排查時間。
技術事實（先記這三點）：
- 服務名稱：Product.EInvoice.WebApi（對外服務 API）。
- 傳輸：HTTPS，內容為 JSON，編碼 UTF-8。
- 欄位、路徑、錯誤語意 請以本頁下方連結之 線上 Swagger 為準；本頁不逐欄複製 Schema，以免與釋出版本漂移。
和另一頁怎麼分工：需要上線前檢核、流程與角色導覽 → 請看 API 串接總覽。需要端點分組、環境與契約來源 → 留在本頁，並搭配 Swagger 使用。
契約來源：Swagger 與 OpenAPI 靜態檔¶
| 層級 | 來源 | 用途 |
|---|---|---|
| 執行期契約（整合時唯一依據） | 線上 Swagger：Swagger UI 與 /swagger/docs/v1 |
上線前驗收、Try it out、與實際釋出版本一致的欄位與路徑 |
| OpenAPI 靜態檔（參考用） | einvoice-api-openapi.yaml、API 說明與開發注意事項 | 離線查閱、申請流程與情境說明；若與 Swagger 不一致，以 Swagger 為準 |
文件與 Swagger 不一致時
若本頁或靜態 OpenAPI 檔與 線上 Swagger 內容不一致，一律以線上 Swagger 為準。請向技術窗口確認釋出版本，並依官方流程更新文件。
官方文件（必讀）¶
| 項目 | 說明 |
|---|---|
| Swagger UI（互動文件） | Product.EInvoice.WebApi - 對外服務 API |
| OpenAPI／Swagger JSON（v1，Stage） | https://jpe-sl-einvoice-erpapi-stage.azurewebsites.net/swagger/docs/v1 |
| API 名稱 | Product.EInvoice.WebApi - 對外服務 API |
| 版本 | v1 |
請以 Swagger 為準
若您看到的範例路徑、認證方式或 Webhook 描述與 Swagger 不符，請以 Swagger 為準，避免誤接錯誤端點。
環境與 Base URL¶
| 環境 | 說明 |
|---|---|
| Stage（Swagger 根網址） | https://jpe-sl-einvoice-erpapi-stage.azurewebsites.net — 用於對照 Swagger UI 與測試契約 |
| 測試／正式 | 實際 Base URL、路徑前綴（例如是否含 /terpapi 等）與 金鑰，以 API 開通同意書／服務商交付文件／合約 為準 |
串接前須完成 API 開通 並取得金鑰；申請流程與同意書以 聯絡我們 或官網最新公告為準。技術細節亦可參考 API 說明與開發注意事項。
主要 API 路徑（依 Swagger 分組）¶
以下方法均為 POST；完整參數與 Schema 請於 Swagger UI 展開各端點查閱。
Append（新增／匯入）¶
| 路徑 | 摘要 |
|---|---|
/Append/Order |
新增單筆訂單轉發票（訂單版） |
/Append/Orders |
批次新增多筆訂單轉發票 |
/Append/Invoice |
新增已開立發票資料 |
/Append/Invoices |
批次新增已開立發票資料（發票版常見） |
/Append/PrintInvoices |
傳入訂單開立發票並加入雲端列印 |
/Append/BlankCancel |
作廢空白發票 |
/Append/TrackBlank |
新增空白發票號 |
/Append/InvoiceWithCancel |
新增發票並作廢 |
Inquire（查詢）¶
| 路徑 | 摘要 |
|---|---|
/Inquire/GetInvoiceIDList |
查詢發票號碼清單 |
/Inquire/GetInvoicesStatus |
批次查詢發票處理狀態 |
/Inquire/GetInvoicesAppendStatus |
批次查詢發票新增狀態 |
Update（更新／作廢／折讓／列印）¶
| 路徑 | 摘要 |
|---|---|
/Update/Invoices |
批次更新發票資料 |
/Update/SetBlankInvoiceID |
上傳空白發票號碼資料 |
/Update/SplitInvoiceID |
設定發票號碼分割規則（Swagger 註記可能為功能開發中，請以當期規格為準） |
/Update/CancelInvoices |
批次作廢發票 |
/Update/AllowanceInvoices |
批次新增發票折讓單 |
/Update/AllowanceInvoice |
新增發票折讓單 |
/Update/CancelAllowances |
批次作廢折讓單 |
/Update/CancelAllowance |
作廢折讓單 |
/Update/RePrint |
發票重新列印 |
/Update/SecPrint |
發票補列印 |
主動通知（Webhook）
Swagger v1 未宣告由平台主動呼叫客戶 URL 的 Webhook 端點。若需掌握狀態更新，請以 Inquire 類 API 主動查詢，或依 API 開通文件／合約約定之通知機制（若有）為準。
請求體結構（概念）¶
多數 Append／Update 端點使用 InvoiceModel（或陣列）包裝，Swagger 中 required 通常包含：
CompanyID：公司識別Timestamp：時間序（Unix 時間戳概念；勿重複使用同一時間戳提交多筆）Signature：SHA256 簽章（依 Timestamp 與 Hash Salt／加密 KEY 計算；演算法步驟見 Swagger 內欄位說明）Data：發票主檔與明細（實際欄位請以 Swagger definitions 為準）
並請依 Swagger securityDefinitions 設定 Header apiKey。
串接原則（合規與營運）¶
- 合規優先：欄位、稅別、開立時點、上傳期限等須符合電子發票作業規範。
- 營運不中斷：逾時、失敗、重試、重複送出需有 SOP；開立失敗訊息務必處理，避免漏開。
- 可追溯可稽核：建議保存 StatusCode、ResultMessage（或回應內同等欄位）、請求時間、訂單編號／發票號碼與重試紀錄。
工程細節與情境對照（發票版／訂單版）可併讀 systemlead-einvoice 之 docs/tech/API說明與開發注意事項.md。
Rate Limit（速率限制）¶
每分鐘／每日上限 並未於公開 Swagger 中統一宣告；實際配額與節流行為以 合約、開通文件或服務商公告 為準。若收到 HTTP 429，應搭配退避（backoff）與狀態查詢，避免猛送造成重複開立風險。
SDK 與範例程式碼¶
社群或歷史文件可能出現範例 SDK 連結；實作前請以 Swagger 契約校對，版本與驗證方式不一致時以 官方 Swagger 為準。