账户账单

查询账户级的账单汇总，支持月粒度与日粒度，对应控制台「月度账单」页面及其日详情。

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

数据范围随授权范围变化

授权范围为「全部空间」的 Key，返回的是企业下全部空间的汇总；授权范围为「仅当前空间」的 Key，返回的是其绑定空间的汇总。两者响应结构完全一致，均不含空间维度字段。请先通过 Key 信息 接口确认授权范围后再消费数据，避免把单空间数据误当作企业总账。

请求头

Authorization string 必填

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

请求体参数

本接口仅使用公共请求体参数，无额外字段。

granularity string 可选

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

---

start string 必填

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

---

end string 必填

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

---

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
• feeItems：计费项列表，元素含 itemCode、itemName、amount、points
• totalAmount：合计金额（元，字符串，三位小数）
• totalPoints：合计积分（个）

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

请求示例

查询 2026 年 1 月至 8 月的月度账单：

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

查询 2026 年 8 月 1 日至 19 日的每日账单：

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

日粒度的响应结构与月粒度完全相同，仅 period 变为具体日期（如 2026-08-17），每日一条记录。

响应示例

{
  "code": 200,
  "message": "操作成功",
  "success": true,
  "data": {
    "total": 8,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "period": "2026-08",
        "billStatus": "UNSETTLED",
        "feeItems": [
          { "itemCode": "LINE",        "itemName": "线路",     "amount": "0.000", "points": 1410 },
          { "itemCode": "ROBOT",       "itemName": "机器人",   "amount": "0.000", "points": 1350 },
          { "itemCode": "SMS",         "itemName": "短信",     "amount": "0.000", "points": 0 },
          { "itemCode": "VOICE_CLONE", "itemName": "声音克隆", "amount": "0.000", "points": 0 },
          { "itemCode": "CONCURRENCY", "itemName": "并发",     "amount": "0.000", "points": 110000 },
          { "itemCode": "STORAGE",     "itemName": "存储",     "amount": "0.000", "points": 0 },
          { "itemCode": "DEBUG",       "itemName": "调试",     "amount": "0.000", "points": 150 },
          { "itemCode": "ADJUSTMENT",  "itemName": "资金调整", "amount": "0.000", "points": 0 }
        ],
        "totalAmount": "0.000",
        "totalPoints": 112910
      }
    ]
  }
}