# 服务权益

## 个人权益

```http
GET /v1/entitlements
```

需要个人密钥和 `entitlements:read`。只返回密钥创建账号自己的权益。组织密钥调用此接口返回 `403 PERSONAL_KEY_REQUIRED`。

## 组织权益

```http
GET /v1/partners/{partner_id}/entitlements
```

需要绑定该组织的密钥和 `entitlements:read`。

```json
{
  "ok":true,
  "data":{
    "owner_type":"partner",
    "owner_id":"ORGANIZATION_ID",
    "games":[
      {"game":"minecraft","remaining_units":18,"unlimited":false,"total_units":40,"used_units":22,"expires_at":"2026-10-25T00:00:00.000Z","next_starts_at":null},
      {"game":"fps","remaining_units":0,"unlimited":false,"total_units":0,"used_units":0,"expires_at":null,"next_starts_at":null}
    ]
  },
  "request_id":"req_EXAMPLE"
}
```

| 字段 | 含义 |
| --- | --- |
| `remaining_units` | 当前有效权益的剩余计次数之和 |
| `unlimited` | 当前是否存在不限次数权益；为 true 时不能仅用 remaining_units 判断可用性 |
| `total_units` | 当前有效计次权益的总次数 |
| `used_units` | 当前有效权益关联的实际使用数，不包含已退回使用 |
| `expires_at` | 当前权益最早到期时间；存在永久有效权益或没有有效权益时可能为 null |
| `next_starts_at` | 已排队权益的最近开始时间，没有则为 null |

`expires_at:null` 不等于拥有永久免费服务。必须同时查看 `unlimited`、`remaining_units` 和实际有效权益状态。没有任何额度时仍成功返回两个游戏条目，计数为 0。

## 时间与扣次

个人已购买次数按当前业务规则长期有效；组织续订可能排队到当前周期结束后开始。当前返回值只描述查询时刻的有效汇总，不把未开始的未来额度加进当前余额。

此接口没有授予、修改、退款或支付能力，也不返回购买者身份、订单数据或管理员内部原因。额度查询与后续实际扣次之间可能发生变化，因此它只能用于显示和提醒；最终能否完成计次以平台执行实际操作时为准。

组织额度授予、调整、使用及周期开始/结束时可触发 `entitlement.updated`。收到事件后重新查询本接口，不要从通知中直接计算余额。