---
title: 账单接口总览
---

# 账单接口总览

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

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

## 接口清单

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

### 账单查询

| 接口 | 方法 & 路径 |
| --- | --- |
| [账户账单](https://avavox.com/docs/developer/bill/account.html) | `POST /open/api/v1/bills/account/query` |
| [空间账单](https://avavox.com/docs/developer/bill/space.html) | `POST /open/api/v1/bills/spaces/query` |
| [机器人账单](https://avavox.com/docs/developer/bill/robot.html) | `POST /open/api/v1/bills/robots/query` |
| [任务账单](https://avavox.com/docs/developer/bill/task.html) | `POST /open/api/v1/bills/tasks/query` |

### 辅助接口

| 接口 | 方法 & 路径 |
| --- | --- |
| [查询 Key 信息](https://avavox.com/docs/developer/bill/key-info.html) | `GET /open/api/v1/auth/key-info` |
| [查询空间列表](https://avavox.com/docs/developer/bill/space-list.html) | `GET /open/api/v1/spaces` |
| [查询计费项字典](https://avavox.com/docs/developer/bill/fee-items.html) | `GET /open/api/v1/bills/fee-items` |

## 鉴权与授权范围

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

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

App Key 的创建与管理详见 [《App Key 创建与管理》](https://avavox.com/docs/developer/app-key.html)。

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

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

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

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

| 接口 | 本企业全部空间 | 仅当前空间 |
| --- | --- | --- |
| [账户账单](https://avavox.com/docs/developer/bill/account.html) | 企业下全部空间的汇总 | 绑定空间的汇总 |
| [空间账单](https://avavox.com/docs/developer/bill/space.html) | 可传任意 `spaceIds` | 数据锁定为绑定空间；`spaceIds` 不传时默认取绑定空间 |
| [机器人账单](https://avavox.com/docs/developer/bill/robot.html) | 全部空间下的机器人 | 数据自动限定在绑定空间内 |
| [任务账单](https://avavox.com/docs/developer/bill/task.html) | 全部空间下的任务 | 数据自动限定在绑定空间内 |
| [Key 信息](https://avavox.com/docs/developer/bill/key-info.html) | 支持 | 支持 |
| [空间列表](https://avavox.com/docs/developer/bill/space-list.html) | 返回全部空间 | 仅返回绑定的那一个空间 |
| [计费项字典](https://avavox.com/docs/developer/bill/fee-items.html) | 支持 | 支持（字典数据与租户无关） |

### 权限规则

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

::: tip 对接第一步
建议先调用 [Key 信息](https://avavox.com/docs/developer/bill/key-info.html) 接口确认当前 Key 的授权范围，再开始消费账单数据。
:::

## 公共请求体参数

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

<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`（如 `2026-01`）；`day` 粒度传 `YYYY-MM-DD`（如 `2026-08-01`）。格式须与 `granularity` 匹配。

---

<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`，且须大于等于 `start`。

---

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

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

---

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

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

### 时间跨度限制

| granularity | 单次查询最大跨度 |
| --- | --- |
| `month` | 12 个月 |
| `day` | 92 天 |

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

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

## 账单记录的公共结构

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

<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;">period</span> <code style="background:#f0f0f0;">string</code>

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

---

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

出账状态，`SETTLED`（已出账）或 `UNSETTLED`（未出账），详见[数据时效](#数据时效)。

---

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

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

---

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

机器人 ID 与名称。仅[机器人账单](https://avavox.com/docs/developer/bill/robot.html)返回。

---

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

任务 ID 与名称。仅[任务账单](https://avavox.com/docs/developer/bill/task.html)返回。

---

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

用量列表，[机器人账单](https://avavox.com/docs/developer/bill/robot.html)与[任务账单](https://avavox.com/docs/developer/bill/task.html)返回。元素结构：

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

---

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

计费项列表，元素结构：

- `itemCode`：计费项编码，全部枚举见[计费项字典](https://avavox.com/docs/developer/bill/fee-items.html)
- `itemName`：计费项名称
- `amount`：从余额扣减的金额（元）
- `points`：从积分扣减的数量（个）

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

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

| 接口 | 返回的计费项 |
| --- | --- |
| [账户账单](https://avavox.com/docs/developer/bill/account.html) / [空间账单](https://avavox.com/docs/developer/bill/space.html) | 全部计费项，见[计费项字典](https://avavox.com/docs/developer/bill/fee-items.html) |
| [机器人账单](https://avavox.com/docs/developer/bill/robot.html) | `LINE`（线路）、`ROBOT`（机器人）、`DEBUG`（调试） |
| [任务账单](https://avavox.com/docs/developer/bill/task.html) | `LINE`（线路）、`ROBOT`（机器人） |

---

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

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

---

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

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

</div>
</details>

## 数据类型约定

- 请求体与响应体均为 `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  查本空间下的机器人 / 任务账单
```

## 相关文档

- [App Key 创建与管理](https://avavox.com/docs/developer/app-key.html)
- [平台计费与充值规则说明](https://avavox.com/docs/billing-rules.html)