> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询账单

> 按账单类型和账单日期分页查询当前商户已生成成功的账单。

按账单类型和账单日期分页查询当前商户已生成成功的账单。 商户身份由 API Key 确定，无需传入商户 ID。

<Note>
  `bill_date_from` 和 `bill_date_to` 必填，查询区间包含首尾日期且最多为 **90 天**。不传 `bill_types` 时查询全部账单类型。
</Note>

## 认证与请求头

使用 Bearer API Key，并同时携带以下签名请求头。GET 请求的 `requestBody` 为空字符串，签名字符串为 `{timestamp}.{nonce}.`，使用商户 API Secret 计算 HMAC-SHA256 并转换为小写 hex。详见[认证与签名](/zh/api/getting-started#认证与签名)。

<ParamField header="Authorization" type="string" required>
  Bearer API Key，格式：`Bearer sk_live_xxx`。
</ParamField>

<ParamField header="X-StablePay-Timestamp" type="string" required>
  Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
</ParamField>

<ParamField header="X-StablePay-Nonce" type="string" required>
  防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。 最短 16 个字符。 最长 64 个字符。
</ParamField>

<ParamField header="X-StablePay-Signature" type="string" required>
  使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算 HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。
</ParamField>

## 查询参数

<ParamField query="bill_types" type="string[]">
  可选的账单类型标识列表，使用英文逗号分隔，例如 `payment,payment_fee`。不传时查询全部账单类型。 至少 1 项。

  BillProd 维护的稳定账单类型标识。当前值：`payment` 线上支付账单、 `payment_fee` 支付计费账单、`subscription` 订阅支付账单、 `subscription_period` 订阅周期账单、`subscription_fee` 订阅计费账单、 `payout` 分发账单、`payout_fee` 分发计费账单、`capital_flow` 资金账单。 后续可能增加新字符串，客户端应兼容未知值。 匹配规则：`^[a-z][a-z0-9_]{0,63}$`。
</ParamField>

<ParamField query="bill_date_from" type="string" required>
  查询起始账单日期，格式为 `YYYY-MM-DD`，包含当天。 格式：`date`。
</ParamField>

<ParamField query="bill_date_to" type="string" required>
  查询结束账单日期，格式为 `YYYY-MM-DD`，包含当天。 起止日期范围最多为 90 天。 格式：`date`。
</ParamField>

<ParamField query="page" type="integer" default={1}>
  页码，从 1 开始。默认值为 1。 最小值：1。
</ParamField>

<ParamField query="page_size" type="integer" default={20}>
  每页数量，取值范围为 1-100。默认值为 20。 最小值：1。 最大值：100。
</ParamField>

## 成功响应

HTTP `200`，`application/json`。查询成功。没有匹配账单时，`data` 为空数组。

<ResponseField name="data" type="object[]" required>
  当前页账单列表。

  <Expandable title="字段">
    <ResponseField name="bill_id" type="string" required>
      账单 ID。以字符串返回，避免客户端整数精度丢失。 匹配规则：`^[0-9]+$`。
    </ResponseField>

    <ResponseField name="bill_type" type="string" required>
      BillProd 维护的稳定账单类型标识。当前值：`payment` 线上支付账单、 `payment_fee` 支付计费账单、`subscription` 订阅支付账单、 `subscription_period` 订阅周期账单、`subscription_fee` 订阅计费账单、 `payout` 分发账单、`payout_fee` 分发计费账单、`capital_flow` 资金账单。 后续可能增加新字符串，客户端应兼容未知值。 匹配规则：`^[a-z][a-z0-9_]{0,63}$`。
    </ResponseField>

    <ResponseField name="bill_date" type="string" required>
      账单日期。 格式：`date`。
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      账单币种。
    </ResponseField>

    <ResponseField name="transaction_count" type="integer" required>
      账单包含的交易记录数量。 格式：`int64`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_count" type="integer" required>
  符合条件的账单总数。 格式：`int64`。 最小值：0。
</ResponseField>

<ResponseField name="page" type="integer" required>
  当前页码。 最小值：1。
</ResponseField>

<ResponseField name="page_size" type="integer" required>
  每页数量。 最小值：1。 最大值：100。
</ResponseField>

## 错误响应

| HTTP 状态码 | 说明 |
| - | - |
| 400 | 请求参数错误。 |
| 401 | 认证失败。 |
| 503 | BillProd 或其他依赖服务暂时不可用。 |

### 服务错误结构

<ResponseField name="error" type="object" required>
  <Expandable title="字段">
    <ResponseField name="code" type="string" required>
      错误代码，例如 `invalid_parameter`、`resource_not_found`、 `historical_report_unavailable`、`report_incomplete` 或 `service_unavailable`。
    </ResponseField>

    <ResponseField name="message" type="string" required>
      错误信息。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string" required>
  请求 ID。
</ResponseField>

<ResponseField name="timestamp" type="integer" required>
  错误发生时间，Unix 秒。 格式：`int64`。
</ResponseField>

### 网关认证错误结构

API 网关在请求进入 PaymentProd 前可能返回以下结构的 HTTP `401` 响应。

<ResponseField name="status" type="string" required>
  取值：`error`。
</ResponseField>

<ResponseField name="error" type="string" required>
  认证失败原因。
</ResponseField>

下一步：使用返回的 `bill_id` [获取账单下载地址](/zh/api/bills/get-download-url)。

<RequestExample>
  ```bash cURL theme={"system"}
  TIMESTAMP=$(date +%s)
  NONCE=$(uuidgen)
  SIGNATURE=$(printf '%s' "${TIMESTAMP}.${NONCE}." | openssl dgst -sha256 -hmac "${SECRET_KEY}" | awk '{print $NF}')

  curl --get 'https://api.stablepay.co/api/v1/bills' \
    --data-urlencode 'bill_date_from=2026-09-01' \
    --data-urlencode 'bill_date_to=2026-09-30' \
    --data-urlencode 'bill_types=payment,payment_fee' \
    --data-urlencode 'page=1' \
    --data-urlencode 'page_size=20' \
    -H "Authorization: Bearer ${API_KEY}" \
    -H "X-StablePay-Timestamp: ${TIMESTAMP}" \
    -H "X-StablePay-Nonce: ${NONCE}" \
    -H "X-StablePay-Signature: ${SIGNATURE}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200（示例） theme={"system"}
  {
    "data": [
      {
        "bill_id": "1234567890",
        "bill_type": "payment",
        "bill_date": "2026-09-01",
        "currency": "USD",
        "transaction_count": 10
      }
    ],
    "total_count": 1,
    "page": 1,
    "page_size": 20
  }
  ```

  ```json 服务错误（示例） theme={"system"}
  {
    "error": {
      "code": "invalid_parameter",
      "message": "请求参数不合法"
    },
    "request_id": "req_example",
    "timestamp": 1790812800
  }
  ```

  ```json 网关认证错误（示例） theme={"system"}
  {
    "status": "error",
    "error": "认证失败"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.