跳到主要内容

用PDF文件创建签署流程

1. 接口描述

接口请求域名: essbasic.tencentcloudapi.com 。

接口(ChannelCreateFlowByFiles)用PDF文件创建签署流程。

适用场景:适用非制式的合同文件签署,开发者有每个签署流程的PDF,可以通过该接口传入完整的PDF文件及流程信息生成待签署的合同流程。

:

  • 此接口静默签(企业自动签)能力为白名单功能,使用前请联系对接的客户经理沟通。
  • 此接口需要依赖文件上传接口生成pdf资源编号(FileIds)进行使用。整体的逻辑如下图

image

可以作为发起方和签署方的角色列表

场景编号可作为发起方类型可作为签署方的类型
场景一第三方子企业A员工第三方子企业A员工
场景二第三方子企业A员工第三方子企业B(不指定经办人)
场景三第三方子企业A员工第三方子企业B员工
场景四第三方子企业A员工个人/自然人
场景五第三方子企业A员工SaaS平台企业员工

: 1. 发起合同时候, 作为发起方的第三方子企业A员工的企业和员工必须经过实名, 而作为签署方的第三方子企业A员工/个人/自然人/SaaS平台企业员工/第三方子企业B员工企业中的企业和个人/员工可以未实名 2. 不同类型的签署方传参不同, 可以参考开发者中心的FlowApproverInfo结构体说明

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

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

2. 输入参数

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

参数名称必选类型描述
ActionString公共参数,本接口取值:ChannelCreateFlowByFiles。
VersionString公共参数,本接口取值:2021-05-26。
RegionString公共参数,此参数为可选参数。
AgentAgent关于渠道应用的相关信息,包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容,您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。

此接口下面信息必填。

  • 渠道应用标识: Agent.ProxyOrganizationOpenId
  • 第三方平台子客企业标识: Agent. ProxyOperator.OpenId
  • 第三方平台子客企业中的员工标识: Agent.AppId

FlowNameString合同流程的名称(可自定义此名称),长度不能超过200,只能由中文、字母、数字和下划线组成。
示例值:张三的入职合同
FlowDescriptionString合同流程描述信息(可自定义此描述),最大长度1000个字符。
示例值:张三2023年入职市场部的合同
FlowApprovers.NArray of FlowApproverInfo合同流程的参与方列表, 最多可支持50个参与方,可在列表中指定企业B端签署方和个人C端签署方的联系和认证方式等信息,具体定义可以参考开发者中心的FlowApproverInfo结构体

如果合同流程是有序签署,Approvers列表中参与人的顺序就是默认的签署顺序, 请确保列表中参与人的顺序符合实际签署顺序。
FileIds.NArray of String本合同流程需包含的PDF文件资源编号列表,通过UploadFiles接口获取PDF文件资源编号。

注: 目前,此接口仅支持单个文件发起。
示例值:["yDRSRUUgygj6rqi6UuO4zjEBDACwAjgT"]
Components.NArray of Component模板或者合同中的填写控件列表,列表中可支持下列多种填写控件,控件的详细定义参考开发者中心的Component结构体
  • 单行文本控件
  • 多行文本控件
  • 勾选框控件
  • 数字控件
  • 图片控件
  • 数据表格等填写控件
DeadlineInteger合同流程的签署截止时间,格式为Unix标准时间戳(秒),如果未设置签署截止时间,则默认为合同流程创建后的365天时截止。
如果在签署截止时间前未完成签署,则合同状态会变为已过期,导致合同作废。
示例值:1691574041
CallbackUrlString执行结果的回调URL,长度不超过255个字符,该URL仅支持HTTP或HTTPS协议,建议采用HTTPS协议以保证数据传输的安全性。
腾讯电子签服务器将通过POST方式,application/json格式通知执行结果,请确保外网可以正常访问该URL。
回调的相关说明可参考开发者中心的回调通知模块。

注:
如果不传递回调地址, 则默认是配置应用号时候使用的回调地址
示例值:https://capi.toa.com/callback
UnorderedBoolean合同流程的签署顺序类型:
  • false:(默认)有序签署, 本合同多个参与人需要依次签署
  • true:无序签署, 本合同多个参与人没有先后签署限制

: 有序签署时以传入FlowApprovers数组的顺序作为签署顺序
示例值:false
FlowTypeString合同流程的类别分类(可自定义名称,如销售合同/入职合同等),最大长度为255个字符,仅限中文、字母、数字和下划线组成。
示例值:入职合同
CustomShowMapString您可以自定义腾讯电子签小程序合同列表页展示的合同内容模板,模板中支持以下变量:
  • {合同名称}
  • {发起方企业}
  • {发起方姓名}
  • {签署方N企业}
  • {签署方N姓名}

其中,N表示签署方的编号,从1开始,不能超过签署人的数量。

例如,如果是腾讯公司张三发给李四名称为“租房合同”的合同,您可以将此字段设置为:合同名称:{合同名称};发起方: {发起方企业}({发起方姓名});签署方:{签署方1姓名},则小程序中列表页展示此合同为以下样子

合同名称:租房合同
发起方:腾讯公司(张三)
签署方:李四


示例值:合同名称:{合同名称} {发起方企业} {发起方姓名};国家:中国;发起方:{发起方企业};签署方1: {签署方1企业};签署
CustomerDataString调用方自定义的个性化字段(可自定义此名称),并以base64方式编码,支持的最大数据大小为 1000长度。

在合同状态变更的回调信息等场景中,该字段的信息将原封不动地透传给贵方。回调的相关说明可参考开发者中心的回调通知模块。
示例值:eyJpZCI6ImNvbWVmIiwibmFtZSI6IuWRseWRseWPqyJ9
NeedSignReviewBoolean发起方企业的签署人进行签署操作前,是否需要企业内部走审批流程,取值如下:
  • false:(默认)不需要审批,直接签署。
  • true:需要走审批流程。当到对应参与人签署时,会阻塞其签署操作,等待企业内部审批完成。

企业可以通过ChannelCreateFlowSignReview审批接口通知腾讯电子签平台企业内部审批结果
  • 如果企业通知腾讯电子签平台审核通过,签署方可继续签署动作。
  • 如果企业通知腾讯电子签平台审核未通过,平台将继续阻塞签署方的签署动作,直到企业通知平台审核通过。

注:此功能可用于与企业内部的审批流程进行关联,支持手动、静默签署合同
ApproverVerifyTypeString签署人校验方式
VerifyCheck: 人脸识别(默认)
MobileCheck:手机号验证,用户手机号和参与方手机号(ApproverMobile)相同即可查看合同内容(当手写签名方式为OCR_ESIGN时,该校验方式无效,因为这种签名方式依赖实名认证)
参数说明:可选人脸识别或手机号验证两种方式,若选择后者,未实名个人签署方在签署合同时,无需经过实名认证和意愿确认两次人脸识别,该能力仅适用于个人签署方。
SignBeanTagInteger签署方签署控件(印章/签名等)的生成方式:
  • 0:在合同流程发起时,由发起人指定签署方的签署控件的位置和数量。
  • 1:签署方在签署时自行添加签署控件,可以拖动位置和控制数量。

: 发起后添加控件功能不支持添加签批控件
示例值:0
CcInfos.NArray of CcInfo合同流程的抄送人列表,最多可支持50个抄送人,抄送人可查看合同内容及签署进度,但无需参与合同签署。
CcNotifyTypeInteger可以设置以下时间节点来给抄送人发送短信通知来查看合同内容:
  • 0:合同发起时通知(默认值)
  • 1:签署完成后通知
AutoSignSceneString个人自动签名的使用场景包括以下, 个人自动签署(即ApproverType设置成个人自动签署时)业务此值必传:
  • E_PRESCRIPTION_AUTO_SIGN:处方单(医疗自动签)

注: 个人自动签名场景是白名单功能,使用前请与对接的客户经理联系沟通。
示例值:E_PRESCRIPTION_AUTO_SIGN

3. 输出参数

参数名称类型描述
FlowIdString合同流程ID,为32位字符串。
建议开发者妥善保存此流程ID,以便于顺利进行后续操作。
注意:此字段可能返回 null,表示取不到有效值。
示例值:yDwFmUUckpstqfvzUE1h3jo1f3cqjkGm
ApproversArray of ApproverItem签署方信息,如角色ID、角色名称等
注意:此字段可能返回 null,表示取不到有效值。
RequestIdString唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 创建含有动态签署人流程,签署方不指定具体的签署人

创建一个B2C流程,两方签署方不指定具体的签署人 注: 1.签署人相关信息为空,如:姓名、手机号码等 2.FillType需传值为1,表示为动态签署人(不确定具体的签署人),需后续进行补充。 3.需保留对应的角色编号,即RecipientId,后续补充具体的签署人时需指定对应的RecipientId

输入示例

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

{
"Agent": {
"ProxyOperator": {
"OpenId": "zhangsan"
},
"ProxyOrganizationOpenId": "ess_open_organization_1",
"AppId": "yDwFoUUckps**********yhWGhIR2RkhOjw2"
},
"Unordered": true,
"FlowName": "发起动态签署人合同示例",
"FlowApprovers": [
{
"Name": "",
"Mobile": "",
"ApproverType": "PERSON",
"ApproverRoleName": "个人签署方",
"ApproverOption": {
"FillType": 1
},
"SignComponents": [
{
"ComponentPosY": 260,
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SIGNATURE",
"ComponentPage": 1,
"ComponentPosX": 260,
"ComponentHeight": 100
}
]
},
{
"ApproverType": "ORGANIZATION",
"ApproverRoleName": "企业签署方",
"ApproverOption": {
"FillType": 1
},
"SignComponents": [
{
"ComponentPosY": 260,
"ComponentWidth": 100,
"FileIndex": 0,
"ComponentType": "SIGN_SEAL",
"ComponentPage": 1,
"ComponentPosX": 260,
"ComponentHeight": 100
}
]
}
],
"FileIds": [
"yDwFhUUckpsxas68UuZf2EREDkOykmDp"
]
}

输出示例

{
"Response": {
"FlowId": "2fb48c3945****65aaedf6",
"Approvers": [
{
"SignId": "yDw7hUUckpkm57vuUxeFIKavjSsJtcaN",
"RecipientId": "yDw7hUUckpkm57v4UxeFIKaS5kF2iWh8",
"ApproverRoleName": "个人签署方"
},
{
"SignId": "yDw7hUUckpkm57v7UxeFIKa8kitjb9XB",
"RecipientId": "yDw7hUUckpkm57vxUxeFIKaCJX9krcZN",
"ApproverRoleName": "企业签署方"
}
],
"RequestId": "s1234345677xxxx"
}
}

示例2 使用文件创建B2B2C的合同

  1. 包含个人/自然人签署 张三
  2. 包含第三方子企业李四的示例企业员工李四
  3. 包含平台企业王五示例企业的员工王五 (NotChannelOrganization设置为true)
  4. 王五的签署区是通过关键字甲方签章位置生成印章区域

输入示例

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

{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"ProxyAppId": ""
},
"FlowName": "购买50吨西红柿的合同(15:53:35)",
"FlowApprovers": [
{
"Name": "张三",
"Mobile": "18888888888",
"ApproverType": "PERSON",
"SignComponents": [
{
"ComponentType": "SIGN_SIGNATURE",
"FileIndex": 0,
"ComponentWidth": 112,
"ComponentHeight": 40,
"ComponentPage": 1,
"ComponentPosX": 146.15625,
"ComponentPosY": 472.78125,
"ComponentValue": ""
}
]
},
{
"Name": "李四",
"Mobile": "17333333333",
"OrganizationName": "李四的示例企业",
"OpenId": "lisi",
"OrganizationOpenId": "org_lisi",
"ApproverType": "ORGANIZATION",
"SignComponents": [
{
"ComponentType": "SIGN_SEAL",
"FileIndex": 0,
"ComponentWidth": 112,
"ComponentHeight": 40,
"ComponentPage": 1,
"ComponentPosX": 146.15625,
"ComponentPosY": 472.78125,
"ComponentValue": ""
}
]
},
{
"Name": "王五",
"Mobile": "13333333333",
"OrganizationName": "王五示例企业",
"NotChannelOrganization": true,
"ApproverType": "ORGANIZATION",
"SignComponents": [
{
"ComponentType": "SIGN_SEAL",
"FileIndex": 0,
"ComponentWidth": 112,
"ComponentHeight": 40,
"ComponentPage": 1,
"ComponentPosX": 146.15625,
"ComponentPosY": 472.78125,
"ComponentValue": ""
},
{
"ComponentId": "甲方签章位置",
"ComponentType": "SIGN_SEAL",
"GenerateMode": "KEYWORD",
"ComponentWidth": 112,
"ComponentHeight": 40
}
]
}
],
"FileIds": [
"yDSLoUUckpob08ffUxVoXTnu6fPhgjmx"
],
"Unordered": true
}

输出示例

{
"Response": {
"FlowId": "yDSLoUUckpob829aUxvfkKfCKWvrOGyb",
"Approvers": [
{
"SignId": "yDSLoUUckpob829wUxvfkKfCOwpAOD9N",
"RecipientId": "yDSLoUUckpob829yUxvfkKfssEItYFKp",
"ApproverRoleName": ""
},
{
"SignId": "yDSLoUUckpob829tUxvfkKfuX06FFWEw",
"RecipientId": "yDSLoUUckpob829vUxvfkKf83OAYth3A",
"ApproverRoleName": ""
},
{
"SignId": "yDSLoUUckpob829kUxvfkKfuiREpXebq",
"RecipientId": "yDSLoUUckpob829oUxvfkKfwRMwMrwrM",
"ApproverRoleName": ""
}
],
"RequestId": "6545213e-4554-4839-a69d-6ef75344c749"
}
}

示例3 使用文件创建单自然人签署的合同

发起只有个人/自然人签署 张三来签署的合同

输入示例

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

{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "110101200610116558"
},
"ProxyAppId": ""
},
"FlowName": "西瓜采购协议(16:18:47)",
"FlowApprovers": [
{
"Name": "张三",
"Mobile": "18888888888",
"ApproverType": "PERSON",
"SignComponents": [
{
"ComponentType": "SIGN_SIGNATURE",
"FileIndex": 0,
"ComponentWidth": 112,
"ComponentHeight": 40,
"ComponentPage": 1,
"ComponentPosX": 146.15625,
"ComponentPosY": 472.78125,
"ComponentValue": ""
}
]
}
],
"FileIds": [
"yDSLoUUckpob089cUxVoXTn9T1cRb8W7"
],
"Unordered": true
}

输出示例

{
"Response": {
"FlowId": "yDSLoUUckpobjhymUyKMWsdBQKTeh0lS",
"Approvers": [
{
"SignId": "yDSLoUUckpobjhy9UyKMWsdSJ1PF1kag",
"RecipientId": "yDSLoUUckpobjhyfUyKMWsdxqy3zpae2",
"ApproverRoleName": ""
}
],
"RequestId": "c98e62a4-8577-4d78-87d6-16519fcd17e7"
}
}

5. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码描述
FailedOperation操作失败。
FailedOperation.AgeNotAchieveNormalLegal签署人未达到合法年龄。
InternalError内部错误。
InternalError.Db数据库错误。
InternalError.DbConnection数据库连接出错。
InternalError.Decryption解密错误。
InternalError.DependsDb数据库异常。
InternalError.Encryption加密错误。
InternalError.GenerateId生成唯一ID错误。
InternalError.PdfPdf合成错误。
InternalError.System系统错误。
InternalError.ThirdParty第三方错误。
InvalidParameter参数错误。
InvalidParameter.Application应用号不存在。
InvalidParameter.ApproverType参数错误,不合法的签署人类型,请修改后重试。
InvalidParameter.ApproverVerifyTypeApproverVerifyType参数值非法
InvalidParameter.BizApproverAlreadyExists重复添加签署人。
InvalidParameter.CardType证件类型错误。
InvalidParameter.ComponentValue参数错误,控件内容无效。
InvalidParameter.CustomShowMap参数错误,无效的自定义页卡模板,仅支持{合同名称}{发起方姓名}{发起方企业}{签署方N姓名}{签署方N企业},请修改后重试。
InvalidParameter.CustomerData参数错误,UserData长度非法,请修改后重试。
InvalidParameter.DataNotFound数据不存在。
InvalidParameter.FlowApproverInfos参数错误,不合法的备选签署人数量,请检查后重试。
InvalidParameter.FlowApprovers参数错误,参与者数量不能为空且不能超过数量限制,请修改后重试。
InvalidParameter.FlowCallbackUrl参数错误,不合法的签署流程回调链接,请修改后重试。
InvalidParameter.FlowDeadLine参数错误,不合法的签署流程截止日期,请修改后重试。
InvalidParameter.FlowDescription参数错误,不合法的签署流程描述,请修改后重试。
InvalidParameter.FlowFileIds参数错误,目前仅支持单个文件发起,请修改后重试。
InvalidParameter.FlowName参数错误,不合法的签署流程名称,请修改后重试。
InvalidParameter.FlowType参数错误,不合法的FlowType,请修改后重试。
InvalidParameter.Mobile手机号码不正确。
InvalidParameter.Name姓名不符合要求。
InvalidParameter.NonsupportMobile不支持的手机号。
InvalidParameter.OrganizationName企业名称不合法。
InvalidParameter.ParamError参数错误。
InvalidParameter.SignComponentType参数错误,不合法的签署控件类型,请修改后重试。
InvalidParameter.SignComponents类型不支持。
InvalidParameter.Unordered参数错误,不合法的签署顺序,请检查后重试。
InvalidParameter.UnsupportedComponentType参数错误,不支持的控件类型,请检查后重试。
InvalidParameterValue参数取值错误。
LimitExceeded超过配额限制。
MissingParameter缺少参数错误。
MissingParameter.MissComponentName缺少控件名称参数,请检查后重试。
MissingParameter.SealId印章ID为空。
MissingParameter.SignComponents签署人缺少签署控件。
OperationDenied操作被拒绝。
OperationDenied.ByFilesServerSignForbid文件发起静默签未开通白名单。
OperationDenied.ErrNoResourceAccess无资源访问权限。
OperationDenied.InvalidApproverAge签署人未达到合法年龄。
OperationDenied.NoApproverMobileCheckPermission企业暂未开通手机号验证身份的服务,请在企业中心开通再使用
OperationDenied.NoIdentityVerify未通过个人实名。
OperationDenied.NoQuota流程配额不足。
OperationDenied.OverseaAbilityNotOpen当前企业员工没有开通境外签署能力。
OperationDenied.PersonNoOpenServerSign该用户已关闭或者未开启自动签服务
OperationDenied.RequiredComponentNotFill必填控件未填
OperationDenied.UserNotInOrganization用户不归属于当前企业,无法操作,请检查后重试。
ResourceNotFound资源不存在。
ResourceNotFound.Application应用号不存在。
ResourceNotFound.Resource资源不存在。
ResourceNotFound.Seal印章不存在,请检查后重试。
ResourceNotFound.User用户信息不存在。
ResourceUnavailable资源不可用。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。