获取发起合同组嵌入链接
1. 接口描述
接口请求域名: ess.tencentcloudapi.com 。
接口(CreatePrepareFlowGroup)用于创建嵌入式合同组签署流程。
- 该接口当前仅支持文件发起
- 该接口能力和CreateFlowGroupByFiles,
CreateFlowGroupByTemplates保持一致。 - 返回的FlowGroupId 为临时id,只有在页面内成功发起后FlowGroupId才会有效。
默认接口请求频率限制:20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:CreatePrepareFlowGroup。 |
Version | 是 | String | 公共参数,本接口取值:2020-11-11。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
Operator | 是 | UserInfo | 执行本接口操作的员工信息。 注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。 |
FlowGroupName | 是 | String | 合同(流程)组名称(可自定义此名称),长度不能超过200,只能由中文、字母、数字和下划线组成。 示例值:入职合同集 |
FlowGroupInfos.N | 是 | Array of FlowGroupInfo | 合同(流程)组的子合同信息,支持2-50个子合同 |
ResourceType | 是 | Integer | 资源类型,取值有:
示例值:1 |
Agent | 否 | Agent | 代理企业和员工的信息。 在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
FlowGroupId | String | 合同(流程)组的合同组Id 示例值:yDt1JUUckp77a2omUyEmko88eg49PTsN |
PrepareUrl | String | 嵌入式合同组发起链接 示例值:https://embed.test.qian.tencent.cn/contract-create?embed=1&expiredOn=1744785243&code=yDtBLUUckpx65&businessId=yDtBLUUckYNlO&channel=TENCENTCLOUD&operateSource=byFileGroup&themeId=saas_web_theme |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 文件发起嵌入式合同组
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreatePrepareFlowGroup
<公共请求参数>
{
"Operator": {
"UserId": "yDwf3UUckps8dvypUEfH3DjwIpMfa0uw"
},
"FlowGroupInfos": [
{
"FileIds": [
"yDCWiUUckpv6iggyUyuqIrwyppQVS7TR"
],
"FlowName": "预发起合同",
"FlowType": "嵌入式文件发起合同",
"FlowDescription": "这是2025年购买食物的合同",
"Deadline": 1757034793,
"Unordered": false,
"NeedSignReview": false,
"UserData": "",
"Approvers": [
{
"ApproverType": 1,
"OrganizationName": "",
"ApproverName": "典子签",
"ApproverOption": {
"CanEditApprover": true
},
"ApproverMobile": "18700000000",
"SignComponents": [
{
"ChannelComponentId": "",
"ChannelComponentSource": 0,
"ComponentDateFontSize": 0,
"ComponentExtra": "",
"ComponentHeight": 100,
"ComponentId": "",
"ComponentName": "",
"ComponentPage": 3,
"ComponentPosX": 160,
"ComponentPosY": 360,
"ComponentRecipientId": "",
"ComponentRequired": false,
"ComponentType": "SIGN_SIGNATURE",
"ComponentValue": "",
"ComponentWidth": 100,
"FileIndex": 0,
"ForbidMoveAndDelete": true,
"GenerateMode": "",
"IsFormType": false,
"KeywordIndexes": [],
"KeywordOrder": "",
"KeywordPage": 0,
"LockComponentValue": false,
"OffsetX": 0,
"OffsetY": 0,
"RelativeLocation": ""
}
]
}
]
}
],
"FlowGroupName": "group",
"ResourceType": 2
}
输出示例
{
"Response": {
"FlowGroupId": "yDttAUUckpxbcziqUySqdD5Eugn0LPHo",
"RequestId": "s1747034803503801327",
"PrepareUrl": "https://embed.test.qian.tencent.cn/contract-create?embed=1&expiredOn=1747035103&code=yDttAUUckpxbcHI&businessId=yDttAUUckpxbcziqUySqdD5o&channel=TENCENTCLOUD&operateSource=byFileGroup&themeId=saas_web_theme_yDhk9nE0qLixm"
}
}
5. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
FailedOperation | 操作失败。 |
FailedOperation.AgeNotAchieveNormalLegal | 年龄限制无法使用电子签服务,请联系客服咨询处理。 |
FailedOperation.FlowHasDocument | 签署流程已有关联文档,请检查参数修改后重试。 |
FailedOperation.FlowHasNoDocument | 流程未找到关联的电子文件信息,请检查操作步骤,检查参数,并在修改后重试。 |
FailedOperation.NoSignReviewPass | 签署审核未通过,请先完成审核。 |
FailedOperation.OrganizationExperienceChange | 企业经营状态与工商局信息不符。 |
FailedOperation.OrganizationNameChanged | 企业名称与工商局信息不符。 |
FailedOperation.OrganizationNameNeedChange | 企业名称与工商局信息不符,需要超管修改。 |
FailedOperation.PreViewUrlFail | 创建签署流程预览链接失败,请稍后重试。 |
FailedOperation.RequestLimitExceeded | 请求的次数超过了频率限制,请联系客服处理。 |
FailedOperation.UserInfoNoMatch | 用户信息不匹配,请检查后重试。 |
InternalError | 内部错误。 |
InternalError.Db | 数据库异常。 |
InternalError.DbConnection | 数据库连接出错。 |
InternalError.DbInsert | 数据库新增记录出错。 |
InternalError.DependsApi | 依赖的第三方API返回错误。 |
InternalError.DependsDb | 数据库执行错误。 |
InternalError.JsonMarshal | Json序列化失败。 |
InternalError.Pdf | Pdf错误。 |
InternalError.Serialize | 序列化错误。 |
InternalError.System | 系统错误,请稍后重试。 |
InvalidParameter.ApproverType | 不合法的签署人类型,请检查后重试。 |
InvalidParameter.CardNumber | 不合法的证件信息,请检查证件号证件类型是否正确。 |
InvalidParameter.CardType | 不合法的证件信息,请检查证件号证件类型是否正确。 |
InvalidParameter.CcNum | 不合法的抄送方设置,请联系客服了解抄送设置规则,修改后重试。 |
InvalidParameter.ClientToken | ClientToken不合法请检查。 |
InvalidParameter.ComponentFileIndex | 不合法的控件所在文件序号,请检查文件资源与控件的对应关系,并在修改后重试。 |
InvalidParameter.ComponentPage | 不合法的控件页码,请与文件资源检查,并在修改后重试。 |
InvalidParameter.ComponentPosition | 不合法的控件大小或坐标,请检查控件坐标,大小是否合理,并在修改后重试。 |
InvalidParameter.ComponentTypeNoMatchValue | 控件的类型与输入值不匹配,请检查参数修改后重试。 |
InvalidParameter.ComponentValue | 不合法的控件内容,请检查控件是否必填,检查控件内容是否正确设置,并在修改后重试。 |
InvalidParameter.CustomShowMap | 无效的自定义页卡模板,请检查后重试。 |
InvalidParameter.EmptyParams | 参数为空,请检查参数修改后重试。 |
InvalidParameter.EndPoint | 不合法的EndPoint,请检查修改后重试。 |
InvalidParameter.FlowCallbackUrl | 不合法的签署流程回调链接,请修改后重试。 |
InvalidParameter.FlowDeadLine | 不合法的签署流程截止日期,请修改后重试。 |
InvalidParameter.FlowDescription | 不合法的签署流程描述,请修改后重试。 |
InvalidParameter.FlowName | 不合法的签署流程名称,请修改后重试。 |
InvalidParameter.FlowType | 不合法的签署流程类型,请修改后重试。 |
InvalidParameter.FlowUserData | 不合法的签署流程用户自定义数据,请修改后重试。 |
InvalidParameter.FromSource | 不合法的FromSource,请联系开发,检查后重试。 |
InvalidParameter.IdCardValidityOverLimit | 用户个人证件已过期。 |
InvalidParameter.InvalidChannel | Channel不正确。 |
InvalidParameter.InvalidId | id类型参数不合法,请检查后重试。 |
InvalidParameter.InvalidMobile | 手机号码不正确。 |
InvalidParameter.InvalidName | 姓名不正确。 |
InvalidParameter.InvalidOrganizationName | 组织机构名称不正确。 |
InvalidParameter.InvalidVerifyChannel | 实名认证渠道不正确。 |
InvalidParameter.MissingRequiredComponentValue | 缺少必填控件的值。 |
InvalidParameter.Mobile | 不合法的手机号,请检查后重试。 |
InvalidParameter.Name | 不合法的用户名称,请修改后重试。 |
InvalidParameter.NotifyType | 不支持的通知类型,请检查并联系客服处理。 |
InvalidParameter.OrganizationName | 不合法的企业名称,请修改后重试。 |
InvalidParameter.ParamError | 参数错误。 |
InvalidParameter.PersonAutoSignTag | 个人静默签Tag未设置,请检查后重试。 |
InvalidParameter.PreReadTime | 不合法的阅读时长限制,请联系客服了解阅读时长设置规则,修改后重试。 |
InvalidParameter.SealId | 不合法的印章id,请检查印章id是否正确,并在修改后重试。 |
InvalidParameter.SignComponents | 签署控件参数不合法,请检查后重试。 |
InvalidParameter.VerifyChannel | 不合法的认证渠道,请联系客户了解电子签支持的认证渠道,并在修改后重试。 |
InvalidParameterValue | 参数取值错误。 |
LimitExceeded | 超过配额限制。 |
MissingParameter | 缺少参数错误。 |
MissingParameter.ApproverMobile | 缺少签署人手机号,请检查后重试。 |
MissingParameter.ApproverName | 缺少签署人姓名,请检查后重试。 |
MissingParameter.ApproverOrganizationInfo | 缺少签署人企业信息,请检查后重试。 |
MissingParameter.ApproverRole | 缺少签署流程签署人角色信息,请检查修改后重试。 |
MissingParameter.ApproverSignComponent | 缺少签署人签署控件配置,请联系客服了解控件传递规则,并在修改后重试。 |
MissingParameter.Field | 未找到表单域配置信息,请检查控件传参,检查文件资源配置,并在修改后重试。 |
MissingParameter.FileNames | 文件名为空,请检查参数修改后重试。 |
MissingParameter.FlowApprover | 缺少签署流程签署人信息,请指定签署人信息后重试。 |
MissingParameter.FlowId | 缺少签署流程id,请检查修改后重试。 |
MissingParameter.KeyWord | 未找到关键字配置信息,请检查控件传参,检查文件资源配置,并在修改后重试。 |
MissingParameter.Recipient | 缺少模板签署人信息,请检查后重试。 |
MissingParameter.ResourceId | 缺少文件资源ID,请检查后重试。 |
MissingParameter.ServerSignSealId | 缺少静默签印章id,请检查修改后重试。 |
MissingParameter.SignComponents | 缺少签署控件参数。 |
OperationDenied | 操作被拒绝。 |
OperationDenied.ApproverNoMatchTemplate | 签署人设置与模板中签署人配置信息不一致,请检查模板修改参数后重试。 |
OperationDenied.ApproverRepeat | 签署人重复,请联系客服了解发起签署流程签署人规则,修改后重试。 |
OperationDenied.BranchSendFlowToParentNotAllow | 子公司不能发起本方母体公司的合同。 |
OperationDenied.CcForbid | 当前不支持抄送,请联系客服咨询处理。 |
OperationDenied.CcUserRepeat | 抄送方存在相同抄送人,请检查修改后重试。 |
OperationDenied.ErrNoSupportIndividualHasOrganizationName | 个人签署方不支持设置企业名称,请确认签署人类型后重试。 |
OperationDenied.FileDeleted | 文件已被删除,请联系客服处理。 |
OperationDenied.FileNoMatchResource | 文件与资源不匹配,请检查文件名与资源id数量以及对应关系,并在修改后重试。 |
OperationDenied.FlowStatusForbid | 签署流程状态不正确,请检查后重试。 |
OperationDenied.Forbid | 禁止此项操作。 |
OperationDenied.InvalidApproverAge | 签署人年龄限制无法使用电子签服务。 |
OperationDenied.ManyResourceId | 资源id超过使用上限限制,请联系客服了解规则,并在修改后重试。 |
OperationDenied.NoIdentityVerify | 未通过个人实名认证。 |
OperationDenied.NoLogin | 用户未登录,请先登录后再操作。 |
OperationDenied.NoOpenServerSign | 未开通静默签功能,请联系签署方企业开通后重试。 |
OperationDenied.NoPermissionUseResource | 无权限使用文件资源,请检查资源有效性以及资源归属,并在修改后重试。 |
OperationDenied.NoPermissionUseServerSignSeal | 无权限使用印章做静默签,请检查印章是否有效,是否有使用权限,并在修改后重试。 |
OperationDenied.NoQuota | 企业额度不足,请检查企业额度后处理。 |
OperationDenied.NoSupportComponentType | 不支持的控件类型,请联系客服了解支持的控件类型,并在修改后重试。 |
OperationDenied.NoSupportJumpPage | 不支持的跳转页,请联系客服了解跳转配置规则,修改后重试。 |
OperationDenied.OrgUniformSocialCreditCodeErr | 此社会信用编码未查询到结果,请检查后重试。 |
OperationDenied.OrganizationNotActivated | 企业未激活。 |
OperationDenied.OutQueryLimit | 查询限频,请先联系客服了解限频策略,稍后重试。 |
OperationDenied.OverSeaForbid | 当前不支持境外用户,请联系客服咨询处理。 |
OperationDenied.PersonHasNoSignature | 个人名下没用可使用的签名,请联系个人配置签名后重试。 |
OperationDenied.PersonNoOpenServerSign | 该用户已关闭或者未开启自动签服务,请检查后重试。 |
OperationDenied.PersonServerSignForbid | 拒绝个人静默签,请检查个人静默签签署人,并在修改后重试。 |
OperationDenied.RequiredComponentNotFill | 必填控件未设置填写内容,将检查修改后重试。 |
OperationDenied.ServerSignNoAllowComponent | 静默签署方不允许有填写控件,请修改模板,修改参数后重试。 |
OperationDenied.ServerSignNoSupportSignature | 静默签署不支持手写签名,请配置印章并使用印章重试。 |
OperationDenied.SubOrgNotJoin | 子企业暂未加入。 |
OperationDenied.WhiteListForbid | 未开通功能白名单,请联系客服处理。 |
RequestLimitExceeded | 请求的次数超过了频率限制。 |
ResourceInUse | 资源被占用。 |
ResourceInsufficient | 资源不足。 |
ResourceNotFound | 资源不存在。 |
ResourceNotFound.Application | 应用号不存在或已删除。 |
ResourceNotFound.AuthActiveOrganization | 机构未完成认证激活,请检查并联系客服处理。 |
ResourceNotFound.Document | 未找到电子文档信息,请检查后重试。 |
ResourceNotFound.ErrNotExistRole | 未获取到用户角色信息,请检查员工角色配置。 |
ResourceNotFound.Flow | 签署流程未找到,请检查参数。 |
ResourceNotFound.FlowApprover | 签署流程的签署人不存在,请检查后重试。 |
ResourceNotFound.NotExistDocument | 电子文档不存在。 |
ResourceNotFound.NotExistFlow | 流程不存在。 |
ResourceNotFound.NotExistResource | 指定的资源不存在。 |
ResourceNotFound.NotExistTemplate | 模板不存在。 |
ResourceNotFound.Organization | 机构不存在或者未完成认证,请检查机构信息。 |
ResourceNotFound.Resource | 未获取到文件资源,请检查资源是否完成上传,是否有效,并在修改后重试。 |
ResourceNotFound.SuperAdmin | 超管信息不存在,请检查企业认证信息。 |
ResourceNotFound.User | 用户或者员工信息不存在,请检查参数后重试。 |
ResourceNotFound.VerifyUser | 用户或者员工未完成实名认证,请检查参数后重试。 |
ResourceUnavailable | 资源不可用。 |
UnauthorizedOperation | 未授权操作。 |
UnauthorizedOperation.NoPermissionFeature | 请升级到对应版本后即可使用该接口。 |
UnknownParameter | 未知参数错误。 |
UnsupportedOperation | 操作不支持。 |