跳到主要内容

创建小程序发起合同链接

1. 接口描述​

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

创建小程序发起流程链接，在小程序页面上完成签署人等信息的编辑与确认后，可快速发起流程。


适用场景：如果需要签署人在自己的APP、小程序、H5应用中发起合同，可在收集合同信息，签署人等信息后（非必选），通过此接口获取跳转腾讯电子签小程序的合同发起跳转链接，跳转到腾讯电子签小程序继续合同的发起。

跳转到小程序的实现，参考微信官方文档（分为全屏、半屏两种方式），如何配置也可以请参考: 跳转电子签小程序配置

注：

  • 1. 签署链接的有效期为90天，超过有效期链接不可用
  • 2. 生成的链路后面不能再增加参数（会出现覆盖链接中已有参数导致错误）
  • 3. 调用接口后，流程不会立即发起，需使用链接跳转到小程序上继续发起流程操作。
  • 4. 使用链接成功发起一份合同后，链接立即失效

其中小程序的原始Id如下，或者查看小程序信息自助获取。

小程序AppID原始ID
腾讯电子签（正式版）wxa023b292fd19d41dgh_da88f6188665
腾讯电子签Demowx371151823f6f3edfgh_39a5d3de69fa

默认接口请求频率限制：20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数​

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。

参数名称必选类型描述
Action是String公共参数，本接口取值：CreateMiniAppPrepareFlow。
Version是String公共参数，本接口取值：2020-11-11。
Region否String公共参数，此参数为可选参数。
Operator是UserInfo执行本接口操作的员工信息。使用此接口时，必须填写userId。
支持填入集团子公司经办人 userId 代发合同。

注: 在调用此接口时，请确保指定的员工已获得所需的接口调用权限，并具备接口传入的相应资源的数据权限。
示例值：{"UserId":"yDxjOUUgydjfxgnzUuO5zjEWA07rC5xl"}
ResourceType是Integer资源类型，取值有：
  • 1：模板
  • 2：文件

示例值：1
ResourceId是String资源id，与ResourceType相对应，取值范围：

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


注意：需要同时设置 ResourceType 参数指定资源类型
示例值：yDxZtUyKQD2JuqUuO4zjERYG3XNeEJXw
FlowName是String自定义的合同流程的名称，长度不能超过200个字符，只能由中文汉字、中文标点、英文字母、阿拉伯数字、空格、小括号、中括号、中划线、下划线以及（,）、（;）、（.）、(&)、（+）组成。

该名称还将用于合同签署完成后文件下载的默认文件名称。
示例值：合同名称
Agent否Agent代理企业和员工的信息。
在集团企业代理子企业操作的场景中，需设置此参数。在此情境下，ProxyOrganizationId（子企业的组织ID）为必填项。
示例值：{"ProxyOrganizationId":"yDwiyUUckpodg1g9UuDwx6KuPMVKNEnk"}
Approvers.N否Array of MiniAppCreateApproverInfo合同流程的参与方列表，最多可支持50个参与方，可在列表中指定企业B端签署方和个人C端签署方的联系和认证方式等信息。
示例值：[{"ApproverType":1,"ApproverName":"张某","ApproverMobile":"18200000000"}]
CcInfos.N否Array of CcInfo合同流程的抄送人列表，最多可支持50个抄送人，抄送人可查看合同内容及签署进度，但无需参与合同签署。

注：暂不支持通过NotifyType参数控制抄送人通知方式
示例值：[{"CcType":0,"Name":"程某","Mobile":"18700000000"}]
Unordered否Boolean合同流程的签署顺序类型：
  • false：(默认)有序签署, 本合同多个参与人需要依次签署
  • true：无序签署, 本合同多个参与人没有先后签署限制


注：仅在文件发起模式下设置有效，模板发起以模板配置为准
示例值：true
DeadlineAfterStartDays否Integer合同发起后经过多少天截止（1-30天可选），默认7天
示例值：3
UserFlowTypeId否String用户自定义合同类型Id 该id为电子签企业内的合同类型id， 可以在控制台-合同-自定义合同类型处获取
示例值：yDR1dUUgygj77gh6UuO4zjEvSXYRnQ84
FlowOption否MiniAppCreateFlowOption发起合同个性化参数
用于满足小程序合同创建的个性化要求
具体定制化内容详见数据接口说明
示例值：{"RemindedOn":1753286400,"NeedCreateReview":false,"FlowDisplayType":1}
PageOption否MiniAppCreateFlowPageOption发起合同小程序页面个性化参数
用于满足小程序合同创建页面的个性化要求 具体定制化内容详见数据接口说明
示例值：{"HideSignCodeAfterStart":true}
UserData否String调用方自定义的个性化字段(可自定义此名称)，并以base64方式编码，支持的最大数据大小为 1000 长度。

在合同状态变更的回调信息等场景中，该字段的信息将原封不动地透传给贵方。回调的相关说明可参考开发者中心的回调通知模块。
示例值：自定义数据

3. 输出参数​

参数名称类型描述
LongUrlStringH5跳转到电子签小程序链接, 一般用于发送短信中带的链接, 打开后进入腾讯电子签小程序
示例值：https://res.ess.tencent.cn/cdn/h5-activity-dev/jump-mp.html?to=CREATE_CONTRACT&shortKey=yDtGEUqBRu0a9TF5sO511
ShortUrlStringH5跳转到电子签小程序链接的短链形式, 一般用于发送短信中带的链接, 打开后进入腾讯电子签小程序
示例值：https://test.essurl.cn/t8c0UBN2722
MiniAppPathStringAPP或小程序跳转电子签小程序链接, 一般用于客户小程序或者APP跳转过来, 打开后进入腾讯电子签小程序
示例值：pages/guide/index?to=CREATE_CONTRACT&shortKey=yDtGEUqBRu0a9TF5sO51
FlowIdString创建的合同id（还未实际发起，也未扣费），每次调用会生成新的id，用户可以记录此字段对应后续在小程序发起的合同，若在小程序上未成功发起，则此字段无效。
示例值：yDwcCUUgyg3tgmvhUEVzyNa15Zayy6Sf
QrcodeUrlString跳转至电子签小程序的二维码链接
示例值：https://dyn.test.ess.tencent.cn/imgs/qrcode_urls/create_contract/yDtGEUUckp95bu13UuQn9oe3FEBKizIN.png
WeixinQrcodeUrlString直接跳转至电子签小程序的二维码链接，无需通过中转页。需要自行将其转换为二维码，使用微信扫码后可直接进入。
示例值：https://res.ess.tencent.cn/mp-gate/develop/CREATE_CONTRACT?shortKey=yDtGEUqBE5oBLdr2d591
ExpiredOnInteger链接过期时间，精确到秒，若在此过期时间前未使用，则链接失效。

示例值：1761031031
RequestIdString唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例​

示例1 文件发起​

输入示例​

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateMiniAppPrepareFlow
<公共请求参数>

{
    "Operator": {
        "UserId": "yDxjOUUgydjfxgnzUuO5zjEWA07rC5xl"
    },
    "ResourceId": "yDtIfUUckp9grxnsUyecoDMwRdhpe8IE",
    "UserFlowTypeId": "",
    "ResourceType": 2,
    "FlowName": "小程序合同发起测试",
    "Unordered": true,
    "DeadlineAfterStartDays": 3,
    "UserData": "VXNlckRhdGE=",
    "FlowOption": {
        "NeedCreateReview": false,
        "FlowDisplayType": 1
    },
    "PageOption": {
        "HideSignCodeAfterStart": true
    },
    "CcInfos": [
        {
            "CcType": 0,
            "Name": "程某",
            "Mobile": "18700000000"
        }
    ],
    "Approvers": [
        {
            "ApproverType": 0,
            "OrganizationName": "电子签测试企业",
            "ApproverName": "何规",
            "ApproverMobile": "18200000000"
        },
        {
            "ApproverType": 1,
            "ApproverName": "张某",
            "ApproverMobile": "18200000000"
        }
    ]
}

输出示例​

{
    "Response": {
        "ExpiredOn": 1761031031,
        "FlowId": "yDtGEUUckp95buvoUuQn9oeynYWruYTL",
        "LongUrl": "https://res.ess.tencent.cn/cdn/h5-activity-dev/jump-mp.html?to=CREATE_CONTRACT&shortKey=yDtGEUqBRu0a9TF5sO50",
        "MiniAppPath": "pages/guide/index?to=CREATE_CONTRACT&shortKey=yDtGEUqBRu0a9TF5sO50",
        "WeixinQrcodeUrl": "https://res.ess.tencent.cn/mp-gate/develop/CREATE_CONTRACT?shortKey=yDtGEUqBE5oBLdr2d590",
        "QrcodeUrl": "https://dyn.test.ess.tencent.cn/imgs/qrcode_urls/create_contract/yDtGEUUckp95bu13UuQn9oe1FEBKizIN.png",
        "RequestId": "s1753255031857612403",
        "ShortUrl": "https://test.essurl.cn/t8c0UBN27z"
    }
}

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请升级到对应版本后即可使用该接口。
更多开发者交流反馈
购买咨询
联系销售
预约咨询
购买热线
售后服务
技术顾问