# 空间账单

按空间维度查询账单，支持月粒度与日粒度，对应控制台账单页面的「账单列表」及其「查看详情」。

<span style="display:inline-block;background:#e6f8ea;color:#fca130;border-radius:6px;padding:2px 8px;font-weight:bold;font-family:monospace;margin-right:8px;">POST</span>
`https://dashboard.avavox.com/open/api/v1/bills/spaces/query`

::: warning 权限说明
授权范围为「全部空间」的 Key 可查询任意空间；授权范围为「仅当前空间」的 Key 数据锁定为绑定空间 —— `spaceIds` 不传时默认取绑定空间，传入其他空间 ID 时请求会失败，不会静默过滤。
:::

## 请求头

<span style="font-family:monospace; color:#3451b2; ">Authorization </span> <code style="background:#f0f0f0; ">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

- 填写格式：`Authorization: Bearer <App Key>`
- `<App Key>` 为控制台「App Key 管理」页面生成的 Key。
- 获取方式详见：[《App Key 创建与管理》](https://avavox.com/docs/developer/app-key.html)。

## 请求体参数

除[公共请求体参数](https://avavox.com/docs/developer/bill/#公共请求体参数)外，本接口支持 `spaceIds` 筛选。

<span style="font-family:monospace; color:#3451b2;">granularity</span> <code style="background:#f0f0f0;">string</code> <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

统计粒度，`month`（默认）或 `day`。

---

<span style="font-family:monospace; color:#3451b2;">start</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

起始时间。`month` 粒度传 `YYYY-MM`，`day` 粒度传 `YYYY-MM-DD`。

---

<span style="font-family:monospace; color:#3451b2;">end</span> <code style="background:#f0f0f0;">string</code> <span style="background:#dc3545; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">必填</span>

结束时间，格式同 `start`。月粒度单次最大跨度 12 个月，日粒度最大 92 天。

---

<span style="font-family:monospace; color:#3451b2;">spaceIds</span> <code style="background:#f0f0f0;">array</code> <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

空间 ID 列表，单次最多 20 个。空间 ID 可通过[空间列表](https://avavox.com/docs/developer/bill/space-list.html)接口获取。

- 授权范围为「全部空间」的 Key：不传时返回全部空间。
- 授权范围为「仅当前空间」的 Key：不传时默认取绑定空间；传入其他空间 ID 时请求失败。

---

<span style="font-family:monospace; color:#3451b2;">page</span> / <span style="font-family:monospace; color:#3451b2;">pageSize</span> <code style="background:#f0f0f0;">int</code> <span style="background:#28a745; color:white; padding:2px 6px; border-radius:3px; font-size:12px;">可选</span>

分页参数。`page` 从 1 开始，默认 `1`；`pageSize` 默认 `20`，最大 `100`。

## 响应数据

<span style="font-family:monospace; color:#3451b2;">code</span> <code style="background:#f0f0f0;">int</code>

状态码，200 为成功，其他状态均为失败。

---

<span style="font-family:monospace; color:#3451b2;">success</span> <code style="background:#f0f0f0;">boolean</code>

是否成功，`true` 表示成功，`false` 表示失败。

---

<span style="font-family:monospace; color:#3451b2;">message</span> <code style="background:#f0f0f0;">string</code>

描述信息。

---

<span style="font-family:monospace; color:#3451b2;">data</span> <code style="background:#f0f0f0;">object</code>

<details>
<summary>点击展开字段说明</summary>
<div style="margin: 16px 0; padding: 16px;  border-left: 1px solid #f0f0f0; border-radius: 6px;">

<span style="font-family:monospace; color:#3451b2;">total</span> <code style="background:#f0f0f0;">int</code>

符合条件的账单记录总数。

---

<span style="font-family:monospace; color:#3451b2;">page</span> <code style="background:#f0f0f0;">int</code>

当前页码。

---

<span style="font-family:monospace; color:#3451b2;">pageSize</span> <code style="background:#f0f0f0;">int</code>

每页条数。

---

<span style="font-family:monospace; color:#3451b2;">list</span> <code style="background:#f0f0f0;">array</code>

账单记录列表，每个「账期 × 空间」一条。元素结构：

- `period`：账期，月粒度为 `YYYY-MM`，日粒度为 `YYYY-MM-DD`
- `billStatus`：出账状态，`SETTLED` / `UNSETTLED`
- `spaceId` / `spaceName`：空间 ID 与名称
- `feeItems`：计费项列表，元素含 `itemCode`、`itemName`、`amount`、`points`
- `totalAmount`：合计金额（元，字符串，三位小数）
- `totalPoints`：合计积分（个）

完整字段说明见[账单记录的公共结构](https://avavox.com/docs/developer/bill/#账单记录的公共结构)。

</div>
</details>

默认按 `period` 倒序排列，同一账期内按 `spaceId` 排序。

## 请求示例

查询 2026 年各空间的月度账单（授权范围为「全部空间」的 Key，不传 `spaceIds` 即返回全部空间）：

```shell
curl -X POST --location 'https://dashboard.avavox.com/open/api/v1/bills/spaces/query' \
--header 'Authorization: Bearer $Key' \
--header 'Content-Type: application/json' \
--data '{
  "granularity": "month",
  "start": "2026-01",
  "end": "2026-08"
}'
```

查询「花花」空间 2026 年 8 月的每日账单（等价于控制台的「查看详情」）：

```shell
curl -X POST --location 'https://dashboard.avavox.com/open/api/v1/bills/spaces/query' \
--header 'Authorization: Bearer $Key' \
--header 'Content-Type: application/json' \
--data '{
  "granularity": "day",
  "start": "2026-08-01",
  "end": "2026-08-31",
  "spaceIds": ["sp_001"]
}'
```

## 响应示例

```json
{
  "code": 200,
  "message": "操作成功",
  "success": true,
  "data": {
    "total": 2,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "period": "2026-08",
        "billStatus": "UNSETTLED",
        "spaceId": "sp_001",
        "spaceName": "花花",
        "feeItems": [
          { "itemCode": "LINE",  "itemName": "线路",   "amount": "0.000", "points": 1000 },
          { "itemCode": "ROBOT", "itemName": "机器人", "amount": "0.000", "points": 420 },
          { "itemCode": "DEBUG", "itemName": "调试",   "amount": "0.000", "points": 50 }
        ],
        "totalAmount": "0.000",
        "totalPoints": 1470
      },
      {
        "period": "2026-08",
        "billStatus": "UNSETTLED",
        "spaceId": "sp_default",
        "spaceName": "默认空间",
        "feeItems": [
          { "itemCode": "LINE",        "itemName": "线路",   "amount": "0.000", "points": 410 },
          { "itemCode": "ROBOT",       "itemName": "机器人", "amount": "0.000", "points": 930 },
          { "itemCode": "CONCURRENCY", "itemName": "并发",   "amount": "0.000", "points": 100000 },
          { "itemCode": "DEBUG",       "itemName": "调试",   "amount": "0.000", "points": 100 }
        ],
        "totalAmount": "0.000",
        "totalPoints": 101440
      }
    ]
  }
}
```