天猫店铺如何下载支付宝账户对账文件？

2026-10-24支付阿杰

结论

要下载天猫店铺所绑定支付宝商家账户的交易对账文件，需要以该支付宝账户对应的商户身份接入支付宝开放平台，并调用账单下载接口：

alipay.data.dataservice.bill.downloadurl.query

接口返回临时下载地址后，通过 HTTP 下载并解压对账文件。

支付宝接口提供的是支付宝侧的交易或资金账单，不包含天猫平台的订单、佣金、技术服务费等平台账单。如果对账范围包括天猫平台费用，还需要从天猫商家后台对应的账房或财务模块获取相关账单，并将两类账单结合使用。

接入前提

接入前先确认以下信息：

天猫店铺绑定的支付宝商家账户。
当前开放平台应用是否由该支付宝账户创建，或是否已经取得该账户的应用授权。
企业是否已完成支付宝开放平台要求的实名认证、应用签约，以及密钥或证书配置。
应用是否拥有账单查询相关接口权限。

可申请的能力名称、签约条件和审核要求可能会随开放平台调整，请以应用控制台的实际展示为准。

接入方式

商户自行下载本账户账单

如果开放平台应用与天猫店铺绑定的支付宝商家账户属于同一主体，可以使用该应用直接调用账单下载接口。

这种方式一般不需要传入 app_auth_token，但应用必须完成上线、签约和接口权限配置。

服务商代商户下载账单

如果系统以服务商身份为多个店铺提供对账服务，需要使用第三方应用授权模式：

服务商创建第三方应用并配置接口权限。
天猫店铺对应的支付宝商家账户完成应用授权。
服务商通过授权流程取得 app_auth_token。
调用账单接口时，传入该商户的 app_auth_token。

app_auth_token 表示商户授权，不能用服务商自己的支付宝账户信息代替。令牌的获取和刷新应按照支付宝开放平台当前的第三方应用授权流程实现。

配置步骤

1. 确认支付宝商户账户

登录天猫商家后台和对应的支付宝商家后台，核实店铺绑定关系，并记录支付宝商户账户的 PID 等必要信息。

对账应以实际收款的支付宝账户为准。如果店铺曾经更换支付宝账户，需要按账户和时间范围分别处理账单。

2. 创建开放平台应用

使用对应的企业账号登录支付宝开放平台，根据业务模式创建网页、移动或第三方应用：

只下载本企业账单时，创建商户自用应用。
为其他商户或多个店铺提供服务时，创建第三方应用，并完成商户授权流程。

3. 配置签名方式

在应用中配置接口签名。常见方式有普通公钥模式和证书模式，具体使用哪一种，取决于应用控制台支持的配置和企业的安全要求。

系统侧至少需要妥善保存：

app_id
应用私钥
支付宝公钥，或支付宝相关证书
第三方应用场景下的 app_auth_token

不要把私钥写入前端代码、公开仓库或普通日志。

4. 申请并签约账单能力

在应用控制台中添加账单下载相关能力，并完成所需的签约或审核。能否正常调用，以控制台中的应用能力状态和接口实际返回结果为准。

5. 查询账单下载地址

调用 alipay.data.dataservice.bill.downloadurl.query 时，主要使用以下业务参数：

bill_type：账单类型，例如 trade 表示交易账单。
bill_date：账单日期。日账单通常使用 yyyy-MM-dd 格式。

可查询的账单类型、日期范围和账单生成时间，请以接口当前文档为准。程序不应默认当天账单一定已经生成。

6. 下载并处理文件

接口调用成功后会返回 bill_download_url。这个地址通常有时效限制，取得后应及时下载，不要长期保存，也不要将完整地址写入公开日志。

下载的文件一般还需要解压、识别字符集、校验字段并汇总数据，然后才能导入内部对账系统。

Java 调用示例

以下示例使用支付宝 Java SDK 的公钥调用方式。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 AlipayBillDownloader {

    public static void main(String[] args) throws Exception {
        String gateway = "https://openapi.alipay.com/gateway.do";
        String appId = System.getenv("ALIPAY_APP_ID");
        String appPrivateKey = System.getenv("ALIPAY_APP_PRIVATE_KEY");
        String alipayPublicKey = System.getenv("ALIPAY_PUBLIC_KEY");

        AlipayClient alipayClient = new DefaultAlipayClient(
                gateway,
                appId,
                appPrivateKey,
                "json",
                "UTF-8",
                alipayPublicKey,
                "RSA2"
        );

        AlipayDataDataserviceBillDownloadurlQueryModel model =
                new AlipayDataDataserviceBillDownloadurlQueryModel();
        model.setBillType("trade");
        model.setBillDate("2026-09-08");

        AlipayDataDataserviceBillDownloadurlQueryRequest request =
                new AlipayDataDataserviceBillDownloadurlQueryRequest();
        request.setBizModel(model);

        // 商户自用应用一般不传 appAuthToken
        AlipayDataDataserviceBillDownloadurlQueryResponse response =
                alipayClient.execute(request);

        // 第三方应用代商户调用时使用以下形式：
        // String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN");
        // AlipayDataDataserviceBillDownloadurlQueryResponse response =
        //         alipayClient.execute(request, null, appAuthToken);

        if (response.isSuccess()) {
            String downloadUrl = response.getBillDownloadUrl();
            System.out.println("账单下载地址已获取");
            // 不建议在生产日志中直接打印完整 downloadUrl。
            // 后续应使用 HTTP 客户端立即下载并安全保存文件。
        } else {
            System.err.println(
                    "账单地址查询失败，code=" + response.getCode()
                    + ", subCode=" + response.getSubCode()
                    + ", subMsg=" + response.getSubMsg()
            );
        }
    }
}

示例日期仅作演示。生产系统应根据待对账日期动态生成日期参数，并检查对应账单是否已经生成。

下载文件示例

取得 bill_download_url 后，可以由服务端使用 HTTP 客户端下载。下面是适用于 Java 11 及以上版本的简化示例：

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;

public class BillFileDownload {

    public static void download(String billDownloadUrl, Path targetFile)
            throws Exception {

        HttpClient client = HttpClient.newBuilder()
                .followRedirects(HttpClient.Redirect.NORMAL)
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(billDownloadUrl))
                .GET()
                .build();

        HttpResponse<Path> response = client.send(
                request,
                HttpResponse.BodyHandlers.ofFile(targetFile)
        );

        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException(
                    "账单文件下载失败，HTTP 状态码：" + response.statusCode()
            );
        }
    }
}

生产环境还需要设置连接超时、读取超时、重试次数和文件大小限制，并检查文件完整性。下载地址属于敏感信息，不应传递给浏览器端。

常见问题与注意事项

查不到账单

常见原因有：

查询日期的账单尚未生成。
bill_type 或 bill_date 不符合接口要求。
应用未签约对应能力。
调用应用与实际收款的支付宝账户不匹配。
第三方应用未传、错传或使用了已经失效的 app_auth_token。
指定日期没有发生可入账交易。

程序应记录 code、sub_code、sub_msg 和请求流水信息，但不要记录私钥、授权令牌或完整下载地址。

账单金额与天猫订单金额不一致

支付宝账单记录的是支付宝侧的实际交易和资金变化，其中可能包括退款、手续费、分账和账期差异。天猫平台账单还可能包含佣金、软件服务费、营销费用等项目，因此不能直接拿订单总额进行简单比较。

对账时至少应按以下维度匹配：

商户订单号
支付宝交易号
支付时间
退款时间
收入金额
支出金额
手续费
交易状态

跨日退款、部分退款和合并支付需要单独设计对账规则。

下载地址已经失效

下载地址不是永久文件地址。接口返回地址后应立即下载。如果地址已经失效，需要重新调用账单查询接口，获取新的下载地址。

测试环境与生产环境

沙箱环境中的账单数据未必与生产账户完全一致。正式接入前，应使用生产应用，在授权范围内选择较小的日期范围进行验证。确认下载文件的字段、字符集和压缩格式后，再开发解析逻辑。

安全与合规

账单可能包含交易号、金额和用户相关信息，需要限制访问权限并加密存储。下载、解压、解析和入库过程应保留审计记录，同时设置合理的数据留存和脱敏策略。