API 电子签名：REST 开发者指南 2026

在您的业务应用中集成电子签名 API 从未像现在这样战略重要。本开发者指南涵盖身份验证、Webhooks 和 eIDAS 合规性的方方面面。

Certyneo 团队2026年5月5日5 分钟阅读

最后更新于 2026年5月19日

Certyneo 团队

编辑 — Certyneo · 关于 Certyneo

Scrabble tiles spell out the word adequate.

简介

在 2026 年，集成 REST 电子签名 API 已成为开发团队不可或缺的前置条件。根据 IDC 欧洲数字转型报告 2025，超过 73% 的欧洲企业已数字化至少一个合同流程，对健壮技术集成的需求呈爆炸式增长。无论您是在构建 LegalTech SaaS、ERP 还是 HR 平台，理解如何使用电子签名 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 的代码交换证明密钥）是必须的，可防止拦截攻击。

基本安全建议：

在 vault 中存储 `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 REST 的生命周期遵循状态模式（`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": "2026 Q3 服务合同", "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) ``` 绝不使用 经典字符串比较——易受时序攻击。

幂等性和重新传送管理

Webhooks 在超时或 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 迁移的技术方面和现有 Webhooks 的兼容性。

要估计集成的投资回报率，请使用我们的电子签名 ROI 计算器，该计算器整合了通过 API 自动化获得的生产力收益。

最后，如果您想进一步了解要签署的文档的自动生成，请发现我们与 REST API 原生接口的 AI 合同生成器。

适用于电子签名 API 的法律框架

集成电子签名 API 不仅是技术问题：它直接涉及编辑者和其客户在若干基础文本上的 法律责任。

欧盟法规 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（带时间戳）签名，以及 PAdES-B-LT 或 PAdES-B-LTA 以保证长期可验证性（10+ 年归档）。

签名过程中收集的个人数据（姓名、名字、电子邮件、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 — 中型工业企业中供应商合同的自动化

一家中型工业企业每年管理约 200 份供应商合同，希望消除纸质往返和占据助理每月 2 天的手动跟踪。开发团队通过以下流程将电子签名 API REST 直接集成到其业务 ERP 中：

在 ERP 中验证采购订单时，`POST /v2/signature-requests` 调用自动触发
生成的 PDF 合同被上传，签名请求发送给参考供应商联系人
`signatory.signed` Webhook 实时更新采购订单状态
已签名的文档和审计日志通过第二个 API 调用自动归档到 DMS

观察到的结果（来自 KPMG/IDC 2024-2025 行业报告的范围）：平均签名延迟从 8 天减少到不足 24 小时，节省行政跟踪时间的 60-70%，零文档丢失。

场景 2 — 律师事务所 LegalTech 平台

一家面向 5 到 30 合作人律师事务所开发 SaaS 解决方案的软件编辑集成了电子签名 API，允许其最终用户直接从办公室界面对授权书、费用协议和诉讼行为进行签署。

采用的技术架构使用 OAuth2 授权代码 + PKCE 流，使每个律师能够以自己的名义验证请求。`signature_request.completed` Webhooks 自动触发已签名文档存放在法律 GED 中的客户文件夹中。

编辑特别重视通过 API 提供 高级电子签名（AES） 的可用性 — 根据法国律师协会会议建议，费用协议所需的级别。初始集成的开发时间对于一名资深后端开发人员约为 3 周，测试覆盖率为 85%。

场景 3 — 私人诊所集团中的数字入职

一个约 600 张床位的私人诊所集团需要数字化知情同意表格和入院合同，这些合同之前在前台打印并手动签署 — 产生数千欧元的印刷成本和接待处的等待延迟。

API 集成连接了医院信息系统（HIS）与电子签名平台。在患者登记时，HIS 调用 API 创建多方签名请求（患者 + 主治医生），签名字段位置根据模板元数据自动计算。

GDPR 合规性需要实施 自动清除程序 通过 API（`PATCH /v2/signature-requests` + 删除确认 Webhook），与医疗记录法定保留期一致（根据法国公共卫生法第 R. 1112-7 条，成年人为 20 年）。测量的收益达到了入院等待时间减少 80%，印刷和扫描成本节省 40%。