签署任务创建 API

通过模板或文件创建并正式发起签署任务。

签署任务创建

本部分包含用于创建和发起签署任务的API接口。

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

使用预先创建好的合同模板来发起一个新的签署流程。

请求 Header (通用认证参数)

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

请求参数 (Body)

参数名 类型 必填 描述
templateId integer (int64) 是 模板ID (模板id和模板编码二选一)
templateCode string 是 模板编码 (模板id和模板编码二选一)
templateName string 否 模板名称 (用于最终流程标题，建议填写)
privaryFlag integer (int32) 否 模板是否保密 (0: 不保密, 1: 保密)
encryptFlag integer (int32) 否 是否加密合同 (0: 普通合同, 1: 加密合同)
reversePayFlag integer (int32) 否 是否对方付 (0: 发起方付, 1: 对方付)
sourceOrderCode string 否 外部单号(企业app过来的可以保留一个外部来源单号)
+participantList array of object 是 设置签署方 (结构见 参与方实体类_1 定义)
+attachmentList array of object 否 选填项设置.合同附件 (结构见 模板附件实体类 定义)
autoFill integer (int32) 否 自动填写标识（0：不需要自动填写，默认值；1：异步自动填写；2：同步自动填写）
+fillComponents array of object 否 自动填写信息 (填写应设置模板所属企业签署方填写，不要设成对方填写)

请求示例

CURL
Java SDK

curl -X POST 'https://your-api-host.com/signTask/startSignFlow' \
-H 'Content-Type: application/json' \
-H 'appId: YOUR_APP_ID' \
-H 'accessToken: YOUR_ACCESS_TOKEN' \
-H 'userId: YOUR_USER_ID' \
-H 'source: pc' \
-d '{
  "templateId": 1001,
  "templateName": "租赁合同-20240315",
  "autoFill": 1,
  "participantList": [
    {
      "participantFlag": "甲方",
      "psnAccount": "13800138000",
      "psnName": "发起人张三"
    },
    {
      "participantFlag": "乙方",
      "psnAccount": "13900139000",
      "psnName": "李四",
      "participantCorpName": "乙方公司",
      "payeeContractFlag": 1,
      "payee": {
        "amount": 500.00,
        "priority": 0
      }
    }
  ],
  "attachmentList": [
     {
       "fileName": "补充协议.pdf",
       "fileUrl": "upload/xxx/attachment.pdf"
     }
  ],
  "fillComponents": [
    {
      "componentKey": "ClientName",
      "componentValue": "张三科技有限公司"
    },
    {
      "componentKey": "ContractAmount",
      "componentValue": "10000.00"
    }
  ]
}'
									
	GetStartSignFlowReq getStartSignFlowReq = new GetStartSignFlowReq();
        getStartSignFlowReq.setHeaderUserId(000000000L);
        getStartSignFlowReq.setTemplateId(1L);
        getStartSignFlowReq.setTemplateName("测试模板");
        getStartSignFlowReq.setAutoFill(0);
        List<GetStartSignFlowParticipantReq> participantList = new ArrayList<>();
        GetStartSignFlowParticipantReq participantReq = new GetStartSignFlowParticipantReq();
        participantReq.setParticipantFlag("签署方1");
        participantReq.setPsnAccount("13700000000");
        participantReq.setPsnName("张三");
        participantReq.setParticipantCorpName("测试公司");
        participantList.add(participantReq);
        GetStartSignFlowParticipantReq participantReq2 = new GetStartSignFlowParticipantReq();
        participantReq2.setParticipantFlag("签署方2");
        participantReq2.setPsnAccount("13700000001");
        participantReq2.setPsnName("李四");
        participantList.add(participantReq2);
        getStartSignFlowReq.setParticipantList(participantList);
        GetStartSignFlowResponse getStartSignFlowResponse = client.execute(getStartSignFlowReq);
        System.out.println(JSON.toJSONString(getStartSignFlowResponse.getData()));

响应参数

参数名 类型 描述
code string 响应码，"200" 表示成功，其他表示错误。
msg string 响应消息。
+data object 响应数据，结构如下：

响应示例

成功响应 (200 OK)

{
  "code": "200",
  "msg": "成功",
  "data": {
    "flowId": 12001,
    "flowStatus": 0,
    "flowTitle": "租赁合同-20240315",
    "flowDesc": "签署中",
    "nextStatus": 2,
    "resultStatus": null,
    "errorMessage": null,
    "participantList": [
      {
        "participantId": 20101,
        "participantFlag": "甲方",
        "signStatus": 2,
        "psnName": "发起人张三",
        "participantType": 0
      },
      {
        "participantId": 20102,
        "participantFlag": "乙方",
        "signStatus": 1,
        "psnName": "李四",
        "participantCorpName": "乙方公司",
        "participantType": 1,
        "payeeContractFlag": 1,
        "payee": {
          "id": 301,
          "amount": 500.00,
          "payeeStatus": 0,
          "priority": 0
        }
      }
    ]
  }
}

错误码

HTTP状态码/业务码 描述
200 成功
400 请求参数错误 (如模板ID无效, 参与方信息缺失)
401 未授权 (Token无效或过期)
403 禁止访问 (无权使用该模板)
404 模板不存在
500 服务器内部错误
POST /signTask/directSignFlow 直接发起合同
POST /signTask/directComponentSignFlow 直接发起合同(指定签署位置处)
POST /signTask/getDesignatedSignatureUrl 获取指定签署位置直接发起合同链接

共享数据模型参考

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

参与方实体类_1 (`参与方实体类_1`)

参数名 类型 必填 描述
participantId int64 否 参与方ID（参与方ID和参与方标识二选一）
participantFlag string 否 参与方标识，同一个模板中不可重复，会展示到模板页面上，例如甲方、乙方等容易理解的业务名词（参与方ID和参与方标识二选一）
psnAccount string 是 经办人手机
psnName string 是 经办人名称
participantCorpName string 否 参与方企业名称 (个人类型时为空)
payeeContractFlag int32 否 是否需要收款 (0:否, 1:是)
+payee object 否 收款信息 (结构见 合同模板收款信息实体类_1 定义)

合同模板收款信息实体类_1 (`合同模板收款信息实体类_1`)

参数名 类型 必填 描述
id int64 否 收款信息ID (修改时传)
amount number 是 收款金额
priority int32 否 签署付款顺序 (0: 先付后签; 1: 先签后付)
remark string 否 收款备注说明

模板附件实体类 (`模板附件实体类`)

参数名 类型 必填 描述
attachmentId int64 否 附件ID
templateId int64 否 模板ID
fileName string 是 文件名称
fileUrl string 是 文件地址 (附件上传后获取)

控件实体类 (`控件实体类`)

用于请求中 fillComponents 数组，填充模板中已定义的控件值。

参数名 类型 必填 描述
componentId int64 否 控件ID (控件ID和控件Key二选一，用于定位模板中的控件)
componentKey string 否 控件Key (控件ID和控件Key二选一，用于定位模板中的控件)
componentValue string 是 需要填充到控件中的值

签署人信息_1 (`签署人信息_1`)

用于响应中 participantList 数组，描述流程中各签署方的详细信息和状态。

参数名 类型 描述
participantId int64 签署人信息ID
participantFlag string 参与方标识，例如甲方、乙方等
signStatus int32 当前签署状态: 1-填写中; 2-签署中; 3-已签署; 4-等待审批; 5-已拒签
participantCorpId int64 企业ID (个人类型时为空)
participantCorpName string 企业名称 (个人类型时为空)
participantType int32 参与方类型 (1-企业, 0-个人)
participateBizType array of string 参与方式 (例如: ["1", "2"] 表示可填写、可签署)
psnId int64 企业经办人账号ID
psnName string 经办人名称
payeeContractFlag int32 是否需要收款 (0:否, 1:是)
+payee object 签署人支付信息 (结构见 签署人支付信息 定义)

签署人支付信息 (`签署人支付信息`)

参数名 类型 描述
id int64 收款信息ID
amount number 收款金额
payeeStatus int32 收款支付状态 (0:未支付, 1:已支付)
auditStatus int32 收款审批状态 (0:未审批, 1:已审批)
priority int32 签署付款顺序 (0:先付后签, 1:先签后付)
remark string 收款备注说明