切换主题

任务账单 ​

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

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

权限说明

授权范围为「全部空间」的 Key 可查询全部空间下的任务；授权范围为「仅当前空间」的 Key，数据自动限定在绑定空间内，spaceIds 传入其他空间时请求会失败。

请求头 ​

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 天。

spaceIds array 可选

空间 ID 列表，单次最多 20 个，用于把结果限定在指定空间内。空间 ID 可通过空间列表接口获取。

taskIds array 可选

任务 ID 列表，单次最多 50 个。任务 ID 可通过查询任务列表接口获取。

taskName string 可选

任务名称，模糊匹配。

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 与名称
  • taskId / taskName：任务 ID 与名称
  • usage：用量列表，元素含 code、name、value、unit
  • feeItems：计费项列表，元素含 itemCode、itemName、amount、points；任务维度固定返回 LINE（线路）、ROBOT（机器人）两项
  • totalAmount：合计金额（元，字符串，三位小数）
  • totalPoints：合计积分（个）

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

请求示例 ​

查询 2026 年 3 月至 8 月全部任务的月度账单：

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

查询指定任务 2026 年 8 月的每日账单（等价于控制台的「查看详情」）：

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

响应示例 ​

json
{
  "code": 200,
  "message": "操作成功",
  "success": true,
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "period": "2026-08",
        "billStatus": "UNSETTLED",
        "spaceId": "sp_001",
        "spaceName": "花花",
        "taskId": "tk_2001",
        "taskName": "8月保单续约提醒",
        "usage": [
          { "code": "LINE_CALLS",  "name": "线路用量",   "value": 10, "unit": "个" },
          { "code": "ROBOT_CALLS", "name": "机器人用量", "value": 15, "unit": "个" }
        ],
        "feeItems": [
          { "itemCode": "LINE",  "itemName": "线路",   "amount": "0.000", "points": 1000 },
          { "itemCode": "ROBOT", "itemName": "机器人", "amount": "0.000", "points": 420 }
        ],
        "totalAmount": "0.000",
        "totalPoints": 1420
      }
    ]
  }
}