8-2. 账单下载

接口名称

下载文件

接口地址

/api/shipper/v1/file/download

请求方式

POST

请求头

参数	类型	必填	说明
sessionId	String	是	登录会话ID
language	String	是	语言
Content-Type	String	是	application/json;charset=UTF-8
Accept	String	是	application/json, text/plain, /

语言取值：

值	说明
zh_CN	中文
en_US	英文

请求参数

参数位置	字段	类型	必填	说明
Query String	fileKey	String	是	文件Key（需要URL编码）

fileKey 参数说明

fileKey 是文件的唯一标识，通常由系统生成。

值	说明
查询账单列表返回的fileId	账单文件

请求示例

curl 'https://tracking-qa.etowertech.com/api/shipper/v1/file/download?fileKey=bill%2F079842f3-d5d3-4f09-9f96-81c34c9b2fa4.xlsx' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'language: zh_CN' \
  -H 'sessionId: 0HgJ-EO-Sq_ZQ6u93rjMnA' \
  --data-raw '{}'

返回示例

成功时返回文件流（Excel文件）

响应头:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename=UBI_billing_100_UBI%20Smart%20Parcel_2025-12-29_CNY.xlsx
Access-Control-Expose-Headers: Content-Disposition

浏览器会自动下载文件，文件名格式为：`

Unknown macro: {服务商}

billing

Unknown macro: {客户ID}

_

Unknown macro: {客户名称}

_

Unknown macro: {日期}

_

Unknown macro: {币种}

.xlsx`

实际下载的文件名会被 URL 解码，例如：

UBI_billing_100_UBI Smart Parcel_2025-12-29_CNY.xlsx

失败时返回JSON:

{
  "success": false,
  "code": "400",
  "errors": [
    {
      "message": "文件不存在或已删除"
    }
  ]
}

返回字段说明

成功时直接返回文件流，浏览器会触发下载文件。

响应头说明：

字段	说明
Content-Type	application/octet-stream（二进制文件流）
Content-Disposition	attachment; filename=xxx.xlsx（指定下载文件名）
Access-Control-Expose-Headers	Content-Disposition（允许前端访问文件名）

失败时返回错误信息：

字段	类型	说明
success	Boolean	请求是否成功
code	String	错误状态码
errors	Array	错误信息列表

页面树结构