切换主题

账单接口总览 ​

账单接口用于以编程方式查询 AVAVOX 的账单数据，覆盖 账户、空间、机器人、任务 四个维度，支持月粒度与日粒度，可用于对接企业财务系统、BI 报表或内部成本核算。

所有账单接口均为只读查询，不会产生任何副作用。

接口清单 ​

四个账单查询接口采用 POST + JSON 请求体（路径以 /query 结尾，表示查询而非创建资源），便于后续扩展筛选条件；零参数或纯分页的辅助接口保留 GET。

账单查询 ​

接口方法 & 路径
账户账单POST /open/api/v1/bills/account/query
空间账单POST /open/api/v1/bills/spaces/query
机器人账单POST /open/api/v1/bills/robots/query
任务账单POST /open/api/v1/bills/tasks/query

辅助接口 ​

接口方法 & 路径
查询 Key 信息GET /open/api/v1/auth/key-info
查询空间列表GET /open/api/v1/spaces
查询计费项字典GET /open/api/v1/bills/fee-items

鉴权与授权范围 ​

账单接口与其他开放接口使用同一套 App Key，请求头携带：

shell
Authorization: Bearer <App Key>
Content-Type: application/json

App Key 的创建与管理详见 《App Key 创建与管理》。

创建 App Key 时需要指定授权范围，它决定了该 Key 能看到哪些数据：

授权范围数据可见范围典型使用方
本企业全部空间企业下全部空间企业财务 / BI 系统
仅当前空间仅创建时所在的那一个空间各业务团队

通常只需要一把 Key

「本企业全部空间」是「仅当前空间」的超集，一把企业级 Key 即可覆盖全部查询场景。只有在需要按团队隔离数据（把 Key 分发给各空间自行使用）时，才需要签发多把空间级 Key。

各接口在两种授权范围下的行为 ​

接口本企业全部空间仅当前空间
账户账单企业下全部空间的汇总绑定空间的汇总
空间账单可传任意 spaceIds数据锁定为绑定空间；spaceIds 不传时默认取绑定空间
机器人账单全部空间下的机器人数据自动限定在绑定空间内
任务账单全部空间下的任务数据自动限定在绑定空间内
Key 信息支持支持
空间列表返回全部空间仅返回绑定的那一个空间
计费项字典支持支持（字典数据与租户无关）

权限规则 ​

请务必留意

  1. 账户账单的「账户」指本 Key 所代表的账户。 企业级 Key 得到的是企业下全部空间的汇总，空间级 Key 得到的是其绑定空间的汇总。使用前请通过 Key 信息 接口确认 Key 的授权范围，避免把单空间数据误当作企业总账。
  2. 越权参数会直接报错，不做静默过滤。 空间级 Key 在 spaceIds 中传入非绑定空间的 ID 时，请求会失败并返回明确提示，而不会悄悄剔除该 ID —— 以免你误以为返回的是多空间合计。
  3. 授权范围在创建 Key 时确定，创建后不可变更；需要调整范围请重新创建 Key。

对接第一步

建议先调用 Key 信息 接口确认当前 Key 的授权范围，再开始消费账单数据。

公共请求体参数 ​

四个账单查询接口的请求体共用以下字段：

granularity string 可选

统计粒度，枚举值：

  • month：月粒度（默认）
  • day：日粒度

start string 必填

起始时间。month 粒度传 YYYY-MM（如 2026-01）；day 粒度传 YYYY-MM-DD（如 2026-08-01）。格式须与 granularity 匹配。

end string 必填

结束时间，格式同 start，且须大于等于 start。

page int 可选

页码，从 1 开始，默认 1。

pageSize int 可选

每页条数，默认 20，最大 100。

时间跨度限制 ​

granularity单次查询最大跨度
month12 个月
day92 天

超出限制的请求会失败，请拆分为多次查询。

各接口特有的维度筛选字段（spaceIds、robotIds、taskIds 等）在对应接口页面中说明。

账单记录的公共结构 ​

四个账单接口的响应体同构，data 均为分页结构，list 中的元素为账单记录；记录中的维度字段随接口逐级递增（账户 → 空间 → 机器人 / 任务）。

点击展开账单记录字段说明

period string

账期。month 粒度为 YYYY-MM，day 粒度为 YYYY-MM-DD。

billStatus string

出账状态，SETTLED（已出账）或 UNSETTLED（未出账），详见数据时效。

spaceId / spaceName string

空间 ID 与名称。空间 / 机器人 / 任务账单接口返回，账户账单不返回。

robotId / robotName string

机器人 ID 与名称。仅机器人账单返回。

taskId / taskName string

任务 ID 与名称。仅任务账单返回。

usage array

用量列表，机器人账单与任务账单返回。元素结构：

  • code：用量编码，如 LINE_CALLS、ROBOT_CALLS
  • name：用量名称，如 线路用量、机器人用量
  • value：用量值
  • unit：单位，如 个

feeItems array

计费项列表，元素结构：

  • itemCode：计费项编码，全部枚举见计费项字典
  • itemName：计费项名称
  • amount：从余额扣减的金额（元）
  • points：从积分扣减的数量（个）

amount 与 points 始终同时返回，分别是该计费项在本账期内从余额、积分扣减的部分，两者互补不重复，可以同时非零：单笔消费在积分不足时会拆成积分 + 余额两段，同一账期内不同消费也可能走不同的支付渠道。未产生费用的计费项也会返回，值为 "0.000" / 0。

不同维度能够产生的计费项不同，因此各接口返回的计费项范围也不同：

接口返回的计费项
账户账单 / 空间账单全部计费项，见计费项字典
机器人账单LINE（线路）、ROBOT（机器人）、DEBUG（调试）
任务账单LINE（线路）、ROBOT（机器人）

totalAmount string

该条记录的合计金额（元）。

totalPoints int

该条记录的合计积分（个）。

数据类型约定 ​

  • 请求体与响应体均为 Content-Type: application/json; charset=utf-8，字段统一使用小驼峰命名。
  • 金额（amount、totalAmount）：字符串类型，保留三位小数，如 "0.050"，以避免浮点精度问题。单位为元。
  • 积分（points、totalPoints）：整数。
  • 月份：YYYY-MM，如 2026-08。
  • 日期：YYYY-MM-DD，如 2026-08-17。

数据时效 ​

账单数据 T+1 出账，当日数据为非最终数据，可能随结算流程调整。每条账单记录都携带 billStatus 字段：

值说明
SETTLED已出账，数据为最终值
UNSETTLED未出账（通常为当月 / 当日），数据可能变化

用于对账和入库时，建议只信任 SETTLED 的记录，或对 UNSETTLED 的记录保留后续覆盖更新的能力。

典型调用链路 ​

企业级 Key（财务 / BI 系统）

1. GET  /open/api/v1/auth/key-info             确认授权范围为「本企业全部空间」
2. GET  /open/api/v1/spaces                    拿到空间 ID
3. POST /open/api/v1/bills/account/query       查看账户总账（月粒度）
4. POST /open/api/v1/bills/spaces/query        按空间下钻
5. POST /open/api/v1/bills/robots|tasks/query  按机器人 / 任务下钻
6. 任一账单接口传 granularity=day               查看某维度的每日明细

空间级 Key（业务团队）

1. GET  /open/api/v1/auth/key-info             确认授权范围与绑定空间
2. POST /open/api/v1/bills/spaces/query        查本空间账单（spaceIds 可省略）
3. POST /open/api/v1/bills/robots|tasks/query  查本空间下的机器人 / 任务账单

相关文档 ​