创建发起流程web页面
1. 接口描述
接口请求域名: ess.tencentcloudapi.com 。
创建发起流程Web页面,通过该接口可以获取发起流程的可嵌入web页面的URL(此web页面可以通过iframe方式嵌入到贵方系统的网页中)。在页面上完成签署控件等信息的编辑与确认后,可快速发起流程。
注意:调用接口后,流程不会立即发起,需在嵌入页面上点击【发起合同】按钮来发起流程。
嵌入页面长相如下:
默认接口请求频率限制:20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:CreatePrepareFlow。 |
Version | 是 | String | 公共参数,本接口取值:2020-11-11。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
Operator | 是 | UserInfo | 执行本接口操作的员工信息。使用此接口时,必须填写userId。 支持填入集团子公司经办人 userId 代发合同。 注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。 |
ResourceId | 是 | String | 资源id,与ResourceType相对应,取值范围:
注意:需要同时设置 ResourceType 参数指定资源类型 |
FlowName | 是 | String | 自定义的合同流程的名称,长度不能超过200个字符,只能由中文汉字、中文标点、英文字母、阿拉伯数字、空格、小括号、中括号、中划线、下划线以及(,)、(;)、(.)、(&)、(+)组成。 该名称还将用于合同签署完成后文件下载的默认文件名称。 |
ResourceType | 否 | Integer | 资源类型,取值有:
示例值:1 |
Unordered | 否 | Boolean | 合同流程的签署顺序类型:
示例值:true |
Deadline | 否 | Integer | 合同流程的签署截止时间,格式为Unix标准时间戳(秒),如果未设置签署截止时间,则默认为合同流程创建后的365天时截止。 |
UserFlowTypeId | 否 | String | 用户自定义合同类型Id 该id为电子签企业内的合同类型id, 可以在控制台-合同-自定义合同类型处获取 注: 该参数如果和FlowType同时传,以该参数优先生效 |
FlowType | 否 | String | 合同流程的类别分类(可自定义名称,如销售合同/入职合同等),最大长度为200个字符,仅限中文、字母、数字和下划线组成。 示例值:"劳动合同" |
Approvers.N | 否 | Array of FlowCreateApprover | 合同流程的参与方列表,最多可支持50个参与方,可在列表中指定企业B端签署方和个人C端签署方的联系和认证方式等信息,具体定义可以参考开发者中心的ApproverInfo结构体。 如果合同流程是有序签署,Approvers列表中参与人的顺序就是默认的签署顺序,请确保列表中参与人的顺序符合实际签署顺序。 |
IntelligentStatus | 否 | String | 开启或者关闭智能添加填写区:
示例值:OPEN |
Components | 否 | Component | 该字段已废弃,请使用InitiatorComponents |
FlowOption | 否 | CreateFlowOption | 发起合同个性化参数 用于满足创建及页面操作过程中的个性化要求 具体定制化内容详见数据接口说明 |
NeedSignReview | 否 | Boolean | 发起方企业的签署人进行签署操作前,是否需要企业内部走审批流程,取值如下:
企业可以通过CreateFlowSignReview审批接口通知腾讯电子签平台企业内部审批结果
注: 此功能可用于与企业内部的审批流程进行关联,支持手动、静默签署合同 |
NeedCreateReview | 否 | Boolean | 发起方企业的签署人进行发起操作是否需要企业内部审批。使用此功能需要发起方企业有参与签署。 若设置为true,发起审核结果需通过接口 CreateFlowSignReview 通知电子签,审核通过后,发起方企业签署人方可进行发起操作,否则会阻塞其发起操作。 |
UserData | 否 | String | 调用方自定义的个性化字段(可自定义此名称),并以base64方式编码,支持的最大数据大小为 20480长度。 在合同状态变更的回调信息等场景中,该字段的信息将原封不动地透传给贵方。回调的相关说明可参考开发者中心的回调通知模块。 |
CcInfos | 否 | CcInfo | 合同流程的抄送人列表,最多可支持50个抄送人,抄送人可查看合同内容及签署进度,但无需参与合同签署。 |
FlowId | 否 | String | 合同Id:用于通过一个已发起的合同快速生成一个发起流程web链接 注: 该参数必须是一个待发起审核的合同id,并且还未审核通过 |
Agent | 否 | Agent | 代理企业和员工的信息。 在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。 |
InitiatorComponents.N | 否 | Array of Component | 模板或者合同中的填写控件列表,列表中可支持下列多种填写控件,控件的详细定义参考开发者中心的Component结构体 |
FlowDisplayType | 否 | Integer | 在短信通知、填写、签署流程中,若标题、按钮、合同详情等地方存在“合同”字样时,可根据此配置指定文案,可选文案如下:
示例值:1 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
Url | String | 发起流程的web页面链接,有效期5分钟 |
FlowId | String | 创建的合同id(还未实际发起),每次调用会生成新的id,用户可以记录此字段对应后续页面发起的合同,若在页面上未成功发起,则此字段无效。 |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 创建签署流程
通过文件发起,无序,b2c,开启智能填写区
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreatePrepareFlow
<公共请求参数>
{
"Operator": {
"UserId": "yDRSsUxxxxxxxxxxxxxxxxxLdSu"
},
"Unordered": true,
"IntelligentStatus": "OPEN",
"FlowName": "文件发起-嵌入式合同",
"Deadline": 1791859333,
"ResourceId": "yDR0xxxxxxxxxxxxxxxxxxxEYm",
"ResourceType": 2,
"UserFlowTypeId": "",
"FlowType": "嵌入式文件发起合同",
"UserData": "",
"FlowId": "",
"InitiatorComponents": [
{
"ComponentPosX": 160,
"ComponentPosY": 760,
"ComponentHeight": 30,
"ComponentWidth": 300,
"FileIndex": 0,
"ComponentType": "TEXT",
"ComponentValue": "这是发起填写控件{{ @now }}",
"LockComponentValue": true,
"ForbidMoveAndDelete": true,
"ComponentRequired": true,
"ComponentPage": 1
}
],
"FlowOption": {
"CanEditFlow": false,
"CanEditFormField": true,
"HideShowFlowName": true,
"HideShowFlowType": true,
"HideShowDeadline": true,
"CanSkipAddApprover": true,
"SkipUploadFile": true,
"ForbidEditFillComponent": true,
"CustomCreateFlowDescription": ""
},
"Approvers": [
{
"ApproverType": 1,
"ApproverName": "典子谦",
"ApproverMobile": "13200000000",
"PreReadTime": 3,
"Required": true,
"ApproverOption": {
"NoRefuse": true,
"NoTransfer": true,
"CanEditApprover": true
},
"ApproverVerifyTypes": [
1,
2
],
"ApproverSignTypes": [
1,
2
],
"Components": [
{
"ComponentPosX": 160,
"ComponentPosY": 560,
"ComponentHeight": 30,
"ComponentWidth": 300,
"FileIndex": 0,
"ComponentType": "TEXT",
"ComponentValue": "这是第一个签署人的填写控件{{ @now }}",
"LockComponentValue": true,
"ForbidMoveAndDelete": true,
"ComponentPage": 1
}
],
"SignComponents": [
{
"ComponentPosX": 160,
"ComponentPosY": 360,
"ComponentHeight": 100,
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ForbidMoveAndDelete": true,
"ComponentValue": "",
"LockComponentValue": true,
"ComponentPage": 1
}
],
"IsFullText": true
},
{
"ApproverType": 0,
"OrganizationName": "典子谦示例企业",
"ApproverName": "典子谦",
"ApproverMobile": "13200000001",
"PreReadTime": 3,
"Required": true,
"Components": [
{
"ComponentPosX": 160,
"ComponentPosY": 660,
"ComponentHeight": 30,
"ComponentWidth": 300,
"FileIndex": 0,
"ComponentType": "TEXT",
"ComponentValue": "这是第二个签署人的填写控件",
"LockComponentValue": true,
"ForbidMoveAndDelete": true,
"ComponentPage": 1
}
],
"SignComponents": [
{
"ComponentPosX": 160,
"ComponentPosY": 260,
"ComponentWidth": 100,
"ComponentHeight": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ForbidMoveAndDelete": true,
"ComponentPage": 1
}
],
"IsFullText": true
}
]
}
输出示例
{
"Response": {
"RequestId": "s1692004929990936987",
"Url": "https://embed.beta.qian.tencent.cn/contract-create?embed=1&expiredOn=1692005230&code=yDwqmxxxxxxxxxxxxxKaLJfQEGm&businessId=yDwqmUUxxxxxxxxxDAgN4fKi&channel=TENCENTCLOUD&operateSource=byFile&themeId=saas_web_theme_732aaefa78c439d726f541b89c49e022"
}
}
示例2 通过模板发起嵌入式url
模板发起,b2c
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreatePrepareFlow
<公共请求参数>
{
"Operator": {
"UserId": "yDRSsUxxxxxxxxxxxxxxxxxLdSu"
},
"Unordered": true,
"IntelligentStatus": "open",
"FlowName": "模板发起-嵌入式合同",
"Deadline": 1991859333,
"ResourceId": "yDwXXUUckxxxxxxxxxx4S7NM8r",
"ResourceType": 1,
"UserFlowTypeId": "",
"FlowType": "",
"UserData": "",
"FlowOption": {
"CanEditFlow": false,
"CanEditFormField": true,
"HideShowFlowName": true,
"HideShowFlowType": true,
"HideShowDeadline": true,
"CanSkipAddApprover": true,
"SkipUploadFile": true,
"ForbidEditFillComponent": true,
"CustomCreateFlowDescription": ""
},
"Approvers": [
{
"ApproverType": 1,
"ApproverName": "典子谦",
"ApproverMobile": "13200000000",
"PreReadTime": 3,
"Required": true,
"RecipientId": "yDwXXxxxxxxxxxxxxxxOZbdgN6",
"ApproverOption": {
"NoRefuse": true,
"NoTransfer": true,
"CanEditApprover": true
},
"ApproverVerifyTypes": [
1,
2
],
"ApproverSignTypes": [
1,
2
],
"IsFullText": true
},
{
"ApproverType": 0,
"OrganizationName": "典子谦示例企业",
"ApproverName": "典子谦",
"ApproverMobile": "13200000001",
"PreReadTime": 3,
"Required": true,
"RecipientId": "yDwXXUUxxxxxxxxxxxxxxO1XEwdCTnI",
"IsFullText": true
}
]
}
输出示例
{
"Response": {
"RequestId": "s1692004929990936987",
"Url": "https://embed.beta.qian.tencent.cn/contract-create?embed=1&expiredOn=1692005230&code=yDwqmxxxxxxxxxxxxxKaLJfQEGm&businessId=yDwqmUUxxxxxxxxxDAgN4fKi&channel=TENCENTCLOUD&operateSource=byFile&themeId=saas_web_theme_732aaefa78c439d726f541b89c49e022"
}
}
示例3 通过模板发起待签署审核
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreatePrepareFlow
<公共请求参数>
{
"Operator": {
"UserId": "yDRSsUxxxxxxxxxxxxxxxxxLdSu"
},
"Unordered": true,
"IntelligentStatus": "open",
"FlowName": "模板发起-嵌入式合同",
"Deadline": 1991859333,
"ResourceId": "yDwXXUUckxxxxxxxxxx4S7NM8r",
"ResourceType": 1,
"NeedCreateReview": true,
"FlowType": "",
"UserData": "",
"FlowOption": {
"CanEditFlow": false,
"CanEditFormField": true,
"HideShowFlowName": true,
"HideShowFlowType": true,
"HideShowDeadline": true,
"CanSkipAddApprover": true,
"SkipUploadFile": true,
"ForbidEditFillComponent": true,
"CustomCreateFlowDescription": ""
},
"Approvers": [
{
"ApproverType": 1,
"ApproverName": "典子谦",
"ApproverMobile": "13200000000",
"PreReadTime": 3,
"Required": true,
"RecipientId": "yDwXXxxxxxxxxxxxxxxOZbdgN6",
"ApproverOption": {
"NoRefuse": true,
"NoTransfer": true,
"CanEditApprover": true
},
"ApproverVerifyTypes": [
1,
2
],
"ApproverSignTypes": [
1,
2
],
"IsFullText": true
},
{
"ApproverType": 0,
"OrganizationName": "典子谦示例企业",
"ApproverName": "典子谦",
"ApproverMobile": "13200000001",
"PreReadTime": 3,
"Required": true,
"RecipientId": "yDwXXUUxxxxxxxxxxxxxxO1XEwdCTnI",
"IsFullText": true
}
]
}
输出示例
{
"Response": {
"RequestId": "s1692004929990936987",
"Url": "https://embed.beta.qian.tencent.cn/contract-create?embed=1&expiredOn=1692005230&code=yDwqmxxxxxxxxxxxxxKaLJfQEGm&businessId=yDwqmUUxxxxxxxxxDAgN4fKi&channel=TENCENTCLOUD&operateSource=byFile&themeId=saas_web_theme_732aaefa78c439d726f541b89c49e022"
}
}
示例4 文件发起,设置跳过上传文件,必须要传资源id
输入示例
POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreatePrepareFlow
<公共请求参数>
{
"Operator": {
"UserId": "yDRSsUxxxxxxxxxxxxxxxxxLdSu"
},
"Unordered": true,
"IntelligentStatus": "OPEN",
"FlowName": "文件发起-嵌入式合同",
"Deadline": 1791859333,
"ResourceId": "",
"ResourceType": 2,
"UserFlowTypeId": "",
"FlowType": "嵌入式文件发起合同",
"UserData": "",
"FlowId": "",
"FlowOption": {
"CanEditFlow": false,
"CanEditFormField": true,
"HideShowFlowName": true,
"HideShowFlowType": true,
"HideShowDeadline": true,
"CanSkipAddApprover": true,
"SkipUploadFile": true,
"ForbidEditFillComponent": true,
"CustomCreateFlowDescription": ""
},
"Approvers": [
{
"ApproverType": 1,
"ApproverName": "典子谦",
"ApproverMobile": "13200000000",
"PreReadTime": 3,
"Required": true,
"ApproverOption": {
"NoRefuse": true,
"NoTransfer": true,
"CanEditApprover": true
},
"ApproverVerifyTypes": [
1,
2
],
"ApproverSignTypes": [
1,
2
],
"Components": [
{
"ComponentPosX": 160,
"ComponentPosY": 560,
"ComponentHeight": 30,
"ComponentWidth": 300,
"FileIndex": 0,
"ComponentType": "TEXT",
"ComponentValue": "这是第一个签署人的填写控件{{ @now }}",
"LockComponentValue": true,
"ForbidMoveAndDelete": true,
"ComponentPage": 1
}
],
"SignComponents": [
{
"ComponentPosX": 160,
"ComponentPosY": 360,
"ComponentHeight": 100,
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ForbidMoveAndDelete": true,
"ComponentValue": "",
"LockComponentValue": true,
"ComponentPage": 1
}
],
"IsFullText": true
},
{
"ApproverType": 0,
"OrganizationName": "典子谦示例企业",
"ApproverName": "典子谦",
"ApproverMobile": "13200000001",
"PreReadTime": 3,
"Required": true,
"Components": [
{
"ComponentPosX": 160,
"ComponentPosY": 660,
"ComponentHeight": 30,
"ComponentWidth": 300,
"FileIndex": 0,
"ComponentType": "TEXT",
"ComponentValue": "这是第二个签署人的填写控件",
"LockComponentValue": true,
"ForbidMoveAndDelete": true,
"ComponentPage": 1
}
],
"SignComponents": [
{
"ComponentPosX": 160,
"ComponentPosY": 260,
"ComponentWidth": 100,
"ComponentHeight": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ForbidMoveAndDelete": true,
"ComponentPage": 1
}
],
"IsFullText": true
}
]
}
输出示例
{
"Response": {
"Error": {
"Code": "InvalidParameterValue",
"Message": "请指定文件类型的资源id"
},
"RequestId": "s1694764534616690016"
}
}
5. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
FailedOperation | 操作失败。 |
FailedOperation.AgeNotAchieveNormalLegal | 年龄限制无法使用电子签服务,请联系客服咨询处理。 |
FailedOperation.FlowHasDocument | 签署流程已有关联文档,请检查参数修改后重试。 |
FailedOperation.OrganizationExperienceChange | 企业经营状态与工商局信息不符。 |
FailedOperation.OrganizationNameChanged | 企业名称与工商局信息不符。 |
FailedOperation.OrganizationNameNeedChange | 企业名称与工商局信息不符,需要超管修改。 |
FailedOperation.RequestLimitExceeded | 请求的次数超过了频率限制,请联系客服处理。 |
FailedOperation.UserInfoNoMatch | 用户信息不匹配,请检查后重试。 |
InternalError.Db | 数据库异常。 |
InternalError.DbInsert | 数据库新增记录出错。 |
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.CustomShowMap | 无效的自定义页卡模板,请检查后重试。 |
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 | 不合法的阅读时长限制,请联系客服了解阅读时长设置规则,修改后重试。 |
InvalidParameterValue.Mask | 需要屏蔽的告警。 |
LimitExceeded | 超过配额限制。 |
MissingParameter.ApproverMobile | 缺少签署人手机号,请检查后重试。 |
MissingParameter.ApproverName | 缺少签署人姓名,请检查后重试。 |
MissingParameter.ApproverOrganizationInfo | 缺少签署人企业信息,请检查后重试。 |
OperationDenied | 操作被拒绝。 |
OperationDenied.ApproverRepeat | 签署人重复,请联系客服了解发起签署流程签署人规则,修改后重试。 |
OperationDenied.BranchSendFlowToParentNotAllow | 子公司不能发起本方母体公司的合同。 |
OperationDenied.CcForbid | 当前不支持抄送,请联系客服咨询处理。 |
OperationDenied.CcUserRepeat | 抄送方存在相同抄送人,请检查修改后重试。 |
OperationDenied.Forbid | 禁止此项操作。 |
OperationDenied.InvalidApproverAge | 签署人年龄限制无法使用电子签服务。 |
OperationDenied.NoIdentityVerify | 未通过个人实名认证。 |
OperationDenied.NoLogin | 用户未登录,请先登录后再操作。 |
OperationDenied.NoOpenServerSign | 未开通静默签功能,请联系签署方企业开通后重试。 |
OperationDenied.NoQuota | 企业额度不足,请检查企业额度后处理。 |
OperationDenied.OrgUniformSocialCreditCodeErr | 此社会信用编码未查询到结果,请检查后重试。 |
OperationDenied.OrganizationNotActivated | 企业未激活。 |
OperationDenied.OutQueryLimit | 查询限频,请先联系客服了解限频策略,稍后重试。 |
OperationDenied.OverSeaForbid | 当前不支持境外用户,请联系客服咨询处理。 |
OperationDenied.PersonHasNoSignature | 个人名下没用可使用的签名,请联系个人配置签名后重试。 |
OperationDenied.PersonNoOpenServerSign | 该用户已关闭或者未开启自动签服务,请检查后重试。 |
OperationDenied.WhiteListForbid | 未开通功能白名单,请联系客服处理。 |
RequestLimitExceeded | 请求的次数超过了频率限制。 |
ResourceNotFound | 资源不存在。 |
ResourceNotFound.Application | 应用号不存在或已删除。 |
ResourceNotFound.AuthActiveOrganization | 机构未完成认证激活,请检查并联系客服处理。 |
ResourceNotFound.FlowApprover | 签署流程的签署人不存在,请检查后重试。 |
ResourceNotFound.Organization | 机构不存在或者未完成认证,请检查机构信息。 |
ResourceNotFound.SuperAdmin | 超管信息不存在,请检查企业认证信息。 |
ResourceNotFound.User | 用户或者员工信息不存在,请检查参数后重试。 |
ResourceNotFound.VerifyUser | 用户或者员工未完成实名认证,请检查参数后重试。 |
UnauthorizedOperation.NoPermissionFeature | 请升级到对应版本后即可使用该接口。 |