跳到主要内容

模板发起合同-发起签署流程

1. 接口描述

接口请求域名: ess.tencentcloudapi.com 。

此接口用于启动流程。它是模板发起合同的最后一步。 在创建签署流程创建电子文档之后,用于开始整个合同流程, 推进流程进入到签署环节。

image

注: 1.合同发起后就会扣减合同的额度, 只有撤销没有参与方签署过或只有自动签署签署过的合同,才会返还合同额度。(过期,拒签,签署完成,解除完成等状态不会返还额度)

2.静默(自动)签署不支持非本企业合同签署方存在填写功能

3.在发起签署流程之前,建议等待 PDF合成完成的回调,尤其是当模板中存在动态表格等复杂填写控件时,因为合成过程可能会耗费秒级别的时间。

默认接口请求频率限制:300次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称必选类型描述
ActionString公共参数,本接口取值:StartFlow。
VersionString公共参数,本接口取值:2020-11-11。
RegionString公共参数,此参数为可选参数。
OperatorUserInfo执行本接口操作的员工信息。
注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。
FlowIdString合同流程ID,为32位字符串。
此处需要传入创建签署流程接口得到的FlowId。
示例值:yDwFk****qS26
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
CcNotifyTypeInteger若在创建签署流程时指定了关注人CcInfos,此参数可设定向关注人发送短信通知的类型:
  • 0 :合同发起时通知通知对方来查看合同(默认)
  • 1 : 签署完成后通知对方来查看合同

3. 输出参数

参数名称类型描述
StatusString发起成功后返回的状态,根据合同流程的不同,返回不同状态:
  • START : 发起成功, 合同进入签署环节
  • REVIEW : 提交审核成功, 合同需要发起审核, 发起方企业通过接口审核通过后合同才进入签署环境 白名单功能,使用前请联系对接的客户经理沟通。
  • EXECUTING : 已提交发起任务且PDF合同正在合成中, 等PDF合同合成成功后进入签署环节
RequestIdString唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 正常启动签署流程

启动签署流程

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: StartFlow
<公共请求参数>

{
"Operator": {
"UserId": "yDxZ1UyKQDSIMaUuO5zjEypPWudeHbnG"
},
"FlowId": "yDwJ0UUckpk2071xUxgm9jJEvuhEhqD7"
}

输出示例

{
"Response": {
"Status": "START",
"RequestId": "xgm9jJv5GGyJXCh"
}
}

示例2 启动签署流程-电子文档尚未准备好

在调用此接口时,若流程电子文档尚未准备就绪,将返回相关错误信息。 在此状态下,可以进行重试。 通常建议在调用创建签署流程电子文档接口后等待3秒,再调用此接口以启动签署流程。

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: StartFlow
<公共请求参数>

{
"Operator": {
"UserId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc"
},
"FlowId": "yDRS4UUgygqdcjjtUuO4zjESYiOVONL1"
}

输出示例

{
"Response": {
"Error": {
"Code": "OperationDenied.DocumentNoAvailable",
"Message": "电子文档不可用,请稍后重试。"
},
"RequestId": "uO4zjEwxRFIf8q1"
}
}

5. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码描述
FailedOperation操作失败。
FailedOperation.FlowHasNoDocument流程未找到关联的电子文件信息,请检查操作步骤,检查参数,并在修改后重试。
FailedOperation.NoSignReviewPass签署审核未通过,请先完成审核。
FailedOperation.NotFoundShadowUser未找到集团子企业相关用户信息,请检查用户相关参数
InternalError内部错误。
InternalError.Db数据库异常。
InternalError.DbConnection数据库连接出错。
InternalError.DbRead内部错误,数据库查询失败,请稍后重试。
InternalError.System系统错误,请稍后重试。
InvalidParameter参数错误。
InvalidParameter.ClientTokenClientToken不合法请检查。
InvalidParameter.InvalidIdid类型参数不合法,请检查后重试。
InvalidParameter.ParamError参数错误。
InvalidParameterValue.Mask需要屏蔽的告警。
MissingParameter缺少参数错误。
MissingParameter.ApproverSignComponent缺少签署人签署控件配置,请联系客服了解控件传递规则,并在修改后重试。
OperationDenied操作被拒绝。
OperationDenied.DocumentNoAvailable电子文档不可用,请稍后重试。
OperationDenied.FlowCancelForbid签署流程无法撤销,请检查签署流程状态,检查签署流程归属企业,检查当前操作人是否有权限,并在修改后重试。
OperationDenied.FlowHasStarted签署流程已经被发起,请检查。
OperationDenied.FlowHasTerminated签署流程已经被终止,请检查。
OperationDenied.FlowNoNeedReview签署流程不需要进行审核,请修改后重试。
OperationDenied.FlowStatusForbid签署流程状态不正确,请检查后重试。
OperationDenied.Forbid禁止此项操作。
OperationDenied.NoFlowPermission无权限操作签署流程,请联系客服了解权限,并在修改后重试。
OperationDenied.NoIdentityVerify未通过个人实名认证。
OperationDenied.NoLogin用户未登录,请先登录后再操作。
OperationDenied.NoOpenServerSign未开通静默签功能,请联系签署方企业开通后重试。
OperationDenied.NoQuota企业额度不足,请检查企业额度后处理。
OperationDenied.WhiteListForbid未开通功能白名单,请联系客服处理。
ResourceInUse资源被占用。
ResourceNotFound资源不存在。
ResourceNotFound.Flow签署流程未找到,请检查参数。
ResourceNotFound.FlowApprover签署流程的签署人不存在,请检查后重试。
ResourceNotFound.NotExistDocument电子文档不存在。
ResourceNotFound.NotExistFlow流程不存在。
ResourceNotFound.Organization机构不存在或者未完成认证,请检查机构信息。
ResourceNotFound.Resource未获取到文件资源,请检查资源是否完成上传,是否有效,并在修改后重试。
ResourceUnavailable资源不可用。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。
UnknownParameter未知参数错误。
UnsupportedOperation操作不支持。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062