API 電子簽名：REST 開發人員指南 2026

簡介

整合 REST 電子簽名 API 已成為 2026 年開發團隊必不可少的前置條件。據 IDC 歐洲數位轉型報告 2025 指出，超過 73% 的歐洲企業已將至少一項合約流程數位化，技術整合需求呈爆發性成長。無論您正在開發 LegalTech SaaS、ERP 或人力資源平台，了解如何使用電子簽名 API — OAuth2 身份驗證、Webhooks 管理、eIDAS 合規性 — 直接決定您文件流程的品質和法律效力。本 REST 開發人員指南逐步引導您：架構、身份驗證、文件生命週期、即時 Webhooks 和安全最佳實踐。

---

REST 電子簽名 API 的架構

RESTful 原則和端點結構

精心設計的 REST 電子簽名 API 基於明確識別的資源和語義 HTTP 動詞。基本資源通常包括：

• `/documents` — PDF/DOCX 文件上傳、管理和檢索

• `/signature-requests` — 簽名請求的建立和控制

• `/signatories` — 簽署人管理和身份識別

• `/audit-trails` — 認證審計日誌檢索

• `/templates` — 可重複使用的文件範本管理

每個資源公開標準 CRUD 端點（`GET`、`POST`、`PUT`、`PATCH`、`DELETE`）並返回帶有標準化 HTTP 代碼的 JSON 回應：`200 OK`、`201 Created`、`400 Bad Request`、`401 Unauthorized`、`422 Unprocessable Entity`、`429 Too Many Requests`。

經常被忽視的一個關鍵方面是分頁管理。成熟的 API 使用基於游標的模式而非偏移/限制，這確保即使在數千個已簽署文件的卷上也能保持穩定的效能。驗證目標 API 是否暴露 `X-Next-Cursor` 標頭或正文中的 `next_page_token` 欄位。

API 版本控制和向後相容性

版本控制是整合商需要特別注意的重點。2026 年主導的兩種方法是：

• URL 版本控制：`https://api.certyneo.com/v2/signature-requests` — 易讀、可被 CDN 快取、推薦用於 B2B API。

• 標頭版本控制：`Accept: application/vnd.certyneo.v2+json` — 架構上更簡潔但可見性較低。

優先考慮承諾最少 12 個月貶值政策並發佈公共變更日誌的供應商。簽名流中未宣佈的相容性中斷可能產生直接的法律後果（合約未簽署、截止日期錯過）。

---

OAuth2 身份驗證和 API 呼叫安全

OAuth2：client_credentials 與 authorization_code 流程

身份驗證是任何電子簽名 API 整合的基石。對開發人員最相關的兩個 OAuth2 流程是：

客戶端認證流程（M2M — 機器對機器）：``` POST /oauth/token Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET &scope=documents:write signature_requests:write audit_trails:read ``` 此流程適合伺服器對伺服器整合，其中身份驗證中不涉及最終使用者（批次處理、合約自動化）。

授權碼流程 + PKCE：當您的應用程式代表已識別的最終使用者行動時推薦。PKCE（代碼交換的證明金鑰）自 RFC 7636 起強制執行，可防止攔截攻擊。

基本安全建議：

• 將 `client_secret` 儲存在保管庫（HashiCorp Vault、AWS Secrets Manager）— 絕不在未加密的環境變數中

• 實施自動權杖輪換，在過期前 60 秒有緩衝區

• 使用細粒度範圍：僅要求嚴格必要的權限

API 金鑰管理和速率限制

對於輕量級整合或測試環境，某些 API 提供靜態 API 金鑰（Bearer Token）。如果在生產中使用，系統地應用：

• 季度金鑰輪換

• 按 IP 限制（允許清單）

• 透過 SIEM 監控異常呼叫

速率限制是不可避免的現實：簽名 API 通常根據計劃限制在每分鐘 100 至 1000 個呼叫。實施帶抖動的指數重試機制： ``` retry_delay = base_delay * (2^attempt) + random_jitter ``` 嚴格尊重與 `429 Too Many Requests` 一起返回的 `Retry-After` 標頭。

---

透過 API 的簽名請求生命週期

簽名請求的建立和配置

簽名請求透過 API 的生命週期遵循狀態模式（`draft` → `pending` → `in_progress` → `completed` | `declined` | `expired`）。以下是詳細的技術步驟：

步驟 1 — 文件上傳： ``` POST /v2/documents Content-Type: multipart/form-data

file=@contrat.pdf ``` 回應：`{ "document_id": "doc_a1b2c3", "checksum_sha256": "e3b0c442..." }`

步驟 2 — 建立請求： ```json POST /v2/signature-requests { "document_id": "doc_a1b2c3", "name": "Contrat de prestation Q3 2026", "signatories": [ { "email": "signataire@client.fr", "first_name": "Marie", "last_name": "Dupont", "signature_level": "advanced", "fields": [{ "type": "signature", "page": 3, "x": 120, "y": 680 }] } ], "expiry_date": "2026-06-05T23:59:59Z", "reminder_settings": { "enabled": true, "frequency_days": 3 } } ```

步驟 3 — 啟用：`POST /v2/signature-requests/req_x9y8z7/activate`

啟用後，簽署人收到邀請，請求進入 `in_progress` 狀態。

檢索已簽署文件和審計追蹤

達到 `completed` 狀態後（可透過 Webhook 檢測 — 見下一節），檢索：

``` GET /v2/signature-requests/req_x9y8z7/document/signed → 帶嵌入式電子簽名的已簽署 PDF（PAdES-B-T 根據 ETSI EN 319 132）

GET /v2/signature-requests/req_x9y8z7/audit-trail → 認證審計日誌 PDF（RFC 3161 合格時間戳記） ```

始終將兩個檔案一起儲存在您的 GED 或 DMS 中。審計日誌是司法爭議中的相反證據。

---

Webhooks：即時事件和錯誤處理

Webhook 配置和安全性

Webhooks 將您的整合從昂貴的輪詢轉變為反應式事件架構。配置您的 Webhook 端點：

``` POST /v2/webhooks { "url": "https://votre-app.com/hooks/certyneo", "events": [ "signature_request.completed", "signature_request.declined", "signatory.signed", "signature_request.expired" ], "secret": "whsec_votre_secret_hmac" } ```

強制 HMAC 安全性：透過比較計算的 HMAC-SHA256 簽名與 `X-Certyneo-Signature` 標頭來驗證每個傳入的有效負載： ```python import hmac, hashlib

def verify_webhook(payload: bytes, secret: str, signature_header: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature_header) ``` 絕不使用標準字串比較 — 容易受到計時攻擊。

冪等性和重新傳遞管理

Webhook 可能在超時或來自您端點的 5xx 錯誤時重新傳遞。強制實施冪等性：

• 從每個 Webhook 有效負載提取唯一的 `event_id`

• 檢查此 `event_id` 是否已在資料庫中處理

• 立即返回 `200 OK`（即使重複）以避免無限重新傳遞

• 以非同步方式處理業務邏輯（佇列：Redis、RabbitMQ、SQS）

黃金法則：您的 Webhook 端點必須在 5 秒內回應。任何繁重的業務處理（傳送電子郵件、GED 存檔、ERP 通知）應委派給非同步工作流程。

若要深入瞭解透過 API 可用的簽名級別，請查閱我們的 電子簽名完整指南，其中詳細說明簡單、進階和合格簽名之間的差異。

---

整合最佳實踐和效能

沙箱環境和測試策略

任何認真的電子簽名 API 都應提供與生產隔離的沙箱環境。採用此測試策略：

• 單位測試：模擬 API 回應（Wiremock、MSW）以驗證業務邏輯而不依賴網路

• 整合測試：針對實際沙箱執行以驗證完整生命週期（建立 → 簽署 → 檢索）

• 負載測試：模擬同時請求尖峰以識別生產前的瓶頸

• 混亂測試：模擬超時和 5xx 錯誤以驗證重試邏輯

絕不在生產環境中使用真實簽署人身份進行測試。在沙箱中建立的電子簽名沒有法律效力，這正是您測試所需的。

監控、可觀測性和警報

在生產中，使用以下工具檢測您的整合：

• 指標：API 呼叫成功率、延遲 p95/p99、每個端點的錯誤率

• 分佈式追蹤：在標頭中傳播 `trace-id` 以關聯您的日誌與供應商 API 日誌

• 警報：如果錯誤率超過 1% 或 p99 延遲超過 3 秒，則觸發警報

查閱我們的 電子簽名解決方案比較 以評估不同供應商提供的可用性 SLA（正常運行時間） — 在 API 整合期間經常被低估的標準。

如果您從另一個平台遷移，我們的指南 如何從 DocuSign 或 YouSign 遷移至 Certyneo 涵蓋 API 遷移的技術方面和現有 Webhook 的相容性。

若要估計整合的投資回報率，請使用我們的 電子簽名 ROI 計算機，其中整合了透過 API 自動化相關的生產力收益。

最後，如果您想進一步探索要簽署的文件的自動化生成，請探索我們的 AI 合約產生器，它與我們的 REST API 本機整合。

適用於電子簽名 API 的法律框架

電子簽名 API 的整合不限於技術問題：它直接涉及編輯和用戶端對多個基礎文本的法律責任。

eIDAS 規例 910/2014 和 eIDAS 2.0

規例 (EU) 910/2014 (eIDAS) 為歐盟內電子簽名建立法律框架。它區分三個級別：

• 簡單電子簽名 (SES)：最低法律值，適合低風險行為

• 進階電子簽名 (AES)：與簽署人唯一相關，從其專有控制下的資料建立 — eIDAS 第 26 條

• 合格電子簽名 (QES)：在整個歐盟相當於手寫簽名 — eIDAS 第 25 條第 2 款

隨著eIDAS 2.0 規例（歐盟規例 2024/1183）的逐步實施，開發人員必須預期在身份驗證流程中整合歐洲數位身份錢包 (EUDIW)。查閱我們的 eIDAS 2.0 指南 了解詳細技術影響。

法國民法典 — 第 1366 和 1367 條

根據法國民法典第 1366 條，「電子書寫與紙上書寫具有相同的證明力，但須能適當識別其來源人員，並以能保證其完整性的方式建立和保存」。

第 1367 條明確可靠電子簽名的條件：簽署人識別和文件完整性保證。這些要求在技術上轉化為保存認證審計日誌和簽名期間使用的身份證明的義務 — API 必須公開且您必須儲存的元素。

ETSI EN 319 132 標準 — PAdES

符合 eIDAS 的 PDF 簽名的強制技術格式是 PAdES（PDF 進階電子簽名），由 ETSI EN 319 132 標準定義。您的 API 必須至少產生 PAdES-B-T 簽名（帶時間戳記），以及保證長期有效性（10+ 年存檔）的 PAdES-B-LT 或 PAdES-B-LTA。

GDPR 2016/679 — 簽署人資料

簽名流程期間收集的個人資料（姓名、名字、電郵、IP 地址、AES/QES 身份資料）構成個人資料受 GDPR 約束。作為資料控制者或處理者的義務包括：

• 定義有理由的保留期（通常符合訴訟時效期：民事為 5 年）

• 透過 API 提供自動清除機制（`DELETE /v2/signature-requests/{id}/personal-data`）

• 在資料處理活動登記中記錄處理（GDPR 第 30 條）

• 與 API 供應商簽訂 DPA（資料處理協議）

NIS2 指令和服務連續性

對於被 NIS2 指令 (2022/2555) 視為必要或重要實體的軟體編輯，與第三方 API 的整合建立依賴，必須在供應鏈網路安全風險分析中記錄。要求您的 API 供應商提供 SOC 2 Type II 認證和 ≥ 99.9% 的可用性 SLA。

使用案例：電子簽名 API 實踐

案例 1 — 工業 SME 供應商合約自動化

一家工業 SME 管理約 200 份年度供應商合約，希望消除紙張往返和手動提醒，其消耗行政助理每月 2 天。開發團隊透過以下流程將電子簽名 API REST 直接整合到其 ERP 系統中：

• 驗證 ERP 中的採購訂單時，自動觸發 `POST /v2/signature-requests` 呼叫

• 生成的 PDF 合約已上傳，簽名請求發送至參考的供應商聯絡人

• Webhook `signatory.signed` 實時更新採購訂單狀態

• 已簽署文件和審計日誌透過第二個 API 呼叫自動存檔到 DMS

觀察到的結果（KPMG/IDC 2024-2025 部門報告範圍）：平均簽名延遲從 8 天減少至少於 24 小時、行政時間成本節省估計 60-70%、文件零遺失。

案例 2 — 律師事務所 LegalTech 平台

開發專為 5 至 30 人律師事務所量身打造之 SaaS 軟體解決方案的編輯整合了電子簽名 API，使其最終使用者能夠直接從事務所介面簽署授權書、費用協議和程序檔案。

所選技術架構使用 OAuth2 授權碼 + PKCE 流程，以便每位律師以其名義驗證請求。Webhook `signature_request.completed` 自動將已簽署文件存入法律 GED 的用戶端資料夾。

編輯特別重視透過 API 提供 進階電子簽名 (AES) 的可用性 — 根據國家律師委員會建議，費用協議所需的級別。初始整合的開發時間為高級後端開發人員約 3 週，測試覆蓋率達 85%。

案例 3 — 私人診所集團數位登記

約 600 床位的私人診所集團需要將知情同意表格和入院合約數位化，之前在掛號處列印和手簽 — 產生估計數千歐元的列印成本和掛號等待延遲。

API 整合連接醫院資訊系統 (HIS) 與電子簽名平台。患者登記時，HIS 呼叫 API 建立多方簽名請求（患者 + 主治醫師），簽名欄位位置根據範本元資料自動計算。

GDPR 合規需要實施透過 API 的自動清除排程（`PATCH /v2/signature-requests` + 刪除確認 Webhook），符合法律記錄保留期（根據公共衛生法典第 R. 1112-7 條，成人 20 年）。測量的收益達到入院等待時間減少 80%，列印和掃描成本節省 40%。

結論

在 2026 年整合 REST 電子簽名 API 需要同時掌握多個方面：穩健的 RESTful 架構、安全的 OAuth2 身份驗證、透過 Webhooks 的事件管理，以及 eIDAS 和 GDPR 要求的合規性。從整合設計階段預期這些問題的開發人員可避免昂貴的重構和主要法律風險。

需記住的三個支柱：保護您的 API 呼叫（OAuth2 + 最小範圍 + 保管庫）、以非同步和冪等方式處理事件透過 Webhooks，以及系統地存檔簽署文件及其認證審計日誌。

Certyneo 提供記錄完善的 REST API、符合 eIDAS、免費沙箱和專門開發人員技術支援。建立 Certyneo 帳戶 以取得沙箱 API 金鑰並立即開始整合。