开放平台接入文档

  ____             _   ____            _ 
 / ___|  ___  __ _| | / ___| _   _ ___| |_ ___ _ __ ___  
 \___ \ / _ \/ _` | | \___ \| | | / __| __/ _ \ '_ ` _ \ 
  ___) |  __/ (_| | |  ___) | |_| \__ \ ||  __/ | | | | |
 |____/ \___|\__,_|_| |____/ \__, |___/\__\___|_| |_| |_|
                             |___/

企业级电子印章管理与合同签署系统

作者： 小华同学 ai
官网： https://s.leepm.com
版本： v1.6.0

概述

Contract.Pro 开放平台为第三方系统提供电子合同签署能力的集成方案。无论你是想通过 API 快速对接、使用 SDK 简化开发，还是将整套系统私有化部署到自己的服务器，Contract.Pro 都能满足。

开放平台提供的核心能力：

能力	说明
合同签署	基于模板创建签署任务，支持多方签署
签署页面	提供开箱即用的签署页面（seal-core），支持 iframe / WebView 嵌入
状态通知	通过 Webhook 实时推送签署状态变更
文件管理	合同 PDF 生成、签章合成、已签署文件下载
安全保障	多种认证模式、数据隔离、IP 白名单、请求限流

你不需要自己开发签署页面。 Contract.Pro 提供完整的签署页面（seal-core），包含 PDF 预览、签名绘制、印章盖章等全部签署交互。你只需要将签署链接嵌入到自己的系统中即可。

整体架构：

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  你的系统                          Contract.Pro 开放平台              │
│                                                                     │
│  ┌──────────────┐                 ┌──────────────────────────────┐  │
│  │  业务系统     │  API / SDK      │  Open API 服务               │  │
│  │  (你开发)     │ ──────────────→ │  - 签署任务管理               │  │
│  │              │ ←────────────── │  - Webhook 回调               │  │
│  └──────┬───────┘                 │  - 文件下载                   │  │
│         │                         └──────────┬───────────────────┘  │
│         │ 嵌入 signUrl                        │                      │
│         ▼                                    ▼                      │
│  ┌──────────────┐                 ┌──────────────────────────────┐  │
│  │  你的前端页面  │   iframe /      │  签署页面 (seal-core)         │  │
│  │  (你开发)     │   WebView       │  (Contract.Pro 提供，开箱即用) │  │
│  └──────────────┘                 └──────────────────────────────┘  │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

API 对接基本信息（当前已支持的接入方式）：

项目	说明
Base URL	`https://your-domain.com/open-api`
协议	HTTPS
数据格式	JSON
字符编码	UTF-8

接入方式选择

Contract.Pro 提供三种接入方式，适用于不同的业务场景和技术能力。请根据你的需求选择合适的方式。

方式总览

接入方式	接入难度	开发周期	适用场景	签署页面	当前状态
API 对接	★★☆	1-3 天	已有业务系统，需要嵌入签署能力	使用 Contract.Pro 提供的签署页面（seal-core）	✅ 已支持
SDK 对接（Spring Boot Starter）	★☆☆	0.5-1 天	Spring Boot 项目深度集成，将签署能力嵌入自己的系统	使用 Contract.Pro 提供的签署页面（seal-core）	✅ 已支持
私有化部署	★★★★	1-2 周	数据安全要求极高，需完全自主可控	全部自有	📋 企业版

方式一：API 对接（本文档重点）

通过 HTTP RESTful API 直接调用 Contract.Pro 的签署服务。这是当前推荐的标准接入方式。

工作原理：

┌─────────────────────────────────────────────────────────────────┐
│  你需要开发的部分                                                  │
│                                                                 │
│  ┌──────────────┐    HTTP API    ┌──────────────────────────┐   │
│  │  你的业务系统  │ ─────────────→ │  Contract.Pro Open API   │   │
│  │              │ ←───────────── │  (后端服务)               │   │
│  │  - 调用 API   │               └──────────┬───────────────┘   │
│  │  - 处理回调   │                           │                   │
│  │  - 业务页面   │                           │                   │
│  └──────┬───────┘                           │                   │
│         │                                   │                   │
│         │ 嵌入 signUrl                       │                   │
│         ▼                                   ▼                   │
│  ┌──────────────┐               ┌──────────────────────────┐   │
│  │  你的前端页面  │    iframe /   │  签署页面 (seal-core)     │   │
│  │  (合同列表等) │    WebView    │  ← Contract.Pro 提供     │   │
│  └──────────────┘               │  ← 你不需要开发这部分     │   │
│                                 └──────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

你需要开发：

调用 Open API 的后端逻辑（创建任务、查询状态、处理 Webhook 回调）

你自己系统内的业务页面（合同列表、状态展示、操作入口等）

将签署链接（signUrl）嵌入到你的页面中（iframe / WebView / 直接跳转）

你不需要开发：

签署页面（seal-core 提供，包含 PDF 预览、签名绘制、印章盖章等全部签署交互）

PDF 处理逻辑（合同生成、签章合成、文件存储等由 Contract.Pro 后端处理）

短信通知（notifyChannel: "platform" 模式下由平台自动发送）

适用场景：

HR 系统集成合同签署功能

CRM 系统嵌入合同签约流程

ERP 系统对接采购/销售合同签署

任何已有业务系统需要增加电子签署能力

方式二：SDK 对接（Spring Boot Starter）

通过 Maven 依赖引入 yudao-module-seal-spring-boot-starter，将完整的电子签署能力嵌入你的 Spring Boot 项目。Seal 模块的 Controller、Service、数据访问层全部通过 Spring Boot 自动配置注册到你的应用中，数据存储在你自己的数据库里。

本质上，SDK 对接 = 把 Seal 模块跑在你自己的 JVM 里，用你自己的数据库和存储。与 API 对接的区别是：API 对接调用的是远程服务，SDK 对接是本地方法调用。

工作原理：

┌─────────────────────────────────────────────────────────────────┐
│  你的 Spring Boot 项目                                           │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  1. 添加 Maven 依赖                                       │   │
│  │     yudao-module-seal-spring-boot-starter                │   │
│  │     (自动传递依赖 seal-api + seal-biz)                    │   │
│  └──────────────────────────────────────────────────────────┘   │
│                          ↓                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  2. 配置 application.yml（可选，Starter 已内置默认配置）    │   │
│  │     yudao.seal.auth.type=jwt / oauth2 / custom            │   │
│  │     yudao.seal.storage.type=local / oss / minio           │   │
│  │                                                           │   │
│  │     ℹ️ mode=starter 由 Starter JAR 内置配置自动设置，      │   │
│  │        你不需要手动配置这个值                                │   │
│  └──────────────────────────────────────────────────────────┘   │
│                          ↓                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  3. (可选) 实现自定义 SPI 接口                              │   │
│  │     @Component                                            │   │
│  │     class MyAuthProvider implements SealAuthProvider {...} │   │
│  └──────────────────────────────────────────────────────────┘   │
│                          ↓                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  自动装配流程（引入 Starter 后自动完成）                     │   │
│  │                                                           │   │
│  │  Starter JAR 内置 mode=starter                            │   │
│  │       ↓ 触发                                              │   │
│  │  SealAutoConfiguration 生效                                │   │
│  │       ↓ 扫描并注册                                         │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────────────┐  │   │
│  │  │ 认证适配器  │→ │ Controller │→ │ Service + 数据层    │  │   │
│  │  │ 存储适配器  │  │ 自动暴露   │  │ 自动注册            │  │   │
│  │  │ 用户验证器  │  │            │  │                    │  │   │
│  │  └────────────┘  └────────────┘  └────────────────────┘  │   │
│  │                                                           │   │
│  │  同时，seal-biz 通过 SealConfigurationLoader 自动加载      │   │
│  │  application-seal.yaml（模块默认配置）                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  你的数据库 (MySQL)  │  你的缓存 (Redis)  │  你的存储 (本地/OSS) │
└─────────────────────────────────────────────────────────────────┘

双模式架构说明：

Seal 模块采用「双模式」设计，同一套代码支持两种运行方式：

	内部模式（direct）	Starter 模式（starter）
使用者	Contract.Pro 自身（yudao-seal-server）	第三方客户
依赖方式	直接依赖 `seal-biz`	依赖 `seal-spring-boot-starter`
模式值	`mode=direct`（默认值，不设置即生效）	`mode=starter`（Starter JAR 内置，自动生效）
自动配置	`SealAutoConfiguration` 不生效	`SealAutoConfiguration` 生效
认证方式	Ruoyi Security 框架	Starter 提供的适配器（JWT/OAuth2/自定义）
配置加载	`application-seal.yaml`（通过 `SealConfigurationLoader`）	`application-seal.yaml` + Starter 内置 `application.yml`

mode 的切换是自动的：引入 Starter 依赖 → Starter JAR 里的 application.yml 设置了 mode: starter → SealAutoConfiguration 的 @ConditionalOnProperty 条件满足 → 自动配置生效。你不需要手动设置 mode。

前置条件：

Java 1.8+ 的 Spring Boot 2.7.x 项目

MySQL 5.7+ / 8.0+（需要导入 Seal 模块的数据表，SQL 脚本在 sql/ 目录）

Redis 6.0+（用于缓存和分布式锁）

Step 1：添加 Maven 依赖

只需引入一个 Starter 依赖（它会自动传递依赖 seal-api 和 seal-biz）：

<dependency>
    <groupId>cn.iocoder.boot</groupId>
    <artifactId>yudao-module-seal-spring-boot-starter</artifactId>
    <version>${seal.version}</version>
</dependency>

seal-api 模块是开源的，包含所有 SPI 接口定义和标准 DTO。seal-biz 和 seal-spring-boot-starter 是闭源的商业模块。

Step 2：配置 application.yml

引入 Starter 依赖后，mode: starter 由 Starter JAR 内置配置自动设置，你不需要手动配置。你只需要根据自己的需求配置认证方式和存储方式：

配置优先级：你的 application.yml > Starter 内置 application.yml > application-seal.yaml（模块默认配置）。你在自己的配置文件中设置的值会覆盖 Starter 和模块的默认值。

Step 3（按需）：实现自定义认证

如果内置的 JWT / OAuth2 适配器不满足需求，实现 SealAuthProvider 接口：

Step 4：导入数据库表结构，启动项目。

启动成功后会看到 Seal 模块的 Banner 和配置信息日志：

  ____             _   ____            _
 / ___|  ___  __ _| | / ___| _   _ ___| |_ ___ _ __ ___
 \___ \ / _ \/ _` | | \___ \| | | / __| __/ _ \ '_ ` _ \
  ___) |  __/ (_| | |  ___) | |_| \__ \ ||  __/ | | | | |
 |____/ \___|\__,_|_| |____/ \__, |___/\__\___|_| |_| |_|
                               |___/
 :: Seal电子印章系统 ::        (v2.0.0)

Seal 模块配置信息：
  - 集成模式: starter (Starter自动配置已启用)
  - 认证方式: jwt
  - 存储方式: local

核心 SPI 接口（全部定义在 seal-api 模块，开源）：

接口	说明	内置实现
`SealAuthProvider`	认证提供者，从 `SealAuthContext` 中提取用户信息	JwtAuthAdapter、OAuth2AuthAdapter、RuoyiAuthAdapter
`SealStorageProvider`	文件存储，管理合同 PDF / 印章图片等文件	LocalStorageAdapter、OssStorageAdapter、MinioStorageAdapter、RuoyiFileClientAdapter
`SealUserValidator`	用户验证器，校验 userId 是否存在且可用	RuoyiUserValidator、NoOpUserValidator
`SealQuotaValidator`	配额验证器，校验签署配额是否充足	RuoyiQuotaValidator、NoOpQuotaValidator
`SealSignTaskApi`	签署任务 API，可在代码中直接调用（创建任务、查询状态、下载文件）	框架内置实现

内置认证适配器及装配条件：

适配器	装配条件	适用场景
`JwtAuthAdapter`	`yudao.seal.auth.type=jwt`	标准 JWT Token 认证，从 `Authorization: Bearer {jwt}` 提取，JWT Payload 需包含 `userId`、`tenantId`
`OAuth2AuthAdapter`	`yudao.seal.auth.type=oauth2`	Spring Security OAuth2 项目，从 `SecurityContextHolder` 获取认证信息
`RuoyiAuthAdapter`	classpath 中存在 `SecurityFrameworkUtils` 类时自动启用	Ruoyi-Vue-Pro 框架项目，直接从 Ruoyi 的 SecurityContext 获取 `LoginUser`
自定义	实现 `SealAuthProvider` 接口并注册为 `@Component`	以上都不满足时，自行实现认证逻辑

注意：RuoyiAuthAdapter 的装配条件是 @ConditionalOnClass（检测 classpath），不是配置项。如果你的项目引入了 Ruoyi Security 模块，它会自动生效，优先级高于配置的 type。

内置存储适配器：

适配器	装配条件	说明
`LocalStorageAdapter`	`yudao.seal.storage.type=local`	本地磁盘存储，适合开发测试
`OssStorageAdapter`	`yudao.seal.storage.type=oss`	阿里云 OSS，需配置 endpoint / accessKeyId / accessKeySecret / bucketName
`MinioStorageAdapter`	`yudao.seal.storage.type=minio`	MinIO 对象存储，支持私有化部署，自动创建 Bucket
`RuoyiFileClientAdapter`	手动注入（需要 Ruoyi 的 `FileClient` Bean）	复用 Ruoyi 框架的文件存储体系（支持 S3、FTP、SFTP、DB 等）

完整配置参考（所有可配置项）：

SDK 对接与 API 对接的区别：

对比项	API 对接	SDK 对接（Spring Boot Starter）
集成方式	HTTP RESTful 调用远程服务	Maven 依赖，嵌入你的应用进程
认证处理	自行管理 AppKey/SecretKey/Token	SPI 接口自动适配你的认证体系
数据存储	数据在 Contract.Pro 平台	数据在你自己的数据库
文件存储	由平台管理	你自己选择存储方式（本地/OSS/MinIO）
签署页面	使用 seal-core（不变）	使用 seal-core（不变）
适用语言	任何语言（HTTP 调用）	仅 Java（Spring Boot 2.7.x）
扩展性	受限于 API 能力	可深度定制（5 个 SPI 接口可扩展）
数据隔离	按 AppKey 隔离	按你的租户体系隔离（tenantId）
运维	无需运维签署服务	需要自行运维（数据库、Redis、存储）

在代码中直接调用签署能力（SealSignTaskApi）：

SDK 模式下，你可以在代码中直接注入 SealSignTaskApi 调用签署能力，无需走 HTTP：

附加能力：

健康检查：集成 Spring Boot Actuator 后，访问 GET /actuator/health/seal 可查看 Seal 模块状态

Bean 加载日志：启动时自动打印已加载的认证适配器和存储适配器

License 验证：支持试用版（限时限量）和正式版（License 文件授权）

示例项目：

examples/ 目录下提供了 5 个开箱即用的示例项目：

示例	难度	认证方式	文件存储	适用场景
`example-minimal`	⭐	JWT	本地	快速验证，3 分钟启动
`example-springboot`	⭐⭐	JWT	阿里云 OSS	标准 Spring Boot 生产项目
`example-ruoyi`	⭐⭐	Ruoyi（自动检测）	Ruoyi FileClient	Ruoyi-Vue-Pro 项目无缝集成
`example-microservice`	⭐⭐⭐	OAuth2	OSS	Spring Cloud 微服务架构
`example-docker`	⭐⭐	JWT	本地/OSS	Docker Compose 一键部署

详细的 SDK 集成指南请参考 COMMERCIAL_INTEGRATION_GUIDE.md，示例项目说明请参考 examples/README.md。

方式三：私有化部署（企业版）

将 Contract.Pro 整套系统部署到你自己的服务器，包括后端服务、签署页面、管理后台。适合对数据安全有极高要求的企业。

包含内容：

Contract.Pro 后端服务（ruoyi-vue-pro + yudao-module-seal）

签署页面（seal-core）

管理后台前端

移动端应用（mini-contract，可选）

部署文档和技术支持

你需要准备：

服务器环境（Linux + Docker / K8s）

MySQL 5.7+ / 8.0+

Redis 6.0+

域名和 HTTPS 证书

对象存储（OSS / MinIO，用于合同文件存储）

快速体验： 可以先通过 examples/example-docker/ 中的 Docker Compose 示例快速搭建一套完整环境进行评估。

私有化部署方案请联系商务团队：shawn@leepm.com

如何选择？

你有自己的业务系统，想嵌入签署能力？
  └─ 是 → 你的项目是 Spring Boot 吗？
  │        └─ 是 → 方式二：SDK 对接（Spring Boot Starter，最省事）
  │        └─ 否 → 方式一：API 对接（通用方案，支持任何语言）
  └─ 否 → 你需要完全自主可控？
           └─ 是 → 方式三：私有化部署
           └─ 否 → 直接使用 Contract.Pro 平台即可，无需对接

本文档后续内容以「方式一：API 对接」为主。SDK 对接的详细指南请参考 COMMERCIAL_INTEGRATION_GUIDE.md 和 examples/README.md。

前置条件

在调用 Open API 之前，你需要在 Contract.Pro 管理后台完成以下准备工作。每一步都是必须的，缺少任何一步都会导致接口调用失败。

前置条件一：拥有管理后台账号

你需要一个 Contract.Pro 管理后台的管理员账号。

管理后台地址： https://your-domain.com/admin

登录方式： 管理员账号密码登录

所需权限： 需要拥有 seal:api-key:create、seal:template:create 等权限

如果你是第三方开发者，请联系 Contract.Pro 的运营方为你开通管理后台账号并分配相应权限。

前置条件二：创建 API 密钥（获取 AppKey / SecretKey）

API 密钥是调用 Open API 的身份凭证，所有接口都需要通过 AppKey + SecretKey 进行认证。

操作路径： 管理后台 → API 密钥管理 → 创建密钥

操作步骤：

登录管理后台

进入左侧菜单「API 密钥管理」

点击「新增」按钮

填写应用名称（如：HR系统对接、CRM集成），用于标识这组密钥的用途

点击「确定」，系统自动生成 AppKey 和 SecretKey

创建成功后你会得到：

字段	格式示例	说明
AppKey	`ak_xxxxxxxxxxxxxxxx`	API 密钥标识，可多次查看
SecretKey	`sk_xxxxxxxxxxxxxxxx`	API 密钥密码，仅创建时展示一次

⚠️ 重要提醒： SecretKey 仅在创建时展示一次，之后无法再次查看。请在创建后立即复制并妥善保存到安全的地方（如密钥管理系统、加密配置文件）。如果遗失，只能删除后重新创建。

密钥状态管理：

状态值	说明	影响
0	启用（默认）	正常调用 API
1	禁用	所有使用该密钥的请求将返回 `API_KEY_DISABLED` 错误

管理员可以随时在后台启用/禁用密钥，无需删除重建。

前置条件三：创建合同模板（获取 templateId）

Open API 创建签署任务时必须指定一个合同模板。模板定义了合同的 PDF 内容、表单字段和签署位。

操作路径： 管理后台 → 合同模板管理 → 创建模板

操作步骤：

进入左侧菜单「合同模板管理」

点击「新增模板」

上传合同 PDF 文件（或使用在线编辑器创建）

配置表单字段（如：姓名、金额、日期等可填充字段）

配置签署方（如：甲方、乙方）及签署位置

发布模板

创建成功后你会得到：

字段	说明
templateId	模板 ID（数字），创建签署任务时需要传入
表单字段名列表	模板中定义的可填充字段名，用于 `formData` 参数
签署方列表	模板中定义的签署方角色名（如「甲方」「乙方」），用于 `participants.signatoryName` 参数

模板中的表单字段名和签署方角色名，在调用 API 创建签署任务时需要精确匹配。建议在模板创建完成后，记录这些信息供开发时使用。

前置条件四（可选）：配置 IP 白名单

为了提高安全性，可以为 API 密钥配置 IP 白名单。配置后，只有白名单内的 IP 地址才能调用 API。

操作路径： 管理后台 → IP 白名单管理

操作步骤：

进入「IP 白名单管理」

选择要配置的 API 密钥

添加允许访问的 IP 地址

支持的 IP 格式：

格式	示例	说明
单个 IP	`203.0.113.50`	精确匹配一个 IP
CIDR 网段	`203.0.113.0/24`	匹配一个网段内的所有 IP

如果不配置 IP 白名单，则不限制来源 IP（所有 IP 均可访问）。生产环境强烈建议配置。

前置条件五（可选）：准备 Webhook 回调地址

如果你希望实时接收签署状态变更通知（推荐），需要在你的系统中准备一个 HTTP(S) 回调接口。

回调接口要求：

要求	说明
协议	建议 HTTPS，支持 HTTP
方法	POST
响应时间	必须在 10 秒内返回 HTTP 2xx
公网可达	回调地址必须能被 Contract.Pro 服务器访问到

Webhook 配置可以在创建签署任务时通过 callbackUrl 参数指定（任务级别），也可以通过 API 配置全局 Webhook。详见 Webhook 回调章节。

接入检查清单

在开始编码之前，请确认以下事项全部就绪：

✅ 拥有管理后台账号，且有 API 密钥管理权限
✅ 已创建 API 密钥，拿到 AppKey（ak_xxx）和 SecretKey（sk_xxx）
✅ 已创建合同模板，拿到 templateId
✅ 已记录模板中的表单字段名和签署方角色名
✅ （可选）已配置 IP 白名单
✅ （可选）已准备好 Webhook 回调接口
✅ 确认你的服务器能访问 Contract.Pro 的 Open API 地址

全部就绪后，按以下步骤接入：

Step 1. 选择认证方式  →  简单模式 / Token 模式 / 签名模式（三选一）
Step 2. 创建签署任务  →  POST /api/v1/seal/sign-tasks
Step 3. 嵌入签署页面  →  将响应中的 signUrl 嵌入 iframe / WebView
Step 4. 接收签署结果  →  Webhook 回调 或 主动轮询
Step 5. 下载签署文件  →  GET /api/v1/seal/sign-tasks/{taskId}/download

5 分钟跑通（简单模式）

最快的接入方式，每次请求直接带 AppKey + SecretKey：

注意：templateId 和 signatoryName 必须与管理后台创建的模板一致，否则会报错。

认证机制

Open API 提供三种认证方式，根据安全需求选择：

模式	安全级别	适用场景	前置条件
简单模式	★★☆	测试、内网系统	AppKey + SecretKey
Token 模式	★★★	生产环境推荐	AppKey + SecretKey
签名模式	★★★★	高安全要求（金融等）	AppKey + SecretKey + 签名算法实现

三种模式都需要先在管理后台创建 API 密钥（见前置条件二）。

模式一：简单模式

每次请求在 Header 中同时携带 AppKey 和 SecretKey。

请求头：

Header 名	必填	示例值	说明
`Seal-Api-Key`	是	`ak_xxxxxxxxxxxxxxxx`	管理后台创建的 AppKey
`Seal-Secret-Key`	是	`sk_xxxxxxxxxxxxxxxx`	管理后台创建的 SecretKey

示例：

优点： 接入最简单，无需额外逻辑
缺点： SecretKey 每次传输，安全性相对较低
适用： 测试环境、内网系统、快速验证

模式二：Token 模式（推荐）

先用 AppKey + SecretKey 换取短期 Token（5 分钟有效），后续请求只带 Token。SecretKey 只在获取 Token 时传输一次。

Step 1：获取 Token

POST /api/v1/seal/auth/token
Content-Type: application/x-www-form-urlencoded

请求参数（form 表单）：

参数	类型	必填	说明
apiKey	string	是	管理后台创建的 AppKey（`ak_xxx` 格式）
secretKey	string	是	管理后台创建的 SecretKey（`sk_xxx` 格式）
nonce	string	是	随机字符串（如 UUID），防重放攻击，10 分钟内不可重复

请求示例：

成功响应：

{
  "code": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 300
  }
}

响应字段	说明
accessToken	访问令牌，后续请求使用
tokenType	令牌类型，固定为 `Bearer`
expiresIn	有效期（秒），默认 300 秒（5 分钟）

Step 2：使用 Token 调用业务接口

后续所有业务接口在 Header 中携带：

Header 名	必填	示例值	说明
`Seal-Token`	是	`eyJhbGciOiJIUzI1NiJ9...`	Step 1 获取的 accessToken

注意事项：

Token 有效期 5 分钟，过期后需重新获取

同一 AppKey 同时只有一个活跃 Token，获取新 Token 会使旧 Token 失效

nonce 在 10 分钟内不可重复使用（防重放）

建议在 Token 过期前 1 分钟刷新

模式三：签名模式

对请求参数进行 MD5 签名，防止参数被篡改。适合对安全性要求最高的场景。

请求头：

Header 名	必填	示例值	说明
`Seal-Api-Key`	是	`ak_xxxxxxxxxxxxxxxx`	管理后台创建的 AppKey
`Seal-Sign`	是	`5A8F3D2E1B4C7A9F...`	请求参数签名（大写 MD5）
`Seal-Timestamp`	是	`1708000000`	当前时间戳（秒），签名有效期 5 分钟

签名算法（4 步）：

1. 收集所有请求参数（Query 参数 + Seal- 开头的请求头）
2. 按参数名 ASCII 字典序排序
3. 拼接为 key1=value1&key2=value2&...&key=sk_xxx（末尾拼接 SecretKey）
4. 对拼接字符串计算 MD5，转大写 → 即为签名值

Java 签名示例：

注意事项：

签名有效期 5 分钟（基于 Seal-Timestamp），超时返回签名无效

签名模式下不需要 Token，每次请求独立签名

需要你的系统实现签名算法

通知策略

创建签署任务时，可以通过 notifyChannel 字段控制平台是否自动发送短信通知给签署人。

值	说明	行为
`platform`（默认）	由平台通知	创建任务后，平台自动发送短信给所有签署人，短信中包含签署短链接
`caller`	由调用方通知	平台不发送任何短信，调用方通过 `GET /sign-tasks/{taskId}/sign-links` 获取签署链接后自行通知

如何选择：

场景	推荐值	原因
快速集成，不想处理通知逻辑	`platform`	开箱即用，签署人自动收到短信
有自己的通知渠道（企业微信、钉钉、邮件等）	`caller`	完全控制通知体验和内容
需要自定义短信内容	`caller`	平台短信模板固定，自行发送可自定义
内部系统，签署人通过系统内跳转	`caller`	无需短信，直接在系统内嵌入签署页面

使用 caller 模式的完整流程：

1. 创建签署任务时设置 notifyChannel: "caller"
2. 从创建响应中获取各参与人的 signUrl
3. 通过你自己的渠道将 signUrl 发送给签署人
4. 签署人点击链接完成签署

示例：

{
  "name": "劳动合同",
  "templateId": 1,
  "notifyChannel": "caller",
  "participants": [
    {
      "signatoryName": "甲方",
      "userName": "张三",
      "userMobile": "13800138000"
    }
  ]
}

注意：即使设置 notifyChannel: "caller"，签署过程中的状态变更通知（如签署完成）仍由平台发送。notifyChannel 仅控制创建任务时的初始邀请通知。

签署任务 API

创建签署任务

基于合同模板创建签署任务，返回各参与人的签署链接。

POST /api/v1/seal/sign-tasks

前置条件：

已完成认证（三种模式任选其一）

已在管理后台创建合同模板，拿到 templateId

已知模板中的签署方角色名（如「甲方」「乙方」）

已知模板中的表单字段名（如果需要填充表单数据）

请求体：

{
  "name": "XX公司劳动合同",
  "templateId": 1024,
  "deadline": "2026-03-01 00:00:00",
  "formData": {
    "employeeName": "李四",
    "salary": "15000",
    "startDate": "2026-03-01"
  },
  "participants": [
    {
      "signatoryName": "甲方（公司）",
      "type": "enterprise",
      "companyName": "XX科技有限公司",
      "userName": "王总",
      "userMobile": "13900139000"
    },
    {
      "signatoryName": "乙方（员工）",
      "type": "personal",
      "userName": "李四",
      "userMobile": "13800138000"
    }
  ],
  "signSecurityLevel": 0,
  "notifyChannel": "platform",
  "callbackUrl": "https://your-system.com/webhook/sign"
}

请求体字段说明：

字段	类型	必填	默认值	说明
name	string	是	-	任务名称，用于展示和检索
templateId	long	是	-	合同模板 ID（管理后台创建模板后获得）
deadline	string	否	无	截止时间，格式 `yyyy-MM-dd HH:mm:ss`，超时自动过期
formData	object	否	无	模板表单填充数据，key 必须与模板中定义的字段名一致
participants	array	是	-	签署参与人列表，至少 1 人
signSecurityLevel	int	否	0	0-快捷签署（点链接直接签），1-登录签署（需登录后签）
notifyChannel	string	否	`platform`	通知策略，详见通知策略
callbackUrl	string	否	无	单任务回调地址（优先级高于全局 Webhook）

participants 字段说明：

字段	类型	必填	说明
signatoryName	string	是	签署方角色名称，必须与模板中定义的签署方名称一致（如「甲方」「乙方」）
type	string	否	`personal`（个人，默认）或 `enterprise`（企业）
companyName	string	条件必填	企业名称，`type=enterprise` 时必须填写
userName	string	是	签署人真实姓名
userMobile	string	是	签署人手机号（用于身份匹配和通知）
signatoryId	long	否	模板签署方 ID，用于精确匹配模板中的签署位（不传则按 signatoryName 匹配）

成功响应：

{
  "code": 0,
  "data": {
    "taskId": 1024,
    "name": "XX公司劳动合同",
    "status": 2,
    "statusName": "签署中",
    "needFormFilling": false,
    "deadline": "2026-03-01 00:00:00",
    "createTime": "2026-02-12 10:30:00",
    "participants": [
      {
        "participantId": 1,
        "signatoryName": "甲方（公司）",
        "type": "enterprise",
        "userName": "王总",
        "userMobile": "139****9000",
        "status": 0,
        "signUrl": "https://seal.example.com/s/abc123"
      },
      {
        "participantId": 2,
        "signatoryName": "乙方（员工）",
        "type": "personal",
        "userName": "李四",
        "userMobile": "138****8000",
        "status": 0,
        "signUrl": "https://seal.example.com/s/def456"
      }
    ]
  }
}

手机号在响应中自动脱敏（中间 4 位替换为 ****）。signUrl 可直接嵌入 iframe 或在 WebView 中打开。

常见错误：

错误	原因	解决方案
合同模板ID不能为空	未传 templateId	检查请求体
模板不存在	templateId 不正确	在管理后台确认模板 ID
签署方角色名称不匹配	signatoryName 与模板不一致	在管理后台查看模板的签署方配置
签署参与人列表不能为空	participants 为空	至少传入 1 个参与人

查询签署任务

GET /api/v1/seal/sign-tasks/{taskId}

前置条件： 已完成认证；taskId 必须是当前 AppKey 创建的任务（数据隔离）

路径参数：

参数	类型	说明
taskId	long	签署任务 ID（创建任务时返回的 `taskId`）

成功响应：

{
  "code": 0,
  "data": {
    "taskId": 1024,
    "name": "XX公司劳动合同",
    "status": 3,
    "statusName": "已完成",
    "createTime": "2026-02-12 10:30:00",
    "signedFileUrl": "https://oss.example.com/signed/contract-1024.pdf",
    "participants": [
      {
        "participantId": 1,
        "signatoryName": "甲方（公司）",
        "userName": "王总",
        "status": 1,
        "signTime": "2026-02-12 11:00:00"
      }
    ]
  }
}

任务状态码：

status	说明	可执行操作
2	签署中	可撤销、可获取签署链接
3	已完成（所有人签署完毕）	可下载签署文件
4	已撤销	无
5	已拒签	无
6	已过期	无
7	表单填写中	等待表单填写完成

参与人状态码：

status	说明
0	待签署
1	已签署
2	已拒签

撤销签署任务

撤销进行中的签署任务。已完成的任务无法撤销。

POST /api/v1/seal/sign-tasks/{taskId}/cancel

前置条件： 已完成认证；任务状态必须为「签署中」(status=2)

成功响应：

{ "code": 0, "data": true }

获取签署链接

签署链接过期后可重新获取。仅返回待签署参与人的链接。

GET /api/v1/seal/sign-tasks/{taskId}/sign-links

前置条件： 已完成认证；任务状态必须为「签署中」(status=2)

使用场景：

notifyChannel: "caller" 模式下，获取链接后通过自己的渠道发送

签署链接过期后重新获取

签署人反馈链接无法打开时重新生成

成功响应：

{
  "code": 0,
  "data": [
    {
      "participantId": 2,
      "signatoryName": "乙方（员工）",
      "userName": "李四",
      "status": 0,
      "signUrl": "https://seal.example.com/s/new-link-789"
    }
  ]
}

已签署的参与人不会出现在响应中。

下载已签署文件

获取签署完成后的合同 PDF 文件下载地址。

GET /api/v1/seal/sign-tasks/{taskId}/download

前置条件： 已完成认证；任务状态必须为「已完成」(status=3)

成功响应：

{
  "code": 0,
  "data": "https://oss.example.com/signed/contract-1024.pdf"
}

返回的 URL 为 OSS 预签名地址，有一定有效期。建议获取后尽快下载或转存。

Webhook 回调

前置条件

使用 Webhook 前，你需要：

在你的系统中实现一个 HTTP(S) POST 接口，用于接收回调通知

该接口必须公网可达（Contract.Pro 服务器需要能访问到）

该接口必须在 10 秒内返回 HTTP 2xx 状态码

配置方式

有两种方式配置 Webhook，可以同时使用：

方式	配置方法	生效范围	优先级
任务级别	创建签署任务时传入 `callbackUrl` 参数	仅对该任务生效	高
全局级别	调用 Webhook 配置 API	对该 AppKey 下所有任务生效	低

如果同时配置了两种，任务级别的 callbackUrl 优先。

配置全局 Webhook

前置条件： 已完成认证（Token 模式或简单模式）

创建/更新：

POST /api/v1/seal/webhooks
Content-Type: application/json

{
  "callbackUrl": "https://your-system.com/webhook/seal",
  "secret": "your-hmac-secret",
  "subscribedEvents": "sign_completed,sign_rejected,sign_cancelled"
}

字段	类型	必填	说明
callbackUrl	string	是	回调地址，建议 HTTPS
secret	string	否	HMAC-SHA256 签名密钥，为空则系统自动生成（建议自行指定）
subscribedEvents	string	否	订阅事件（逗号分隔），为空则订阅全部事件

查询配置：

GET /api/v1/seal/webhooks

删除配置：

DELETE /api/v1/seal/webhooks

回调事件类型

事件	说明	触发时机
`sign_completed`	签署完成	所有参与人完成签署
`sign_rejected`	签署拒绝	任一参与人拒签
`sign_cancelled`	签署撤销	发起人撤销任务

回调请求格式

Contract.Pro 会向你的回调地址发送如下 POST 请求：

请求头：

Header	说明
`Content-Type`	`application/json`
`X-Seal-Signature`	HMAC-SHA256 签名（用于验证请求来源）
`X-Seal-Event`	事件类型（如 `sign_completed`）
`X-Seal-Timestamp`	时间戳（毫秒）

请求体：

{
  "eventType": "sign_completed",
  "taskId": 1024,
  "taskName": "XX公司劳动合同",
  "status": 3,
  "timestamp": 1707724800000,
  "signedFileUrl": "https://oss.example.com/signed/contract-1024.pdf"
}

signedFileUrl 仅在 sign_completed 事件中返回。

验证回调签名

为了确保回调请求确实来自 Contract.Pro（而非伪造），你应该验证 X-Seal-Signature。

验证逻辑： 使用你配置的 secret 对请求体（原始 JSON 字符串）进行 HMAC-SHA256 计算，与 X-Seal-Signature 比对。

Java：

Python：

Node.js：

回调响应要求

你的回调接口必须：

在 10 秒内 返回 HTTP 2xx 状态码（如 200）

响应体内容不限（Contract.Pro 不解析响应体）

非 2xx 或超时视为失败，触发重试

重试策略

次数	延迟	说明
第 1 次重试	1 分钟后	首次失败后
第 2 次重试	5 分钟后	指数退避
第 3 次重试	30 分钟后	最后一次

超过 3 次仍失败则放弃。你可以通过 GET /api/v1/seal/sign-tasks/{taskId} 主动轮询最终状态作为兜底方案。

签署页面嵌入

创建签署任务后，响应中每个参与人会返回 signUrl，将此 URL 嵌入你的系统即可。

前置条件

已通过 API 创建签署任务并获得 signUrl

你的页面支持 iframe（Web）或 WebView（移动端）

签署页面域名已在浏览器/WebView 的安全策略中放行

iframe 嵌入（Web）

allow="camera; microphone" 用于支持人脸识别等高级验证场景。

WebView 嵌入（移动端）

Android：

iOS (WKWebView)：

uni-app：

签署安全级别

创建任务时通过 signSecurityLevel 控制签署人的验证方式：

级别	值	用户体验	适用场景
快捷签署	0	点击链接直接进入签署页，无需登录	内部合同、低风险场景
登录签署	1	需要登录 + 实名认证后才能签署	外部合同、高安全要求

安全机制

数据隔离

每个 AppKey 创建的签署任务相互隔离：

只能查询、操作自己创建的任务

无法访问其他 AppKey 或平台用户创建的任务

Webhook 配置也按 AppKey 隔离

IP 白名单

管理员可在后台为每个 AppKey 配置 IP 白名单（见前置条件四）。

未配置白名单时，不限制来源 IP

配置后，只有白名单内的 IP 才能调用 API

不在白名单内的请求返回 AUTH_IP_NOT_ALLOWED 错误

请求限流

维度	限制	说明
单接口	10 req/s	每个 AppKey 对单个接口的请求频率
全局	50 req/s	每个 AppKey 的总请求频率

超过限流阈值返回 AUTH_RATE_LIMIT_EXCEEDED 错误（HTTP 429）。建议客户端实现指数退避重试。

Nonce 防重放

Token 模式下，获取 Token 时的 nonce 参数在 10 分钟内不可重复使用，防止请求被截获后重放。

状态码与错误处理

统一响应格式

所有接口返回统一的 JSON 格式：

{
  "code": 0,
  "msg": "",
  "data": {}
}

code = 0：成功

code != 0：失败，msg 包含错误描述

常见错误码

code	说明	常见原因	处理建议
0	成功	-	-
400	请求参数错误	缺少必填字段、格式不正确	检查请求体字段
401	认证失败	Token 无效/过期、AppKey/SecretKey 错误	检查凭证，重新获取 Token
403	无权限	任务不属于当前 AppKey、IP 不在白名单	检查数据归属和 IP 配置
404	资源不存在	taskId 不存在或已被删除	检查 taskId
429	请求频率超限	超过限流阈值	降低请求频率，实现退避重试
500	服务器内部错误	系统异常	联系技术支持

认证相关错误码

错误标识	说明	处理建议
`API_KEY_NOT_EXISTS`	AppKey 不存在	检查 `Seal-Api-Key` header 值是否正确
`API_KEY_DISABLED`	AppKey 已被禁用	联系管理员在后台启用
`AUTH_TOKEN_INVALID`	Token 无效或已过期	重新调用 `/auth/token` 获取新 Token
`AUTH_SIGNATURE_INVALID`	签名验证失败	检查签名算法实现和 SecretKey
`AUTH_IP_NOT_ALLOWED`	IP 不在白名单	联系管理员添加你的服务器 IP
`AUTH_RATE_LIMIT_EXCEEDED`	请求频率超限	降低请求频率
`AUTH_PARAM_MISSING`	缺少认证参数	检查是否携带了认证 Header

完整集成示例

Java (OkHttp)

前置条件： 已获取 AppKey、SecretKey、templateId

Python (requests)

前置条件： pip install requests，已获取 AppKey、SecretKey、templateId

cURL 完整流程

FAQ

Q1: AppKey / SecretKey 在哪里获取？

管理后台 → API 密钥管理 → 点击「新增」→ 填写应用名称 → 确定。系统自动生成 AppKey 和 SecretKey。SecretKey 仅在创建时展示一次，请立即复制保存。详见前置条件二。

Q2: templateId 在哪里获取？

管理后台 → 合同模板管理 → 找到你要使用的模板 → 模板 ID 即为 templateId。如果还没有模板，需要先创建。详见前置条件三。

Q3: 三种认证模式该选哪个？

场景	推荐模式
测试阶段、快速验证	简单模式
生产环境	Token 模式（推荐）
金融、法律等高安全场景	签名模式

Q4: Token 过期了怎么办？

重新调用 POST /api/v1/seal/auth/token 获取新 Token。建议在过期前 1 分钟刷新。Token 有效期 5 分钟（300 秒）。

Q5: 创建任务后签署人没收到短信？

检查 notifyChannel 参数：

如果设置为 caller，平台不会发短信，需要你自己获取签署链接并通知签署人

如果设置为 platform（或不传），平台会自动发短信

如果是 platform 模式仍未收到，请检查手机号是否正确

Q6: 如何知道签署完成了？

两种方式：

配置 Webhook 接收 sign_completed 事件（推荐，实时性好）

定时轮询 GET /sign-tasks/{taskId} 查看 status 是否变为 3

Q7: 签署链接有效期多久？

签署链接基于 JWT Token，默认有效期 7 天。过期后可通过 GET /sign-tasks/{taskId}/sign-links 重新获取。

Q8: 能否在创建任务时不指定模板，直接上传 PDF？

当前版本需要先在管理后台创建模板，再通过 templateId 引用。后续版本将支持直接上传 PDF。

Q9: 一个 AppKey 能创建多少任务？

无数量限制。请求频率限制为单接口 10 req/s，全局 50 req/s。

Q10: 报错「签署方角色名称不匹配」怎么办？

participants 中的 signatoryName 必须与模板中定义的签署方名称完全一致。请在管理后台查看模板的签署方配置，确认角色名称（如「甲方」「乙方」）是否匹配。

Q11: 报错「API_KEY_NOT_EXISTS」怎么办？

检查 Seal-Api-Key header 的值是否正确。确认：

AppKey 格式为 ak_xxx

在管理后台确认该密钥存在且状态为「启用」

Header 名称是 Seal-Api-Key（注意大小写和连字符）

Q12: 报错「AUTH_IP_NOT_ALLOWED」怎么办？

你的服务器 IP 不在白名单中。联系管理员在后台「IP 白名单管理」中添加你的服务器出口 IP。如果不确定出口 IP，可以先让管理员清空白名单（不配置白名单 = 不限制 IP）。

技术支持

邮件：shawn@leepm.com

API 文档（Swagger）：https://your-domain.com/doc.html

GitHub Issues：https://github.com/YunaiV/ruoyi-vue-pro/issues

目录#

概述#

接入方式选择#

方式总览#

方式一：API 对接（本文档重点）#

方式二：SDK 对接（Spring Boot Starter）#

方式三：私有化部署（企业版）#

如何选择？#

前置条件#

前置条件一：拥有管理后台账号#

前置条件二：创建 API 密钥（获取 AppKey / SecretKey）#

前置条件三：创建合同模板（获取 templateId）#

前置条件四（可选）：配置 IP 白名单#

前置条件五（可选）：准备 Webhook 回调地址#

接入检查清单#

5 分钟跑通（简单模式）#

认证机制#

模式一：简单模式#

模式二：Token 模式（推荐）#

模式三：签名模式#

通知策略#

签署任务 API#

创建签署任务#

查询签署任务#

撤销签署任务#

获取签署链接#

下载已签署文件#

Webhook 回调#

前置条件#

配置方式#

配置全局 Webhook#

回调事件类型#

回调请求格式#

验证回调签名#

回调响应要求#

重试策略#

签署页面嵌入#

前置条件#

iframe 嵌入（Web）#

WebView 嵌入（移动端）#

签署安全级别#

安全机制#

数据隔离#

IP 白名单#

请求限流#

Nonce 防重放#

状态码与错误处理#

统一响应格式#

常见错误码#

认证相关错误码#

完整集成示例#

Java (OkHttp)#

Python (requests)#

cURL 完整流程#

FAQ#

技术支持#

目录

概述

接入方式选择

方式总览

方式一：API 对接（本文档重点）

方式二：SDK 对接（Spring Boot Starter）

方式三：私有化部署（企业版）

如何选择？

前置条件

前置条件一：拥有管理后台账号

前置条件二：创建 API 密钥（获取 AppKey / SecretKey）

前置条件三：创建合同模板（获取 templateId）

前置条件四（可选）：配置 IP 白名单

前置条件五（可选）：准备 Webhook 回调地址

接入检查清单

5 分钟跑通（简单模式）

认证机制

模式一：简单模式

模式二：Token 模式（推荐）

模式三：签名模式

通知策略

签署任务 API

创建签署任务

查询签署任务

撤销签署任务

获取签署链接

下载已签署文件

Webhook 回调

前置条件

配置方式

配置全局 Webhook

回调事件类型

回调请求格式

验证回调签名

回调响应要求

重试策略

签署页面嵌入

前置条件

iframe 嵌入（Web）

WebView 嵌入（移动端）

签署安全级别

安全机制

数据隔离

IP 白名单

请求限流

Nonce 防重放

状态码与错误处理

统一响应格式

常见错误码

认证相关错误码

完整集成示例

Java (OkHttp)

Python (requests)

cURL 完整流程

FAQ

技术支持