跳到主要内容

获取发起合同组嵌入链接

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：模板
  • 2：文件

示例值：2
Agent否Agent代理企业和员工的信息。
在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。

3. 输出参数​

参数名称类型描述
FlowGroupIdString合同(流程)组的合同组Id
示例值：yDt1JUUckp77a2omUyEmko88eg49PTsN
PrepareUrlString嵌入式合同组发起链接
示例值：https://embed.test.qian.tencent.cn/contract-create?embed=1&expiredOn=1744785243&code=yDtBLUUckpx65&businessId=yDtBLUUckYNlO&channel=TENCENTCLOUD&operateSource=byFileGroup&themeId=saas_web_theme
RequestIdString唯一请求 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.JsonMarshalJson序列化失败。
InternalError.PdfPdf错误。
InternalError.Serialize序列化错误。
InternalError.System系统错误，请稍后重试。
InvalidParameter.ApproverType不合法的签署人类型，请检查后重试。
InvalidParameter.CardNumber不合法的证件信息，请检查证件号证件类型是否正确。
InvalidParameter.CardType不合法的证件信息，请检查证件号证件类型是否正确。
InvalidParameter.CcNum不合法的抄送方设置，请联系客服了解抄送设置规则，修改后重试。
InvalidParameter.ClientTokenClientToken不合法请检查。
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.InvalidChannelChannel不正确。
InvalidParameter.InvalidIdid类型参数不合法，请检查后重试。
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操作不支持。
更多开发者交流反馈