## 接口说明

接口名称：`alipay.data.dataservice.bill.downloadurl.query`

为方便商户快速查账，支付宝支持商户通过本接口获取商户离线账单下载地址。

## 公共请求参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` |
| `method` | String | 必选 | 128 | 接口名称 | `alipay.data.dataservice.bill.downloadurl.query` |
| `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` |
| `charset` | String | 必选 | 10 | 请求使用的编码格式，如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` |
| `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型，目前支持 `RSA2` 和 `RSA`，推荐使用 `RSA2` | `RSA2` |
| `sign` | String | 必选 | 344 | 商户请求参数的签名串，详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 |
| `timestamp` | String | 必选 | 19 | 发送请求的时间，格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` |
| `version` | String | 必选 | 3 | 调用的接口版本，固定为 `1.0` | `1.0` |
| `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - |
| `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外，所有请求参数都必须放在该参数中传递，具体参照各产品快速接入文档 | - |

## 业务请求参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- |
| `bill_type` | string | 必选 | 20 | 账单类型，商户通过接口，或商户经开放平台授权后其所属服务商通过接口，可以获取对应账单类型 | `trade`：商户基于支付宝交易收单的业务账单<br>`signcustomer`：基于商户支付宝余额收入及支出等资金变动的账务账单<br>`merchant_act`：营销活动账单，包含营销活动的发放、核销记录<br>`trade_zft_merchant`：直付通二级商户查询交易的业务账单<br>`zft_acc`：直付通平台商查询二级商户流水使用，返回所有二级商户流水<br>`settlementMerge`：每日结算到卡的资金对应明细，下载内容包含批次结算到卡明细文件和批次结算到卡汇总文件；若查询时间范围内有多个批次，会将多个批次的明细和汇总文件打包到一份压缩包中 | `trade` |
| `bill_date` | string | 必选 | 15 | 账单时间 | 日账单格式为 `yyyy-MM-dd`，最早可下载近 6 年的日账单；不支持下载当日账单，只能下载前一日 24 点前的账单数据（T+1），当日数据一般于次日 9 点前生成，特殊情况可能延迟<br>月账单格式为 `yyyy-MM`，最早可下载近 6 年的月账单；不支持下载当月账单，只能下载上一月账单数据，当月账单一般在次月 3 日生成，特殊情况可能延迟<br>当 `biz_type` 为 `settlementMerge` 时，时间为汇总批次结算资金到账日期，格式为 `yyyy-MM-dd`，最早可下载 2023 年 4 月 17 日及以后的账单<br>接口调用仅支持下载近 6 年的账单，更多账单请前往 `b.alipay.com` 对账中心-账单下载页下载 | `2025-05-01` |
| `smid` | string | 可选 | 20 | 二级商户 `smid` | 仅在 `bill_type` 为 `trade_zft_merchant` 时可使用 | `2088123412341234` |

## 请求示例

### cURL

```bash
curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.data.dataservice.bill.downloadurl.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2&timestamp=${now}' \
  -F 'app_auth_token=${app_auth_token}' \
  -F 'biz_content={
    "bill_type":"trade",
    "bill_date":"2025-05-01",
    "smid":"2088123412341234"
  }'
```

## 公共响应参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 |
| --- | --- | --- | --- | --- | --- |
| `code` | String | 必选 | - | 网关返回码，详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` |
| `msg` | String | 必选 | - | 网关返回码描述，详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` |
| `sub_code` | String | 可选 | - | 业务返回码，参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` |
| `sub_msg` | String | 可选 | - | 业务返回码描述，参见具体 API 接口文档 | `交易已被支付` |
| `sign` | String | 必选 | - | 签名，详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=` |

## 业务响应参数

| 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 |
| --- | --- | --- | --- | --- | --- | --- |
| `bill_download_url` | string | 可选 | 2048 | 当账单可获取时，返回账单下载地址链接 | 获取链接后 30 秒内未下载，链接地址失效 | `http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X` |
| `bill_file_code` | string | 可选 | 64 | 账单文件结果说明，描述本次申请的账单文件状态 | `EMPTY_DATA_WITH_BILL_FILE`：当前周期无数据时产生的空账单数据文件。目前仅对默认配置用户生效，主动配置的不会返回当前字段 | `EMPTY_DATA_WITH_BILL_FILE` |

## 响应示例

::::aipay-tabs{defaultActiveKey="正常示例"}
:::aipay-tab{key="正常示例" title="正常示例"}
```json
{
  "alipay_data_dataservice_bill_downloadurl_query_response": {
    "code": "10000",
    "msg": "Success",
    "bill_download_url": "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X",
    "bill_file_code": "EMPTY_DATA_WITH_BILL_FILE"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```
:::

:::aipay-tab{key="异常示例" title="异常示例"}
```json
{
  "alipay_data_dataservice_bill_downloadurl_query_response": {
    "code": "20000",
    "msg": "Service Currently Unavailable",
    "sub_code": "isp.unknow-error",
    "sub_msg": "系统繁忙"
  },
  "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
```
:::

::::

## 公共错误码

[前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f)

## 业务错误码

| 错误码 | 错误描述 | 解决方案 |
| --- | --- | --- |
| `BILL_DATE_BEFORE_REGISTRATION` | 请求的账单时间早于注册时间 | 确认参数后重新查询 |
| `BILL_NOT_EXIST` | 账单不存在 | 确认参数后重新查询 |
| `INVAILID_ARGUMENTS` | 入参不合法 | 确认参数后重新查询 |
| `NO_BILL_DATA` | 商户在请求的账单时间内没有发生当前账单类型的业务 | 确认参数后重新查询 |
| `SYSTEM_RATE_LIMIT` | 系统当前负载较高，请求被限流，请稍后重试 | 间隔 1 分钟后重试 |
| `TYPE_NOT_SUPPORTED` | 此账单类型不支持下载 | 根据不同 `bill_type` 确定解决方案：<br>`trade`：需签约支付宝支付产品，且有对应产品产生的实际流水，支付产品范围详见[支付宝产品大全](https://b.alipay.com/page/product-mall/all-product?mrchportalwebServer=https%3A%2F%2Fmrchportalweb.alipay.com#J_wysk)<br>`signcustomer`：非支付宝商家身份，建议先签约收钱码或经营码产品<br>`merchant_act`：一年内无营销动作，具体请参考[营销账单使用](https://ideservice.alipay.com/cms/site/03ae7i?pathHash=83ffda2d)<br>`trade_zft_merchant`：请联系直付通平台商提供对应账单数据<br>`zft_acc`：请先签约[互联网平台直付通](https://b.alipay.com/page/product-mall/solution-detail?solutionCode=SP000001000000007155&sceneCode=PAYMENT)产品<br>`settlementMerge`：请先签约[收款到银行账户](https://b.alipay.com/page/product-mall/product-detail/I1080300001000041457/ALL?)产品<br>其他：该账单类型不支持下载操作，请再次确认账单类型及所选日期。如有需求，请联系支付宝小二排查 |
| `UNKNOWN_ERROR` | 未知错误 | 稍后重试或联系小二排查问题 |
| `USER_RATE_LIMIT` | 调用频率超限 | 间隔 1 分钟后重试，查看[调用频率限制](https://ideservice.alipay.com/cms/site/01inen?pathHash=4fae1c5e)中新增的 2.4 请求频次 |