# 计量计费 RESTful API (/zh-CN/realtime-media/marketplace/reference/usage-billing)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
服务商将插件发布在声网云市场前,需要实现一套计量计费的 RESTful API,并将对应的 URL 地址提供给声网。声网会定期调用这套 API,向插件服务商获取指定计量和计费相关信息,并通知到使用插件的 App 开发者。
## 接口要求 [#接口要求]
实现计量计费 RESTful API 时,请确保你的服务器满足如下要求:
- 每秒钟可以处理至少 100 个请求。
- 使用规范的 HTTP 错误信息及排查方法。
每次调用后,声网服务器会等待 500 毫秒。如果等待期内没有收到响应信息,会再次调用接口。重复调用达到三次将会停止调用。
## 查询用量(GET) [#查询用量get]
App 开发者在声网控制台项目中启用插件后,声网会每天调用一次该 API 获取插件用量,将获取的用量求和并向上求整,然后更新控制台界面的用量信息。
### HTTP 请求 [#http-请求]
**请求 URL**
```shell
GET https://{host}/usage?fromTs={ts}&toTs={ts}&pageNum={pageNum}&apiKey={apiKey}&signature={signature}
```
**查询参数**
| 参数 | 是否必需 | 类型 | 数据长度 | 描述 |
| --- | --- | --- | --- | --- |
| `fromTs` | 必需 | 时间戳 | 10 | 要查询的时间段的起点,必须在当天 UTC 时间的 0 点之后。 |
| `toTs` | 必需 | 时间戳 | 10 | 要查询的时间段的终点,必须在当天 UTC 时间的 `23:59:59` 之前。 |
| `pageNum` | 必需 | Int | N/A | [usage-billing-markdown-3-3-4 details](#table-slot-usage-billing-markdown-3-3-4) |
| `limit` | 可选 | Int | N/A | 每次响应最多包含多少条数据。请确保你为该字段设置了一个默认值。 |
| `apiKey` | 必需 | String | 32 | 你的 API Key,用于和声网之间的鉴权。你需要向声网提供自行生成的 API Key。 |
| `signature` | 必需 | String | N/A | 通过[签名算法](/zh-CN/realtime-media/marketplace/build/create-extensions/signature-algorithm)生成的签名。你需要自己部署签名算法,以确认该请求是声网发送的。 |
**usage-billing-markdown-3-3-4 details**
用量列表的页数,表示查询第几页的用量。你需要对用量列表进行分页设置,并在响应参数的 `hasNext` 字段中返回是否还有下一页。声网在每天第一次调用该方法时,会始终将该参数设为 1,并在收到响应后重复调用该方法,直到响应参数中的 `hasNext` 字段返回 `false`。
### HTTP 响应 [#http-响应]
响应包体中包含以下字段:
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `status` | Int | 请求的状态码。0 表示请求成功。 |
| `statusReason` | String | 状态对应的原因。 |
| `totalSize` | Int | 已启用插件的项目总数。 |
| `pageNum` | Int | 用量列表的第几页。该字段需要和请求中的 `pageNum` 字段一致。 |
| `hasNext` | Boolean | [usage-billing-html-0-5-2 details](#table-slot-usage-billing-html-0-5-2) |
| `data` | Array | [usage-billing-html-0-6-2 details](#table-slot-usage-billing-html-0-6-2) |
**usage-billing-html-0-5-2 details**
用量列表是否还有下一页:
- `true`: 有下一页。声网会继续发送用量请求。
- `false`: 没有下一页。声网会停止用量请求。
**usage-billing-html-0-6-2 details**
用量信息,包含如下数据:
- `projectId`:项目 ID。
- `amount`:用量。数据格式为 BigDecimal。单位如下:
- 如果按时长计算用量,单位默认为分钟。
- 如果按次数计算用量,单位默认为次。
- 如果需要其它单位,联系声网协商配置。
- `description`:用量的详细信息。
`projectId` 为空或者 `amount` 为 0 的数据不需要返回。
### 示例 [#示例]
**请求行**
```shell
GET https://{host}/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=Q7**************************Sa HTTP/1.1
```
**响应包体**
```json
{
"status": 0,
"statusReason": "Success getting usage data",
"data": {
"totalSize": 2,
"pageNum": 2,
"hasNext": false,
"data": [
{
"projectId": "4****2",
"amount": 1,
"description": "1 分钟 × 声网云市场单价 (¥***/月)"
}
]
}
}
```
## 查询计费(GET) [#查询计费get]
App 开发者在声网控制台项目中启用插件后,声网会在每个月末调用该 API 获取使用插件产生的计费信息,将每次请求获取到的费用相加后向上取整,然后更新控制台界面的计费信息。
### HTTP 请求 [#http-请求-1]
**请求 URL**
```shell
GET https://{host}/bill?fromTs={ts}&toTs={ts}&pageNum={pageNum}&apiKey={apiKey}&signature={signature}
```
**查询参数**
| 参数 | 是否必需 | 类型 | 数据长度 | 描述 |
| --- | --- | --- | --- | --- |
| `fromTs` | 必需 | 时间戳 | 10 | 要查询的时间段的起点,必须在当月第一天的 UTC 时间 0 点之后。 |
| `toTs` | 必需 | 时间戳 | 10 | 要查询的时间段的终点,必须在当月最后一天的 UTC 时间 `23:59:59` 之前。 |
| `pageNum` | 必需 | Int | N/A | [usage-billing-markdown-4-3-4 details](#table-slot-usage-billing-markdown-4-3-4) |
| `limit` | 可选 | Int | N/A | 每次响应最多包含多少条数据。请确保你给该字段设置了一个默认值。 |
| `apiKey` | 必需 | String | 32 | 你的 API Key,用于和声网之间的鉴权。你需要向声网提供自行生成的 API Key。 |
| `signature` | 必需 | String | N/A | 通过[签名算法](/zh-CN/realtime-media/marketplace/build/create-extensions/signature-algorithm)生成的签名。你需要自己部署签名算法,以确认该请求是声网发送的。 |
**usage-billing-markdown-4-3-4 details**
用量列表的页数,表示查询第几页的用量。你需要对用量列表进行分页设置,并在响应参数的 `hasNext` 字段中返回是否还有下一页。声网在每天第一次调用该方法时,会始终将该参数设为 1,并在收到响应后重复调用该方法,直到响应参数中的 `hasNext` 字段返回 `false`。
### HTTP 响应 [#http-响应-1]
响应包体中包含以下字段:
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `status` | Int | 请求的状态码。0 表示请求成功。 |
| `statusReason` | String | 状态对应的原因。 |
| `totalSize` | Int | 已启用插件的项目总数。 |
| `pageNum` | Int | 费用列表的第几页。该字段需要和请求中的 `pageNum` 字段一致。 |
| `hasNext` | Boolean | [usage-billing-html-1-5-2 details](#table-slot-usage-billing-html-1-5-2) |
| `data` | Array | [usage-billing-html-1-6-2 details](#table-slot-usage-billing-html-1-6-2) |
**usage-billing-html-1-5-2 details**
费用列表是否还有下一页:
- `true`: 有下一页。声网会继续发送计费请求。
- `false`: 没有下一页。声网会停止计费请求。
**usage-billing-html-1-6-2 details**
费用信息,包含如下数据:
- `projectId`:项目 ID。
- `amount`:费用。数据格式为 BigDecimal。
- `description`: 费用的详细信息。
`projectId` 为空或者 `amount` 为 0 的数据不需要返回。
### 示例 [#示例-1]
**请求行**
```shell
GET https://{host}/bill?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=Q7**************************Sa HTTP/1.1
```
**响应示例**
```json
{
"status": 0,
"statusReason": "Success getting billing data",
"data": {
"totalSize": 2,
"pageNum": 2,
"hasNext": false,
"data": [
{
"projectId": "4xxxx2",
"amount": 1,
"description": "1 分钟 × 声网云市场单价 (¥***/月)"
}
]
}
}
```
## 查询 License 详情(GET) [#查询-license-详情get]
:::info[信息]
该方法适用于使用授权 License 方式对 App 开发者计费的插件服务商。
:::
该方法获取指定开发者的 License 信息。如果你使用授权 License 的方式进行计费,声网会在需要时调用该方法获取指定 License 的有效期和剩余次数。
### HTTP 请求 [#http-请求-2]
**请求 URL**
```shell
GET https://{host}/customers/{customerId}/license&apiKey={apiKey}&signature={signature}
```
**路径参数**
| 参数 | 是否必需 | 类型 | 数据长度 | 描述 |
| ------------ | -------- | ------ | -------- | ------------------------------------------------------------ |
| `customerId` | 必需 | String | N/A | 开发者在声网控制台注册的账户 ID。 |
| `apiKey` | 必需 | String | 32 | 你的 API Key,用于和声网之间的鉴权。你需要向声网提供自行生成的 API Key。 |
| `signature` | 必需 | String | N/A | 通过[签名算法](/zh-CN/realtime-media/marketplace/build/create-extensions/signature-algorithm)生成的签名。你需要自己部署签名算法,以确认该请求是声网发送的。 |
### HTTP 响应 [#http-响应-2]
响应包体中包含以下字段:
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `status` | String | [usage-billing-html-2-1-2 details](#table-slot-usage-billing-html-2-1-2) |
| `statusReason` | String | 状态对应的原因。 |
| `expireDate` | String | App 开发者的 License 过期时间。 |
| `residueCount` | String | License 剩余次数。 |
**usage-billing-html-2-1-2 details**
请求状态:
- `success`:请求成功。
- `failed`:请求失败。
### 示例 [#示例-2]
**请求行**
```shell
GET https://{host}/customers/1xxxx6/license&apiKey=pz*************gd&signature=Q7**************************Sa HTTP/1.1
```
**响应包体**
```json
{
"status": "success",
"statusReason": "",
"data": {
"expireDate": "2025-10-01",
"residueCount": "100"
}
}
```