服务权益

个人权益

GET /v1/entitlements

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

组织权益

GET /v1/partners/{partner_id}/entitlements

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

{
  "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。收到事件后重新查询本接口，不要从通知中直接计算余额。