# 充值加油包

`POST` `/api/tokenBudget/grantTopup`

为指定身份主体的某个配额账户充值一次性追加额度（加油包），用于周期主额度不足时临时提额。不传 scopeAgentId 充入全局账户；传入共享配额的一组智能体中任意一个智能体的ID时，充入这组智能体共享的智能体组账户，要求该账户已存在。加油包不参与周期重置，用完即止、过期作废；消耗时先扣主额度再扣加油包，多个加油包之间先扣临近过期的。充值要求目标账户已存在，且所绑策略已分配给当前应用，否则返回 403 错误。本接口仅支持通过API调用。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### 请求体（JSON）

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| scopeAgentId | integer | 否 | 共享配额的一组智能体中任意一个智能体的ID，选填。不传或 0 表示充入主体的全局账户；传入时按该智能体所属智能体组定位到对应账户并将加油包充入该账户，组内智能体共享这份额度，要求该账户已存在 |
| tokenAmount | integer | 是 | 加油包额度（Token 数），必须大于0 |
| expireAt | string | 否 | 加油包失效时间，不传表示长期有效直到用完；传值时必须晚于当前时间。过期后剩余额度作废且不退还 |
| remark | string | 否 | 备注，选填，用于记录本次充值原因，最长200个字符 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | GrantTopupResultVO | 响应数据 |
|     topupId | integer | 新充值的加油包ID，后续撤销该加油包时需传入 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |