跳轉到
e首發票 e首發票 官方導入指南
線上報價 後台登入

認證與金鑰管理

本文說明 Product.EInvoice.WebApi（對外服務 API）之認證要點。細節以 Swagger UI 之 securityDefinitions 與 InvoiceModel 等 Schema 為準。

認證方式（與 Swagger 對齊）

1. Header：apiKey

Swagger v1 宣告 API Key 類型驗證：

項目 說明
型別 apiKey
Header 名稱 apiKey
傳遞位置 HTTP Header

實際金鑰值於 API 開通 後由服務商提供；請勿寫死在程式碼或提交至版本庫。

2. 請求體簽章：CompanyID、Timestamp、Signature

多數作業請求採 InvoiceModel（或陣列），其中 必填 常包含：

欄位 說明
CompanyID 公司識別（與貴公司於 e首發票／服務商約定者一致）
Timestamp 時間序字串；勿以同一 Timestamp 重複提交多筆
Signature 以 SHA256 對「Timestamp 與 Hash Salt（加密 KEY） 串接後字串」雜湊，再轉為 Hex 字串（步驟見 Swagger 內欄位說明與參考連結）
Data 發票資料本體；簽章計算不包含整段任意替換之資料邏輯時，請嚴格依 Swagger 與開通文件

認證方式請以 Swagger 為準

本 API 需同時使用 Header apiKey 與請求體 CompanyID、Timestamp、Signature。若您手邊範例僅使用 Authorization: Bearer ... 而無上述欄位，請改以 Swagger UI 為準。

取得 KEY 與開通

  1. 依 「e首發票 API 測試申辦與開通使用同意書」 等流程完成開通（表單與連結以 官網或客服最新提供 為準）。
  2. 開通後取得 API KEY 及簽章用之 加密 KEY（Hash Salt）。
  3. 測試開通效期、正式環境網址 與金鑰，以當次開通／合約為準。

客服聯絡方式可參考 聯絡我們 或 systemlead-einvoice docs/tech/API說明與開發注意事項.md 所載電話／電子郵件。

沙盒 vs. 正式環境

環境 說明
Stage（對照 Swagger） https://jpe-sl-einvoice-erpapi-stage.azurewebsites.net — 用於對照 Swagger UI 與契約測試
測試／正式 Base URL、路徑前綴、金鑰與效期以 開通交付 為準；勿假設與 Stage 完全相同

安全性建議

不要將金鑰寫入程式碼

❌ 不建議：

const apiKey = "your-secret-key"; // 易外洩

✅ 建議使用環境變數或秘密管理服務：

const apiKey = process.env.EINV_API_KEY;
const hashSalt = process.env.EINV_HASH_SALT;

使用 .env 並排除版本控制

# .env（加入 .gitignore）
EINV_API_KEY=...
EINV_HASH_SALT=...

分環境管理金鑰

建議為本機、測試、正式分別建立金鑰，降低交叉污染與權限外溢風險。

金鑰輪換與停用

  1. 依服務商流程申請或產生新金鑰。
  2. 於維護視窗切換呼叫端。
  3. 確認無流量後停用舊金鑰。

若懷疑外洩，請立即停用、保留異常時間帶與端點紀錄，並聯絡客服。

主動推送（Webhook）

本對外服務 API 之 Swagger v1 未宣告 Webhook，亦無法從該規格推得「平台必定會 POST 至客戶 URL」之契約。
若您需要「狀態變更即時得知」，請以 Inquire 類端點 主動查詢 為主，或向服務商確認 是否有 獨立通知產品／文件。

責任邊界

e首發票／服務商可提供金鑰與 API 契約，但串接方仍須負責程式碼安全、憑證保存、伺服器與網路設定、錯誤處理與稽核紀錄。

相關文件