跳到主要内容

查询文件下载URL

1. 接口描述

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

本接口(DescribeFileUrls)用于查询文件的下载URL。 适用场景:通过传参合同流程编号,下载对应的合同PDF文件流到本地。

2. 确保合同的PDF已经合成后,再调用本接口。

用户创建合同或者提交签署动作后,后台需要1~3秒的时间就进行合同PDF合成或者签名,为了确保您下载的是签署完成的完整合同文件,我们建议采取下面两种方式的一种来确保PDF已经合成完成,然后在调用本接口

第一种:请确保您的系统配置了接收合同完成通知的回调功能。一旦所有参与方签署完毕,我们的系统将自动向您提供的回调地址发送完成通知。

第二种:通过调用我们的获取合同信息接口来主动检查合同的签署状态。请仅在确认合同状态为“签署完成”后,进行文件的下载操作。

3. 链接具有有效期限

生成的链接是有时间限制的,过期后将无法访问。您可以在接口返回的信息中查看具体的过期时间。为避免错误,请确保在链接过期之前进行下载操作。

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

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

2. 输入参数

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

参数名称必选类型描述
ActionString公共参数,本接口取值:DescribeFileUrls。
VersionString公共参数,本接口取值:2020-11-11。
RegionString公共参数,此参数为可选参数。
OperatorUserInfo执行本接口操作的员工信息。
注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。
BusinessTypeString文件对应的业务类型,目前支持:

  • FLOW : 如需下载合同文件请选择此项
  • TEMPLATE : 如需下载模板文件请选择此项
  • DOCUMENT : 如需下载文档文件请选择此项
  • SEAL : 如需下载印章图片请选择此项


示例值:DOCUMENT
BusinessIds.NArray of String业务编号的数组,取值如下:

  • 流程编号
  • 模板编号
  • 文档编号
  • 印章编号
  • 如需下载合同文件请传入FlowId,最大支持20个资源


示例值:["yDRSRUUgygj6rq7wUuO4zjECxndqQApl","yDwFkUUckpstzjhfUugNAWf1KibXqS26"]
FileNameString下载后的文件命名,只有FileType为zip的时候生效
示例值:张三的入职合同
FileTypeString要下载的文件类型,取值如下:

  • JPG
  • PDF
  • ZIP


示例值:PDF
OffsetInteger指定分页返回第几页的数据,如果不传默认返回第一页,页码从 0 开始,即首页为 0,最大 1000。
示例值:0
LimitInteger指定分页每页返回的数据条数,如果不传默认为 20,单页最大支持 100。
示例值:0
UrlTtlInteger下载url过期时间,单位秒。0: 按默认值5分钟,允许范围:1s~24x60x60s(1天)
示例值:0
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。

3. 输出参数

参数名称类型描述
FileUrlsArray of FileUrl文件URL信息;
链接不是永久链接, 过期时间受UrlTtl入参的影响, 默认有效期5分钟后, 到期后链接失效。
TotalCountIntegerURL数量
示例值:4
RequestIdString唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 查询的文件没有权限

输入示例

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

{
"Operator": {
"UserId": "yDxM6UyK********QDV8dJUuO4zjEu"
},
"FileType": "PDF",
"BusinessType": "FLOW",
"FileName": "合同",
"Limit": 0,
"Offset": 0,
"BusinessIds": [
"11114444",
"11114444555",
"12315215515",
"12415251512"
]
}

输出示例

{
"Response": {
"Error": {
"Code": "ResourceNotFound",
"Message": "资源不存在或无权限"
},
"RequestId": "s166*******3046"
}
}

示例2 获取下载文件链接 --- 单个合同

下载单个合同文件

输入示例

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

{
"Operator": {
"UserId": "yDRSRUUgygj6qnwfUuO4zjEwc193c2hH"
},
"BusinessType": "FLOW",
"BusinessIds": [
"yDwFkUUckpstzjhfUugNAWf1KibXqS26"
]
}

输出示例

{
"Response": {
"FileUrls": [
{
"Option": "[\"595.00,841.00\",\"-1\"]",
"Url": "https://file.test.ess.tencent.cn/file/FLOW/yDR0dUxxxxxxxxWe1SbE7r/0/0.PDF?hkey=c80b3f1357821exxxxxxxxxxx2ad82345c777"
}
],
"RequestId": "1e1da50xxxxxx5d570ab151c9",
"TotalCount": 1
}
}

示例3 获取下载文件链接 --- 多个文件

下载多个合同文件

输入示例

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

{
"Operator": {
"UserId": "yDxM6UyK********QDV8dJUuO4zjEu"
},
"FileType": "PDF",
"BusinessType": "DOCUMENT",
"FileName": "合同",
"Limit": 0,
"Offset": 0,
"BusinessIds": [
"11114444",
"11114444555",
"12315215515",
"12415251512"
]
}

输出示例

{
"Response": {
"FileUrls": [
{
"Url": "https://file.ess.myqcloud.com/file/xxxx.PDF?key=abc",
"Option": ""
},
{
"Url": "https://file.ess.myqcloud.com/file/DOCUMENT/xxxx.PDF?key=abc",
"Option": ""
},
{
"Url": "https://file.ess.myqcloud.com/file/DOCUMENT/xxx.PDF?key=abc",
"Option": ""
},
{
"Url": "https://file.ess.myqcloud.com/file/DOCUMENT/xxx.PDF?key=abc",
"Option": ""
}
],
"TotalCount": 4,
"RequestId": "XXXX"
}
}

示例4 获取下载文件链接 --- 压缩多文件

下载文件压缩包

输入示例

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

{
"Operator": {
"UserId": "f2d8********f56b7"
},
"FileType": "ZIP",
"BusinessType": "DOCUMENT",
"FileName": "合同",
"Limit": 0,
"Offset": 0,
"BusinessIds": [
"e1a5****dfabfdbec6",
"670d****590d4dcd",
"dc3df****07f8323"
]
}

输出示例

{
"Response": {
"FileUrls": [
{
"Url": "https://file.ess.myqcloud.com/files/DOCUMENT/xxxx.ZIP?key=key********1234",
"Option": ""
}
],
"TotalCount": 1,
"RequestId": "XXXX"
}
}

5. 错误码

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

错误码描述
FailedOperation操作失败。
InternalError内部错误。
InternalError.Db数据库异常。
InternalError.DbRead内部错误,数据库查询失败,请稍后重试。
InternalError.DependsApi依赖的第三方API返回错误。
InternalError.System系统错误,请稍后重试。
InvalidParameter参数错误。
InvalidParameter.BusinessId不合法的业务id,请检查是否传递,检查是否超过接口上限数量,并在修改后重试。
InvalidParameter.BusinessType不合法的业务类型,请检查后重试。
InvalidParameter.ParamError参数错误。
MissingParameter缺少参数错误。
OperationDenied操作被拒绝。
OperationDenied.ErrNoResourceAccess此企业无该资源使用权限。
OperationDenied.FileDeleted文件已被删除,请联系客服处理。
OperationDenied.Forbid禁止此项操作。
OperationDenied.NoIdentityVerify未通过个人实名认证。
OperationDenied.NoLogin用户未登录,请先登录后再操作。
OperationDenied.OrganizationNotActivated企业未激活。
ResourceNotFound资源不存在。
ResourceNotFound.Application应用号不存在或已删除。
ResourceNotFound.NotExistDocument电子文档不存在。
ResourceNotFound.Resource未获取到文件资源,请检查资源是否完成上传,是否有效,并在修改后重试。
ResourceUnavailable资源不可用。
UnauthorizedOperation未授权操作。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。
UnknownParameter未知参数错误。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062