跳到主要内容

用PDF文件创建签署流程

1. 接口描述​

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

此接口（CreateFlowByFiles）用来通过上传后的pdf资源编号来创建待签署的合同流程。
适用场景1：适用非制式的合同文件签署。一般开发者自己有完整的签署文件，可以通过该接口传入完整的PDF文件及流程信息生成待签署的合同流程。
适用场景2：可通过该接口传入制式合同文件，同时在指定位置添加签署控件。可以起到接口创建临时模板的效果。如果是标准的制式文件，建议使用模板功能生成模板ID进行合同流程的生成。
注意事项：该接口需要依赖“多文件上传”接口生成pdf资源编号（FileIds）进行使用。

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

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

2. 输入参数​

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

参数名称必选类型描述
Action是String公共参数，本接口取值：CreateFlowByFiles。
Version是String公共参数，本接口取值：2020-11-11。
Region否String公共参数，本接口不需要传递此参数。
Operator是UserInfo调用方用户信息，userId 必填。支持填入集团子公司经办人 userId 代发合同
FlowName是String签署流程名称,最大长度200个字符
Approvers.N是Array of ApproverInfo签署参与者信息，最大限制50方
FileIds.N是Array of String签署pdf文件的资源编号列表，通过UploadFiles接口获取，暂时仅支持单文件发起
FlowType否String签署流程的类型(如销售合同/入职合同等)，最大长度200个字符
Components.N否Array of Component经办人内容控件配置
CcInfos.N否Array of CcInfo被抄送人的信息列表。
注:此功能为白名单功能，若有需要，请联系电子签客服开白使用
NeedPreview否Boolean是否需要预览，true：预览模式，false：非预览（默认）；
预览链接有效期300秒；

注：如果使用“预览模式”，出参会返回合同预览链接 PreviewUrl，不会正式发起合同，且出参不会返回签署流程编号 FlowId；如果使用“非预览”，则会正常返回签署流程编号 FlowId，不会生成合同预览链接 PreviewUrl。
PreviewType否Integer预览链接类型 默认:0-文件流, 1- H5链接 注意:此参数在NeedPreview 为true 时有效,
Deadline否Integer签署流程的签署截止时间。
值为unix时间戳,精确到秒,不传默认为当前时间一年后
Unordered否Boolean发送类型：
true：无序签
false：有序签
注：默认为false（有序签）
CustomShowMap否String合同显示的页卡模板，说明：只支持{合同名称}, {发起方企业}, {发起方姓名}, {签署方N企业}, {签署方N姓名}，且N不能超过签署人的数量，N从1开始
NeedSignReview否Boolean发起方企业的签署人进行签署操作是否需要企业内部审批。使用此功能需要发起方企业有参与签署。
若设置为true，审核结果需通过接口 CreateFlowSignReview 通知电子签，审核通过后，发起方企业签署人方可进行签署操作，否则会阻塞其签署操作。

注：企业可以通过此功能与企业内部的审批流程进行关联，支持手动、静默签署合同。
UserData否String用户自定义字段，回调的时候会进行透传，长度需要小于20480
ApproverVerifyType否String签署人校验方式
VerifyCheck: 人脸识别（默认）
MobileCheck：手机号验证
参数说明：可选人脸识别或手机号验证两种方式，若选择后者，未实名个人签署方在签署合同时，无需经过实名认证和意愿确认两次人脸识别，该能力仅适用于个人签署方。
FlowDescription否String签署流程描述,最大长度1000个字符
SignBeanTag否Integer标识是否允许发起后添加控件。0为不允许1为允许。如果为1，创建的时候不能有签署控件，只能创建后添加。注意发起后添加控件功能不支持添加骑缝章和签批控件
Agent否Agent代理相关应用信息，如集团主企业代子企业操作的场景中ProxyOrganizationId必填
CcNotifyType否Integer给关注人发送短信通知的类型，0-合同发起时通知 1-签署完成后通知
AutoSignScene否String个人自动签场景。发起自动签署时，需设置对应自动签署场景，目前仅支持场景：处方单-E_PRESCRIPTION_AUTO_SIGN

3. 输出参数​

参数名称类型描述
FlowIdString签署流程编号。

注：如入参 是否需要预览 NeedPreview 设置为 true，不会正式发起合同，此处不会有值返回；如入参 是否需要预览 NeedPreview 设置为 false，此处会正常返回签署流程编号 FlowId。
PreviewUrlString合同预览链接。

注：如入参 是否需要预览 NeedPreview 设置为 true，会开启“预览模式”，此处会返回预览链接；如入参 是否需要预览 NeedPreview 设置为 false，此处不会有值返回。
注意：此字段可能返回 null，表示取不到有效值。
RequestIdString唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 示例​

示例1 创建签署流程​

通过文件发起单C流程，有文本控件、签署控件

输入示例​

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

{
    "Operator": {
        "UserId": "19561039******de6a"
    },
    "FlowName": "合同名称",
    "NeedPreview": false,
    "FlowDescription": "测试签署流程的描述信息",
    "Unordered": false,
    "FlowType": "劳动合同",
    "Deadline": 1604912664,
    "ApproverVerifyType": "VerifyCheck",
    "CustomShowMap": "合同名称:{合同名称} {发起方企业} {发起方姓名};国家:中国;发起方:{发起方企业};签署方1:  {签署方1企业};签署方2:  {签署方2企业}{签署方2姓名};签署方3:  {签署方3姓名}",
    "Approvers": [
        {
            "ApproverType": 0,
            "OrganizationName": "xxx有限公司",
            "ApproverName": "张三",
            "ApproverMobile": "15912345678",
            "SignComponents": [
                {
                    "ComponentValue": "SealId",
                    "ComponentPosY": 100,
                    "ComponentWidth": 100,
                    "FileIndex": 0,
                    "ComponentType": "SIGN_SEAL",
                    "ComponentPage": 1,
                    "ComponentPosX": 100,
                    "ComponentHeight": 100
                },
                {
                    "ComponentValue": "",
                    "ComponentPosY": 120,
                    "ComponentWidth": 120,
                    "FileIndex": 0,
                    "ComponentType": "SIGN_DATE",
                    "ComponentPage": 1,
                    "ComponentPosX": 120,
                    "ComponentHeight": 120
                }
            ]
        },
        {
            "ApproverType": 1,
            "ApproverName": "李四",
            "ApproverMobile": "185111111111",
            "SignComponents": [
                {
                    "ComponentValue": "",
                    "ComponentPosY": 100,
                    "ComponentWidth": 100,
                    "FileIndex": 0,
                    "ComponentType": "SIGN_SIGNATURE",
                    "ComponentPage": 1,
                    "ComponentPosX": 100,
                    "ComponentHeight": 100
                },
                {
                    "ComponentValue": "",
                    "ComponentPosY": 120,
                    "ComponentWidth": 120,
                    "FileIndex": 0,
                    "ComponentType": "SIGN_DATE",
                    "ComponentPage": 1,
                    "ComponentPosX": 120,
                    "ComponentHeight": 120
                }
            ]
        }
    ],
    "FileIds": [
        "61a82f0*******c2d0d807"
    ],
    "Components": [
        {
            "ComponentValue": "自定义单行文本内容",
            "ComponentPosY": 100,
            "ComponentWidth": 100,
            "FileIndex": 0,
            "ComponentType": "TEXT",
            "ComponentPage": 1,
            "ComponentPosX": 100,
            "ComponentHeight": 100,
            "ComponentExtra": "{\"FontSize\":20}"
        },
        {
            "ComponentValue": "自定义多行文本内容",
            "ComponentPosY": 100,
            "ComponentWidth": 100,
            "FileIndex": 0,
            "ComponentType": "MULTI_LINE_TEXT",
            "ComponentPage": 1,
            "ComponentPosX": 100,
            "ComponentHeight": 100,
            "ComponentExtra": "{\"FontSize\":20}"
        }
    ]
}

输出示例​

{
    "Response": {
        "FlowId": "61a82f0c********0d807",
        "PreviewUrl": "",
        "RequestId": "requestId-xxx"
    }
}

示例2 创建简单的签署流程​

通过文件发起单C流程，只有一个签署区域

输入示例​

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

{
    "UserData": "字符串",
    "FlowName": "字符串",
    "FlowDescription": "字符串",
    "NeedPreview": "false",
    "FlowType": "字符串",
    "Approvers": [
        {
            "ApproverMobile": "15912345678",
            "SignComponents": [
                {
                    "ComponentWidth": 50,
                    "FileIndex": 0,
                    "ComponentName": "字符串",
                    "OffsetX": 11,
                    "OffsetY": 11,
                    "ComponentType": "SIGN_SIGNATURE",
                    "ComponentPage": 1,
                    "ComponentPosX": 50,
                    "ComponentPosY": 50,
                    "ComponentId": "字符串",
                    "ComponentHeight": 50
                }
            ],
            "ApproverName": "张三",
            "ApproverType": 1,
            "NotifyType": "NONE"
        }
    ],
    "Operator": {
        "UserId": "yDRtRUUgygqa2mtyUuO4zjEyckqC592v"
    },
    "FileIds": [
        "yDRI5UUgygsupv5oUuO4zjEESmE4Ip0s"
    ]
}

输出示例​

{
    "Response": {
        "FlowId": "yDRsDUUgyg1aczxtUuNAW8Cx4WsAiEB5",
        "PreviewUrl": "",
        "RequestId": "43b9474a-c909-4d89-aa7b-3632f02fa8a4"
    }
}

5. 开发者资源​

腾讯云 API 平台​

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

API Inspector​

用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。

SDK​

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

命令行工具​

6. 错误码​

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

错误码描述
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操作不支持。