跳到主要内容

查询文件下载URL

1. 接口描述​

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

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

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

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

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

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

3. 链接具有有效期限​

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

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

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

2. 输入参数​

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

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

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


示例值：DOCUMENT
BusinessIds.N是Array of String业务编号的数组，取值如下：

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


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

  • JPG
  • PDF
  • ZIP


示例值：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. 输出参数​

参数名称类型描述
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