开放平台接入文档

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

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

┌─────────────────────────────────────────────────────────────────┐
│  你的 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) │
└─────────────────────────────────────────────────────────────────┘

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

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

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

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

✅ 拥有管理后台账号，且有 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

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

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

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

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

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

POST /api/v1/seal/sign-tasks

{
  "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"
}

{
  "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"
      }
    ]
  }
}

GET /api/v1/seal/sign-tasks/{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"
      }
    ]
  }
}

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

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

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

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

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

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

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"
}

GET /api/v1/seal/webhooks

DELETE /api/v1/seal/webhooks

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

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