切换主题

空间账单 ​

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

POSThttps://dashboard.avavox.com/open/api/v1/bills/spaces/query

权限说明

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

请求头 ​

Authorization string 必填

  • 填写格式：Authorization: Bearer <App Key>
  • <App Key> 为控制台「App Key 管理」页面生成的 Key。
  • 获取方式详见：《App Key 创建与管理》。

请求体参数 ​

除公共请求体参数外，本接口支持 spaceIds 筛选。

granularity string 可选

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

start string 必填

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

end string 必填

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

spaceIds array 可选

空间 ID 列表，单次最多 20 个。空间 ID 可通过空间列表接口获取。

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

page / pageSize int 可选

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

响应数据 ​

code int

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

success boolean

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

message string

描述信息。

data object

点击展开字段说明

total int

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

page int

当前页码。

pageSize int

每页条数。

list array

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

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

完整字段说明见账单记录的公共结构。

默认按 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
      }
    ]
  }
}