补充签署流程签署人信息
1. 接口描述
接口请求域名: ess.tencentcloudapi.com 。
适用场景 :
当通过模板或文件发起合同时, 签署人不制定, 等合同发起后再指定 可以用下面2种方案
1. 或签合同: 若未指定企业签署人信息(只指定企业的名字),合同变成或签合同(个人签署方不支持或签合同)。需调用此接口补充或添加签署人。或签签署人在控制台上的展示样式如下(会带有或签标识):2. 动态签署人合同: 若未指定具体签署人的信息,则合同变成动态签署人合同。需调用此接口补充或添加签署人。可以参考文档 动态签署人合同 。动态签署人在控制台上的展示样式如下:实际签署人需要通过获取跳转至腾讯电子签小程序的签署链接生成的链接进入小程序,领取合同并签署。同一签署环节可补充多个员工作为或签署人,最终实际签署人取决于谁先领取合同完成签署。
限制条件:
1.本企业(发起方企业)企业微信签署人仅支持通过企业微信UserId或姓名+手机号进行补充。
2.本企业(发起方企业)非企业微信签署人仅支持通过姓名+手机号进行补充。
3.他方企业仅支持通过姓名+手机号进行补充。
4.个人签署人支持通过姓名+手机号进行补充(若个人用户已完成实名,动态签署人合同也可以可通过姓名+证件号码进行补充)
整体流程如下图:
默认接口请求频率限制:30次/秒。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:CreateFlowApprovers。 |
Version | 是 | String | 公共参数,本接口取值:2020-11-11。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
Operator | 是 | UserInfo | 执行本接口操作的员工信息。 注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。 |
Approvers.N | 是 | Array of FillApproverInfo | 补充签署环节签署候选人信息。 注: 如果发起方指定的补充签署人是企业微信签署人(ApproverSource=WEWORKAPP),则需要提供企业微信UserId进行补充; 如果不指定,则使用姓名和手机号进行补充。 |
FlowId | 否 | String | 合同流程ID,为32位字符串。 建议开发者妥善保存此流程ID,以便于顺利进行后续操作。 可登录腾讯电子签控制台,在 "合同"->"合同中心" 中查看某个合同的FlowId(在页面中展示为合同ID)。 |
FillApproverType | 否 | Integer | 签署人信息补充方式
|
Initiator | 否 | String | 在可定制的企业微信通知中,发起人可以根据具体需求进行自定义设置。 |
Agent | 否 | Agent | 代理企业和员工的信息。 在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。 |
FlowGroupId | 否 | String | 合同流程组的组ID, 在合同流程组场景下,生成合同流程组的签署链接时需要赋值 示例值:yDR1AUUgygjazuesUuO4zjESPW4PkfNi |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
FillError | Array of FillError | 批量补充签署人时,补充失败的报错说明 注: 目前仅补充动态签署人时会返回补充失败的原因 注意:此字段可能返回 null,表示取不到有效值。 |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 B2C签署,补充合同组动态签署人信息
在B2C签署中,双方签署方未指定具体签署人时,需要进行补充。
注:
1.补充动态签署人时FillApproverType传值为1
2.补充合同组动态签署人每个签署方都需指定FlowId
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowGroupId": "yDCVMUUckpwytlc2UE1RW1FSgWksaiI3",
"FillApproverType": 1,
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "典子谦",
"ApproverMobile": "13200000000",
"OrganizationName": "***有限公司",
"FlowId": "yDCVMUUckpwytlcrUE1RW1Fvnl52FPBB"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverName": "张三",
"ApproverMobile": "18888888888",
"FlowId": "yDCVMUUckpwytlc5UE1RW1FwLn7Hcn01"
}
]
}
输出示例
{
"Response": {
"RequestId": "s1234345677xxxx"
}
}
示例2 B2C签署,批量补充两方动态签署人信息
在B2C签署中,双方签署方未指定具体签署人时,需要进行补充。
注:补充动态签署人时FillApproverType传值为1
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"FillApproverType": 1,
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "典子谦",
"ApproverMobile": "13200000000",
"OrganizationName": "***有限公司"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverName": "张三",
"ApproverMobile": "18888888888"
}
]
}
输出示例
{
"Response": {
"RequestId": "s1234345677xxxx"
}
}
示例3 B2B签署,补充签署流程本企业企业签署人信息
在B2B签署中,双方签署方指定签署人类型为企业签署人,但未指定具体签署人时,需要进行企业签署人的补充。
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "典子谦",
"ApproverMobile": "13200000000"
},
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "张三",
"ApproverMobile": "18888888888"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverName": "李四",
"ApproverMobile": "15100000000"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverName": "王五",
"ApproverMobile": "13700000000"
}
]
}
输出示例
{
"Response": {
"RequestId": "s1694694766993518983"
}
}
示例4 B2B签署,补充签署流程本企业企业微信签署人信息
在B2B签署中,双方签署方指定签署人类型为企业微信签署人,但未指定具体签署人时,需要进行企业微信签署人的补充。
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "Zhangsan"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "Lisi"
},
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "Wangwu"
},
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "ZhaoLiu"
}
]
}
输出示例
{
"Response": {
"RequestId": "s1694694766993518983"
}
}
示例5 B2C签署,批量补充两方动态签署人信息时重复补充报错
在B2C签署中,双方签署方未指定具体签署人时,需要进行补充。当重复补充同一个签署节点时,会进行部分补充报错。
注:补充动态签署人时FillApproverType传值为1
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"FillApproverType": 1,
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverName": "典子谦",
"ApproverMobile": "13200000000",
"OrganizationName": "***有限公司"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverName": "张三",
"ApproverMobile": "18888888888"
}
]
}
输出示例
{
"Response": {
"FillError": [
{
"ErrMessage": "个人信息已补充,请勿重复补充",
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc"
}
],
"RequestId": "s1696921563375938822"
}
}
示例6 B2C签署,通过姓名和证件类型、证件号码补充已实名个人用户
通过姓名和证件类型、证件号码补充已实名个人用户
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"FillApproverType": 1,
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "典子谦",
"ApproverIdCardType": "ID_CARD",
"ApproverIdCardNumber": "620000198802020000"
}
]
}
输出示例
{
"Response": {
"RequestId": "s1234345677xxxx"
}
}
示例7 B2B签署,补充签署流程本企业企业签署人和企业微信签署人信息
在B2B签署中,如果第一方签署方指定企业签署人类型,但未指定具体签署人,需要进行企业签署人的补充指定;同时第二方签署方指定签署人为企业微信,但也未指定具体签署人,此时也需要进行企业微信签署人的补充。
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "典子谦",
"ApproverMobile": "13200000000"
},
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "张三",
"ApproverMobile": "18888888888"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "Wangwu"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "ZhaoLiu"
}
]
}
输出示例
{
"Response": {
"RequestId": "s1694694766993518983"
}
}
示例8 错误示例, B2B签署,补充签署流程本企业企业签署人使用了姓名和手机号进行补充报错
错误示例,B2B签署,在B2B签署中,如果双方签署方均指定企业签署人类型为企业微信签署人,但都未指定具体签署人,且使用了姓名和手机号进行补充,这种方式是不被支持的。企业微信签署人的补充需要使用企业微信UserId进行补充。
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateFlowApprovers
<公共请求参数>
{
"Operator": {
"UserId": "yDRCLUUgygq2xun5UuO4zjEwg0vjoimj"
},
"FlowId": "yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm",
"Approvers": [
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "典子谦",
"ApproverMobile": "13200000000"
},
{
"RecipientId": "yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR",
"ApproverName": "张三",
"ApproverMobile": "18888888888"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "Wangwu"
},
{
"RecipientId": "yDRS4UUgygqdcj2tUuO4zjEEFuP35Swc",
"ApproverSource": "WEWORKAPP",
"CustomUserId": "ZhaoLiu"
}
]
}
输出示例
{
"Response": {
"Error": {
"Code": "OperationDenied",
"Message": "签署人RecipientId【yDRS4UUgygqdcj51UuO4zjEyWTmzsIAR】对应的签署人,在发起时限制补充企微或签签署人,请通过CustomUserId指定"
},
"RequestId": "s1694694766993518983"
}
}
5. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
FailedOperation | 操作失败。 |
FailedOperation.AgeNotAchieveNormalLegal | 年龄限制无法使用电子签服务,请联系客服咨询处理。 |
FailedOperation.FlowHasDocument | 签署流程已有关联文档,请检查参数修改后重试。 |
FailedOperation.OrganizationExperienceChange | 企业经营状态与工商局信息不符。 |
FailedOperation.OrganizationNameChanged | 企业名称与工商局信息不符。 |
FailedOperation.OrganizationNameNeedChange | 企业名称与工商局信息不符,需要超管修改。 |
FailedOperation.RequestLimitExceeded | 请求的次数超过了频率限制,请联系客服处理。 |
FailedOperation.UserInfoNoMatch | 用户信息不匹配,请检查后重试。 |
InternalError.Db | 数据库异常。 |
InternalError.DbRead | 内部错误,数据库查询失败,请稍后重试。 |
InternalError.Decryption | 解密失败。 |
InternalError.DependsApi | 依赖的第三方API返回错误。 |
InternalError.DependsDb | 数据库执行错误。 |
InternalError.Encryption | 加密失败。 |
InternalError.System | 系统错误,请稍后重试。 |
InvalidParameter.ApproverType | 不合法的签署人类型,请检查后重试。 |
InvalidParameter.CardNumber | 不合法的证件信息,请检查证件号证件类型是否正确。 |
InvalidParameter.CardType | 不合法的证件信息,请检查证件号证件类型是否正确。 |
InvalidParameter.CcNum | 不合法的抄送方设置,请联系客服了解抄送设置规则,修改后重试。 |
InvalidParameter.ClientToken | ClientToken不合法请检查。 |
InvalidParameter.FlowCallbackUrl | 不合法的签署流程回调链接,请修改后重试。 |
InvalidParameter.FlowDeadLine | 不合法的签署流程截止日期,请修改后重试。 |
InvalidParameter.FlowDescription | 不合法的签署流程描述,请修改后重试。 |
InvalidParameter.FlowName | 不合法的签署流程名称,请修改后重试。 |
InvalidParameter.FlowType | 不合法的签署流程类型,请修改后重试。 |
InvalidParameter.FlowUserData | 不合法的签署流程用户自定义数据,请修改后重试。 |
InvalidParameter.FromSource | 不合法的FromSource,请联系开发,检查后重试。 |
InvalidParameter.IdCardValidityOverLimit | 用户个人证件已过期。 |
InvalidParameter.InvalidMobile | 手机号码不正确。 |
InvalidParameter.InvalidName | 姓名不正确。 |
InvalidParameter.Mobile | 不合法的手机号,请检查后重试。 |
InvalidParameter.Name | 不合法的用户名称,请修改后重试。 |
InvalidParameter.NotifyType | 不支持的通知类型,请检查并联系客服处理。 |
InvalidParameter.OrganizationName | 不合法的企业名称,请修改后重试。 |
InvalidParameter.ParamError | 参数错误。 |
InvalidParameter.PersonAutoSignTag | 个人静默签Tag未设置,请检查后重试。 |
InvalidParameter.PreReadTime | 不合法的阅读时长限制,请联系客服了解阅读时长设置规则,修改后重试。 |
InvalidParameter.Sensitive | 参数包含有敏感词 |
InvalidParameterValue.Mask | 需要屏蔽的告警。 |
LimitExceeded | 超过配额限制。 |
MissingParameter.ApproverMobile | 缺少签署人手机号,请检查后重试。 |
MissingParameter.ApproverName | 缺少签署人姓名,请检查后重试。 |
MissingParameter.ApproverOrganizationInfo | 缺少签署人企业信息,请检查后重试。 |
OperationDenied | 操作被拒绝。 |
OperationDenied.ApproverRepeat | 签署人重复,请联系客服了解发起签署流程签署人规则,修改后重试。 |
OperationDenied.CcForbid | 当前不支持抄送,请联系客服咨询处理。 |
OperationDenied.CcUserRepeat | 抄送方存在相同抄送人,请检查修改后重试。 |
OperationDenied.Forbid | 禁止此项操作。 |
OperationDenied.NoIdentityVerify | 未通过个人实名认证。 |
OperationDenied.NoLogin | 用户未登录,请先登录后再操作。 |
OperationDenied.NoOpenServerSign | 未开通静默签功能,请联系签署方企业开通后重试。 |
OperationDenied.NoQuota | 企业额度不足,请检查企业额度后处理。 |
OperationDenied.OrgUniformSocialCreditCodeErr | 此社会信用编码未查询到结果,请检查后重试。 |
OperationDenied.OrganizationNotActivated | 企业未激活。 |
OperationDenied.OverSeaForbid | 当前不支持境外用户,请联系客服咨询处理。 |
OperationDenied.PersonHasNoSignature | 个人名下没用可使用的签名,请联系个人配置签名后重试。 |
OperationDenied.WhiteListForbid | 未开通功能白名单,请联系客服处理。 |
RequestLimitExceeded | 请求的次数超过了频率限制。 |
ResourceNotFound | 资源不存在。 |
ResourceNotFound.Application | 应用号不存在或已删除。 |
ResourceNotFound.AuthActiveOrganization | 机构未完成认证激活,请检查并联系客服处理。 |
ResourceNotFound.FlowApprover | 签署流程的签署人不存在,请检查后重试。 |
ResourceNotFound.Organization | 机构不存在或者未完成认证,请检查机构信息。 |
ResourceNotFound.SuperAdmin | 超管信息不存在,请检查企业认证信息。 |
ResourceNotFound.User | 用户或者员工信息不存在,请检查参数后重试。 |
ResourceNotFound.VerifyUser | 用户或者员工未完成实名认证,请检查参数后重试。 |
UnauthorizedOperation.NoPermissionFeature | 请升级到对应版本后即可使用该接口。 |