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

# 查询月账单明细

## 请求头

<ParamField header="Authorization" type="string" required={true}>
  Bearer 身份验证格式，例如：Bearer \{\{API 密钥}}。
</ParamField>

## 查询参数

<ParamField query="startMonth" type="string" required={false}>
  查询起始月份，格式为 `YYYY-MM`，例如 `2025-10`。月账单数据最早从 `2025-10` 开始查询。
</ParamField>

<ParamField query="page" type="int32" required={false}>
  页码，从 `1` 开始。
</ParamField>

<ParamField query="pageSize" type="int32" required={false}>
  每页数量。
</ParamField>

<Info>
  当前生产环境会补齐从 `startMonth` 起的月份，返回数量可能不会严格等于 `pageSize`。
</Info>

## 响应参数

<ResponseField name="data" type="object[]" required={true}>
  月账单明细列表。

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="billId" type="string" required={true}>
      月账单 ID。
    </ResponseField>

    <ResponseField name="userId" type="string" required={true}>
      用户账号 ID。
    </ResponseField>

    <ResponseField name="billingMonth" type="string" required={true}>
      账单月份，格式为 `YYYY-MM`。
    </ResponseField>

    <ResponseField name="totalAmount" type="string" required={true}>
      月账单应付总额，单位为 1/10000 元。
    </ResponseField>

    <ResponseField name="originTotalAmount" type="string" required={true}>
      优惠或抵扣前的原始总额，单位为 1/10000 元。
    </ResponseField>

    <ResponseField name="voucherPayAmount" type="string" required={true}>
      代金券支付金额，单位为 1/10000 元。
    </ResponseField>

    <ResponseField name="cashPayAmount" type="string" required={true}>
      现金支付金额，单位为 1/10000 元。
    </ResponseField>

    <ResponseField name="debtAmount" type="string" required={true}>
      欠费金额，单位为 1/10000 元。
    </ResponseField>

    <ResponseField name="repaidAmount" type="string" required={true}>
      已还款金额，单位为 1/10000 元。
    </ResponseField>

    <ResponseField name="status" type="string" required={true}>
      月账单状态。取值：

      * `pending`：未出账。
      * `outed`：已出账。
      * `paid`：已支付。
      * `overdue`：已逾期。
      * `voided`：已作废。
    </ResponseField>

    <ResponseField name="invoiceUrl" type="string" required={true}>
      账单或发票下载地址。空字符串表示暂无可下载文件。
    </ResponseField>

    <ResponseField name="startTime" type="string" required={true}>
      账单周期开始时间，秒级 Unix 时间戳。
    </ResponseField>

    <ResponseField name="endTime" type="string" required={true}>
      账单周期结束时间，秒级 Unix 时间戳。
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl --request GET \
    --url 'https://api.ppio.com/openapi/v1/billing/monthly/bill?startMonth=2025-10&page=1&pageSize=20' \
    --header 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "billId": "<string>",
        "userId": "<string>",
        "billingMonth": "2025-12",
        "totalAmount": "1000000",
        "originTotalAmount": "1200000",
        "voucherPayAmount": "200000",
        "cashPayAmount": "800000",
        "debtAmount": "0",
        "status": "paid",
        "invoiceUrl": "",
        "startTime": "1764547200",
        "endTime": "1767225599",
        "repaidAmount": "0"
      }
    ]
  }
  ```
</ResponseExample>