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

# 权益 API

权益 API 使用团队 AK/SK 的 HMAC 签名，不接受 OAuth Token、用户 API Key 或成员 Bearer Token。基础路径：`/open/v1/team/entitlements`。

以下两个接口均仅支持主账号拥有 ACTIVE（已生效）Open 权益的团队；Team、个人版以及无有效权益的账号不允许查询。

## Scope

| Scope                         | 能力                  |
| :---------------------------- | :------------------ |
| `team.entitlement.usage.read` | 查询团队整体或指定团队成员的权益使用量 |

团队 AK/SK 需显式配置该 Scope；已有成员查询权限不包含权益用量查询权限。

## 查询团队成员当前周期用量

```text theme={null}
POST /open/v1/team/entitlements/member-usage/current
Content-Type: application/json

{
  "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y",
  "codes": ["max_projects", "sandbox_runtime"]
}
```

所需 Scope：`team.entitlement.usage.read`。

**字段说明**

* `member_id`（string，必填）：团队成员公开 ID，格式为 `tm_...`，使用[团队成员 API](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/c0ca3603-79ca-40fa-aa93-0b6bc8be9ff9) 返回的真实成员编号。不能传秒悟内部用户 ID 或阿里云 OpenID。
* `codes`（string\[ ]，可选）：待查询的权益 code 列表。省略或传 `[ ]` 时查询全部支持项；重复 code 去重，按首次出现的顺序返回。传入任一不支持的 code，整个请求返回参数错误；`null` 不等同于空数组。

示例中的成员编号仅作格式演示，调用时请替换为凭证所属团队的真实成员编号。不接受额外的主账号、内部用户 ID 或起止时间参数。

**支持的权益 code**

| code                   | 权益展示名         |
| :--------------------- | :------------ |
| `max_projects`         | 项目数量          |
| `supabase_count`       | 云服务（AI数据库等）数量 |
| `supabase_db_storage`  | 数据存储空间        |
| `sandbox_runtime`      | 构建沙箱          |
| `cloud_function_count` | 云函数           |
| `fullstack_app_access` | 全栈应用访问        |
| `static_app_access`    | 静态应用访问        |

全量查询按上表顺序返回。展示名与单位以实际权益配置返回值为准；本接口不返回额度、剩余额度或权益可用性。

仅查询当前 AK/SK 绑定团队的成员。成员不存在或不属于当前团队时返回 404；已冻结或标记删除的成员仍可查询其用量。此接口不会创建成员、开通权益或发放积分。

省略 `codes`、查询全部支持项的请求：

```text theme={null}
{
  "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y"
}
```

响应：

```text theme={null}
{
  "member_id": "tm_Kx7Qm2pV9sRa4nBt6cWd8Y",
  "start_time": "2026-09-03T00:00:00",
  "end_time": "2026-10-03T00:00:00",
  "items": [
    {
      "code": "max_projects",
      "name": "项目数量",
      "used": 3,
      "unit": "个"
    },
    {
      "code": "sandbox_runtime",
      "name": "构建沙箱",
      "used": 120.5,
      "unit": "分钟"
    }
  ]
}
```

以上响应对应指定 `codes` 的首个请求，数值仅为示例。

**响应字段说明**

* `member_id`（string）：本次查询的公开成员 ID，与请求值一致。
* `start_time`（string）：主账号当前账期的开始时间。
* `end_time`（string）：主账号当前账期的结束时间。
* `items`（object\[ ]）：权益使用量明细，每项包含：
  * `code`（string）：权益 code。
  * `name`（string）：权益展示名。
  * `used`（number）：实际使用量，非负数，可包含小数。
  * `unit`（string）：用量单位，例如“个”“分钟”“GB”“次”。

`member_id`、`start_time`、`end_time` 仅在顶层返回，明细中不重复这三个字段。成功响应是对象，不是顶层数组，也不包含 `owner_id` 或内部用户 ID。

**账期与用量说明**

* 主账号及当前账期由服务端根据团队凭证解析，调用方无需也不能传入时间。
* `start_time`、`end_time` 保留账期服务返回的本地时间字符串，可带小数秒；不是 Unix epoch 毫秒时间戳，不额外附加或转换时区。
* 只有配置为 `MONTHLY` 的计量项使用该账期的开始、结束时间；其他周期类型（如 `NONE`）保持原有计量语义，不传账期过滤时间。因此，不能将顶层账期理解为所有 `items` 均在该区间内累计。
* 查询不按套餐是否包含该 code 或额度值（如 `0`、`-1`）进行拦截；但主账号必须满足 ACTIVE Open 准入要求。
* 任一项查询失败、配置缺失或返回无效用量时，整个请求失败；不返回部分明细，也不把异常用量降级为 `0`。

## 查询团队当前周期用量

```text theme={null}
POST /open/v1/team/entitlements/team-usage/current
Content-Type: application/json

{
  "codes": ["max_projects", "sandbox_runtime"]
}
```

所需 Scope：`team.entitlement.usage.read`。与成员用量接口共用权限，不新增 Scope。

本接口查询当前 AK/SK 绑定团队的整体用量：由服务端解析团队 Owner，查询 Owner 归属下不限定成员的用量，并非仅查询 Owner 本人产生的用量。

**字段说明**

* `codes`（string\[ ]，可选）：查询范围与上文成员接口相同，共用 7 项权益白名单。省略或传 `[ ]` 查询全部支持项；重复项去重，按首次出现的顺序返回。
* 不接受 `member_id`、内部成员 ID、主账号或起止时间字段；传入这些额外字段会返回 `400 invalid_request`，不会静默忽略。
* 请求体为 JSON 对象。查询全部权益可发送 `{}` 或 `{"codes":[ ]}`；`codes:null` 不等同于空数组。

响应：

```text theme={null}
{
  "start_time": "2026-09-03T00:00:00",
  "end_time": "2026-10-03T00:00:00",
  "items": [
    {
      "code": "max_projects",
      "name": "项目数量",
      "used": 12,
      "unit": "个"
    },
    {
      "code": "sandbox_runtime",
      "name": "构建沙箱",
      "used": 360.5,
      "unit": "分钟"
    }
  ]
}
```

以上数值仅为示例。

**响应字段说明**

* `start_time`（string）：主账号当前账期的开始时间。
* `end_time`（string）：主账号当前账期的结束时间。
* `items`（object\[ ]）：团队整体权益用量明细，每项包含 `code`、`name`、`used`、`unit`，含义与成员接口一致。
* 响应不包含 `member_id`、`owner_id` 或内部用户 ID，既不在顶层返回，也不在明细中返回。

**查询规则**

* 同样仅支持主账号拥有 ACTIVE Open 权益的团队；普通 Team、个人版及无有效权益均不允许查询。
* 服务端不读取目标成员关系，也不添加成员过滤条件；该接口不要求先创建或选择某个成员。
* 使用主账号当前账期原值，不重新计算或转换时区。只有配置为 `MONTHLY` 的计量项使用该账期；其他周期（如 `NONE`）保持原计量语义。“当前周期”不表示所有权益项都按该账期累计。
* 不按套餐是否包含 code 或额度值进行拦截。任一项查询失败、配置缺失或返回无效用量时，整个请求返回错误，不交付部分数据，不将异常降级为 `0`。
* 错误格式与下方“常见错误”一致；成员归属相关的 `404 not_found` 仅适用于成员用量接口。

## 常见错误

| HTTP | Code                      | 说明                                                         |
| :--- | :------------------------ | :--------------------------------------------------------- |
| 400  | `invalid_request`         | 请求格式不合法、codes 类型错误/不支持或携带不允许的字段；成员接口缺少有效 member\_id 也返回此错误 |
| 401  | `invalid_signature`       | 团队凭证、请求摘要或 HMAC 签名无效                                       |
| 401  | `signature_expired`       | 签名时间戳已过期                                                   |
| 401  | `signature_replayed`      | 签名 Nonce 已被使用                                              |
| 403  | `insufficient_scope`      | 团队凭证缺少 team.entitlement.usage.read 权限                      |
| 403  | `entitlement_required`    | 主账号没有 ACTIVE Open 权益                                       |
| 404  | `not_found`               | 仅成员接口：成员不存在或不属于当前团队                                        |
| 429  | `temporarily_unavailable` | 请求频率超过限制，或限流服务暂不可用                                         |
| 503  | `service_unavailable`     | 权益服务、账期数据、配置或任一计量项查询暂不可用                                   |

错误响应使用 `application/problem+json`，示例：

```text theme={null}
{
  "type": "about:blank",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "权益用量服务暂不可用",
  "code": "service_unavailable",
  "trace_id": "example_trace_id"
}
```

排查问题时请提供响应中的 `trace_id`。错误响应不返回 `items` 或部分用量数据。

HMAC 生成方法和完整调用流程见[团队系统集成指南](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/8b2e4f11-3395-4dd1-b58e-2e6935dd1392)。签名时使用本次调用接口的完整新路径和实际发送的 JSON 请求体；两个接口的路径不同，签名不可互换。