苏心签开放接口文档

v1.0.28 | 专业的电子合同服务接口

1. 概述

1.1 文档说明

本文档描述了苏心签开放接口的使用方法和接口规范，帮助开发者快速集成苏心签的电子合同服务。

1.2 接口基础信息

  • 基础路径：https://pc.suxin365.com/api/v1
  • 认证方式：Bearer Token 认证
  • 请求方法：GET/POST/DELETE
  • 响应格式：JSON
  • 字符编码：UTF-8

1.3 响应结构

所有接口返回统一的响应结构：

成功响应
JSON
{
  "success": true,
  "data": { /* 业务数据 */ }
}
失败响应
JSON
{
  "success": false,
  "code": "5001",
  "msg": "错误信息"
}

1.4 分页参数

涉及分页的接口支持以下参数：

  • page：页码，默认值 1
  • pageSize：每页数量，默认值 10
分页响应结构
JSON
{
  "success": true,
  "data": {
    "totalSize": 100,
    "results": [ /* 数据列表 */ ]
  }
}

2. 认证接口

2.1 获取访问令牌

  • 接口路径：POST /auth/token
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：使用 API Key 获取访问令牌，用于后续接口调用
参数名 类型 必填 描述
appId String 是 应用ID
apiKey String 是 API密钥
请求示例
JSON
{
  "appId": "app_test_1234567890",
  "apiKey": "sk_test_1234567890"
}

响应参数

参数名 类型 描述
accessToken String 访问令牌
expire Integer 令牌有效期（秒）
userId String 当前接入应用的默认用户 ID；PDF 上传发起等场景可作发起人使用
orgs Array 当前接入应用可用的企业列表；创建模板等归属接入应用的场景可从中选取企业 ID；按发起人发起合同时请改用企业列表接口
orgs[].orgId String 企业 ID
orgs[].orgName String 企业名称
响应示例
JSON
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expire": 3600,
    "userId": "123456",
    "orgs": [
      { "orgId": "1", "orgName": "示例科技有限公司" },
      { "orgId": "88", "orgName": "授权访问企业有限公司" }
    ]
  }
}

2.2 使用令牌

  • 认证方式：在请求头中添加 Authorization: Bearer <token>
  • 令牌有效期：默认 3600 秒（1小时）
  • 错误示例：
    • 缺少认证信息 - 缺少认证头
    • 认证方案无效 - 认证方案错误
    • 令牌无效或已过期 - 令牌无效或已过期

3. 合同管理

合同发起支持两种业务路径：

PDF 上传发起

同一发起人完成上传与创建；发起人可在平台查看，也可用用户合同列表查询。

flowchart TD A["上传 PDF"] --> B["获得文件"] B --> C["创建草稿"] C --> D["设计签署位置"] C --> K["发起签署时传关键词"] D --> E["发起签署"] K --> E E --> F["获取签署链接"] C --> G["用户合同列表查询"]

模板发起

模板来自接入应用；传入发起人后合同归发起人，可用用户合同列表查询。

flowchart TD T0["创建模板 可选"] --> T1["查询模板"] T1 --> T2["模板发起或批量发起"] T2 --> T3["获取签署链接"] T2 --> T4["用户合同列表查询"]

创建或发起合同时，可选填签署完成通知地址与跳转地址，说明见 §3.10.1。

合同状态说明

合同落库字段 status 仅有下列四种取值（字符串，大小写敏感）。列表筛选、创建/发起/撤回响应中的 status 均为此字段；轮询进度请用 §3.14。

status 含义 如何进入 可继续操作
DRAFT 草稿：已创建合同，尚未对外发起签署 §3.7 创建草稿（PDF 流程）；模板发起不会停留在草稿 设计页摆放控件，或发起签署时传关键词定位 → §3.9 发起签署；可用 §3.17 删除；不可签署、不可撤回
PENDING 待签署：已发起，等待一方或多方完成签署 §3.9，或 §3.5 / §3.6 模板发起成功后 获取签署链接、签署；可用 §3.16 撤回；用 §3.14 看各方是否已签
SIGNED 已签署：需签署的参与方全部签完 最后一方签署成功后由系统自动更新 可预览/下载；不可再撤回；§3.14 的 completedTime 有值
REVOKED 已撤回：发起方主动撤销待签合同 仅能从 PENDING 经 §3.16 撤回 不可再签署；可用 §3.17 删除；草稿、已签合同不能撤回

展示状态 displayStatus（仅 §3.14 返回，不落库）：一般与 status 相同；当 status = PENDING 且当前时间已超过签署截止时间 deadline 时，displayStatus = EXPIRED（表示逾期未签完，落库仍为 PENDING，仍可尝试签署或撤回，除非业务另行拦截）。

状态流转

DRAFT → PENDING → SIGNED；PENDING 也可撤回为 REVOKED。EXPIRED 仅为展示值。

flowchart LR DRAFT["DRAFT 草稿"] -->|发起签署| PENDING["PENDING 待签署"] PENDING -->|全部签完| SIGNED["SIGNED 已签署"] PENDING -->|撤回| REVOKED["REVOKED 已撤回"] PENDING -.->|逾期展示| EXPIRED["EXPIRED 仅展示"]

接入方判断建议：签完看 status === "SIGNED"；进行中看 PENDING 并结合 §3.14 的 participants[].signed；是否逾期看 displayStatus === "EXPIRED"；列表筛选请传落库值（勿传 EXPIRED）。

3.1 上传合同 PDF

  • 接口路径：POST /contract/upload-template
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：上传合同 PDF，返回文件 ID，供创建草稿使用；上传后系统会生成预览图
  • 注意事项：须指定发起人；后续创建草稿须使用同一发起人与本接口返回的文件 ID

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求参数

参数名 类型 必填 描述
fileName String 是 文件名
fileContent String 是 文件内容（Base64编码）
fileType String 否 文件类型（预留字段）
userId String 是 发起人用户 ID（须与创建草稿时一致）
请求示例
JSON
{
  "fileName": "template.pdf",
  "fileContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKNCAwIG9iago8PC9MZW5ndGggNTM1L0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nGNgYNgh4A/EYGVhZABkYAQwgWgDcIgDcQAZgYGPgBYH5AYGPoB2EAAKcAg==",
  "userId": "123456"
}

响应参数

参数名 类型 描述
fileId Long 文件ID
fileName String 文件名
fileType String 文件类型
fileUrl String 文件访问URL
响应示例
JSON
{
  "success": true,
  "data": {
    "fileId": 1,
    "fileName": "contract.pdf",
    "fileType": "application/pdf",
    "fileUrl": "https://example.com/...(服务端返回的模板文件下载完整 URL)"
  }
}

3.2 创建合同模板

  • 接口路径：POST /contract/templates
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：上传 Word（.docx）创建合同模板，归属当前接入应用。企业须为接入应用下可用企业（建议从获取令牌返回的企业列表选取）。未传字段定义时，系统自动识别文档中的 {{关键词}}。创建后可用于模板发起 / 批量发起合同。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求参数

参数名 类型 必填 描述
name String 是 模板名称
orgId String 是 所属企业 ID（须为当前接入应用下的企业，建议取自获取令牌返回的企业列表）
fileName String 是 Word 文件名，须以 .docx 结尾
fileContent String 是 Word 文件 Base64（可含 data:...;base64, 前缀）
description String 否 模板描述
category String 否 分类
fields String 否 字段定义 JSON，如 [{"key":"甲方名称","label":"甲方名称","required":true}]；不传则自动提取
sealPositions String 否 默认签署/盖章位置 JSON（结构同模板详情 sealPositions）
status String 否 状态，默认 ACTIVE
请求示例
JSON
{
  "name": "服务协议模板",
  "orgId": "10001",
  "fileName": "service-agreement.docx",
  "fileContent": "UEsDBBQAAAAI...",
  "description": "标准服务协议",
  "sealPositions": "[{\"type\":\"sign_area\",\"page\":1,\"left\":100,\"top\":200,\"width\":126,\"height\":126,\"signerIndex\":1}]"
}

响应参数

data 结构与 §3.3 模板列表 单项相同（含 templateId、fields、fileObjectId 等）。

3.3 查询模板列表

  • 接口路径：GET /contract/templates（可选 Query：orgId）
  • 请求类型：Query 参数（orgId 非必填）
  • 功能说明：查询当前接入应用下已启用的合同模板。可按企业筛选；不传企业则返回该应用下全部启用模板。

企业请从获取令牌返回的企业列表中选取。传入不可用的企业时接口返回业务错误。

请求参数

参数名 类型 必填 描述
orgId String 否 企业 ID（建议取自获取令牌返回的企业列表）。不传则返回当前接入应用下全部启用模板
请求示例
HTTP
GET /api/v1/contract/templates
Authorization: Bearer <token>

# 或按企业筛选
GET /api/v1/contract/templates?orgId=1
Authorization: Bearer <token>

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

响应参数

参数名 类型 描述
data Array 模板列表
data[].templateId Long 模板 ID
data[].orgEntityId Long 所属企业组织 ID
data[].orgEntityName String 所属企业名称（由 orgEntityId 解析；未绑定企业时为空）
data[].name String 模板名称
data[].description String 模板描述
data[].category String 模板分类
data[].status String 模板状态
data[].fileObjectId Long 模板源文件 ID
data[].fileName String 模板源文件名
data[].fields String 模板字段 JSON，如 [{"key":"甲方名称","label":"甲方名称","required":true}]
data[].pageCount Integer 页数
data[].approvalFlowId Long 关联审批流 ID
data[].approvalFlowName String 关联审批流名称
data[].sealPositions String 默认签署/盖章位置配置 JSON，如 [{"type":"sign_area","page":1,"left":100,"top":200,"width":126,"height":126,"signerIndex":1}]；其中 type 为 sign_area（签署区域）/sign_date（签署日期）/page_seal（骑缝章），signerIndex 为签署方序号（从 1 开始，对应发起时 signers 的签署顺序 order）。未配置时为 null
data[].createdAt String 创建时间
响应示例
JSON
{
  "success": true,
  "data": [
    {
      "templateId": 1,
      "orgEntityId": 1,
      "orgEntityName": "示例科技有限公司",
      "name": "劳动合同",
      "description": "标准劳动合同模板",
      "category": "人事",
      "status": "ACTIVE",
      "fileObjectId": 100,
      "fileName": "labor.docx",
      "fields": "[{\"key\":\"甲方名称\",\"label\":\"甲方名称\",\"required\":true}]",
      "pageCount": 3,
      "approvalFlowId": null,
      "approvalFlowName": null,
      "sealPositions": "[{\"type\":\"sign_area\",\"page\":1,\"left\":100,\"top\":200,\"width\":126,\"height\":126,\"signerIndex\":1}]",
      "createdAt": "2026-05-01 10:00:00"
    }
  ]
}

3.4 查询模板详情

  • 接口路径：GET /contract/templates/{templateId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path
  • 功能说明：根据模板 ID 获取模板详情，含字段定义等信息

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
templateId String 是 模板 ID

响应参数

与 §3.3 列表项结构相同，data 为单个模板对象。

响应示例
JSON
{
  "success": true,
  "data": {
    "templateId": 1,
    "orgEntityId": 1,
    "orgEntityName": "示例科技有限公司",
    "name": "劳动合同",
    "description": "标准劳动合同模板",
    "category": "人事",
    "status": "ACTIVE",
    "fileObjectId": 100,
    "fileName": "labor.docx",
    "fields": "[{\"key\":\"甲方名称\",\"label\":\"甲方名称\",\"required\":true}]",
    "pageCount": 3,
    "approvalFlowId": null,
    "approvalFlowName": null,
    "sealPositions": "[{\"type\":\"sign_area\",\"page\":1,\"left\":100,\"top\":200,\"width\":126,\"height\":126,\"signerIndex\":1}]",
    "createdAt": "2026-05-01 10:00:00"
  }
}

3.5 根据模板发起合同

  • 接口路径：POST /contract/create-from-template
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：按接入应用下的模板填写字段并生成合同；配置了默认签署位置时将直接进入待签署。未配置默认位置时可传 keywordControls 按关键词定位并自动发起。传入发起人时，合同与生成文件归属该发起人（与 PDF 创建草稿一致）；不传则使用接入应用默认账号。

典型流程：先调用 §3.3 / §3.4 获取模板及字段定义 → 填写 fieldValues、发起人与签署方 → 调用本接口（或 §3.6 批量发起）→ 使用 §3.10 获取签署链接引导用户签署。查询该发起人合同见 §3.13。

签署位置：优先使用模板默认位置；否则可传 keywordControls（字段同 §3.9）。二者皆无时合同可能仍为草稿，需后续补充位置后再发起。

签署意愿：可为每位签署方指定短信验证、人脸识别或两者；不传时默认仅人脸识别。字段说明见创建草稿中的签署方说明。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求参数

参数名 类型 必填 描述
templateId Long 是 模板 ID
title String 否 合同标题，为空时使用模板名称
fieldValues Object 否 模板字段值，key 为字段标识（与模板 fields 中 key 对应）
userId String 否 发起人用户 ID；有则合同归属该用户，可用用户合同列表查询；不传则用接入应用默认账号
orgId String 否 发起组织 ID；有发起人时须属于发起人租户下的企业（建议从企业列表按发起人选取）
signers Array 否 签署方信息列表，结构同 §3.7 创建草稿
signOrderMode Integer 否 签署顺序模式：1-顺序签署，2-并行签署
expireTime Long 否 签署截止日期（毫秒时间戳）
callbackUrl String 否 签署完成回调推送地址
redirectUrl String 否 签署完成后跳转地址
keywordControls Array 否 按关键词定位签署位置并自动发起；模板已有默认位置时忽略。字段同 §3.9
请求示例
JSON
{
  "templateId": 1,
  "title": "张三劳动合同",
  "fieldValues": {
    "甲方名称": "某某科技有限公司",
    "乙方姓名": "张三",
    "入职日期": "2026-06-01"
  },
  "userId": "123456",
  "orgId": "1",
  "signOrderMode": 1,
  "callbackUrl": "https://your-domain.com/api/sign-callback",
  "redirectUrl": "https://your-domain.com/sign/success",
  "signers": [
    {
      "type": "ENTERPRISE",
      "order": 1,
      "orgId": "1",
      "verifyMethods": "2"
    },
    {
      "type": "PERSON",
      "order": 2,
      "name": "张三",
      "mobile": "13800138000",
      "verifyMethods": "1,2"
    }
  ],
  "keywordControls": [
    {
      "keyword": "甲方（盖章）",
      "occurrenceIndex": 0,
      "signerName": "某某科技有限公司",
      "controlType": "sign_area",
      "width": "126",
      "height": "126"
    },
    {
      "keyword": "乙方（签字）",
      "occurrenceIndex": 0,
      "signerName": "张三",
      "controlType": "sign_area"
    }
  ],
  "expireTime": 1793568000000
}

响应参数

参数名 类型 描述
contractId Long 合同 ID
status String 合同状态，发起成功后为 PENDING（见 合同状态说明）
响应示例
JSON
{
  "success": true,
  "data": {
    "contractId": 123456,
    "status": "PENDING"
  }
}

3.6 批量根据模板发起合同

  • 接口路径：POST /contract/batch-create-from-template
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：按 items 逐份调用与 §3.5 相同的模板发起逻辑（填充字段、生成 PDF、创建合同并自动发起签署）。各份独立处理，部分失败不影响其余成功项。
  • 数量限制：items 不能为空；单次请求最多 50 份，超出时整单拒绝并返回错误：单次最多发起50份合同

items[] 中每个元素的结构与参数说明同 §3.5 根据模板发起合同（含 templateId、fieldValues、userId、signers 等）。模板默认签署/盖章位置规则亦与 §3.5 一致。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求参数

参数名 类型 必填 描述
items Array 是 待发起的合同列表，1–50 份；每项结构同 §3.5
请求示例
JSON
{
  "items": [
    {
      "templateId": 1,
      "title": "张三劳动合同",
      "fieldValues": {
        "乙方姓名": "张三"
      },
      "userId": "123456",
      "orgId": "1",
      "signOrderMode": 1,
      "signers": [
        {
          "type": "ENTERPRISE",
          "order": 1,
          "orgId": "1",
          "verifyMethods": "2"
        },
        {
          "type": "PERSON",
          "order": 2,
          "userId": "789012",
          "verifyMethods": "1,2"
        }
      ]
    },
    {
      "templateId": 1,
      "title": "李四劳动合同",
      "fieldValues": {
        "乙方姓名": "李四"
      },
      "userId": "123456",
      "orgId": "1",
      "signOrderMode": 1,
      "signers": [
        {
          "type": "ENTERPRISE",
          "order": 1,
          "orgId": "1",
          "verifyMethods": "2"
        },
        {
          "type": "PERSON",
          "order": 2,
          "userId": "789013",
          "verifyMethods": "1,2"
        }
      ]
    }
  ]
}

响应参数

参数名 类型 描述
total Integer 请求总份数
successCount Integer 成功份数
failCount Integer 失败份数
results Array 各份处理结果，顺序与 items 一致
results[].index Integer 在 items 中的序号，从 0 开始
results[].success Boolean 该份是否成功
results[].contract Object 成功时返回，含 contractId、status 等，结构同 §3.5 响应
results[].errorMessage String 失败时的错误原因
响应示例
JSON
{
  "success": true,
  "data": {
    "total": 2,
    "successCount": 2,
    "failCount": 0,
    "results": [
      {
        "index": 0,
        "success": true,
        "contract": {
          "contractId": 123456,
          "status": "PENDING"
        }
      },
      {
        "index": 1,
        "success": true,
        "contract": {
          "contractId": 123457,
          "status": "PENDING"
        }
      }
    ]
  }
}

HTTP 状态码为 200 时，仍可能有部分 results[].success 为 false，请按序号检查每份结果。仅当 items 为空或超过 50 份时，整单以业务错误拒绝。

3.7 创建合同草稿

  • 接口路径：POST /contract/create
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：使用已上传的 PDF 创建草稿合同，并保存签署方；随后可通过设计页或发起签署时传关键词定位签署位置
  • 注意事项：发起人须与上传 PDF 时一致；签署方可为本平台其他企业或个人

若使用 Word 模板且无需自行设计位置，请使用模板发起或批量模板发起。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求参数

参数名 类型 必填 描述
title String 是 合同标题
fileId Long 是 合同 PDF 文件 ID（§3.1 上传返回）
userId String 是 发起人用户 ID（须与上传 PDF 时一致）
orgId String 否 发起组织 ID
signOrderMode Integer 否 签署顺序模式：1-顺序签署，2-并行签署
signers Array 否 签署方列表，见下表
expireTime Long 否 签署截止日期（毫秒时间戳）
callbackUrl String 否 签署完成回调推送地址
redirectUrl String 否 签署完成后跳转地址

signers[] 元素

每个元素描述一名签署方，可通过平台 ID 或姓名、手机号等方式指定。

参数名 类型 必填 描述
type String 是 PERSON 个人；ENTERPRISE 或 COMPANY 企业/个体户
order Integer 否 签署顺序，默认按数组顺序从 1 递增
userId String 否 平台用户 ID（个人签署方；与姓名+手机号二选一）。可为外部签署人
orgId String 否 平台企业 ID（企业签署方；与企业名称等信息二选一）。可为外部签署企业
name String 条件 签署方名称：个人为姓名，企业为企业全称
mobile String 条件 手机号：个人用于身份验证；企业为经办人/接收短信手机号
contact String 否 同 mobile，二者任填其一
unifiedSocialCreditCode String 否 统一社会信用代码（企业可选）
idCardNumber String 否 身份证号（个人可选）
verifyMethods String 否 签署要求（意愿验证）：1 短信验证，2 人脸识别，1,2 两者均需；不传默认 2
请求示例（平台 ID 方式）
JSON
{
  "title": "服务协议",
  "fileId": 1,
  "signOrderMode": 1,
  "signers": [
    {
      "type": "PERSON",
      "order": 1,
      "userId": "123456",
      "verifyMethods": "2"
    },
    {
      "type": "ENTERPRISE",
      "order": 2,
      "orgId": "789012",
      "verifyMethods": "1,2"
    }
  ],
  "userId": "123456"
}
请求示例（姓名/手机号）
JSON
{
  "title": "服务协议",
  "fileId": 1,
  "signOrderMode": 1,
  "callbackUrl": "https://your-domain.com/api/sign-callback",
  "redirectUrl": "https://your-domain.com/sign/success",
  "signers": [
    {
      "type": "PERSON",
      "order": 1,
      "name": "张三",
      "mobile": "13800138000",
      "verifyMethods": "1,2"
    },
    {
      "type": "ENTERPRISE",
      "order": 2,
      "name": "某某科技有限公司",
      "mobile": "13900139000",
      "unifiedSocialCreditCode": "91330100MA2XXXXXXX",
      "verifyMethods": "2"
    }
  ],
  "expireTime": 1793568000000,
  "userId": "123456"
}

响应参数

参数名 类型 描述
contractId Long 合同 ID
title String 合同标题
status String 合同状态，创建成功为 DRAFT（见 合同状态说明）
响应示例
JSON
{
  "success": true,
  "data": {
    "contractId": 123456,
    "title": "服务协议",
    "status": "DRAFT"
  }
}

3.8 获取设计合同页面

  • 接口路径：GET /contract/design-page/{contractId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path
  • 功能说明：获取合同设计页面 URL，用于配置签署控件位置

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId Long 是 合同ID

响应参数

参数名 类型 描述
contractId Long 合同ID
token String 页面访问令牌
tokenType String 令牌类型：design
expiresIn Integer 令牌有效期（秒），默认 2592000（30 天）
pcUrl String PC端设计页面URL
h5Url String H5端设计页面URL
响应示例
JSON
{
  "success": true,
  "data": {
    "contractId": 1,
    "token": "abc123xyz",
    "tokenType": "design",
    "expiresIn": 2592000,
    "pcUrl": "https://example.com/open-contract/pc/design?token=abc123xyz",
    "h5Url": "https://example.com/open-contract/h5/design?token=abc123xyz"
  }
}

注意：返回 URL 含 token 参数，凭 token 打开设计页。令牌默认有效期 30 天，过期后重新调用本接口获取。

3.9 发起签署

  • 接口路径：POST /contract/initiate-sign/{contractId}
  • 请求类型：JSON（Content-Type: application/json）；Body 可为空
  • 功能说明：发起合同签署。可选传入 keywordControls，按 PDF 中的关键词定位签署位置（可跳过设计页）。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId String 是 合同ID

请求参数

参数名 类型 必填 描述
keywordControls Array 否 按关键词生成签署位置；不传则沿用已有控件（如设计页已摆放）
keywordControls[].keyword String 是 PDF 中的定位关键词
keywordControls[].occurrenceIndex Integer 否 第几次出现，从 0 起；默认 0
keywordControls[].controlType String 否 控件类型，默认 sign_area
keywordControls[].participantId Long 否 关联签署方 ID（优先）
keywordControls[].signerName String 否 按签署方姓名匹配；与 participantId 二选一。仅一名签署方时可省略
keywordControls[].width / height String 否 控件宽高，默认 126
keywordControls[].offsetX / offsetY Float 否 相对关键词位置的偏移，默认 0
请求示例
JSON
{
  "keywordControls": [
    {
      "keyword": "甲方（盖章）",
      "occurrenceIndex": 0,
      "signerName": "某某科技有限公司",
      "controlType": "sign_area",
      "width": "126",
      "height": "126",
      "offsetX": 0,
      "offsetY": 0
    },
    {
      "keyword": "乙方（签字）",
      "occurrenceIndex": 0,
      "signerName": "张三"
    }
  ]
}

响应参数

参数名 类型 描述
contractId Long 合同ID
status String 合同状态，发起成功后为 PENDING（见 合同状态说明）
message String 操作信息
响应示例
JSON
{
  "success": true,
  "data": {
    "contractId": 1,
    "status": "PENDING",
    "message": "发起签署成功"
  }
}

3.10 获取签署链接

  • 接口路径：GET /contract/sign-url/{contractId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path 与 Query
  • 功能说明：获取合同签署链接，用于引导用户完成签署

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId String 是 合同ID

查询参数

参数名 类型 必填 描述
userId String 否 用户 ID（可选，用于指定签署方视角）
orgId String 否 组织 ID（可选，用于指定签署方视角）
callbackUrl String 否 签署完成回调推送地址（覆盖创建合同时的配置，见 §3.10.1）
redirectUrl String 否 签署完成后跳转地址（覆盖创建合同时的配置，见 §3.10.1）

响应参数

参数名 类型 描述
contractId Long 合同ID
token String 页面访问令牌
tokenType String 令牌类型：sign
expiresIn Integer 令牌有效期（秒），默认 2592000（30 天）
pcUrl String PC端签署链接
h5Url String H5端签署链接
响应示例
JSON
{
  "success": true,
  "data": {
    "contractId": 1,
    "token": "abc123xyz",
    "tokenType": "sign",
    "expiresIn": 2592000,
    "pcUrl": "https://example.com/open-contract/pc/sign?token=abc123xyz",
    "h5Url": "https://example.com/open-contract/h5/sign?token=abc123xyz"
  }
}

注意：返回 URL 含 token 参数，签署人打开链接后按页面提示完成身份验证与签署。令牌默认有效期 30 天，过期后重新调用本接口获取。

3.10.1 签署完成回调与跳转

在 §3.7 创建草稿、§3.5 模板发起合同、§3.6 批量模板发起 或 §3.10 获取签署链接 时，可传入以下可选参数：

参数名 说明
callbackUrl 签署结果通知地址。平台向该地址 POST JSON，通知签署进度（见下方示例）
redirectUrl 签署完成跳转地址。当前签署人在签署页完成签署后，将跳转至该地址

callbackUrl 通知说明

  • 请求方式：POST，Content-Type: application/json
  • 有签署方完成签署时推送一次；全部签署方均完成后会再推送一次「合同已完成」通知
  • 请使用 HTTPS 地址，并在您的服务端按 contractId 更新业务状态
单方完成签署 — 通知示例
JSON
{
  "event": "signer.signed",
  "contractId": 123456,
  "title": "服务协议",
  "status": "PENDING",
  "signerId": 789,
  "signerName": "张三",
  "signerContact": "13800138000",
  "signedAt": 1719500000000,
  "timestamp": 1719500000000
}
合同全部完成 — 通知示例
JSON
{
  "event": "contract.completed",
  "contractId": 123456,
  "title": "服务协议",
  "status": "SIGNED",
  "completedAt": 1719503600000,
  "timestamp": 1719503600000
}

redirectUrl 说明

  • 浏览器 H5 / PC：填写您的业务页面完整 URL，如 https://your-domain.com/sign/success
  • 微信小程序 web-view：请填写您小程序内的页面路径，如 pages/order/sign-success?contractId=123456（对接步骤见 §3.10.2）
  • 未填写时，签署成功页仅展示完成提示，不自动跳转

3.10.2 微信小程序 web-view 对接

若希望在您自己的微信小程序内完成签署，可将 §3.10 返回的 h5Url 放入小程序 <web-view> 组件打开。签署页为平台提供的 H5，签署流程（手机号验证、实名、阅读、签署）与独立 H5 一致。

对接步骤

  1. 创建或发起合同时传入 redirectUrl，填写您小程序的成功页路径，例如 pages/order/sign-success?contractId=123456
  2. 调用 GET /contract/sign-url/{contractId} 获取 h5Url
  3. 在小程序页面中使用 <web-view src="{{h5Url}}"></web-view> 打开签署链接
  4. （推荐）配置 callbackUrl，由您的服务端接收签署结果通知，与页面跳转互为补充

前置条件

  • h5Url 的域名须已加入微信小程序「业务域名」白名单
  • redirectUrl 须为您小程序 app.json 中已注册的页面路径，以 pages/ 开头
  • 请勿将 redirectUrl 填写为外部 H5 地址：web-view 内无法像浏览器一样跳转到任意外链

签署成功后的跳转

签署完成后，平台 H5 签署页会自动处理跳转（无需您自行编写 H5 代码）：

redirectUrl 配置 签署成功后的行为
已填写 pages/... 路径 H5 调用微信 JSSDK wx.miniProgram.redirectTo，跳转到您指定的小程序页面（推荐）
未填写，或填写为 https 外链 H5 返回 web-view 上一页；您可在小程序 bindmessage 中接收签署成功消息并自行跳转（见下方说明）

bindmessage（可选）

签署成功时，H5 会向小程序发送消息（event 为 openContract.signSuccess）。按微信规则，消息在 web-view 页面返回或关闭时才会送达，请在承载 web-view 的小程序页监听 bindmessage：

消息字段
字段 说明
event 固定为 openContract.signSuccess
contractId 合同 ID
contractTitle 合同标题
redirectUrl 创建合同时配置的跳转地址
timestamp 时间戳（毫秒）
小程序示例（微信原生语法）
XML
<!-- 签署页 wxml -->
<web-view src="{{signH5Url}}" bindmessage="onSignMessage"></web-view>
JavaScript
// 签署页 js
Page({
  data: {
    signH5Url: '' // 来自 §3.9 接口返回的 h5Url
  },
  onSignMessage(e) {
    const messages = e.detail.data || []
    messages.forEach(function (msg) {
      if (!msg || msg.event !== 'openContract.signSuccess') return
      // 可按 contractId 更新本地业务状态
      if (msg.redirectUrl && /^pages\//.test(msg.redirectUrl)) {
        wx.redirectTo({ url: '/' + msg.redirectUrl.replace(/^\//, '') })
      }
    })
  }
})

说明：若已正确配置 pages/... 格式的 redirectUrl，签署成功后 H5 会直接跳转，多数场景无需依赖 bindmessage。bindmessage 适用于未配置跳转地址、或需在返回上一页时同步业务状态的场景。使用 Taro、uni-app 等框架时，请改用对应框架的 web-view 与消息监听写法，跳转 API 与微信原生 wx.redirectTo 等价即可。

3.11 获取合同预览地址

  • 接口路径：GET /contract/preview-url/{contractId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path 与 Query
  • 功能说明：获取合同预览地址，用于查看合同内容

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId String 是 合同ID

查询参数

参数名 类型 必填 描述
userId String 否 用户ID（userId和orgId必须提供一个）
orgId String 否 组织ID（userId和orgId必须提供一个）

响应参数

参数名 类型 描述
contractId Long 合同ID
token String 页面访问令牌
tokenType String 令牌类型：preview
expiresIn Integer 令牌有效期（秒），默认 2592000（30 天）
pcUrl String PC端预览链接
h5Url String H5端预览链接
响应示例
JSON
{
  "success": true,
  "data": {
    "contractId": 1,
    "token": "abc123xyz",
    "tokenType": "preview",
    "expiresIn": 2592000,
    "pcUrl": "https://example.com/open-contract/pc/detail?token=abc123xyz",
    "h5Url": "https://example.com/open-contract/h5/detail?token=abc123xyz"
  }
}

注意：预览页无需登录，可直接查看合同内容。令牌默认有效期 30 天，过期后重新调用本接口获取。

3.12 查询组织合同列表

  • 接口路径：GET /contract/list
  • 请求类型：无 JSON/表单请求体；参数见 URL Query
  • 功能说明：按企业分页查询合同；可按状态、合同 ID 过滤。适用于按企业维度查询；若合同归属指定发起人，请优先使用 §3.13 用户合同列表。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
orgId String 是 组织ID
page Integer 否 页码，默认1
pageSize Integer 否 每页数量，默认10
status String 否 合同状态（落库值），见 合同状态说明：DRAFT / PENDING / SIGNED / REVOKED（勿传 EXPIRED）
contractIds String 否 合同ID集合，逗号分隔（如 1,2,3），最多 100 个；与 orgId/status 组合过滤

响应参数

参数名 类型 描述
totalSize Integer 总记录数
results Array 合同列表
results[].contractId Long 合同ID
results[].title String 合同标题
results[].status String 合同状态（落库值），见 合同状态说明
results[].createdAt String 创建时间
响应示例
JSON
{
  "success": true,
  "data": {
    "totalSize": 100,
    "results": [
      {
        "contractId": 1,
        "title": "服务协议",
        "status": "DRAFT",
        "createdAt": "2026-04-19 10:00:00"
      }
    ]
  }
}

3.13 查询用户合同列表

  • 接口路径：GET /contract/tenant-list
  • 请求类型：无 JSON/表单请求体；参数见 URL Query
  • 功能说明：查询指定用户作为发起人创建的合同（与该用户登录平台后可见范围一致）；可按企业、状态、合同 ID 过滤

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
userId String 是 发起人用户 ID
orgId String 否 组织 ID，传入则仅返回该组织下合同
page Integer 否 页码，默认 1
pageSize Integer 否 每页数量，默认 10
status String 否 合同状态，见 合同状态说明：DRAFT / PENDING / SIGNED / REVOKED（勿传 EXPIRED）
contractIds String 否 合同ID集合，逗号分隔（如 1,2,3），最多 100 个；与 orgId/status 组合过滤

响应参数

参数名 类型 描述
totalSize Integer 总记录数
page Integer 当前页码
pageSize Integer 每页数量
results Array 合同列表，项结构同 §3.12
响应示例
JSON
{
  "success": true,
  "data": {
    "totalSize": 100,
    "page": 1,
    "pageSize": 10,
    "results": [
      {
        "contractId": 1,
        "title": "服务协议",
        "status": "PENDING",
        "createdAt": "2026-04-19 10:00:00"
      }
    ]
  }
}

3.14 实时合同状态

  • 接口路径：GET /contract/status/{contractId}
  • 请求类型：无 JSON/表单请求体；参数见 Path
  • 功能说明：查询合同当前状态及各参与方签署进度，适合接入方轮询「是否已签完 / 谁已签」；比列表接口更细，含截止时间与展示状态
  • 租户校验：不校验 API Key 所属租户与合同归属是否一致，仅按合同 ID 查询
  • 状态取值：响应中的 status 为落库状态，完整含义与流转见本章开头 合同状态说明；另有仅本接口返回的展示字段 displayStatus（可出现 EXPIRED，不落库）

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId String 是 合同ID

响应参数

参数名 类型 描述
contractId Long 合同ID
title String 合同标题
status String 落库状态：DRAFT / PENDING / SIGNED / REVOKED，详见 合同状态说明
displayStatus String 展示状态：一般与 status 相同；仅当 PENDING 且已超过 deadline 时为 EXPIRED（不改落库 status，仍可签署或撤回）。列表筛选请勿使用 EXPIRED
deadline String 签署截止时间，格式 yyyy-MM-dd HH:mm:ss；未设置则为 null
completedTime String 全部签署完成时间；未完成则为 null
createdAt String 创建时间
isSequentialSigning Boolean 是否顺序签署
orgEntityId Long 发起方组织 ID
participants Array 参与方列表（按 sort 升序），结构见下表

participants[] 项结构

参数名 类型 描述
participantId Long 参与方 ID
type String PERSON / ENTERPRISE
name String 参与方名称
contact String 联系方式
sign Boolean 是否需要签署
signed Boolean 是否已签署
signedTime String 签署时间；未签则为 null
sort Integer 排序
响应示例
JSON
{
  "success": true,
  "data": {
    "contractId": 1,
    "title": "服务协议",
    "status": "PENDING",
    "displayStatus": "PENDING",
    "deadline": "2026-08-01 23:59:59",
    "completedTime": null,
    "createdAt": "2026-07-29 10:00:00",
    "isSequentialSigning": false,
    "orgEntityId": 1001,
    "participants": [
      {
        "participantId": 11,
        "type": "PERSON",
        "name": "张三",
        "contact": "13800138000",
        "sign": true,
        "signed": true,
        "signedTime": "2026-07-29 11:20:00",
        "sort": 1
      },
      {
        "participantId": 12,
        "type": "ENTERPRISE",
        "name": "某某科技有限公司",
        "contact": "13900139000",
        "sign": true,
        "signed": false,
        "signedTime": null,
        "sort": 2
      }
    ]
  }
}

说明：

  • 判断是否签完：status === "SIGNED"（勿仅用 displayStatus）
  • 判断是否进行中：status === "PENDING"；各方进度看 participants 中 sign === true 的 signed
  • 判断是否逾期未签完：displayStatus === "EXPIRED"（此时落库仍为 PENDING）
  • 判断是否已撤回：status === "REVOKED"
  • 状态全集与流转图见 合同状态说明

3.15 签署人签订记录

  • 接口路径：GET /contract/signing-records/{contractId}
  • 请求类型：无 JSON/表单请求体；参数见 Path
  • 功能说明：返回该合同下签署人的签订审计记录（按签署时间正序），含验证方式、成功/失败及 IP 等；与 §3.14 的参与方进度互补——进度看谁签了，记录看每次签署明细
  • 租户校验：不校验 API Key 所属租户与合同归属是否一致，仅按合同 ID 查询

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId String 是 合同ID

响应参数

data 为数组，每项字段如下：

参数名 类型 描述
recordId Long 记录 ID
participantId Long 参与方 ID
userId Long 实际签署操作人用户 ID（平台用户 ID）；企业参与方为授权经办人，个人参与方为签署人本人
orgId Long 企业组织 ID；企业参与方返回对应企业，个人参与方为 null
signerName String 签署人姓名
signerContact String 签署人联系方式
signerType String PERSON / ENTERPRISE
signedTime String 签署时间 yyyy-MM-dd HH:mm:ss
verifyMethod String 验证方式：SMS / FACE / BOTH
smsVerified Boolean 是否短信验证通过
faceVerified Boolean 是否人脸验证通过
signingOrder Integer 签署顺序（可空）
status String SUCCESS / FAILED
failReason String 失败原因（成功时为 null）
ipAddress String 签署时 IP
userAgent String 签署时 User-Agent
location String 地理位置（可空）
fileHash String 签署后文件 SHA-256
remarks String 意愿留痕说明
响应示例
JSON
{
  "success": true,
  "data": [
    {
      "recordId": 101,
      "participantId": 11,
      "userId": 10001,
      "orgId": null,
      "signerName": "张三",
      "signerContact": "13800138000",
      "signerType": "PERSON",
      "signedTime": "2026-07-29 11:20:00",
      "verifyMethod": "BOTH",
      "smsVerified": true,
      "faceVerified": true,
      "signingOrder": 1,
      "status": "SUCCESS",
      "failReason": null,
      "ipAddress": "1.2.3.4",
      "userAgent": "Mozilla/5.0",
      "location": null,
      "fileHash": "a1b2c3...",
      "remarks": "短信意愿核验通过（手机号：138****8000）；人脸活体意愿核验通过"
    },
    {
      "recordId": 102,
      "participantId": 12,
      "userId": 10002,
      "orgId": 863409687826006869,
      "signerName": "某某科技有限公司",
      "signerContact": "13900139000",
      "signerType": "ENTERPRISE",
      "signedTime": "2026-07-29 11:35:00",
      "verifyMethod": "SMS",
      "smsVerified": true,
      "faceVerified": false,
      "signingOrder": 2,
      "status": "SUCCESS",
      "failReason": null,
      "ipAddress": "1.2.3.5",
      "userAgent": "Mozilla/5.0",
      "location": null,
      "fileHash": "d4e5f6...",
      "remarks": "短信意愿核验通过"
    }
  ]
}

说明：尚无任何人签署时返回空数组 []。

3.16 合同撤回

  • 接口路径：POST /contract/revoke/{contractId}
  • 请求类型：JSON（Content-Type: application/json）；Body 可为空或省略
  • 功能说明：撤回待签署合同，状态由 PENDING 变为 REVOKED；草稿/已签/已撤回不可调用
  • 租户校验：不校验 API Key 所属租户与合同归属、不校验发起方组织；仅校验合同状态为 PENDING

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 否 有 Body 时建议 application/json

路径参数

参数名 类型 必填 描述
contractId String 是 合同ID

请求参数（Body，均可选）

参数名 类型 必填 描述
userId String 否 操作人用户 ID；不传则使用合同创建人
remarks String 否 撤回备注，写入操作记录；默认「合同撤回」

响应参数

参数名 类型 描述
contractId Long 合同ID
title String 合同标题
status String 撤回后为 REVOKED（见 合同状态说明）
createdAt String 创建时间
请求示例
JSON
{
  "userId": "10001",
  "remarks": "对方要求暂停签署"
}
响应示例
JSON
{
  "success": true,
  "msg": "撤回成功",
  "data": {
    "contractId": 1,
    "title": "服务协议",
    "status": "REVOKED",
    "createdAt": "2026-07-29 10:00:00"
  }
}

常见错误：非 PENDING 状态（如已签完、已撤回、草稿）会返回「当前状态的合同无法撤回」；合同不存在或已删除同其他合同接口。

3.17 删除合同

  • 接口路径：DELETE /contract/delete/{contractId}
  • 请求类型：无 JSON Body；可选 Query 参数
  • 功能说明：删除合同。仅 DRAFT（草稿）或 REVOKED（已撤回）可删；PENDING（待签署）与 SIGNED（已签署）不可删。删除后列表与状态查询将查不到该合同
  • 租户校验：不校验 API Key 所属租户与合同归属是否一致；仅校验合同状态允许删除

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId String 是 合同ID

查询参数

参数名 类型 必填 描述
userId String 否 操作人用户 ID；不传则使用合同创建人

响应参数

参数名 类型 描述
data Long 被删除的合同 ID
请求示例
HTTP
DELETE /api/v1/contract/delete/1?userId=10001
Authorization: Bearer <token>
响应示例
JSON
{
  "success": true,
  "msg": "删除成功",
  "data": 1
}

常见错误：PENDING / SIGNED 会返回「该合同已提交签署或已完成签署，无法删除」；已删除或不存在返回「合同不存在或已删除」。若需去掉待签合同，请先 §3.16 撤回 再删除。

3.18 下载合同文件

  • 接口路径：GET /contract/download/{contractId}
  • 请求类型：无 JSON Body；Query 参数 type 区分下载内容
  • 功能说明：一个接口按类型下载：签署后的合同 PDF、证据报告 PDF、或归档 OFD。成功时直接返回文件二进制流（非 JSON Result），失败时仍返回 JSON 业务错误
  • 租户校验：不校验 API Key 所属租户与合同归属是否一致，仅按合同 ID 查询（与 §3.14–§3.17 一致）

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
contractId String 是 合同 ID

查询参数

参数名 类型 必填 描述
type String 否 下载类型，默认 CONTRACT。可选：
  • CONTRACT：签署后的合同 PDF（Content-Type: application/pdf）
  • EVIDENCE：区块链证据报告 PDF（application/pdf）
  • ARCHIVE：归档 OFD 文件（application/ofd；合同须已归档）
兼容别名：SIGNED_PDF/PDF→CONTRACT，EVIDENCE_REPORT→EVIDENCE，OFD/ARCHIVE_OFD→ARCHIVE
请求示例
HTTP
# 下载合同 PDF
GET /api/v1/contract/download/1?type=CONTRACT
Authorization: Bearer <token>

# 下载证据报告
GET /api/v1/contract/download/1?type=EVIDENCE
Authorization: Bearer <token>

# 下载归档文件
GET /api/v1/contract/download/1?type=ARCHIVE
Authorization: Bearer <token>
成功响应
  • HTTP 200，Body 为文件字节流
  • Content-Disposition: attachment; filename*=UTF-8''...
  • Content-Type：合同/证据为 application/pdf；归档为 application/ofd

常见错误（JSON）：合同不存在或已删除；合同文件不存在（尚未生成签署 PDF）；ARCHIVE 时「合同尚未归档，无法下载归档文件」；type 非法。

3.19 发送短信验证码

  • 接口路径：POST /contract/send-sms-code
  • 请求类型：表单（application/x-www-form-urlencoded）或 URL Query；参数名 mobile（与下列「查询参数」一致）
  • 功能说明：向指定手机号发送签署场景短信验证码，用于意愿认证（业务类型 SIGN）

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
mobile String 是 接收验证码的手机号

响应参数

参数名 类型 描述
data String 固定为 OK 表示已触发发送
响应示例
JSON
{
  "success": true,
  "data": "OK"
}

说明：发送频率、有效期等规则与系统内签署验证码策略一致；请勿频繁调用以免触发限流。

3.20 获取活体验证（人脸识别）

  • 接口路径：POST /contract/face-recognition
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：根据姓名与身份证号发起 H5 活体认证，返回二维码链接与 token（需 Bearer 令牌，无需传递用户 ID）

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求体（JSON）

参数名 类型 必填 描述
realName String 是 真实姓名
idCard String 是 身份证号
isReturnUrl Boolean 否 为 true 时 data.qrCodeUrl 直接为认证页 URL；否则为二维码图片地址
returnUrl String 否 认证完成后的跳转地址（未传时由服务端使用占位默认值）
请求示例
JSON
{
  "realName": "张三",
  "idCard": "320***********1234",
  "isReturnUrl": true,
  "returnUrl": "https://example.com/h5/sign/callback"
}

响应参数（data 对象）

参数名 类型 描述
qrCodeUrl String 二维码图片 URL 或认证页 URL（取决于 isReturnUrl）
token String 本次活体会话 token，用于后续查询认证结果
响应示例
JSON
{
  "success": true,
  "data": {
    "qrCodeUrl": "https://...",
    "token": "xxxxxxxx"
  }
}

说明：返回的 token 用于后续签署等流程中的活体验证；服务端会将姓名、证件号与 token 短时关联缓存。开放接口中该 token 有效期为 12 小时（其他场景默认 30 分钟）。需在个人开户/实名前为指定平台用户发起活体、并与该用户 ID 绑定时，使用 §5.5 POST /person/face-recognition（userId 可选）；查询结果仍可用本节下一小节 §3.21 或 §5.6（路径不同，参数与响应结构一致）。

3.21 根据 token 查询活体是否认证成功

  • 接口路径：GET /contract/face-recognition/success
  • 请求类型：无 JSON/表单请求体；参数 token 见 URL Query
  • 功能说明：根据活体 token 查询认证结果，返回是否通过与是否计费等信息

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
token String 是 活体 token（POST /contract/face-recognition 返回的 data.token）

响应参数

参数名 类型 描述
data Object 活体状态对象
data.passed Boolean 是否通过：true 通过；false 未通过/未完成
data.charged Boolean 是否计费：按返回 code 判断（R101、R102、R214、R215、R216、R218、R219、R221、R233、R234、R235 视为计费）
data.code String 认证结果码（用于判断通过与计费）
data.codeDesc String 结果描述
响应示例
JSON
{
  "success": true,
  "data": {
    "passed": true,
    "charged": true,
    "code": "R102",
    "codeDesc": "认证成功"
  }
}

3.22 根据 token 查询活体token是否过期

  • 接口路径：GET /contract/face-recognition/check-token
  • 请求类型：无 JSON/表单请求体；参数 token 见 URL Query
  • 功能说明：根据活体 token 查询 token 是否在 Redis 中存在（即是否过期），返回剩余有效期等信息。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
token String 是 活体 token（POST /contract/face-recognition 返回的 data.token）

响应参数

参数名 类型 描述
data Object Token 有效性信息对象
data.valid Boolean token 是否有效：true 未过期；false 已过期或不存在
data.remainingSeconds Long 剩余有效期（秒）。-2 表示 token 不存在；>0 为剩余秒数；null 表示查询失败
data.message String 描述信息，如“活体token有效，剩余43185秒”或“活体token已过期或不存在”
响应示例（token 有效）
JSON
{
  "success": true,
  "message": "token有效",
  "data": {
    "valid": true,
    "remainingSeconds": 43185,
    "message": "活体token有效，剩余43185秒"
  }
}
响应示例（token 已过期）
JSON
{
  "success": true,
  "message": "token已过期或不存在",
  "data": {
    "valid": false,
    "remainingSeconds": -2,
    "message": "活体token已过期或不存在"
  }
}

使用场景：在调用 §3.23 开放签署 PDF 之前，可先通过本接口检查 token 是否仍然有效，避免使用过期 token 发起签署请求。注意：本接口仅检查 token 是否存在，不验证活体认证是否通过（请使用 §3.21 查询认证结果）。

3.23 开放签署 PDF（关键词落章）

  • 接口路径：POST /contract/sign-pdf
  • 请求类型：JSON（Content-Type: application/json）
  • 能力：上传待签 PDF（fileContentBase64），在文档内用 keyword 定位落章点，经意愿校验后在该位置落章，返回已签 PDF 的 Base64。本接口不持久化合同主数据。须传 contractNo 作业务与存证编号；已配链时可回 openSignEvidenceId、transactionHash。签章区域固定 126×126。verifyType 未传时默认 1,2（需按实参传 faceToken、smsCode）。

联调前

  • 意愿含短信（verifyType 含 2）时：先调 POST /contract/send-sms-code，业务类型 SIGN，再向本接口传 smsCode。
  • 意愿含活体（含 1）时：先调 POST /contract/face-recognition 取 faceToken，再向本接口传入。
  • 参与人为新个人、或三要素在平台创建新企业时，须按下文「企业新建」对活体、法人三要素的约束准备参数。

印模用名

当次落章在平台上与哪一枚印匹配，由「印模用名」决定：只根据请求体你填的字段推导，不会用库内企业名自动顶替。

签署方 当次印模用名
企业 ENTERPRISE / COMPANY enterpriseName 非空时取其值；否则取 participantName
个人 PERSONAL 取 participantName

仅会选用平台印章「名称」与当次印模用名逐字相同的章（详见「选章与 sealId」）。participantMobile 须为解析到签署人平台账号的绑定手机。通常 participantName 填经办人真名，并与账号登记姓名一致；若将 participantName 填为企业/印模用名（与账号名不同），则须该账号在本企业下或本人名下存在同「名称」的可用章（本企业章、本人章或用印授权，与 §6.5 同源数据），否则不通过。

按参与方准备参数

个人（participantType=PERSONAL）：以 participantMobile 定位用户；participantName 与实名、章面一致。含 1 时传 faceToken，含 2 时传 smsCode。无个人账号时可由当次活体会话在平台完成开户。

企业：目标已存在且可唯一定位：企业名/统一社会信用代码在平台能唯一条命中已认证企业，或你直接传 participantOrgId（须已认证）。participantUserId 一般可省略，以 participantMobile 在该目标企业下已加入用户中找经办。若多人在同机号，请补充 enterpriseName、participantName 等由服务端消歧，仍不唯一时可再传 participantUserId。仅按名命中多家已认证企业时，须传 participantOrgId 指定其一。

多数场景只传 participantMobile 与企业相关字段即可不必在本地存 sealId、participantUserId。确需多枚章中强指定时 sealId 可选，且该章「名称」须与当次印模用名一致（见下表 sealId 行）。用印授权由服务端在 §6.5 同数据上匹配，一般不需要为签署先调授权查询接口（§6.5.4 为运营/对账可选）。

企业：三要素在平台新建：当名称/码尚不能唯一定位已认证企业时，verifyType 须含 1 并传 faceToken。请求带 unifiedSocialCreditCode、legalPersonName、legalPersonIdCard 等，以 enterpriseName / participantName 声明拟盖的企业章/印模用名（企业盖章时 participantName 可填企业名，不必同法人体检名）。首次在平台创建该企业时，法人姓名/证件号须与当前 faceToken 活体会话中实名、证件号一致。

各参与方通用：若 verifyType 含 1，且已存在与活体同证件的个人档案且其预留手机已填写，该号码须与 participantMobile 一致，否则拒签。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求体（JSON）主要字段

参数名 类型 必填 描述
contractNo String 是 业务合同编号；用于存证与蚂蚁链摘要，建议接入方保证在自身业务域内唯一
fileContentBase64 String 是 PDF 文件 Base64（可含 data: 前缀）
fileType String 是 目前仅支持 pdf
keyword String 是 用于定位签章位置的关键词
keywordOccurrenceIndex Integer 否 第几次出现（从 0 开始）；默认 0
sealId Long 否 一般可不传。不传时，仅在 「名称」与当次印模用名逐字相同 的候选项中落章；同一名称多枚时优先选默认章（isDefault=true，详见「印章自动选用与用印授权」）。须指定某一枚时传 sealId：该章的「名称」须与当次印模用名一致，否则报错；若名称一致但非本企业组织下章、且对签署人尚无用印授权，将不采用该 id，改在同印模用名候选项中按自动选章（仍优先默认章）。章属本企业组织、或已获用印授权时，使用所传 sealId 落章。
verifyType String 否 1 仅活体，2 仅短信，1,2 两者；不传默认 1,2
faceToken String 条件 验证类型含 1 或（个人且用户不存在，或企业三要素新建需开户）时必传；活体流程返回的 token。含 1 时，若已有个人实名档案与活体姓名、证件号一致，其预留手机号须与 participantMobile 一致
smsCode String 条件 验证类型含 2 时必传；与 participantMobile 对应，业务类型 SIGN
participantName String 是 参与人相关姓名：个人须与实名人名、个人章印模、活体姓名等一致；企业可填经办人姓名，与解析账号登记姓名须一致，或与同机号/账号在当次可用人名/同名企业章的核对规则见上文「印模用名与参与人关联」；亦可将本字段填为企业/印模用名（与 enterpriseName 二选一/并存关系见 enterpriseName 说明），此时以印模、授权为准
participantMobile String 是 参与人手机号，须为本次签署在平台中解析到账号所绑定的手机，并与短信/活体核对目标一致
participantType String 是 PERSONAL 个人；ENTERPRISE 或 COMPANY 企业
participantUserId Long 条件 企业已存在且已认证时可省略：用 participantMobile 在目标企业组织下解析经办用户；解析失败或多解时再传本字段。企业将按名称新建（三要素）时可省略，须 verifyType 含 1 且传 faceToken。个人可选，用于多账号时指定
participantOrgId Long 否 企业组织实体 ID；须为平台内已认证企业。不传则按企业名称（及可选统一社会信用代码）全局匹配；多条命中时必填本字段
enterpriseName String 条件 企业参与时建议填写：公章/印模上主体名称，亦作为印模用名优先来源。无 participantOrgId 时用于匹配/创建企业。未传时印模用名退化为 participantName，由接入方保证与拟盖印章「名称」一致；二者语义区分：本字段偏企业全称/公章名，participantName 常填经办人，也可在对接上改填企业名（与上文「印模用名与参与人关联」一起读）
unifiedSocialCreditCode String 条件 统一社会信用代码；企业不在系统中与三要素一并必填
legalPersonName String 条件 法人姓名；企业新建时必填。首次建企且 verifyType 含活体时，须与 faceToken 对应活体会话中的姓名一致
legalPersonIdCard String 条件 法人身份证号；企业新建时必填。首次建企且含活体时，须与 faceToken 对应活体会话中的证件号一致
offsetX / offsetY Float 否 相对关键词命中点的偏移（单位：像素）
sealWidth / sealHeight Float 否 印章宽度/高度（单位：点，pt）。默认值：126pt（约 44.4mm）；最小值：28.4pt（约 10mm）。不传时使用默认值，保持原有尺寸不变。适用于需要自定义印章大小的场景
destroyFaceTokenAfterUse Boolean 否 活体token是否用完即销毁（默认 false）。true: 签署完成后立即销毁活体token；false: 活体token保留至自然过期（12小时或30分钟）。适用于一次性签署场景，提升安全性

选章与用印授权

在已得到当次印模用名（见上表）且已解析出签署人（通常由 participantMobile 在企业内定位）的前提下，只在平台印章「名称」与印模用名逐字相同的集合中选章；不要求必传 sealId。显式传 sealId 时，该章「名称」须仍与印模用名一致。无可用同名章或未获授权时签署失败。

① 本企业组织下：名称与印模用名相同的多枚中优先默认章（isDefault=true），否则按服务端规则取定。个人组织同。

② 本人制章（制章人为当前签署人）：同名多枚时优先默认章。

③ 用印授权（§6.5 同源、未撤销）：仍须名与印模用名一致，多枚时优先默认。§6.5.4 列表为运营/对账用，非签署必调。

响应参数（data）

参数名 类型 描述
contractNo String 回显请求中的业务合同编号
signedFileBase64 String 签署后的 PDF Base64
signerUserId Long 签署人用户 ID
sealId Long 实际落章使用的印章 ID
orgEntityId Long 仅当签署方为企业（ENTERPRISE/COMPANY）时返回：落章所属企业组织实体 ID；个人签署不返回该字段（值为空）
openSignEvidenceId Long 本笔开放签署的存证业务标识；蚂蚁链未配置或上链失败时可能为空
transactionHash String 蚂蚁链交易哈希；未上链时为空

补充：三要素新建企业通过后，由服务端创建企业及默认章；首次建企时法人姓名、证件号须与当次 faceToken 活体会话一致。个人新用户须先完成 POST /contract/face-recognition。含短信意愿时须先 POST /contract/send-sms-code 再传 smsCode（同「联调前」）。

4. 企业账号管理

企业相关能力：查询用户已加入的企业、创建企业、查询企业详情、企业三要素核验，以及将用户加入企业。

4.1 查询用户企业列表

  • 接口路径：GET /org/list
  • 请求类型：无 Body；Query 必填 userId
  • 功能说明：查询指定用户可访问的企业（含公司、个体户），用于选企。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
userId String 是 平台用户 ID

响应参数

参数名 类型 描述
data Array 企业列表
data[].orgId String 企业组织 ID
data[].name String 企业名称
data[].unifiedCode String 统一社会信用代码
data[].entityType String 组织类型：COMPANY / SELF_EMPLOYED
data[].certifyStatus String 认证状态：VERIFIED / UNVERIFIED
data[].source String 来源：用户已加入该企业
响应示例
JSON
{
  "success": true,
  "data": [
    {
      "orgId": "1",
      "name": "某某科技有限公司",
      "unifiedCode": "91330000MA2XXXXXX",
      "entityType": "COMPANY",
      "certifyStatus": "VERIFIED",
      "source": "OWN"
    },
    {
      "orgId": "88",
      "name": "合作方有限公司",
      "unifiedCode": "91330000MA2YYYYYY",
      "entityType": "COMPANY",
      "certifyStatus": "VERIFIED",
      "source": "SEAL_AUTH"
    }
  ]
}

4.2 添加企业账号

  • 接口路径：POST /org/add
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：为企业账号完成企业认证并创建企业。要求 userId 对应用户已个人实名；未传 phone 时使用该用户手机号。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

请求参数

参数名 类型 必填 描述
userId Long 是 用户ID（须已个人实名认证）
name String 是 企业名称
unifiedCode String 是 统一社会信用代码
legalName String 是 法定代表人姓名
legalIdCard String 是 法定代表人身份证号
phone String 否 法定代表人手机号；未传则取 userId 对应用户手机号
请求示例
JSON
{
  "userId": 1,
  "name": "测试公司",
  "unifiedCode": "91110000MA12345678",
  "legalName": "张三",
  "legalIdCard": "110101199001011234",
  "phone": "13800138000"
}

响应参数

参数名 类型 描述
orgId Long 组织ID
name String 企业名称
unifiedCode String 统一社会信用代码
certifyStatus String 认证状态：VERIFIED / UNVERIFIED
legalName String 法人姓名
响应示例
JSON
{
  "success": true,
  "data": {
    "orgId": 1,
    "name": "测试公司",
    "unifiedCode": "91110000MA12345678",
    "certifyStatus": "VERIFIED",
    "legalName": "张三"
  }
}

4.3 查询企业账号

  • 接口路径：GET /org/get/{orgId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path
  • 功能说明：查询企业账号详情

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
orgId Long 是 组织ID

响应参数

参数名 类型 描述
orgId Long 组织ID
name String 企业名称
unifiedCode String 统一社会信用代码
certifyStatus String 认证状态
legalName String 法人姓名
响应示例
JSON
{
  "success": true,
  "data": {
    "orgId": 1,
    "name": "测试公司",
    "unifiedCode": "91110000MA12345678",
    "certifyStatus": "UNVERIFIED",
    "legalName": "张三"
  }
}

4.4 按企业三要素查询企业与印章

  • 接口路径：POST /org/lookup-identity
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：先调用与控制台「企业法人认证」POST /auth/enterprise/legal-person 同源的创瑞企业三要素核验（企名+统一社会信用代码+法人姓名），通过后再在平台内查组织与印章。在全部未删除的 COMPANY / SELF_EMPLOYED 中按企名+统一社会信用代码匹配；每条印章含制章人用户 ID与制章人手机号。多命中时取组织 id 最大的一条。响应中 legalName 为经核验的法人姓名；若与平台主账号登记略有不一致，仅记日志不拦截。

请求体（JSON）

参数名 类型 必填 描述
name String 是 企业名称
unifiedCode String 是 统一社会信用代码
legalName String 是 法人姓名

响应 data 主要字段

参数名 类型 描述
orgId / name / unifiedCode / certifyStatus — 企业组织标识、名称、统一码、认证状态（如 VERIFIED / UNVERIFIED）
legalName String 与三要素通过校验的登记用户姓名
seals Array 该组织下印章列表。元素含 sealId、name、isDefault、sealCreatedByUserId、sealCreatedByUserMobile
请求示例
JSON
{
  "name": "某科技公司",
  "unifiedCode": "91110000MA12345678",
  "legalName": "张三"
}
响应示例
JSON
{
  "success": true,
  "data": {
    "orgId": 1001,
    "name": "某科技公司",
    "unifiedCode": "91110000MA12345678",
    "certifyStatus": "VERIFIED",
    "legalName": "张三",
    "seals": [
      {
        "sealId": 1,
        "name": "某科技公司",
        "isDefault": true,
        "sealCreatedByUserId": 2,
        "sealCreatedByUserMobile": "13800138000"
      }
    ]
  }
}

4.5 用户加入企业

  • 接口路径：POST /org/join
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：将指定用户加入指定企业。开放接口加入后即可使用（无需企业管理员再审核）。常用于变更企业章持有人之前，先让新持有人加入目标企业。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

请求体（JSON）

参数名 类型 必填 描述
userId Long 是 要加入组织的平台用户 ID
orgId Long 是 企业/个体户组织实体 ID（OrgEntity.id）

响应

成功时返回入企结果（含企业、用户及加入时间等）。

请求示例
JSON
{
  "userId": 100,
  "orgId": 2001
}
响应示例
JSON
{
  "success": true,
  "data": {
    "id": 3001,
    "orgEntityId": 2001,
    "userId": 100,
    "status": "ACTIVE",
    "joinTime": "2026-04-26T10:00:00"
  }
}
  • 接口路径：POST /contract/change-legal-person
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：按企业名称与统一社会信用代码定位企业，将法人变更为指定用户。若新法人尚无账号，系统将自动开户。注意：变更后企业归新法人使用，企业下印章一并跟随。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求体（JSON）

参数名 类型 必填 描述
enterpriseName String 是 企业名称，用于定位企业
unifiedSocialCreditCode String 是 统一社会信用代码，用于精确定位企业（必传）
newLegalName String 是 新法人姓名
newLegalIdCard String 是 新法人身份证号
faceToken String 是 活体认证 token，用于验证新法人身份。需先调用 §3.20 获取
contactPhone String 是 联系电话，用于创建新用户和更新企业联系方式（必传）
请求示例
JSON
{
  "enterpriseName": "测试有限公司",
  "unifiedSocialCreditCode": "91110000MA12345678",
  "newLegalName": "李四",
  "newLegalIdCard": "320***********5678",
  "faceToken": "xyz789abc",
  "contactPhone": "13800138000"
}

响应参数

参数名 类型 描述
data Object 变更结果对象
data.orgId Long 企业组织ID
data.newLegalUserId Long 新法人用户ID
data.sealCount Integer 已迁移的印章数量
响应示例
JSON
{
  "success": true,
  "message": "法人变更成功",
  "data": {
    "orgId": 123456,
    "newLegalUserId": 987654321,
    "sealCount": 2
  }
}

业务规则

  • 企业查询：使用企业名称 + 统一社会信用代码进行精确匹配，确保定位到唯一的企业
  • 新法人处理：
    • 若新法人已存在：直接使用该用户作为企业新法人
    • 若新法人不存在：自动创建新用户并关联为企业法人
  • 企业归属迁移：
    • 企业将迁移到新法人的账号下
    • 企业下所有印章也会跟随企业同步迁移
  • 活体验证：必须提供有效的活体 token，用于验证新法人身份真实性
  • 审计记录：系统会自动记录法人变更信息，包括变更时间等

注意事项：

  • 变更后企业归属到新法人的账号下，原法人不再拥有该企业
  • 企业下的所有印章也会跟随企业迁移到新法人账号
  • 建议变更前确认新法人已完成实名认证
  • 联系电话将用于创建新用户（如需要）和更新企业联系方式

5. 个人账号管理

5.1 添加个人账号

  • 接口路径：POST /person/add
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：添加个人账号，用于合同签署

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

请求参数

参数名 类型 必填 描述
name String 是 姓名
mobile String 是 手机号
请求示例
JSON
{
  "name": "张三",
  "mobile": "13800138000"
}

响应参数

参数名 类型 描述
userId Long 用户ID
name String 姓名
mobile String 手机号
realNameStatus String 实名状态
响应示例
JSON
{
  "success": true,
  "data": {
    "userId": 1,
    "name": "张三",
    "mobile": "13800138000",
    "realNameStatus": "UNVERIFIED"
  }
}

5.2 查询个人账号

  • 接口路径：GET /person/get/{userId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path
  • 功能说明：查询个人账号详情

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
userId Long 是 用户ID

响应参数

参数名 类型 描述
userId Long 用户ID
name String 姓名
mobile String 手机号
realNameStatus String 实名状态
响应示例
JSON
{
  "success": true,
  "data": {
    "userId": 1,
    "name": "张三",
    "mobile": "13800138000",
    "realNameStatus": "UNVERIFIED"
  }
}

5.3 按手机号查询姓名与身份证

  • 接口路径：POST /person/lookup-by-mobile
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：根据手机号查询平台用户姓名与身份证号。与 §5.9 按实名查用户与章 互为反向查询：本接口由手机查实名，§5.9 由姓名+身份证查用户与印章。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求参数

参数名 类型 必填 描述
mobile String 是 手机号

响应参数

参数名 类型 描述
userId Long 用户 ID
mobile String 手机号
realName String 姓名；已完成个人实名时取个人组织姓名，否则取用户表姓名
idNumber String 身份证号；用户已完成个人实名/制章时返回，未实名时为空
请求示例
JSON
{
  "mobile": "13800138000"
}
响应示例
JSON
{
  "success": true,
  "data": {
    "userId": 123456,
    "mobile": "13800138000",
    "realName": "张三",
    "idNumber": "110101199001011234"
  }
}
业务说明
  • 手机号在平台内唯一匹配到一名用户时返回结果
  • 若该手机号对应多个用户，接口报错，请改用 userId 或 §5.9 按姓名+身份证查询
  • 若手机号未注册，返回「未找到该手机号对应的用户」

5.4 账号注销

  • 接口路径：DELETE /person/delete/{userId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path
  • 功能说明：注销个人账号

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
userId String 是 用户ID

响应参数

参数名 类型 描述
deleted Boolean 是否注销成功
响应示例
JSON
{
  "success": true,
  "data": {
    "deleted": true
  }
}

5.5 获取个人活体验证（人脸识别）

  • 接口路径：POST /person/face-recognition
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：与 §3.20 POST /contract/face-recognition 同源（姓名、身份证号发起 H5 活体，返回二维码或认证页 URL 与 token）。userId 为可选参数：传递 userId 时绑定系统用户并校验该用户存在且未注销，否则不返回成功；不传 userId 时仅进行活体验证。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求体（JSON）

参数名 类型 必填 描述
userId Long 否 平台个人用户 ID（传递时须存在且未注销，否则失败；不传时仅活体验证）
realName String 是 真实姓名
idCard String 是 身份证号
isReturnUrl Boolean 否 为 true 时 data.qrCodeUrl 直接为认证页 URL；否则为二维码图片地址
returnUrl String 否 认证完成后的跳转地址（未传时由服务端使用占位默认值）
请求示例（不传 userId）
HTTP
POST /person/face-recognition
Content-Type: application/json

{
  "realName": "张三",
  "idCard": "320***********1234"
}
请求示例（传递 userId）
HTTP
POST /person/face-recognition
Content-Type: application/json

{
  "userId": 123,
  "realName": "张三",
  "idCard": "320***********1234",
  "isReturnUrl": true,
  "returnUrl": "https://example.com/h5/callback"
}

响应参数（data 对象）

与 §3.20 相同：qrCodeUrl、token。

参数名 类型 描述
qrCodeUrl String 二维码图片 URL 或认证页 URL（取决于 isReturnUrl）
token String 本次活体会话 token，用于 §5.6 或 §3.21 查询结果
响应示例
JSON
{
  "success": true,
  "data": {
    "qrCodeUrl": "https://...",
    "token": "xxxxxxxx"
  }
}
业务说明
  • userId 为可选参数：不传 userId 时，系统会自动将 requestNotice 设为 false（不发送通知）
  • 传递 userId 时：用户必须存在且未注销，否则接口失败；通过后 requestNotice 为 true，会发送活体验证结果通知
  • 不传 userId 时：仅进行活体验证，不与系统用户绑定
  • 返回的 token 有效期为 12 小时，用于后续签署等流程中的活体验证

5.6 根据 token 查询个人侧活体是否认证成功

  • 接口路径：GET /person/face-recognition/success
  • 请求类型：无 JSON/表单请求体；参数 token 见 URL Query
  • 功能说明：与 §3.21 GET /contract/face-recognition/success 一致，仅路径前缀为 /person；根据活体 token 返回是否通过、是否计费及结果码等。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
token String 是 活体 token（POST /person/face-recognition/{userId} 或合同侧活体接口返回的 data.token）

响应参数

与 §3.21 相同：data.passed、data.charged、data.code、data.codeDesc。

参数名 类型 描述
data Object 活体状态对象
data.passed Boolean 是否通过：true 通过；false 未通过/未完成
data.charged Boolean 是否计费：按返回 code 判断（与 §3.21 所列计费码一致）
data.code String 认证结果码（用于判断通过与计费）
data.codeDesc String 结果描述
响应示例
JSON
{
  "success": true,
  "data": {
    "passed": true,
    "charged": true,
    "code": "R102",
    "codeDesc": "认证成功"
  }
}

5.7 运营商三要素验证

  • 接口路径：POST /person/three-factor-verification
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：验证姓名、身份证号、手机号三要素是否匹配。仅返回验证结果，不进行用户创建、组织创建等额外操作。适用于外部系统身份预验证。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>
Content-Type String 是 application/json

请求体（JSON）

参数名 类型 必填 描述
realName String 是 真实姓名
idCard String 是 身份证号
phone String 是 手机号
请求示例
JSON
{
  "realName": "张三",
  "idCard": "320***********1234",
  "phone": "13800138000"
}

响应参数

参数名 类型 描述
data Object 验证结果对象
data.verified Boolean 是否验证通过：true 三要素一致；false 不一致或验证失败
data.charged Boolean 是否计费：true 计费；false 不计费
data.code String 状态码（详见下方状态码说明）
data.message String 验证结果描述或错误原因

状态码说明

状态码 含义 是否计费
1 手机三要素一致 ✅ 是
2 手机三要素不一致 ✅ 是
3 请求参数错误 ❌ 否
10001 查询无结果 ❌ 否
10002 授权不通过 ❌ 否
10003 白名单不通过 ❌ 否
10004 余额不足 ❌ 否
10005 无效的证件号 ❌ 否
20000 系统异常 ❌ 否
20001 参数错误 ❌ 否
20002 参数映射异常 ❌ 否
20003 运营商无可用供应商 ❌ 否
20004 无效的签名算法 ❌ 否
20005 模板未找到 ❌ 否
响应示例（验证通过）
JSON
{
  "success": true,
  "message": "三要素验证通过",
  "data": {
    "verified": true,
    "charged": true,
    "code": "1",
    "message": "手机三要素一致"
  }
}
响应示例（验证失败但计费）
JSON
{
  "success": true,
  "message": "三要素验证失败",
  "data": {
    "verified": false,
    "charged": true,
    "code": "2",
    "message": "手机三要素不一致"
  }
}
响应示例（不计费错误）
JSON
{
  "success": true,
  "message": "三要素验证失败",
  "data": {
    "verified": false,
    "charged": false,
    "code": "10004",
    "message": "余额不足"
  }
}

注意：本接口仅进行验证，不会创建用户、组织或印章，也不会发送通知。如需完成实名认证并创建个人账号，请使用其他接口。

5.8 获取独立认证页面

  • 接口路径：POST /person/certify-page
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：获取个人账号的独立认证页面链接

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

请求参数

参数名 类型 必填 描述
userId Long 是 用户ID
notifyUrl String 否 实名认证完成回调推送地址
redirectUrl String 否 实名认证完成后跳转地址

响应参数

参数名 类型 描述
h5Url String 实名链接（H5）
pcUrl String 实名链接（PC）
userId Long 用户ID

notifyUrl、redirectUrl 由服务端与 token 关联存储，打开链接后通过 GET /login-by-token 获取，不会出现在 URL 查询参数中。

链接格式：{前端域名}/open-verification/{h5|pc}/{token}，token 默认有效期 3600 秒。

响应示例
JSON
{
  "success": true,
  "data": {
    "h5Url": "https://example.com/open-verification/h5/abcdef123456",
    "pcUrl": "https://example.com/open-verification/pc/abcdef123456",
    "userId": 123
  }
}

5.9 按姓名、身份证号查询用户与可用印章

  • 接口路径：POST /person/lookup-identity
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：按姓名与身份证号查找个人，返回用户、可用印章（自有与授权）及已加入的企业。

请求体（JSON）

参数名 类型 必填 描述
realName String 是 真实姓名
idNumber String 是 身份证号

响应 data 主要字段

参数名 类型 描述
userId / mobile Long / String 匹配到的平台用户与绑定手机
boundEnterprises Array 用户已加入/绑定的企业组织（ACTIVE）。元素含 orgId、name、unifiedCode、entityType（COMPANY / SELF_EMPLOYED）
seals Array 可用印章列表。元素含 sealId、name、isDefault、relationType、sealOrgId、sealOrgType、sealOrgName、sealOrgIdNumber（个人组织为身份证号，企业组织为统一社会信用代码）、sealCreatedByUserId、sealCreatedByUserMobile、sealCreatedByUserIdNumber（制章人身份证号，取自其个人实名组织）
请求示例
JSON
{
  "realName": "张三",
  "idNumber": "110101199001011234"
}
响应示例
JSON
{
  "success": true,
  "data": {
    "userId": 1,
    "mobile": "13800138000",
    "boundEnterprises": [
      {
        "orgId": 100,
        "name": "某科技公司",
        "unifiedCode": "91110000MA12345678",
        "entityType": "COMPANY"
      }
    ],
    "seals": [
      {
        "sealId": 10,
        "name": "张三",
        "isDefault": true,
        "relationType": "OWN",
        "sealOrgId": 50,
        "sealOrgType": "PERSONAL",
        "sealOrgName": "张三",
        "sealOrgIdNumber": "110101199001011234",
        "sealCreatedByUserId": 1,
        "sealCreatedByUserMobile": "13800138000",
        "sealCreatedByUserIdNumber": "110101199001011234"
      }
    ]
  }
}

5.10 通过验证码修改手机号

  • 接口路径：POST /person/change-mobile-by-sms
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：通过原手机号和新手机号的验证码修改手机号。需要分别发送原手机号和新手机号的验证码。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

请求体（JSON）

参数名 类型 必填 描述
oldMobile String 是 原手机号（通过原手机号自动定位用户）
oldCode String 是 原手机号验证码（场景码：CHANGE_MOBILE_OLD）
newMobile String 是 新手机号
newCode String 是 新手机号验证码（场景码：CHANGE_MOBILE_NEW）
请求示例
JSON
{
  "oldMobile": "13800138000",
  "oldCode": "123456",
  "newMobile": "13900139000",
  "newCode": "654321"
}
响应示例
JSON
{
  "success": true,
  "data": "手机号修改成功"
}
业务说明
  • 需要先调用短信接口发送原手机号验证码（场景码：CHANGE_MOBILE_OLD）
  • 需要先调用短信接口发送新手机号验证码（场景码：CHANGE_MOBILE_NEW）
  • 修改成功后会自动同步更新 tenant 表和 orgEntity 表的联系电话
  • 新手机号不能已被其他用户使用

5.11 通过活体认证修改手机号

  • 接口路径：POST /person/change-mobile-by-face
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：通过姓名、身份证号匹配并验证活体认证后修改手机号。适用于原手机号不可用的场景。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

请求体（JSON）

参数名 类型 必填 描述
userId Long 否 用户ID（当姓名+身份证号匹配到多个用户时必填）
realName String 是 真实姓名
idCard String 是 身份证号
faceToken String 是 活体认证token（通过活体验证接口获取）
newMobile String 是 新手机号
请求示例（单个用户匹配）
JSON
{
  "realName": "张三",
  "idCard": "110101199001011234",
  "faceToken": "face_token_xxx",
  "newMobile": "13900139000"
}
请求示例（多个用户匹配）
JSON
{
  "userId": 123456,
  "realName": "张三",
  "idCard": "110101199001011234",
  "faceToken": "face_token_xxx",
  "newMobile": "13900139000"
}
响应示例
JSON
{
  "success": true,
  "data": "手机号修改成功"
}
业务说明
  • 需要先调用活体验证接口（/person/face-recognition）获取 faceToken
  • 系统会根据姓名和身份证号自动匹配用户
  • 当姓名+身份证号匹配到多个用户时，必须传递 userId 参数指定具体用户
  • 验证活体认证状态必须为通过（passed = true）
  • 新手机号不能已被其他用户使用
  • 活体 token 有效期通常为 1 小时，请及时使用

6. 印章管理

6.1 添加印章

  • 接口路径：POST /seal/add
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：为指定用户添加印章（系统自动生成印模）。用户登录平台后可查看并使用该印章。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

请求参数

参数名 类型 必填 描述
name String 是 印章名称
type Integer 是 印章类型（1-个人章，2-企业章）
orgId Long 否 所属组织ID（企业章时必填）
userId Long 是 印章持有人用户 ID（用户登录后可见该章；授权短信发往该用户手机）
sealShape Integer 否 签章形状（0-圆形，1-椭圆，默认0，仅企业章有效）
isDefault Integer 否 是否设置为默认印章（0-否，1-是，默认0）
请求示例（个人章）
JSON
{
  "name": "张三印章",
  "type": 1,
  "userId": 1,
  "isDefault": 1
}
请求示例（企业章-圆形）
JSON
{
  "name": "测试公司公章",
  "type": 2,
  "orgId": 1,
  "sealShape": 0,
  "isDefault": 1
}
请求示例（企业章-椭圆）
JSON
{
  "name": "测试公司合同章",
  "type": 2,
  "orgId": 1,
  "sealShape": 1,
  "isDefault": 0
}

响应参数

参数名 类型 描述
sealId Long 印章ID
name String 印章名称
type Integer 印章类型（1-个人章，2-企业章）
userId Long 用户ID（个人章）
orgId Long 组织ID（企业章）
sealShape Integer 签章形状（0-圆形，1-椭圆）
isDefault Boolean 是否默认印章
status String 印章状态
响应示例
JSON
{
  "success": true,
  "data": {
    "sealId": 1,
    "name": "张三印章",
    "type": 1,
    "userId": 1,
    "orgId": null,
    "sealShape": 0,
    "isDefault": true,
    "status": "ACTIVE"
  }
}

6.2 上传印章图片

  • 接口路径：POST /v1/seal/upload-image
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：上传图片生成印章。支持个人章和企业章，系统使用固定尺寸（个人章 300×150px，企业章 210×210px），无需传递印章大小参数。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <accessToken>

请求参数

参数名 类型 必填 描述
userId Long 是 用户ID（印章所属用户）
imageBase64 String 是 图片 Base64 格式（可包含 data:image/xxx;base64, 前缀）。图片大小不能超过 2MB
name String 是 印章名称
type Integer 是 印章类型：1=个人章，2=企业章
orgId Long 条件 组织ID（企业章时必填）
isDefault Integer 否 是否设置为默认印章：0=否，1=是，默认 0
请求示例（个人章）
JSON
{
  "userId": 123456,
  "imageBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "name": "张三的个人章",
  "type": 1,
  "isDefault": 0
}
请求示例（企业章-设为默认）
JSON
{
  "userId": 123456,
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "name": "某某科技有限公司",
  "type": 2,
  "orgId": 789012,
  "isDefault": 1
}

响应参数

参数名 类型 描述
sealId Long 印章ID
name String 印章名称
type Integer 印章类型（1-个人章，2-企业章）
userId Long 用户ID
orgId Long 组织ID（企业章）
isDefault Boolean 是否默认印章
响应示例
JSON
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "sealId": 345678,
    "name": "某某科技有限公司",
    "type": 2,
    "userId": 123456,
    "orgId": 789012,
    "isDefault": true
  }
}
注意事项
  • 图片大小限制：图片不能超过 2MB
  • 印章类型校验：type 必须为 1（个人章）或 2（企业章）
  • 组织ID要求：企业章（type=2）时必须传递 orgId
  • 企业章权限校验：只有企业的创建者才能为企业创建印章。如果用户不是企业创建者，将返回错误：“只有企业创建者才能为企业创建印章”
  • 默认印章：同一企业下仅允许一枚默认章；设置新默认时自动取消原默认
  • 印章样式：个人章使用矩形样式（rectangle），企业章使用圆形样式（circle-enterprise）

6.3 设置默认印章

  • 接口路径：POST /seal/set-default/{sealId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path
  • 功能说明：设置默认印章，用于自动签署

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
sealId String 是 印章ID

响应参数

参数名 类型 描述
set Boolean 是否设置成功
响应示例
JSON
{
  "success": true,
  "data": {
    "set": true
  }
}

6.3 查询印章详情

  • 接口路径：GET /seal/get/{sealId}
  • 请求类型：无 JSON/表单请求体；参数见 URL Path
  • 功能说明：查询印章详情

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

路径参数

参数名 类型 必填 描述
sealId Long 是 印章ID

响应参数

参数名 类型 描述
sealId Long 印章ID
name String 印章名称
type Integer 印章类型（1-个人章，2-企业章）
userId Long 用户ID（个人章）
orgId Long 组织ID（企业章）
sealShape Integer 签章形状（0-圆形，1-椭圆）
isDefault Boolean 是否默认印章
status String 印章状态
createdAt String 创建时间
响应示例
JSON
{
  "success": true,
  "data": {
    "sealId": 1,
    "name": "个人印章",
    "type": 1,
    "userId": 1,
    "orgId": null,
    "sealShape": 0,
    "isDefault": true,
    "status": "ACTIVE",
    "createdAt": "2026-04-19T10:00:00"
  }
}

6.4 查询印章列表

  • 接口路径：GET /seal/list
  • 请求类型：无 JSON/表单请求体；参数见 URL Query
  • 功能说明：查询指定用户名下的印章；可按企业过滤

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <token>

查询参数

参数名 类型 必填 描述
userId String 是 用户 ID
orgId String 否 组织 ID，传入则仅返回该组织下印章

响应参数

参数名 类型 描述
totalSize Integer 总记录数
results Array 印章列表
results[].sealId Long 印章ID
results[].name String 印章名称
results[].type Integer 印章类型（1-个人章，2-企业章）
results[].userId Long 用户ID（个人章）
results[].orgId Long 组织ID（企业章）
results[].sealShape Integer 签章形状（0-圆形，1-椭圆）
results[].isDefault Boolean 是否默认印章
results[].status String 印章状态
results[].createdAt String 创建时间
响应示例
JSON
{
  "success": true,
  "data": {
    "totalSize": 3,
    "results": [
      {
        "sealId": 1,
        "name": "个人印章",
        "type": 1,
        "userId": 1,
        "orgId": null,
        "sealShape": 0,
        "isDefault": true,
        "status": "ACTIVE",
        "createdAt": "2026-04-19T10:00:00"
      },
      {
        "sealId": 2,
        "name": "公司公章",
        "type": 2,
        "userId": null,
        "orgId": 1,
        "sealShape": 0,
        "isDefault": true,
        "status": "ACTIVE",
        "createdAt": "2026-04-19T10:00:00"
      },
      {
        "sealId": 3,
        "name": "公司合同章",
        "type": 2,
        "userId": null,
        "orgId": 1,
        "sealShape": 1,
        "isDefault": false,
        "status": "ACTIVE",
        "createdAt": "2026-04-19T10:00:00"
      }
    ]
  }
}

6.5 印章授权

在平台内为某枚印章管理用印权限（授权、撤销、按章查询列表）。被授权人可与印章、印章持有人不属同一企业。

推荐对接（引导页）：调用 6.5.0 获取授权页链接，将返回的 h5Url/pcUrl 发给被授权人。被授权人打开页面完成手机号验证与个人实名（可自动开户）后，由企业法定代表人手机接收 SEAL_AUTH 验证码完成授权。适用于被授权人尚未开户/实名的场景。

服务端直连模式（保留）：① 先调用「发码」接口，将短信发至该印章持有人在平台绑定的手机。② 持有人将短信验证码交予您方业务系统，由业务系统调用「确认授权」。被授权人须已开户且已个人实名。

授权成功后，若已配置蚂蚁链，服务端将自动把本次授权摘要上链存证，含印章名称、持有人/授权人及被授权人姓名与手机号、业务 ID 等，无需单独再传存证材料。

下述 6.5.0～6.5.4 接口（除引导页内嵌交互外）均须在请求头携带 Authorization: Bearer <token>。完整请求 URL 为文档中的基础路径，与本节各条「接口路径」所列相对路径拼接。变更印章刻制/持有人（所有人）见本节 6.6，短信类型与 6.5.1 同为 SEAL_AUTH。

与 §3.23 开放签署 PDF 联用：对一线业务只传参与人手机及参与人/企业等资料、可不传 sealId 的对接，§3.23 在服务端用印授权与这里同数据，且仅在 与当次印模用名（见 §3.23）一致的印章上落章。无需为签署先调 6.5.4。6.5.4 等授权查询接口适用于运营、排查或事后核对，非接 §3.23 前必须步骤。

6.5.0 获取印章授权页链接（推荐）

  • 接口路径：POST /seal/authorization/page-link
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：签发 PC/H5 引导页链接。被授权人打开链接完成身份核验与实名后，由企业法定代表人手机收到的 SEAL_AUTH 验证码确认授权。印章须关联已认证企业（有 orgId），个人章不适用本接口。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <accessToken>
Content-Type String 是 application/json

请求参数

参数名 类型 必填 描述
sealId Long 是 待授权印章 ID（须为企业章，已关联企业组织）
granteeMobile String 是 被授权人手机号；链接绑定此号，打开页须验证此手机号
granteeUserId Long 否 若被授权人已开户可预填；须与 granteeMobile 为同一用户
callbackUrl String 否 授权成功后服务端 POST 通知地址
redirectUrl String 否 引导页成功后跳转地址

请求示例

JSON
POST /seal/authorization/page-link
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "sealId": 1001,
  "granteeMobile": "13800138000",
  "callbackUrl": "https://your.example.com/seal-auth/callback",
  "redirectUrl": "https://your.example.com/done"
}

响应参数（data）

字段 类型 描述
pcUrl String PC 引导页：{front}/open-seal-auth/pc?token=…
h5Url String H5 引导页：{front}/open-seal-auth/h5?token=…
token String 授权页令牌（72 小时有效）
expiresIn Integer 有效期秒数（259200）
sealId Long 印章 ID

引导页流程说明

  1. 被授权人打开 h5Url/pcUrl，使用链接绑定的手机号收短信完成身份验证（未开户则自动开户）。
  2. 若未个人实名，引导完成人脸/三要素/银行卡实名。
  3. 确认印章与企业信息后，点击向法定代表人发送验证码。
  4. 输入法人收到的验证码并确认，写入用印授权（与 6.5.2 同源 SealUserAuth，可上蚂蚁链）。
  5. 若配置了 callbackUrl，服务端 POST：{ token, status, sealId, userId, authId, … }。

注意：引导页意愿确认短信发往企业法定代表人手机；6.5.1/6.5.2 直连模式仍发往印章持有人手机。二者验证码接收方不同，请勿混用。

6.5.1 发送授权短信（服务端直连）

  • 接口路径：POST /seal/authorization/send-sms-code
  • 请求类型：无请求体；参数通过 URL Query 传递
  • 功能说明：向该印章持有人在平台绑定的手机号发送本次授权用短信验证码，用于稍后在「确认授权」中校验（与签署意愿类短信区分）。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <accessToken>

请求参数

参数名 位置 类型 必填 描述
sealId Query Long 是 目标印章 ID，须为平台内未删除的印章，且能解析出持有人与手机号

响应参数

顶层为统一结构：code、success、data、msg。本接口成功时仅通过 msg 返回提示，data 一般为 null。

参数名 类型 说明
msg String 成功时如「验证码已发送」；失败时见错误信息
data null 本接口不返回业务数据时为空
请求示例
HTTP
POST /seal/authorization/send-sms-code?sealId=1001
Authorization: Bearer <accessToken>
响应示例
JSON
{
  "code": 200,
  "success": true,
  "msg": "验证码已发送",
  "data": null
}

6.5.2 确认授权

  • 接口路径：POST /seal/authorization/grant
  • 请求类型：JSON（Content-Type: application/json）
  • 功能说明：用持有人手机收到的验证码完成授权。通过后写入或恢复一条 sealId + 被授权 userId 的授权关系；并尝试上蚂蚁链存证。验证码须与 6.5.1 为同一批、发至同一手机号。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <accessToken>
Content-Type String 是 application/json

请求体参数

参数名 类型 必填 描述
sealId Long 是 印章 ID，须为平台内未删除的印章
userId Long 是 被授权方在平台上的用户 ID，可与印章/持有人在不同企业或不同归属侧
smsCode String 是 6.5.1 发至印章持有人手机上的短信验证码

响应参数

顶层为 code、success、msg、data；成功时 data 为下表对象，msg 多为 null。

data 对象字段
参数名 类型 说明
authId Long 本笔授权在平台侧的业务标识，撤销接口 6.5.3 使用
sealId Long 印章 ID
userId Long 被授权用户 ID
sealAuthEvidenceId Long 本笔授权对应的蚂蚁链存证业务标识；未配链或上链失败时可为 null
transactionHash String 蚂蚁链交易哈希；未上链时可为 null
请求体示例
JSON
{
  "sealId": 1001,
  "userId": 2002,
  "smsCode": "123456"
}
响应示例
JSON
{
  "code": 200,
  "success": true,
  "msg": null,
  "data": {
    "authId": 5001,
    "sealId": 1001,
    "userId": 2002,
    "sealAuthEvidenceId": 90001,
    "transactionHash": "0xabc123..."
  }
}

6.5.3 撤销授权

  • 接口路径：POST /seal/authorization/revoke/{authId}
  • 请求类型：无请求体；authId 在 Path 中
  • 功能说明：将指定授权记录置为已撤销（软删），被授权人不再具备该章用印权限。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <accessToken>

请求参数

参数名 位置 类型 必填 描述
authId Path Long 是 6.5.2 返回的、平台内未撤销的 authId

响应参数

本接口与 6.5.1 相同，成功时以 msg 返回「撤销成功」等提示，data 一般为 null。

参数名 类型 说明
msg String 成功时如「撤销成功」
data null 无业务数据时为空
请求示例
HTTP
POST /seal/authorization/revoke/5001
Authorization: Bearer <accessToken>
响应示例
JSON
{
  "code": 200,
  "success": true,
  "msg": "撤销成功",
  "data": null
}

6.5.4 查询某印章的授权列表

  • 接口路径：GET /seal/authorization/list
  • 请求类型：无请求体；sealId 在 URL Query
  • 功能说明：查询指定印章在当前的、未撤销的授权关系列表（每条结构同 6.5.2 的 data 对象，含可返回的存证与交易哈希）。用于运营/对账、核对某章已授权人；不是调 §3.23 的前置必调接口——仅传参与人手机时 §3.23 在服务端会自行按授权与组织选章，与上表数据一致。须已知 sealId 才能查本接口；日常签署对接可不依赖本接口。

请求头

请求头 类型 必填 描述
Authorization String 是 Bearer <accessToken>

请求参数

参数名 位置 类型 必填 描述
sealId Query Long 是 要查询的印章 ID，须为平台内未删除的印章

响应参数

参数名 类型 说明
data Array 无授权时可能为空数组 []。元素为对象，字段同 6.5.2「响应参数（data 对象）」表
请求示例
HTTP
GET /seal/authorization/list?sealId=1001
Authorization: Bearer <accessToken>
响应示例
JSON
{
  "code": 200,
  "success": true,
  "msg": null,
  "data": [
    {
      "authId": 5001,
      "sealId": 1001,
      "userId": 2002,
      "sealAuthEvidenceId": 90001,
      "transactionHash": "0xabc123..."
    }
  ]
}

6.6 变更印章所有人

将印章的刻制/持有人从当前平台用户变更为另一用户。仍须通过原持有人手机接收的 SEAL_AUTH 短信完成意愿校验（与 6.5.1 同一发码通道）。

企业章：新持有人须已加入该企业；可先调用加入企业接口。个人章无此限制。

若已配置蚂蚁链，变更成功后会将摘要上链并生成存证；响应中可返回 sealOwnerTransferEvidenceId、ownerTransferTransactionHash；未配链或上链失败时二者可为空，不影响持有人已变更。

  • 接口路径：POST /seal/transfer-owner
  • 请求类型：JSON
  • 功能说明：见上。须先 POST /seal/authorization/send-sms-code?sealId=… 向原持有人发码，再提交本接口中的 smsCode。

请求体（JSON）

参数名 类型 必填 描述
sealId Long 是 印章 ID
newOwnerUserId Long 是 变更后的所有人用户 ID
smsCode String 是 发至原持有人手机的 SEAL_AUTH 验证码

响应 data 主要字段

参数名 类型 说明
sealId / name / orgId / userId / type / sealShape / isDefault — 与 6.3 印章详情一致；userId 为变更后的新持有人
sealOwnerTransferEvidenceId Long 本笔变更对应的蚂蚁链存证业务标识；未上链时为 null
ownerTransferTransactionHash String 蚂蚁链交易哈希；未上链时为 null
请求示例
JSON
{
  "sealId": 1001,
  "newOwnerUserId": 2002,
  "smsCode": "123456"
}
响应示例
JSON
{
  "success": true,
  "data": {
    "sealId": 1001,
    "name": "某某公司",
    "orgId": 500,
    "userId": 2002,
    "isDefault": true,
    "sealOwnerTransferEvidenceId": 90002,
    "ownerTransferTransactionHash": "0xdef456..."
  }
}

7. 错误码说明

错误码 描述
4001 参数校验失败
4002 业务操作失败
4003 资源不存在
4010 未授权
5000 系统内部错误

8. 调用示例

8.1 获取令牌

BASH
curl -X POST \
  https://your.domain/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"appId": "app_test_1234567890", "apiKey": "sk_test_1234567890"}'

8.2 创建合同草稿

须先通过 §3.1 上传 PDF 取得 fileId。

BASH
curl -X POST \
  https://your.domain/api/v1/contract/create \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"title": "服务协议", "fileId": 1, "userId": "123456", "signers": [{"type": "PERSON", "order": 1, "userId": "123456"}]}'

8.3 用户加入企业

将平台已有用户加入指定企业/个体户（与 §4.5 一致）。须先 8.1 取令牌，请求中携带平台内有效 userId 与 orgId。

BASH
curl -X POST \
  https://your.domain/api/v1/org/join \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"userId": 100, "orgId": 2001}'

9. 常见问题

9.1 令牌过期怎么办？

当令牌过期时，需要重新调用 /api/v1/auth/token 接口获取新的令牌。建议在令牌过期前提前刷新。

9.2 如何处理签名失败？

签名失败通常是由于签名人信息不匹配或印章不存在导致的。请检查签名人信息和印章是否正确。

9.3 接口调用频率限制

为保证系统稳定性，每个应用（按 API Key / 开放凭证）的接口调用频率限制为：

  • 认证接口：100次/分钟
  • 其他接口：500次/分钟

10. 版本说明

版本 发布日期 变更说明
v1.0 2026-04-19 初始版本
v1.0.1 2026-04-23 合同开放接口新增 POST /contract/send-sms-code（发送签署短信验证码）
合同开放接口新增 POST /contract/face-recognition（活体验证，请求体无需 userId）
合同开放接口新增 POST /contract/sign-pdf（关键词落章 + 意愿校验 + 返回签署 PDF Base64）
v1.0.2 2026-04-24 合同开放接口 GET /contract/face-recognition/success 响应升级：返回 passed/charged/code/codeDesc，并按 code（R101、R102、R214、R215、R216、R218、R219、R221、R233、R234、R235）判断是否计费
v1.0.3 2026-04-25 POST /contract/sign-pdf：企业已认证且可唯一解析目标企业组织时，participantUserId 改为可选，默认按 participantMobile 在该组织下匹配经办用户；verifyType 含活体时，若已存在与活体姓名、身份证一致的个人组织档案且预留手机号已填，须与 participantMobile 一致。开放接口 印章授权：POST /seal/authorization/send-sms-code、POST /seal/authorization/grant（成功后摘要上蚂蚁链）、POST /seal/authorization/revoke/{authId}、GET /seal/authorization/list；授权短信发往印章持有人手机
v1.0.4 2026-04-25 POST /contract/sign-pdf 文档：补充印模用名与参与人关联（enterpriseName/participantName 来源、与账号手机/姓名及同名企业章/授权的关系）、只选用与当次印模用名完全一致的 Seal 名称的选章规则，以及 sealId、participantName 等参数说明
v1.0.5 2026-04-26 新增 POST /org/lookup-identity、POST /person/lookup-identity。其中 POST /org/lookup-identity 先经与 POST /auth/enterprise/legal-person 同源创瑞企业三要素核验、再于平台内查组织与章，在 COMPANY / SELF_EMPLOYED 中按企名+统一社会信用代码匹配。
新增 POST /org/join、POST /seal/transfer-owner。企业章变更所有人时，新所有人须已在目标 orgId 下为 ACTIVE 成员，成功后可上链 sealOwnerTransferEvidenceId 等。
POST /contract/sign-pdf 补充：首次在平台建企时 legalPersonName、legalPersonIdCard 须与 faceToken 活体会话中实名、证件号一致等说明
v1.0.6 2026-04-27 个人开放接口补充文档：POST /person/face-recognition（发起 H5 活体，userId 为可选参数）、GET /person/face-recognition/success（查询活体结果，与合同侧 GET /contract/face-recognition/success 响应结构一致）。原 §5.4/§5.5 独立认证页与按实名查询顺延为 §5.6/§5.7。
v1.0.7 2026-05-07 活体 Token 管理增强：
• 新增 GET /contract/face-recognition/check-token（查询活体 token 是否过期，返回剩余有效期）
• 开放接口活体 token 有效期延长至 12 小时（其他场景默认 30 分钟）
• POST /contract/sign-pdf 新增 destroyFaceTokenAfterUse 参数（默认 false，签署后立即销毁 token，提升安全性）

企业变更法人功能：
• 新增 POST /contract/change-legal-person（通过企业名称和信用代码定位企业，变更法人）
• 支持自动创建新法人用户和企业归属迁移
• 企业下所有印章跟随企业同步迁移到新法人账号
• 入参调整：使用 enterpriseName + unifiedSocialCreditCode 替代 orgId，降低接入门槛
v1.0.8 2026-05-07 运营商三要素验证功能：
• 新增 POST /person/three-factor-verification（验证姓名、身份证号、手机号三要素）
• 纯验证接口：仅返回验证结果，不创建用户、组织或印章
• 支持详细的计费判断：status=1/2 计费，错误码不计费
• 完整的状态码体系：1（一致）、2（不一致）、3（参数错误）、10001-10005（业务错误）、20000-20005（系统错误）
v1.0.9 2026-05-07 开放签署 PDF 增强：
• POST /contract/sign-pdf 新增 sealWidth、sealHeight 参数（单位：pt）
• 默认值：126pt（约 44.4mm），保持原有尺寸不变
• 最小值：28.4pt（约 10mm），防止印章过小
• 可选参数，不传时使用默认值，向后兼容

上传印章图片功能：
• 新增 POST /v1/seal/upload-image（上传图片生成印章）
• 支持个人章和企业章，使用固定尺寸（个人章 300×150px，企业章 210×210px）
• 企业章权限校验：只有企业创建者才能为企业创建印章
• 图片大小限制：不超过 2MB
• 支持设置默认印章，自动处理互斥逻辑
v1.0.10 2026-05-23 个人账号手机号修改功能：
• 新增 POST /person/change-mobile-by-sms（通过验证码修改手机号，无需 userId）
• 新增 POST /person/change-mobile-by-face（通过活体认证修改手机号，多用户匹配时需 userId）
• 支持两种验证方式：原手机号验证码、活体人脸识别
• 短信验证码场景码：CHANGE_MOBILE_OLD（原手机号）、CHANGE_MOBILE_NEW（新手机号）
• 活体认证需先调用 POST /person/face-recognition 获取 faceToken（userId 可选）

域名变更：
• 基础路径从 https://pc.suxin365.com/api/v1 变更为 https://pc.suxin365.com/api/v1
v1.0.11 2026-05-27 按实名查询用户与印章增强：
• POST /person/lookup-identity 响应 seals[] 补充印章所属组织（sealOrgId、sealOrgType、sealOrgName、sealOrgIdNumber）及制章人信息（sealCreatedByUserId、sealCreatedByUserMobile、sealCreatedByUserIdNumber）
• 新增 boundEnterprises：返回用户已加入的企业组织列表（ACTIVE，含 COMPANY / SELF_EMPLOYED）
v1.0.12 2026-05-27 加入企业审核（控制台）：
• 控制台「加入企业」提交后成员关系状态为 PENDING，须企业管理员审核通过后变为 ACTIVE
• 开放接口 POST /org/join 仍为直接加入（ACTIVE），与控制台行为区分
v1.0.13 2026-05-30 合同模板开放接口：
• 新增 GET /contract/templates（查询租户启用的模板列表）
• 新增 GET /contract/templates/{templateId}（查询模板详情，含字段定义）
• 新增 POST /contract/create-from-template（按模板填充字段、生成 PDF 并发起合同，状态为 PENDING）
• 新增 GET /contract/tenant-list（租户合同列表，orgId 可选）
• 原 §3.2–§3.12 合同管理小节顺延为 §3.5–§3.16
v1.0.14 2026-05-30 PDF 上传创建合同流程重构：
• POST /contract/upload-template、POST /contract/create 租户 ID 统一取自 API Key，并校验 userId / 文件 / 签署方归属
• 创建合同：签署方类型规范为 PERSON / ENTERPRISE（兼容传 COMPANY）；修复签署顺序关联；补全 PDF 预览图转换
• 移除未实现的 callbackUrl、willingnessType、redirectUrl 请求参数
• 文档 §3 补充 PDF 与模板两条发起路径说明
v1.0.15 2026-05-30 个人账号查询增强：
• 新增 POST /person/lookup-by-mobile（按手机号查询用户姓名与身份证号）
• 个人账号 §5.3–§5.10 顺延为 §5.4–§5.11
v1.0.16 2026-06-25 模板默认签署/盖章位置：
• GET /contract/templates、GET /contract/templates/{templateId} 响应新增 sealPositions（模板默认签署/盖章位置 JSON）
• POST /contract/create-from-template 发起时自动应用模板默认位置，按 signerIndex 映射到 signers 的签署顺序 order 生成签署控件，无需再调用设计页
v1.0.17 2026-06-25 获取令牌返回默认组织/用户：
• POST /auth/token 响应新增 userId（API Key 对应租户管理员）与 orgId（API Key 对应默认组织），可直接用于发起合同等接口的 userId / orgId
v1.0.18 2026-06-27 签署完成回调与跳转：
• 创建/发起合同、获取签署链接支持 callbackUrl、redirectUrl
• callbackUrl 接收签署进度 POST 通知；redirectUrl 用于签署完成后页面跳转
• 新增 §3.8.2 微信小程序 web-view 对接说明
• signers[] 支持按姓名、手机号指定签署方
v1.0.19 2026-06-27 签署方与链接：
• signers[] 支持按姓名、手机号指定签署方
• 设计页、签署链接、预览链接 token 默认有效期延长至 30 天
v1.0.20 2026-07-04 批量模板发起合同：
• 新增 POST /contract/batch-create-from-template（按 items 批量发起，结构与 §3.4 单项相同）
• 单次请求最多 50 份，超出整单拒绝；各份独立处理，部分失败不影响其余成功项
• 原 §3.5–§3.16 合同管理小节顺延为 §3.6–§3.17
v1.0.21 2026-07-04 企业列表与模板按企业筛选：
• 新增 GET /org/list（按 API Key 商户返回可访问企业：本商户创建 + 印章授权）
• GET /contract/templates 新增必填参数 orgId，按企业筛选模板；模板新增 orgEntityId 字段
• 企业账号 §4.1–§4.5 顺延为 §4.2–§4.6
v1.0.22 2026-07-06 开放接口 ID 参数类型调整：
• 模板列表 orgId、模板详情 templateId、签署链接/预览地址 contractId/userId/orgId、组织/租户合同列表 orgId、发起签署 contractId、企业列表响应 orgId 等路径/Query 参数改为 String（避免大整数 JSON 精度丢失）
v1.0.23 2026-07-07 获取令牌返回可访问企业列表：
• POST /auth/token 响应将原单个 orgId 调整为 orgs 数组，元素含 orgId、orgName（当前接入应用可用的企业）；userId 改为 String 类型
v1.0.24 2026-07-10 模板列表 orgId 可选并返回企业名称：
• GET /contract/templates 的 orgId 改为非必填；未传时返回该 API Key 租户下全部启用模板
• 列表/详情响应新增 orgEntityName（由 orgEntityId 解析的企业名称）
v1.0.25 2026-07-29 合同状态 / 签订记录 / 撤回：
• 新增 GET /contract/status/{contractId}（实时状态与参与方签署进度，过期展示 EXPIRED）
• 新增 GET /contract/signing-records/{contractId}（签署人签订审计记录）
• 新增 POST /contract/revoke/{contractId}（待签署合同撤回为 REVOKED）
• 原 §3.14–§3.18 顺延为 §3.17–§3.21
v1.0.26 2026-07-30 删除合同：
• 新增 DELETE /contract/delete/{contractId}（仅 DRAFT / REVOKED 可删）
• 原 §3.17–§3.21 顺延为 §3.18–§3.22
v1.0.28 2026-08-06 下载合同文件：
• 新增 GET /contract/download/{contractId}?type=，按类型下载合同 PDF（CONTRACT）、证据报告（EVIDENCE）、归档 OFD（ARCHIVE）
• 成功返回文件二进制流；原 §3.18–§3.22 顺延为 §3.19–§3.23

接口列表

接口路径 方法 请求类型 功能说明
POST /auth/token POST JSON 获取访问令牌
POST /contract/upload-template POST JSON 上传合同 PDF（PDF 发起流程第一步）
POST /contract/templates POST JSON 创建合同模板（Word .docx）
GET /contract/templates GET Query（orgId 可选） 查询启用的合同模板列表
GET /contract/templates/{templateId} GET 无 Body（Path） 查询模板详情
POST /contract/create-from-template POST JSON 根据模板生成 PDF 并发起合同（待签署）
POST /contract/batch-create-from-template POST JSON 批量根据模板发起合同（单次最多 50 份，部分失败可返回明细）
GET /contract/design-page/{contractId} GET 无 Body（Path/Query） 获取设计合同页面
POST /contract/create POST JSON 创建合同草稿（DRAFT，PDF 流程）
POST /contract/initiate-sign/{contractId} POST JSON（Body 可空） 发起签署
GET /contract/sign-url/{contractId} GET 无 Body（Path/Query） 获取签署链接
GET /contract/list GET 无 Body（Query） 按组织 ID 查询合同列表
GET /contract/tenant-list GET 无 Body（Query） 查询用户作为发起人创建的合同列表
GET /contract/status/{contractId} GET 无 Body（Path） 实时合同状态（含参与方签署进度）
GET /contract/signing-records/{contractId} GET 无 Body（Path） 签署人签订记录
POST /contract/revoke/{contractId} POST JSON（Body 可空） 合同撤回（仅 PENDING → REVOKED）
DELETE /contract/delete/{contractId} DELETE 无 Body（Path/Query） 删除合同（仅 DRAFT / REVOKED）
GET /contract/download/{contractId} GET 无 Body（Path/Query） 下载合同文件 / 证据报告 / 归档文件（type 区分）
GET /contract/preview-url/{contractId} GET 无 Body（Path/Query） 获取合同预览地址
POST /contract/send-sms-code POST 表单或 Query（mobile） 发送短信验证码（签署意愿）
POST /contract/face-recognition POST JSON 获取活体验证（人脸识别）二维码
GET /contract/face-recognition/success GET 无 Body（Query：token） 根据 token 查询活体是否认证成功
POST /contract/sign-pdf POST JSON 开放签署 PDF（关键词落章、意愿校验）
GET /org/list GET 无 Body（Query：必填 userId） 查询用户已加入的企业列表
POST /org/add POST JSON 添加企业账号
GET /org/get/{orgId} GET 无 Body（Path） 查询企业账号
POST /org/lookup-identity POST JSON 先创瑞企业三要素核验，再查企业与印章（含制章人用户 ID、手机号）
POST /org/join POST JSON 用户加入企业/个体户
POST /person/add POST JSON 添加个人账号
GET /person/get/{userId} GET 无 Body（Path） 查询个人账号
POST /person/lookup-by-mobile POST JSON 按手机号查询用户姓名与身份证号
POST /person/lookup-identity POST JSON 按姓名、身份证号查询用户手机号、可用印章（含制章人/组织信息）及绑定企业
DELETE /person/delete/{userId} DELETE 无 Body（Path） 账号注销
POST /person/face-recognition POST JSON 获取个人活体验证（人脸识别）二维码或认证页 URL
GET /person/face-recognition/success GET 无 Body（Query：token） 根据 token 查询个人侧活体是否认证成功
POST /person/certify-page POST JSON 获取独立认证页面
POST /seal/add POST JSON 添加印章
POST /seal/set-default/{sealId} POST 无 Body（Path） 设置默认印章
GET /seal/get/{sealId} GET 无 Body（Path） 查询印章详情
GET /seal/list GET 无 Body（Query：必填 userId，可选 orgId） 查询用户名下印章列表
POST /seal/authorization/page-link POST JSON 获取印章授权引导页链接（推荐）
POST /seal/authorization/send-sms-code POST 无 Body（Query：sealId） 发送印章授权短信（持有人手机，服务端直连）
POST /seal/authorization/grant POST JSON 确认印章授权
POST /seal/authorization/revoke/{authId} POST 无 Body（Path） 撤销印章授权
GET /seal/authorization/list GET 无 Body（Query：sealId） 某印章的授权用户列表
POST /seal/transfer-owner POST JSON 变更印章所有人（刻制/持有人），可上链存证