查询文件下载URL
1. 接口描述
接口请求域名: ess.tencentcloudapi.com 。
本接口(DescribeFileUrls)用于查询文件的下载URL。 适用场景:通过传参合同流程编号,下载对应的合同PDF文件流到本地。
2. 确保合同的PDF已经合成后,再调用本接口。
用户创建合同或者提交签署动作后,后台需要1~3秒的时间就进行合同PDF合成或者签名,为了确保您下载的是签署完成的完整合同文件,我们建议采取下面两种方式的一种来确保PDF已经合成完成,然后在调用本接口。
第一种:请确保您的系统配置了接收合同完成通知的回调功能。一旦所有参与方签署完毕,我们的系统将自动向您提供的回调地址发送完成通知。
第二种:通过调用我们的获取合同信息接口来主动检查合同的签署状态。请仅在确认合同状态为“签署完成”后,进行文件的下载操作。
3. 链接具有有效期限
生成的链接是有时间限制的,过期后将无法访问。您可以在接口返回的信息中查看具体的过期时间。为避免错误,请确保在链接过期之前进行下载操作。默认接口请求频率限制:50次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:DescribeFileUrls。 |
Version | 是 | String | 公共参数,本接口取值:2020-11-11。 |
Region | 否 | String | 公共参数,此参数为可选参数。 |
Operator | 是 | UserInfo | 执行本接口操作的员工信息。 注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。 |
BusinessType | 是 | String | 文件对应的业务类型,目前支持:
示例值:DOCUMENT |
BusinessIds.N | 是 | Array of String | 业务编号的数组,取值如下:
示例值:["yDRSRUUgygj6rq7wUuO4zjECxndqQApl","yDwFkUUckpstzjhfUugNAWf1KibXqS26"] |
FileName | 否 | String | 下载后的文件命名,只有FileType为zip的时候生效 示例值:张三的入职合同 |
FileType | 否 | String | 要下载的文件类型,取值如下:
示例值:PDF |
Offset | 否 | Integer | 指定分页返回第几页的数据,如果不传默认返回第一页,页码从 0 开始,即首页为 0,最大 1000。 示例值:0 |
Limit | 否 | Integer | 指定分页每页返回的数据条数,如果不传默认为 20,单页最大支持 100。 示例值:0 |
UrlTtl | 否 | Integer | 下载url过期时间,单位秒。0: 按默认值5分钟,允许范围:1s~24x60x60s(1天) 示例值:0 |
Agent | 否 | Agent | 代理企业和员工的信息。 在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
FileUrls | Array of FileUrl | 文件URL信息; 链接不是永久链接, 过期时间受UrlTtl入参的影响, 默认有效期5分钟后, 到期后链接失效。 |
TotalCount | Integer | URL数量 示例值:4 |
RequestId | String | 唯一请求 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 | 未知参数错误。 |