> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文介绍如何通过扣子 API 对终端用户配额进行管控，并导出终端用户的用量数据。
## 前提条件 {#9cb489e1}

* **套餐限制**：企业旗舰版、原企业版。
* **设备信息上报**：确保企业下的设备已成功上报了设备信息，否则权益额度将无法对该设备生效，设备信息的配置方法可参考[设置设备信息](https://www.coze.cn/open/docs/dev_how_to_guides/deviceInfo)。

## 创建设备权益额度 {#f5a04021}
你可以创建设备的权益额度，以便用户在初始阶段免费体验设备功能，同时避免资源的过度使用。
### 场景描述和限制 {#894b7814}
设备权益额度的管控方式可以基于设备的设备 ID，也可以基于自定义维度的实体 ID。例如，在智慧教育等场景中，如果需要对 APP 中的用户进行配额管控。你可以在上报设备信息时，通过 `custom_consumer` 参数，设置上报的设备信息为 APP 对应的用户名，具体请参见[上报设备信息](/dev_how_to_guides/deviceInfo)。
本文以通过设备 ID 进行权益额度管控为例，介绍具体的实现方式。在设备配额管理中，通常需要针对企业中的所有设备创建累计可用积分额度和时间周期内的积分额度，同时针对个别设备设置累计可用积分额度。
:::tip 说明
* 配置的优先级：若同时为单个设备和企业下所有设备配置了权益额度，则优先使用单个设备的权益额度。例如单个设备的权益额度设置 2000 积分，企业级权益额度设置 5000 积分，该设备以 2000 积分为准。
* 未配置额度的设备：未设置权益额度的设备，将**默认无限制**使用资源。
* 额度设置：当权益配额的生效范围为企业下所有设备或企业下所有自定义维度的实体时，仅能创建一条累计可用额度和一条时间周期内可用额度。
* 生效时间：若权益生效时间已过期，则该条配额规则会失效。
:::
### **场景一：为所有设备创建累计可用积分**额度 {#8a43f101}
为企业下所有设备设置累计可用积分额度。例如，设置企业中每个设备累计额度为 5000 积分，且该配额规则永久有效。当设备 A 的累计使用积分达到 5000 上限后，设备 A 将无法继续使用。实现方法如下：
调用[创建用量限额配置](/developer_guides/create_device_quotas) API，关键参数设置如下：
<!-- @cols-width: 190,100,500 -->
| | | | \
|**参数** |**类型** |**说明** |
|---|---|---|
| | | | \
|entity_type |String |权益配额的生效范围。本场景中设置为 enterprise_all_devices，即权益配额对企业下的所有设备生效。 |
| | | | \
|benefit_info.limit |Long |可用的积分额度。例如 5000。 |
| | | | \
|benefit_info.benefit_type |String |权益额度类型，本示例中设置为 `resource_point`，表示积分配额。 |
| | | | \
|benefit_info.started_at |Long |该条配额规则的生效起始时间，Unixtime 时间戳格式，单位为秒。 |\
| | |例如设置为 `1743004800`，对应 `2025-03-27 00:00:00`。 |
| | | | \
|benefit_info.ended_at |Long |该条配额规则的生效截止时间，Unixtime 时间戳格式，单位为秒。过期后，该条配额规则会失效。 |\
| | |例如设置为 `253402300799`，对应`9999-12-31` ，表示永久有效。 |
| | | | \
|benefit_info.trigger_unit |String |权益可用额度的重置周期，即额度按指定时间间隔恢复或重新计算。 |\
| | |本场景中设置为 `never`，即累计额度。 |

示例代码如下：
```Shell
curl --location --request POST 'https://api.coze.cn/v1/commerce/benefit/limitations' \
--header 'Authorization: Bearer pat_YourAccessTokenHere' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entity_type": "enterprise_all_devices",
  "benefit_info": {
    "benefit_type": "resource_point",
    "active_mode": "absolute_time",
    "started_at": 1743004800,
    "ended_at": 253402300799,
    "limit": 5000,
    "trigger_unit": "never"
  }
}'
```

### **场景二：为所有设备创建周期内可用积分额度** {#956b8d4b}
为企业中的所有设备创建一条时间周期内可用的积分额度。
例如，设置企业中每个设备每日可用额度为 1000 积分，且该配额规则永久有效。当设备 A 今天的使用积分达到 1000 上限后，设备 A 今天将无法继续使用，需等到次日才能恢复使用。
调用[创建用量限额配置](/developer_guides/create_device_quotas) API，关键参数设置如下：
<!-- @cols-width: 190,100,500 -->
| | | | \
|**参数** |**类型** |**说明** |
|---|---|---|
| | | | \
|entity_type |String |权益配额的生效范围。本场景中设置为 enterprise_all_devices，即权益配额对企业下的所有设备生效。 |
| | | | \
|benefit_info.benefit_type |String |权益额度类型，本示例中设置为 `resource_point`，表示积分配额。 |
| | | | \
|benefit_info.started_at |Long |该条配额规则的生效起始时间，Unixtime 时间戳格式，单位为秒。 |\
| | |例如设置为 `1743004800`，对应 `2025-03-27 00:00:00`。 |
| | | | \
|benefit_info.ended_at |Long |该条配额规则的生效截止时间，Unixtime 时间戳格式，单位为秒。过期后，该条配额规则会失效。 |\
| | |例如设置为 `253402300799`，对应`9999-12-31` ，表示永久有效。 |
| | | | \
|benefit_info.limit |Long |周期内可用的积分额度，本场景中设置为 1000。 |
| | | | \
|benefit_info.trigger_unit |String |权益可用额度的重置周期。本场景中设置为 `day`，以天为周期重置额度。 |
| | | | \
|benefit_info.trigger_time |Long |权益额度重置周期的频率。本场景中设置为 1，每日刷新配额。 |

示例代码如下：
```Shell
curl --location --request POST "https://api.coze.cn/v1/commerce/benefit/limitations" \
--header 'Authorization: Bearer pat_YourAccessTokenHere' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entity_type": "enterprise_all_devices",
  "benefit_info": {
    "benefit_type": "resource_point",
    "active_mode": "absolute_time",
    "started_at": 1743004800,
    "ended_at": 253402300799,
    "limit": 1000,
    "trigger_unit": "day",
    "trigger_time": 1
  }
}'
```

### **场景三：为单个设备创建累计可用积分额度** {#62608f0e}
为特定设备单独设置累计额度，例如，设备 ID 为 SN12345 的设备，累计可用积分额度为 2000 积分。
调用[创建用量限额配置](/developer_guides/create_device_quotas) API，关键参数设置如下：
<!-- @cols-width: 190,100,500 -->
| | | | \
|**参数** |**类型** |**说明** |
|---|---|---|
| | | | \
|entity_type |String |权益配额的生效范围。本场景中设置为 `single_device`，即权益配额对单个设备生效。 |
| | | | \
|entity_id |String |设备 ID，例如 SN12345*********。 |
| | | | \
|benefit_info.started_at |Long |该条配额规则的生效起始时间，Unixtime 时间戳格式，单位为秒。 |\
| | |例如设置为 `1743004800`，对应 2025-03-27 00:00:00。 |
| | | | \
|benefit_info.ended_at |Long |该条配额规则的生效截止时间，Unixtime 时间戳格式，单位为秒。过期后，该条配额规则会失效。 |\
| | |例如设置为` 253402300799`，对应`9999-12-31` ，表示永久有效。 |
| | | | \
|benefit_info.limit |Long |累计可用的积分额度，本场景中设置为 2000。 |
| | | | \
|benefit_info.benefit_type |String |权益额度类型，本示例中设置为 `resource_point`，表示积分配额。 |
| | | | \
|benefit_info.trigger_unit |String |权益可用额度的重置周期，即额度按指定时间间隔恢复或重新计算。 |\
| | |本场景中设置为 `never`，即累计额度。 |

示例代码如下：
```Shell
curl --location --request POST 'https://api.coze.cn/v1/commerce/benefit/limitations' \
--header 'Authorization: Bearer pat_YourAccessTokenHere' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entity_type": "single_device",
  "entity_id": "SN12345*********",
  "benefit_info": {
    "benefit_type": "resource_point",
    "active_mode": "absolute_time",
    "started_at": 1743004800,
    "ended_at": 253402300799,
    "limit": 2000,
    "trigger_unit": "never"
  }
}'
```

### **场景四：为所有设备创建周期内可用语音和积分配额** {#a250c964}
如果企业购买了 **AI 智能通话许可（系统音色）**或 **AI 智能通话许可（复刻音色）**，你可以创建语音通话时长配额。本文以为企业中的所有设备创建每日可用的语音通话时长配额和积分配额为例。当任一配额用尽后，设备在当前周期内将无法继续使用。
例如，智能体使用系统音色，你可以设置企业中每个设备每日可用**语音通话时长配额（系统音色）​**为 1200 秒，**积分配额**为 500 积分。当设备 A 今天使用的积分或语音通话时长任一个达到上限后，设备 A 今天将无法继续使用，需等到次日才能恢复使用。
你需要调用两次 API，分别为两种 `benefit_type` 创建配额规则。

1. 调用[创建用量限额配置](/developer_guides/create_device_quotas) API，配置语音通话时长配额，关键参数设置如下：
   <!-- @cols-width: 190,100,500 -->
   | | | | \
   |**参数** |**类型** |**说明** |
   |---|---|---|
   | | | | \
   |entity_type |String |权益配额的生效范围。本场景中设置为 enterprise_all_devices，即权益配额对企业下的所有设备生效。 |
   | | | | \
   |benefit_info.benefit_type |String |权益额度类型，枚举值： |\
   | | | |\
   | | |* `resource_point`：积分配额。 |\
   | | |* `voice_unified_duration_system`：语音通话时长配额（系统音色）。 |\
   | | |* `voice_unified_duration_custom`：语音通话时长配额（复刻音色）。 |
   | | | | \
   |benefit_info.started_at |Long |该条配额规则的生效起始时间，Unixtime 时间戳格式，单位为秒。 |\
   | | |例如设置为 `1756684800`，对应 `2025-09-01 00:00:00`。 |
   | | | | \
   |benefit_info.ended_at |Long |该条配额规则的生效截止时间，Unixtime 时间戳格式，单位为秒。过期后，该条配额规则会失效。 |\
   | | |例如设置为 `253402300799`，对应`9999-12-31` ，表示永久有效。 |
   | | | | \
   |benefit_info.limit |Long |周期内可用的额度。 |\
   | | | |\
   | | |* 如果权益配额类型为 `resource_point`，可用额度的单位为积分。 |\
   | | |* 如果权益配额类型为`voice_unified_duration_system`或`voice_unified_duration_custom`，可用额度的单位为秒。 |
   | | | | \
   |benefit_info.trigger_unit |String |权益可用额度的重置周期。本场景中设置为 `day`，以天为周期重置额度。 |
   | | | | \
   |benefit_info.trigger_time |Long |权益额度重置周期的频率。本场景中设置为 1，每日刷新配额。 |

   示例代码如下：
   ```Shell
   curl --location --request POST "https://api.coze.cn/v1/commerce/benefit/limitations" \
   --header 'Authorization: Bearer pat_YourAccessTokenHere' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "entity_type": "enterprise_all_devices",
     "benefit_info": {
       "benefit_type": "voice_unified_duration_system",
       "active_mode": "absolute_time",
       "started_at": 1756684800,
       "ended_at": 253402300799,
       "limit": 1200,
       "trigger_unit": "day",
       "trigger_time": 1
     }
   }'
   ```

2. 调用[创建用量限额配置](/developer_guides/create_device_quotas) API，配置积分配额，示例代码如下：
   ```Shell
   curl --location --request POST "https://api.coze.cn/v1/commerce/benefit/limitations" \
   --header 'Authorization: Bearer pat_YourAccessTokenHere' \
   --header 'Content-Type: application/json' \
   --data-raw '{
     "entity_type": "enterprise_all_devices",
     "benefit_info": {
       "benefit_type": "resource_point",
       "active_mode": "absolute_time",
       "started_at": 1756684800,
       "ended_at": 253402300799,
       "limit": 500,
       "trigger_unit": "day",
       "trigger_time": 1
     }
   }'
   ```


### 相关 API {#3feca6b7}

* 更新设备权益额度：您可以通过调用[更新用量限额配置](/developer_guides/update_device_quotas) API，修改某条设备权益配额。
* 查询设备权益额度：您可以通过调用[查询用量限额配置](/developer_guides/get_device_quotas) API，查询已配置的权益额度信息。

## 设备用量查询 {#10a0a656}
通过设备用量查询，你可以查看智能设备的用量明细，包括：语音识别 ASR 的音频时长、语音合成 TTS 的字符数、语音合成 TTS 的对话次数、RTC 通话时长、消耗的积分等信息。
### 步骤一：导出设备账单 {#09f97e4b}
调用[导出终端用户账单](/developer_guides/create_bill_task) API，创建导出设备账单的任务。
该 API 为异步接口，若账单数据量较大，可能需等待约 1 分钟，当任务状态为 `succeed` 时，才会返回账单的下载链接。
示例代码如下：
```Shell
curl --location --request POST 'https://api.coze.cn/v1/commerce/benefit/bill_tasks' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json' \

 \
--data-raw '-d '{
  "started_at": 1743004800,
  "ended_at": 1743091200
}''
```

### 步骤二：查询账单文件 {#e6449206}
当导出设备账单的任务状态为 `succeed` 时，可以调用[查询账单文件](/developer_guides/billing_file) API 查询账单文件，获取对应账单文件的 URL 链接，以便下载或查看已导出的账单数据。
示例代码如下：
```Shell
curl --location --request GET 'https://api.coze.cn/v1/commerce/benefit/bill_tasks?page_num=1&page_size=50' \
--header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
--header 'Content-Type: application/json'
```

### 账单字段说明 {#030584bf}
账单文件中的字段说明请参见[账单推送回调事件](/developer_guides/billing_callback_message)。