参与方签署 API - 签署任务

参与方签署

本部分包含用于参与方执行合同填写、签署、意愿认证和支付操作的API接口。

重要提示： 所有签署任务相关的 API 请求，都需要在 HTTP Header 中携带有效的 appId, accessToken, userId (当前操作人ID), 和 source (来源标识) 作为通用认证参数。关于 source 参数的详细说明和取值，请参考快速开始章节。

POST /signTask/fillSignForm 填写合同

参与方提交合同中需要填写的表单域内容。

请求 Header (通用认证参数)

参数名	类型	必填	描述
appId	string	是	您的应用ID
accessToken	string	是	获取到的有效访问令牌
userId	integer (int64)	是	执行此操作的用户ID (操作人)
source	string	是	来源标识 (pc, app, h5, wx, alipay)

请求参数 (Body)

参数名	类型	必填	描述
flowId	integer (int64)	是	流程ID
+components	array of object	是	需要填写的组件列表 (结构见 ComponentCmd 定义)
componentId	integer (int64)	是	组件ID
participantId	integer (int64)	是	参与方ID
contractFileId	integer (int64)	是	合同文档ID
value	string	是	填写值

请求示例

CURL

curl -X POST 'https://your-api-host.com/signTask/fillSignForm' \
-H 'Content-Type: application/json' \
-H 'appId: YOUR_APP_ID' \
-H 'accessToken: YOUR_ACCESS_TOKEN' \
-H 'userId: FILLER_USER_ID' \
-H 'source: pc' \
-d '{
  "flowId": 12001,
  "components": [
    {
      "componentId": 8001,
      "participantId": 15002,
      "contractFileId": 6001,
      "value": "XX街道XX号"
    },
    {
      "componentId": 8002,
      "participantId": 15002,
      "contractFileId": 6001,
      "value": "13912345678"
    }
  ]
}'

响应参数

参数名	类型	描述
code	string	响应码，"0" 表示成功，其他表示错误。
msg	string	响应消息。
data	object	响应数据，通常为空对象 `{}` 或包含更新后的流程状态信息，结构如下（若有）：
flowId	integer (int64)	流程ID。
flowStatus	integer (int32)	填写操作后的流程状态 (如 1:签署中)。

响应示例

成功响应 (200 OK)

{
  "code": "0",
  "msg": "success",
  "data": {
    "flowId": 12001,
    "flowStatus": 1
  }
}

错误码

HTTP状态码/业务码	描述
200	成功
400	请求参数错误 (如组件ID无效, 值格式错误)
401	未授权
403	禁止访问 (非当前填写人或流程状态错误)
404	流程或组件不存在
500	服务器内部错误

POST /signTask/signContract 填写签署

参与方提交签署操作，通常包含使用的印章信息和签署位置。

请求 Header (通用认证参数)

参数名	类型	必填	描述
appId	string	是	您的应用ID
accessToken	string	是	获取到的有效访问令牌
userId	integer (int64)	是	执行此操作的用户ID (操作人)
source	string	是	来源标识 (pc, app, h5, wx, alipay)

请求参数 (Body)

参数名	类型	必填	描述
flowId	integer (int64)	是	流程ID
+components	array of object	是	需要签署的签章区组件列表 (结构见 ComponentCmd_1 定义)
componentId	integer (int64)	是	组件ID
participantId	integer (int64)	是	参与方ID
contractFileId	integer (int64)	是	合同文档ID
pageNum	integer (int32)	是	页码
positionX	number	是	X横坐标
positionY	number	是	Y纵坐标值
fieldType	integer (int32)	是	签署区类型 (0:签章区, 1:备注区, 2:独立签署日期)
sealId	integer (int64)	是	签名的印章ID
+specialAttribute	object	是	控件特有属性 (见 TemplateCompSpecialAttr)
dateFormat	string	否	日期格式 (例如: yyyy年MM月dd日)
font	string	否	字体 (SimSun, FangSong, etc.)
fontSize	integer (int32)	否	字体大小
sealSpecs	integer (int32)	否	落章规则 (1:实际规格, 2:自定义)
showSignDate	integer (int32)	否	签章是否显示日期 (0:否, 1:是)

请求示例

CURL

curl -X POST 'https://your-api-host.com/signTask/signContract' \
-H 'Content-Type: application/json' \
-H 'appId: YOUR_APP_ID' \
-H 'accessToken: YOUR_ACCESS_TOKEN' \
-H 'userId: SIGNER_USER_ID' \
-H 'source: pc' \
-d '{
  "flowId": 12001,
  "components": [
    {
      "componentId": 8005,
      "participantId": 15001,
      "contractFileId": 6001,
      "pageNum": 2,
      "positionX": 150.5,
      "positionY": 650.0,
      "fieldType": 0,
      "sealId": 9001,
      "specialAttribute": {
        "sealSpecs": 1,
        "showSignDate": 1
      }
    }
  ]
}'

响应参数

参数名	类型	描述
code	string	响应码，"0" 表示成功，其他表示错误。
msg	string	响应消息。
data	object	响应数据，包含签署操作后的流程状态信息，结构如下：
flowId	integer (int64)	流程ID。
flowStatus	integer (int32)	签署操作后的流程状态 (如 1:签署中, 2:完成)。

响应示例

成功响应 (200 OK)

{
  "code": "0",
  "msg": "success",
  "data": {
    "flowId": 12001,
    "flowStatus": 2 // 假设这是最后一个签署人，流程完成
  }
}

错误码

HTTP状态码/业务码	描述
200	成功
400	请求参数错误 (如印章ID无效, 位置信息错误)
401	未授权
403	禁止访问 (非当前签署人, 流程状态错误, 未完成意愿认证)
404	流程或组件不存在
500	服务器内部错误 (如签章失败)

POST /signTask/signWish 签署意愿验证

在执行签署操作前或后，根据配置进行意愿认证（如短信验证码、密码、人脸识别）。

请求 Header (通用认证参数)

参数名	类型	必填	描述
appId	string	是	您的应用ID
accessToken	string	是	获取到的有效访问令牌
userId	integer (int64)	是	执行此操作的用户ID (操作人)
source	string	是	来源标识 (pc, app, h5, wx, alipay)

请求参数 (Body)

参数名	类型	必填	描述
flowId	integer (int64)	是	流程ID
authType	string	是	认证方式 ('sms', 'pwd', 'face')
verifyCode	string	看情况	验证码 (authType='sms' 时必填)
signPwd	string	看情况	签署密码 (authType='pwd' 时必填)
newPwd	boolean	否	是否新设置密码 (authType='pwd' 时可选)
code	string	看情况	人脸核身结果码 (authType='face' 时必填)
orderNo	string	看情况	人脸核身订单号 (authType='face' 时必填)
h5faceId	string	看情况	人脸核身H5请求ID (authType='face' 时必填)
newSign / newSignature	string	看情况	人脸核身签名 (authType='face' 时必填)

请求示例 (短信验证)

CURL

curl -X POST 'https://your-api-host.com/signTask/signWish' \
-H 'Content-Type: application/json' \
-H 'appId: YOUR_APP_ID' \
-H 'accessToken: YOUR_ACCESS_TOKEN' \
-H 'userId: SIGNER_USER_ID' \
-H 'source: pc' \
-d '{
  "flowId": 12001,
  "authType": "sms",
  "verifyCode": "123456"
}'

响应参数

参数名	类型	描述
code	string	响应码，"0" 表示认证成功，其他表示失败。
msg	string	响应消息。
data	object	响应数据，认证成功时通常为空对象 `{}`。

响应示例

成功响应 (200 OK)

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

错误码

HTTP状态码/业务码	描述
200	成功
400	请求参数错误 (如验证码错误, 密码错误)
401	未授权
403	禁止访问 (非当前操作人, 认证方式不支持)
404	流程不存在
XXX	业务错误 (如验证失败、人脸核身未通过等特定业务码)
500	服务器内部错误

POST /signTask/reversePayContractFee 对方付合同费用支付

在需要对方支付合同费用的场景下，由此参与方调用此接口以触发支付流程。

注意：此接口通常返回支付所需的订单信息或支付凭证（如URL、二维码），后续需跳转到支付平台完成支付。

请求 Header (通用认证参数)

参数名	类型	必填	描述
appId	string	是	您的应用ID
accessToken	string	是	获取到的有效访问令牌
userId	integer (int64)	是	执行此操作的用户ID (操作人)
source	string	是	来源标识 (pc, app, h5, wx, alipay)

请求参数 (Body)

参数名	类型	必填	描述
flowId	integer (int64)	是	需要支付费用的流程ID

请求示例

CURL

curl -X POST 'https://your-api-host.com/signTask/reversePayContractFee' \
-H 'Content-Type: application/json' \
-H 'appId: YOUR_APP_ID' \
-H 'accessToken: PAYER_ACCESS_TOKEN' \
-H 'userId: PAYER_USER_ID' \
-H 'source: pc' \
-d '{
  "flowId": 12010
}'

响应参数

参数名	类型	描述
code	string	响应码，"0" 表示成功，其他表示错误。
msg	string	响应消息。
data	object	响应数据，包含支付所需信息，具体结构依赖于支付渠道集成，可能包含：
payUrl	string	支付跳转URL (例如支付宝、微信支付的URL)。
qrCode	string	支付二维码内容（如果适用）。
orderNo	string	平台生成的支付订单号。

响应示例

成功响应 (200 OK)

{
  "code": "0",
  "msg": "success",
  "data": {
    "payUrl": "https://pay.alipay.com/...",
    "orderNo": "PAY_ORDER_123",
    "qrCode": null
  }
}

错误码

HTTP状态码/业务码	描述
200	成功
400	请求参数错误
401	未授权
403	禁止访问 (非指定支付方或已支付)
404	流程不存在或非对方付费合同
500	服务器内部错误 (创建支付订单失败)

POST /signTask/getFillUrl 获取填写合同链接

获取指定流程的在线填写页面链接，用于嵌入或直接跳转。

请求 Header (通用认证参数)

参数名	类型	必填	描述
appId	string	是	您的应用ID
accessToken	string	是	获取到的有效访问令牌
userId	integer (int64)	是	执行此操作的用户ID (操作人)
source	string	是	来源标识 (pc, app, h5, wx, alipay)

请求参数 (Body)

参数名	类型	必填	描述
flowId	integer (int64)	是	流程ID

请求示例

CURL

curl -X POST 'https://your-api-host.com/signTask/getFillUrl' \
-H 'Content-Type: application/json' \
-H 'appId: YOUR_APP_ID' \
-H 'accessToken: YOUR_ACCESS_TOKEN' \
-H 'userId: FILLER_USER_ID' \
-H 'source: pc' \
-d '{
  "flowId": 12001
}'

响应参数

参数名	类型	描述
code	string	响应码，"0" 表示成功，其他表示错误。
msg	string	响应消息。
data	string	返回的在线填写页面URL。

响应示例

成功响应 (200 OK)

{
  "code": "0",
  "msg": "success",
  "data": "https://your-system-ui.com/fill?flowId=12001&token=..."
}

错误码

HTTP状态码/业务码	描述
200	成功
401	未授权
403	禁止访问 (非当前填写人或流程状态错误)
404	流程不存在
500	服务器内部错误

POST /signTask/getSignUrl 获取签署链接

获取指定流程的在线签署页面链接，用于嵌入或直接跳转。

请求 Header (通用认证参数)

参数名	类型	必填	描述
appId	string	是	您的应用ID
accessToken	string	是	获取到的有效访问令牌
userId	integer (int64)	是	执行此操作的用户ID (操作人)
source	string	是	来源标识 (pc, app, h5, wx, alipay)

请求参数 (Body)

参数名	类型	必填	描述
flowId	integer (int64)	是	流程ID

请求示例

CURL

curl -X POST 'https://your-api-host.com/signTask/getSignUrl' \
-H 'Content-Type: application/json' \
-H 'appId: YOUR_APP_ID' \
-H 'accessToken: YOUR_ACCESS_TOKEN' \
-H 'userId: SIGNER_USER_ID' \
-H 'source: pc' \
-d '{
  "flowId": 12001
}'

响应参数

参数名	类型	描述
code	string	响应码，"0" 表示成功，其他表示错误。
msg	string	响应消息。
data	string	返回的在线签署页面URL。

响应示例

成功响应 (200 OK)

{
  "code": "0",
  "msg": "success",
  "data": "https://your-system-ui.com/sign?flowId=12001&token=..."
}

错误码

HTTP状态码/业务码	描述
200	成功
401	未授权
403	禁止访问 (非当前签署人或流程状态错误)
404	流程不存在
500	服务器内部错误

共享数据模型参考

以下是本页API请求和响应中涉及的复杂数据结构的详细定义，供参考。

填写组件命令 (`ComponentCmd`)

参数名	类型	必填	描述
componentId	int64	是	组件ID
participantId	int64	是	参与方ID
contractFileId	int64	是	合同文档ID
value	string	是	填写值

签署组件命令 (`ComponentCmd_1`)

参数名	类型	必填	描述
componentId	int64	是	组件ID
participantId	int64	是	参与方ID
contractFileId	int64	是	合同文档ID
pageNum	int32	是	页码
positionX	number	是	X横坐标
positionY	number	是	Y纵坐标值
fieldType	int32	是	签署区类型 (0:签章区, 1:备注区, 2:独立签署日期)
sealId	int64	是	签名的印章ID
+specialAttribute	object	是	控件特有属性 (见 TemplateCompSpecialAttr)
dateFormat	string	否	日期格式 (例如: yyyy年MM月dd日)
font	string	否	字体 (SimSun, FangSong, etc.)
fontSize	integer (int32)	否	字体大小
sealSpecs	integer (int32)	否	落章规则 (1:实际规格, 2:自定义)
showSignDate	integer (int32)	否	签章是否显示日期 (0:否, 1:是)

模板组件特殊属性 (`TemplateCompSpecialAttr`)

此对象包含控件的详细样式和行为属性，如字体、大小、格式、签章规则等。具体字段请参考 JSON 定义。

部分常用参数	类型	描述
dateFormat	string	日期格式 (yyyy年MM月dd日, yyyy-MM-dd 等)
font	string	字体 (SimSun, FangSong, KaiTi, SimHei)
fontSize	int32	字体大小
maxLength	string	文本最大长度
sealSpecs	int32	落章规则 (1:实际规格, 2:自定义)
showSignDate	int32	签章是否显示日期 (0:否, 1:是)
signStyle	int32	签章区样式 (1:单页, 2:骑缝)
...	...	更多属性见JSON

签署意愿验证参数 (`获取流程组件信息请求参数`)

用于意愿认证的参数结构。

参数名	类型	必填	描述
flowId	int64	是	流程ID
authType	string	是	认证方式 ('sms', 'pwd', 'face')
verifyCode	string	看情况	验证码
signPwd	string	看情况	签署密码
newPwd	boolean	否	是否新设置密码
code	string	看情况	人脸核身结果码
orderNo	string	看情况	人脸核身订单号
h5faceId	string	看情况	人脸核身H5请求ID
newSign / newSignature	string	看情况	人脸核身签名

流程ID参数 (`流程id参数`)

参数名	类型	必填	描述
flowId	int64	是	流程ID

获取链接参数 (`填写签署合同流程请求参数`)

参数名	类型	必填	描述
flowId	int64	是	流程ID