账单下载API应添加哪项能力，适用于个人还是企业应用？

2026-10-24支付小周

明确结论

接口 alipay.data.dataservice.bill.downloadurl.query 是支付宝开放平台的“查询对账单下载地址”接口。在控制台中，一般归入账单下载、对账或账务管理等相关能力。

该接口主要供已经签约支付宝支付产品的商家使用，通常需要创建企业应用。个人应用一般无法签约完整的商家支付和对账能力，不适合作为该接口的接入主体。

支付宝开放平台可能调整控制台中的能力名称和入口。如果页面上找不到“查询对账单下载地址”，请查看接口详情页列出的“所属产品”或“获取权限”入口，不要仅根据相近名称添加能力。

为什么需要企业应用

该接口用于获取商家交易账单或业务账单的下载地址。账单与商户签约账号、支付产品及实际交易数据绑定。

调用该接口通常需要满足以下条件：

应用属于已完成认证的支付宝商家账号。
应用已经签约并上线对应的支付产品，例如电脑网站支付、手机网站支付、APP 支付或当面付。
应用拥有账单下载或对账相关接口权限。
调用时使用该应用对应的 app_id、应用私钥和支付宝公钥。
查询的账单属于当前签约商户，不能跨商户下载。

创建应用并配置密钥后，并不会自动获得账单下载权限。应用主体、支付产品签约状态和接口权限都必须符合要求。

添加能力的步骤

登录支付宝开放平台，进入对应应用。
确认应用主体为企业或商家，并已完成支付宝认证。
进入“能力管理”“产品绑定”或名称相近的入口。
搜索以下关键词：
- alipay.data.dataservice.bill.downloadurl.query
- 查询对账单下载地址
- 账单下载
- 对账
按照接口详情页的提示，添加该接口所属的支付产品或账务能力。
如果页面提示需要签约，请先完成产品签约，再等待能力生效。
在应用详情或接口权限列表中确认该接口已经可以调用。

如果控制台只显示支付产品，没有单独列出“账单下载”能力，通常表示该接口权限会随支付产品签约开通。具体权限仍以当前应用控制台中的说明为准。

Java 调用示例

以下示例使用支付宝 Java SDK 查询交易账单下载地址：

import com.alipay.api.AlipayClient;
import com.alipay.api.DefaultAlipayClient;
import com.alipay.api.domain.AlipayDataDataserviceBillDownloadurlQueryModel;
import com.alipay.api.request.AlipayDataDataserviceBillDownloadurlQueryRequest;
import com.alipay.api.response.AlipayDataDataserviceBillDownloadurlQueryResponse;

public class AlipayBillDownloadExample {

    public static void main(String[] args) throws Exception {
        AlipayClient alipayClient = new DefaultAlipayClient(
            "https://openapi.alipay.com/gateway.do",
            "YOUR_APP_ID",
            "YOUR_APP_PRIVATE_KEY",
            "json",
            "UTF-8",
            "ALIPAY_PUBLIC_KEY",
            "RSA2"
        );

        AlipayDataDataserviceBillDownloadurlQueryModel model =
            new AlipayDataDataserviceBillDownloadurlQueryModel();

        model.setBillType("trade");
        model.setBillDate("2026-09-12");

        AlipayDataDataserviceBillDownloadurlQueryRequest request =
            new AlipayDataDataserviceBillDownloadurlQueryRequest();

        request.setBizModel(model);

        AlipayDataDataserviceBillDownloadurlQueryResponse response =
            alipayClient.execute(request);

        if (response.isSuccess()) {
            String downloadUrl = response.getBillDownloadUrl();
            System.out.println("账单下载地址：" + downloadUrl);
        } else {
            System.err.println("调用失败："
                + response.getCode() + " / "
                + response.getSubCode() + " / "
                + response.getSubMsg());
        }
    }
}

参数和返回值说明：

bill_type 是账单类型，常用值包括 trade。其他可用值以当前接口文档为准。
bill_date 是账单日期。可查询的日期格式和时间范围由账单类型及平台规则决定。
返回的 bill_download_url 是临时下载地址。获取地址后应尽快下载，不要将其作为永久文件地址保存。

常见权限问题

如果调用时出现“无权限”“产品未签约”或类似错误，可按以下顺序检查：

当前 app_id 是否属于已认证的商家主体。
应用是否已经签约并上线对应的支付产品。
接口权限列表中是否包含 alipay.data.dataservice.bill.downloadurl.query。
相关交易是否确实由当前商户和应用产生。
是否混用了正式环境与沙箱环境的网关、密钥或应用编号。
账单日期是否在允许查询的范围内。
SDK 是否正确输出 sub_code 和 sub_msg。排查问题时，应优先查看这两个字段。

注意事项

账单下载地址接口不会直接返回账单内容。应先调用接口获取临时 URL，再通过 HTTPS 下载并解压账单文件。

在生产环境中，还需要注意以下事项：

不要将应用私钥、账单地址或账单内容写入公开日志。
如果下载失败，请重新调用接口获取新地址，不要长期重试旧地址。
对账任务需要考虑账单生成时间。刚结束的自然日不一定能立即下载账单。
个人账号即使可以创建某些类型的应用，也不代表可以开通商家支付和账单权限。
控制台中的能力名称可能调整。最终应以接口详情页显示的所属产品、适用应用类型和签约条件为准。