苏心签开放接口文档

1. 概述

1.1 文档说明

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

1.2 接口基础信息

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

1.3 响应结构

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

{
  "success": true,
  "data": { /* 业务数据 */ }
}

{
  "success": false,
  "code": "5001",
  "msg": "错误信息"
}

1.4 分页参数

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

• page：页码，默认值 1
• pageSize：每页数量，默认值 10

{
  "success": true,
  "data": {
    "totalSize": 100,
    "results": [ /* 数据列表 */ ]
  }
}

2. 认证接口

2.1 获取访问令牌

• 接口路径：POST /auth/token
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：使用 API Key 获取访问令牌，用于后续接口调用

{
  "appId": "app_test_1234567890",
  "apiKey": "sk_test_1234567890"
}

响应参数

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expire": 3600
  }
}

2.2 使用令牌

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

3. 合同管理

合同发起支持两种路径：

• PDF 上传流程（需自定义签署控件位置）：§3.1 上传 PDF → §3.5 创建草稿 → §3.6 设计页 → §3.7 发起签署 → §3.8 签署链接
• 模板流程（平台预置 Word 模板）：§3.2 模板列表 → §3.4 模板发起合同（自动进入待签署）→ §3.8 签署链接

3.1 上传合同 PDF

• 接口路径：POST /contract/upload-template
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：上传合同 PDF 文件，返回 fileId 供 §3.5 创建草稿使用；服务端会异步将 PDF 转为预览图片
• 租户校验：租户 ID 取自 API Key 认证上下文；userId 须属于该租户

请求头

请求参数

{
  "fileName": "template.pdf",
  "fileContent": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKNCAwIG9iago8PC9MZW5ndGggNTM1L0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nGNgYNgh4A/EYGVhZABkYAQwgWgDcIgDcQAZgYGPgBYH5AYGPoB2EAAKcAg==",
  "userId": "123456"
}

响应参数

{
  "success": true,
  "data": {
    "fileId": 1,
    "fileName": "contract.pdf",
    "fileType": "application/pdf",
    "fileUrl": "https://example.com/...(服务端返回的模板文件下载完整 URL)"
  }
}

3.2 查询模板列表

• 接口路径：GET /contract/templates
• 请求类型：无 JSON/表单请求体
• 功能说明：查询当前租户下已启用（ACTIVE）的合同模板列表，用于展示可选模板及字段信息

请求头

响应参数

{
  "success": true,
  "data": [
    {
      "templateId": 1,
      "name": "劳动合同",
      "description": "标准劳动合同模板",
      "category": "人事",
      "status": "ACTIVE",
      "fileObjectId": 100,
      "fileName": "labor.docx",
      "fields": "[{\"key\":\"甲方名称\",\"label\":\"甲方名称\",\"required\":true}]",
      "pageCount": 3,
      "approvalFlowId": null,
      "approvalFlowName": null,
      "createdAt": "2026-05-01 10:00:00"
    }
  ]
}

3.3 查询模板详情

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

请求头

路径参数

响应参数

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

{
  "success": true,
  "data": {
    "templateId": 1,
    "name": "劳动合同",
    "description": "标准劳动合同模板",
    "category": "人事",
    "status": "ACTIVE",
    "fileObjectId": 100,
    "fileName": "labor.docx",
    "fields": "[{\"key\":\"甲方名称\",\"label\":\"甲方名称\",\"required\":true}]",
    "pageCount": 3,
    "createdAt": "2026-05-01 10:00:00"
  }
}

3.4 根据模板发起合同

• 接口路径：POST /contract/create-from-template
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：根据模板填充字段、生成 PDF，创建合同并自动发起签署（等价于创建合同 + 发起签署），合同状态为 PENDING（待签署）

典型流程：先调用 §3.2 / §3.3 获取模板及字段定义 → 填写 fieldValues 与签署方 → 调用本接口 → 使用 §3.8 获取签署链接引导用户签署。

请求头

请求参数

{
  "templateId": 1,
  "title": "张三劳动合同",
  "fieldValues": {
    "甲方名称": "某某科技有限公司",
    "乙方姓名": "张三",
    "入职日期": "2026-06-01"
  },
  "userId": "123456",
  "orgId": 1,
  "signOrderMode": 1,
  "signers": [
    {
      "type": "ENTERPRISE",
      "order": 1,
      "orgId": "1"
    },
    {
      "type": "PERSON",
      "order": 2,
      "userId": "789012"
    }
  ],
  "expireTime": 1793568000000
}

响应参数

{
  "success": true,
  "data": {
    "contractId": 123456,
    "status": "PENDING"
  }
}

3.5 创建合同草稿

• 接口路径：POST /contract/create
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：基于 §3.1 返回的 fileId 创建草稿合同（状态 DRAFT），保存签署方信息；后续须通过 §3.6 设计签署控件，再调用 §3.7 发起签署
• 租户校验：租户 ID 取自 API Key；userId、fileId、签署方用户/组织均须属于该租户

若使用平台 Word 模板且无需设计页，请直接使用 §3.4 根据模板发起合同，一步进入 PENDING 状态。

请求头

请求参数

signers[] 元素

{
  "title": "服务协议",
  "fileId": 1,
  "signOrderMode": 1,
  "signers": [
    {
      "type": "PERSON",
      "order": 1,
      "userId": "123456"
    },
    {
      "type": "ENTERPRISE",
      "order": 2,
      "orgId": "789012"
    }
  ],
  "expireTime": 1793568000000,
  "orgId": 1,
  "userId": "123456"
}

响应参数

{
  "success": true,
  "data": {
    "contractId": 123456,
    "title": "服务协议",
    "status": "DRAFT"
  }
}

3.6 获取设计合同页面

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

请求头

路径参数

查询参数

响应参数

{
  "success": true,
  "data": {
    "contractId": 1,
    "pcUrl": "https://example.com/open-contract/pc/design?token=abc123xyz",
    "h5Url": "https://example.com/open-contract/h5/design?token=abc123xyz"
  }
}

注意：URL中的token有效期为1小时，使用token可以调用/contract/get-contract-id接口获取真实的contractId和userId。

3.7 发起签署

• 接口路径：POST /contract/initiate-sign/{contractId}
• 请求类型：JSON（Content-Type: application/json）；Body 可为空或省略，按业务需要传参与默认一致
• 功能说明：发起合同签署，会创建原文件的副本作为签署文件，保留原文件

请求头

路径参数

响应参数

{
  "success": true,
  "data": {
    "contractId": 1,
    "status": "PENDING",
    "message": "发起签署成功"
  }
}

3.8 获取签署链接

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

请求头

路径参数

查询参数

响应参数

{
  "success": true,
  "data": {
    "contractId": 1,
    "pcUrl": "https://example.com/open-contract/pc/sign?token=abc123xyz",
    "h5Url": "https://example.com/open-contract/h5/sign?token=abc123xyz"
  }
}

注意：URL中的token有效期为1小时，使用token可以调用/contract/get-contract-id接口获取真实的contractId和userId。

3.9 获取合同预览地址

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

请求头

路径参数

查询参数

响应参数

{
  "success": true,
  "data": {
    "contractId": 1,
    "pcUrl": "https://example.com/open-contract/pc/detail?token=abc123xyz",
    "h5Url": "https://example.com/open-contract/h5/detail?token=abc123xyz"
  }
}

注意：URL中的token有效期为1小时

3.10 查询组织合同列表

• 接口路径：GET /contract/list
• 请求类型：无 JSON/表单请求体；参数见 URL Query
• 功能说明：按组织 ID 分页查询合同列表（orgId 必填）

请求头

查询参数

响应参数

{
  "success": true,
  "data": {
    "totalSize": 100,
    "results": [
      {
        "contractId": 1,
        "title": "服务协议",
        "status": "DRAFT",
        "createdAt": "2026-04-19 10:00:00"
      }
    ]
  }
}

3.11 查询租户合同列表

• 接口路径：GET /contract/tenant-list
• 请求类型：无 JSON/表单请求体；参数见 URL Query
• 功能说明：分页查询当前租户下合同列表；orgId 可选，不传则返回租户下全部组织的合同

请求头

查询参数

响应参数

{
  "success": true,
  "data": {
    "totalSize": 100,
    "page": 1,
    "pageSize": 10,
    "results": [
      {
        "contractId": 1,
        "title": "服务协议",
        "status": "PENDING",
        "createdAt": "2026-04-19 10:00:00"
      }
    ]
  }
}

3.12 发送短信验证码

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

请求头

查询参数

响应参数

{
  "success": true,
  "data": "OK"
}

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

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

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

请求头

请求体（JSON）

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

响应参数（data 对象）

{
  "success": true,
  "data": {
    "qrCodeUrl": "https://...",
    "token": "xxxxxxxx"
  }
}

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

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

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

请求头

查询参数

响应参数

{
  "success": true,
  "data": {
    "passed": true,
    "charged": true,
    "code": "R102",
    "codeDesc": "认证成功"
  }
}

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

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

请求头

查询参数

响应参数

{
  "success": true,
  "message": "token有效",
  "data": {
    "valid": true,
    "remainingSeconds": 43185,
    "message": "活体token有效，剩余43185秒"
  }
}

{
  "success": true,
  "message": "token已过期或不存在",
  "data": {
    "valid": false,
    "remainingSeconds": -2,
    "message": "活体token已过期或不存在"
  }
}

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

3.16 开放签署 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，再向本接口传入。
• 参与人为新个人、或三要素在平台创建新企业时，须按下文「企业新建」对活体、法人三要素的约束准备参数。

印模用名

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

仅会选用平台印章「名称」与当次印模用名逐字相同的章（详见「选章与 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 一致，否则拒签。

请求头

请求体（JSON）主要字段

选章与用印授权

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

响应参数（data）

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

4. 企业账号管理

含企业创建、单条查询、按三要素查企业与制章人信息，以及 4.4 用户加入企业（POST /org/join，将已有平台用户拉入已存在的企业/个体户；可用于变更企业章所有人前先完成入企，见 6.6）。

4.1 添加企业账号

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

请求头

请求参数

{
  "userId": 1,
  "name": "测试公司",
  "unifiedCode": "91110000MA12345678",
  "legalName": "张三",
  "legalIdCard": "110101199001011234"
}

响应参数

{
  "success": true,
  "data": {
    "orgId": 1,
    "name": "测试公司",
    "unifiedCode": "91110000MA12345678",
    "certifyStatus": "UNVERIFIED",
    "legalName": "张三"
  }
}

4.2 查询企业账号

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

请求头

路径参数

响应参数

{
  "success": true,
  "data": {
    "orgId": 1,
    "name": "测试公司",
    "unifiedCode": "91110000MA12345678",
    "certifyStatus": "UNVERIFIED",
    "legalName": "张三"
  }
}

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

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

请求体（JSON）

响应 data 主要字段

{
  "name": "某科技公司",
  "unifiedCode": "91110000MA12345678",
  "legalName": "张三"
}

{
  "success": true,
  "data": {
    "orgId": 1001,
    "name": "某科技公司",
    "unifiedCode": "91110000MA12345678",
    "certifyStatus": "VERIFIED",
    "legalName": "张三",
    "seals": [
      {
        "sealId": 1,
        "name": "某科技公司",
        "isDefault": true,
        "sealCreatedByUserId": 2,
        "sealCreatedByUserMobile": "13800138000"
      }
    ]
  }
}

4.4 用户加入企业

• 接口路径：POST /org/join
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：将指定平台用户加入指定企业/个体户组织。组织类型须为 COMPANY 或 SELF_EMPLOYED；开放接口直接加入，关系状态为 ACTIVE（控制台「加入企业」需企业审核，见控制台说明）。若用户已在该组织中则报错。常用于变更企业章持有人前先将新所有人加入目标企业（见 6.6）。

请求头

请求体（JSON）

响应

成功时 data 为入企/成员关系对象（含 id、orgEntityId、userId、status（开放接口为 ACTIVE）、joinTime 及可能带 orgName 等扩展字段）。

{
  "userId": 100,
  "orgId": 2001
}

{
  "success": true,
  "data": {
    "id": 3001,
    "orgEntityId": 2001,
    "userId": 100,
    "status": "ACTIVE",
    "joinTime": "2026-04-26T10:00:00"
  }
}

4.5 企业变更法人

• 接口路径：POST /contract/change-legal-person
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：通过企业名称和统一社会信用代码定位企业，将企业的法人变更为新指定的用户。若新法人不存在，则自动创建新租户和用户。注意：变更后企业将归属到新法人的账号下，企业下所有印章也会同步迁移。

请求头

请求体（JSON）

{
  "enterpriseName": "测试有限公司",
  "unifiedSocialCreditCode": "91110000MA12345678",
  "newLegalName": "李四",
  "newLegalIdCard": "320***********5678",
  "faceToken": "xyz789abc",
  "contactPhone": "13800138000"
}

响应参数

{
  "success": true,
  "message": "法人变更成功",
  "data": {
    "orgId": 123456,
    "newLegalUserId": 987654321,
    "sealCount": 2
  }
}

业务规则

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

5. 个人账号管理

5.1 添加个人账号

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

请求头

请求参数

{
  "name": "张三",
  "mobile": "13800138000"
}

响应参数

{
  "success": true,
  "data": {
    "userId": 1,
    "name": "张三",
    "mobile": "13800138000",
    "realNameStatus": "UNVERIFIED"
  }
}

5.2 查询个人账号

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

请求头

路径参数

响应参数

{
  "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 由姓名+身份证查用户与印章。

请求头

请求参数

响应参数

{
  "mobile": "13800138000"
}

{
  "success": true,
  "data": {
    "userId": 123456,
    "mobile": "13800138000",
    "realName": "张三",
    "idNumber": "110101199001011234"
  }
}

5.4 账号注销

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

请求头

路径参数

响应参数

{
  "success": true,
  "data": {
    "deleted": true
  }
}

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

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

请求头

请求体（JSON）

POST /person/face-recognition
Content-Type: application/json

{
  "realName": "张三",
  "idCard": "320***********1234"
}

POST /person/face-recognition
Content-Type: application/json

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

响应参数（data 对象）

与 §3.13 相同：qrCodeUrl、token。

{
  "success": true,
  "data": {
    "qrCodeUrl": "https://...",
    "token": "xxxxxxxx"
  }
}

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

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

请求头

查询参数

响应参数

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

{
  "success": true,
  "data": {
    "passed": true,
    "charged": true,
    "code": "R102",
    "codeDesc": "认证成功"
  }
}

5.7 运营商三要素验证

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

请求头

请求体（JSON）

{
  "realName": "张三",
  "idCard": "320***********1234",
  "phone": "13800138000"
}

响应参数

状态码说明

{
  "success": true,
  "message": "三要素验证通过",
  "data": {
    "verified": true,
    "charged": true,
    "code": "1",
    "message": "手机三要素一致"
  }
}

{
  "success": true,
  "message": "三要素验证失败",
  "data": {
    "verified": false,
    "charged": true,
    "code": "2",
    "message": "手机三要素不一致"
  }
}

{
  "success": true,
  "message": "三要素验证失败",
  "data": {
    "verified": false,
    "charged": false,
    "code": "10004",
    "message": "余额不足"
  }
}

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

5.8 获取独立认证页面

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

请求头

请求参数

响应参数

{
  "success": true,
  "data": {
    "h5Url": "https://example.com/certify/h5/123?token=abcdef123456¬ifyUrl=xxx&redirectUrl=yyy",
    "pcUrl": "https://example.com/certify/pc/123?token=abcdef123456¬ifyUrl=xxx&redirectUrl=yyy",
    "userId": 123
  }
}

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

• 接口路径：POST /person/lookup-identity
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：在平台内、访问令牌可访问范围下，按个人实名（姓名+身份证号）匹配个人组织，返回解析到的用户 userId、mobile，以及该用户下全部可用印章（含自有与经用印授权、去重后按 sealId 排序）。seals 中 relationType 区分 OWN（本人/自有）与 AUTHORIZED（授权使用）。每条印章补充所属组织（个人章/企业章）及制章人绑定手机、身份证号；另返回该用户已加入的绑定企业列表（boundEnterprises，ACTIVE 关系，含 COMPANY / SELF_EMPLOYED）。

请求体（JSON）

响应 data 主要字段

{
  "realName": "张三",
  "idNumber": "110101199001011234"
}

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

6. 印章管理

6.1 添加印章

• 接口路径：POST /seal/add
• 请求类型：JSON（Content-Type: application/json）
• 功能说明：添加印章，用于合同签署。无需上传印章图片，系统会自动生成。

请求头

请求参数

{
  "name": "张三印章",
  "type": 1,
  "userId": 1,
  "isDefault": 1
}

{
  "name": "测试公司公章",
  "type": 2,
  "orgId": 1,
  "sealShape": 0,
  "isDefault": 1
}

{
  "name": "测试公司合同章",
  "type": 2,
  "orgId": 1,
  "sealShape": 1,
  "isDefault": 0
}

响应参数

{
  "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），无需传递印章大小参数。

请求头

请求参数

{
  "userId": 123456,
  "imageBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "name": "张三的个人章",
  "type": 1,
  "isDefault": 0
}

{
  "userId": 123456,
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "name": "某某科技有限公司",
  "type": 2,
  "orgId": 789012,
  "isDefault": 1
}

响应参数

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "sealId": 345678,
    "name": "某某科技有限公司",
    "type": 2,
    "userId": 123456,
    "orgId": 789012,
    "isDefault": true
  }
}

6.3 设置默认印章

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

请求头

路径参数

响应参数

{
  "success": true,
  "data": {
    "set": true
  }
}

6.3 查询印章详情

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

请求头

路径参数

响应参数

{
  "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/表单请求体；参数 orgId 见 URL Query
• 功能说明：查询印章列表

请求头

查询参数

响应参数

{
  "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.1 发送授权短信

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

请求头

请求参数

响应参数

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

POST /seal/authorization/send-sms-code?sealId=1001
Authorization: Bearer <accessToken>

{
  "code": 200,
  "success": true,
  "msg": "验证码已发送",
  "data": null
}

6.5.2 确认授权

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

请求头

请求体参数

响应参数

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

data 对象字段

{
  "sealId": 1001,
  "userId": 2002,
  "smsCode": "123456"
}

{
  "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 中
• 功能说明：将指定授权记录置为已撤销（软删），被授权人不再具备该章用印权限。

请求头

请求参数

响应参数

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

POST /seal/authorization/revoke/5001
Authorization: Bearer <accessToken>

{
  "code": 200,
  "success": true,
  "msg": "撤销成功",
  "data": null
}

6.5.4 查询某印章的授权列表

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

请求头

请求参数

响应参数

GET /seal/authorization/list?sealId=1001
Authorization: Bearer <accessToken>

{
  "code": 200,
  "success": true,
  "msg": null,
  "data": [
    {
      "authId": 5001,
      "sealId": 1001,
      "userId": 2002,
      "sealAuthEvidenceId": 90001,
      "transactionHash": "0xabc123..."
    }
  ]
}

6.6 变更印章所有人

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

请求体（JSON）

响应 data 主要字段

{
  "sealId": 1001,
  "newOwnerUserId": 2002,
  "smsCode": "123456"
}

{
  "success": true,
  "data": {
    "sealId": 1001,
    "name": "某某公司",
    "orgId": 500,
    "userId": 2002,
    "isDefault": true,
    "sealOwnerTransferEvidenceId": 90002,
    "ownerTransferTransactionHash": "0xdef456..."
  }
}

7. 错误码说明

8. 调用示例

8.1 获取令牌

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。

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.4 一致）。须先 8.1 取令牌，请求中携带平台内有效 userId 与 orgId。

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. 版本说明

接口列表