跳到主要内容

创建发起流程web页面

1. 接口描述​

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

创建发起流程web页面


适用场景：通过该接口（CreatePrepareFlow）传入合同文件/模板编号及签署人信息，可获得发起流程的可嵌入页面，在页面完成签署控件等信息的编辑与确认后，快速发起流程。
注：该接口包含模板/文件发起流程的全部功能，调用接口后不会立即发起，需在可嵌入页面点击按钮进行发起流程。

默认接口请求频率限制：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相对应，取值范围：

  • 文件Id（通过UploadFiles获取文件资源Id）
  • 模板Id（通过控制台创建模板后获取模板Id）


注意：需要同时设置 ResourceType 参数指定资源类型
FlowName是String合同流程的名称（可自定义此名称），长度不能超过200，只能由中文、字母、数字和下划线组成。
ResourceType否Integer资源类型，取值有：
  • 1：模板
  • 2：文件（默认值）

示例值：1
Unordered否Boolean合同流程的签署顺序类型：
  • false：(默认)有序签署, 本合同多个参与人需要依次签署
  • true：无序签署, 本合同多个参与人没有先后签署限制

示例值：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：开启（默认值）
  • CLOSE：关闭

示例值：OPEN
Components否Component该字段已废弃，请使用InitiatorComponents
FlowOption否CreateFlowOption发起合同个性化参数
用于满足创建及页面操作过程中的个性化要求
具体定制化内容详见数据接口说明
NeedSignReview否Boolean发起方企业的签署人进行签署操作前，是否需要企业内部走审批流程，取值如下：
  • false：（默认）不需要审批，直接签署。
  • true：需要走审批流程。当到对应参与人签署时，会阻塞其签署操作，等待企业内部审批完成。

企业可以通过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结构体

3. 输出参数​

参数名称类型描述
UrlString发起流程的web页面链接，有效期5分钟
FlowIdString创建的合同id（还未实际发起），每次调用会生成新的id，用户可以记录此字段对应后续页面发起的合同，若在页面上未成功发起，则此字段无效。
RequestIdString唯一请求 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.ClientTokenClientToken不合法请检查。
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请升级到对应版本后即可使用该接口。
更多开发者交流反馈
购买咨询
4006-808-062
4006-808-062