计费组 API - Qoder CN

计费组 API 用于归属成员的 Credits 消耗、设置统计期间共享上限，以及查询统计期间用量。一个成员同一时间最多属于一个计费组。

适用版本：Enterprise。

调用前请先完成获取 API Key，并阅读 OpenAPI 约定与规范。

前置条件

请求头携带 Authorization: Bearer <api_key>。
带 JSON 请求体时，发送 Content-Type: application/json。
organization_id 必须是 API Key 所属组织。
成员分配请求使用用户 ID，而不是组织成员 ID。可从成员 API返回的 userId 字段获取。

关键行为

Unassigned 是系统内置计费组，用于容纳未明确分配计费组的成员，其 ID 为固定字符串 unassigned。
Unassigned 不可重命名、删除或设置计费组上限。
重新分配成员只会改变当前归属。已经产生的用量仍归属于消耗 Credits 时记录的计费组。
删除计费组后，当前成员会移至 Unassigned；历史用量、已删除计费组 ID 及其最后保存的名称仍可通过用量接口查询。
计费组上限和用量均以 Credits 表示。

数据模型

BillingGroup

字段	类型	说明
`id`	string	计费组 ID；系统内置组为 `unassigned`
`organizationId`	string	组织 ID
`name`	string	计费组名称；系统内置组始终为 `Unassigned`
`description`	string	描述；为空时省略
`isUnassigned`	boolean	是否为系统内置 `Unassigned` 计费组
`memberCount`	integer	当前分配到该组的成员数
`limitAmount`	number	统计期间 Credits 上限；`-1` 表示不限额，`0` 表示冻结
`currentUsed`	number	选中统计期间的 Credits 用量；该值可能超过配置的上限
`isBlocked`	boolean	选中统计期间用量是否已达到或超过非负上限
`creatorId`	string	创建人用户 ID；不可用时省略
`createdAt`	string	创建时间，ISO 8601 格式；不可用时省略
`updatedAt`	string	最后更新时间，ISO 8601 格式；不可用时省略

统计期间

统计期间是左闭右开区间：包含 periodStart，不包含 periodEnd。

字段	类型	说明
`periodStart`	string	统计期间开始时间，ISO 8601 格式
`periodEnd`	string	统计期间结束时间，ISO 8601 格式

API 参考

列出计费组

GET /v1/organizations/{organization_id}/billing-groups

查询参数	类型	必填	说明
`periodEnd`	string	否	RFC 3339 格式的精确统计期间结束时间；省略时使用当前或最近期间
`keyword`	string	否	匹配计费组名称，或当前成员的名称、邮箱
`maxResults`	integer	否	每页正式计费组数量，默认 20，最大 100
`nextToken`	string	否	上一页响应返回的游标

第一页会在正式计费组前添加系统生成的 Unassigned 行。该行不计入 maxResults，因此第一页最多可返回 maxResults + 1 条。传入 keyword 时，只有关键字匹配 Unassigned 名称或其当前成员时才返回该行。

成功响应（200 OK）

{
  "billingGroups": [
    {
      "id": "unassigned",
      "organizationId": "org_xxx",
      "name": "Unassigned",
      "isUnassigned": true,
      "memberCount": 4,
      "limitAmount": -1,
      "currentUsed": 320,
      "isBlocked": false
    },
    {
      "id": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34",
      "organizationId": "org_xxx",
      "name": "Platform",
      "description": "Platform cost center",
      "isUnassigned": false,
      "memberCount": 12,
      "limitAmount": 10000,
      "currentUsed": 4250,
      "isBlocked": false,
      "creatorId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-08-01T08:00:00Z",
      "updatedAt": "2026-08-10T09:30:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response",
  "selectedPeriod": {
    "periodStart": "2026-08-01T00:00:00Z",
    "periodEnd": "2026-09-01T00:00:00Z"
  }
}

selectedPeriod 表示各计费组的 currentUsed 和 isBlocked 所对应的统计期间；无可用期间时省略。limitAmount 是计费组的当前配置，并非历史快照。选择历史期间时，isBlocked 会将当前上限与所选历史期间的用量比较。最后一页省略 nextToken，调用方应将其视为不透明值。

创建计费组

POST /v1/organizations/{organization_id}/billing-groups name 会去除首尾空格，且不能为空。有效计费组的名称必须唯一。无论大小写，Unassigned 均为保留名称。

请求体

{
  "name": "Platform",
  "description": "Platform cost center"
}

字段	类型	必填	说明
`name`	string	是	计费组名称
`description`	string	否	计费组描述

成功时返回创建后的 BillingGroup，状态码为 201 Created。新计费组默认 limitAmount: -1（不限额）。创建计费组、设置上限和分配成员是互不具备事务性的独立请求；编排流程时请持久化返回的计费组 ID，并从失败步骤继续。

更新计费组

PUT /v1/organizations/{organization_id}/billing-groups/{billing_group_id} 未传字段保持不变；传入空的 description 可清空描述。系统内置 Unassigned 不可更新。

请求体

{
  "name": "Platform Engineering",
  "description": ""
}

字段	类型	必填	说明
`name`	string	否	新名称；去除首尾空格后不能为空
`description`	string	否	新描述；空字符串表示清空

成功时返回更新后的 BillingGroup，状态码为 200 OK。

删除计费组

DELETE /v1/organizations/{organization_id}/billing-groups/{billing_group_id} 系统内置 Unassigned 不可删除。删除其他计费组会将当前成员移至 Unassigned，历史用量仍保留对应 billingGroupId，并解析已删除计费组最后保存的名称。成功时返回 200 OK：

{}

设置计费组上限

POST /v1/organizations/{organization_id}/billing-groups/{billing_group_id}/limit 设置每个统计期间应用于该计费组的共享 Credits 上限。该字段必填，以防止因省略字段而意外将计费组冻结。新值会立即作用于后续 Credits 消耗。

请求体

{
  "limitAmount": 10000
}

支持以下取值：

`limitAmount`	含义
`-1`	不限额
`0`	冻结计费组
大于 `0`	该统计期间的 Credits 上限

该上限是软性拦截阈值：记录用量达到上限后，会阻止后续从组织共享 Credits 资源池中消耗。进行中或并发的消耗以及延迟记账可能使 currentUsed 超过 limitAmount，因此不要将其视为绝对硬上限。将上限降低到当前用量或以下，会阻止后续消耗。系统内置 Unassigned 不支持设置上限。成功时返回更新后的 BillingGroup，状态码为 200 OK。

分配单个成员

POST /v1/organizations/{organization_id}/billing-groups/assign 分配或重新分配一个组织成员。将 billingGroupId 设为 unassigned，可清除成员的明确计费组归属。

请求体

{
  "userId": "550e8400-e29b-41d4-a716-446655440001",
  "billingGroupId": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34"
}

字段	类型	必填	说明
`userId`	string	是	组织成员对应的用户 UUID
`billingGroupId`	string	是	目标计费组 ID，或 `unassigned`

成功时返回 200 OK：

{}

批量处理 Unassigned 成员

POST /v1/organizations/{organization_id}/billing-groups/resolve 将 Unassigned 中的成员移至一个正式计费组。与单成员分配接口不同，该接口不会重新分配已经属于其他正式计费组的成员，并会返回部分成功明细，而不是因单个成员失败而终止整个批次。

请求体

{
  "userIds": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "billingGroupId": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34"
}

userIds 至少包含一个用户 ID，且不应包含重复值。billingGroupId 必须指向正式计费组，不能为 unassigned。

成功响应（200 OK）

{
  "succeeded": 1,
  "failed": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440002",
      "reason": "not_unassigned"
    }
  ]
}

失败原因	含义
`not_found`	用户不存在
`not_in_org`	用户当前不是该组织成员
`not_unassigned`	成员已经属于正式计费组

列出计费组成员

GET /v1/organizations/{organization_id}/billing-groups/{billing_group_id}/members 将 billing_group_id 设为 unassigned，可列出未明确分配计费组的成员。

查询参数	类型	必填	说明
`keyword`	string	否	匹配成员名称或邮箱
`maxResults`	integer	否	每页数量，默认 20，最大 100
`nextToken`	string	否	上一页响应返回的游标

成功响应（200 OK）

{
  "members": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Alice",
      "email": "alice@example.com"
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

email 不可用时省略，最后一页省略 nextToken。没有当前成员的计费组 ID（包括未知 ID）会返回 200 OK 和空 members 数组。

获取计费组用量

GET /v1/organizations/{organization_id}/billing-groups/usage 按计费组、用户和统计期间返回汇总行。行的唯一维度为 (billingGroupId, userId, periodStart, periodEnd)。如果一个成员在同一期间内先后在两个计费组中消耗 Credits，该用户会返回两行。Credits 消耗时会固定其归属，因此成员重新分配或计费组删除后，历史用量行不会移动。

查询参数	类型	必填	说明
`billingGroupId`	string	否	计费组 ID，或 `unassigned`；省略时返回所有计费组
`periodEnd`	string	否	RFC 3339 格式的精确统计期间结束时间；省略时使用当前或最近期间
`maxResults`	integer	否	每页数量，默认 20，最大 100
`nextToken`	string	否	上一页响应返回的游标

建议使用列出用量统计期间返回的 periodEnd。如果时间戳不能精确匹配已知统计期间，响应可能为空。查询已删除计费组时，可将其保留的 ID 作为 billingGroupId 传入。已删除计费组不会出现在列出计费组响应中，请从不带计费组过滤的用量响应中枚举其 ID。汇总时应使用 billingGroupId 而不是名称，因为计费组改名也会改变历史用量行解析出的名称。

成功响应（200 OK）

{
  "rows": [
    {
      "billingGroupId": "9bcb59cb-07e6-4a2d-9655-56aaf16b0e34",
      "billingGroupName": "Platform",
      "isUnassigned": false,
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "memberName": "Alice",
      "email": "alice@example.com",
      "periodStart": "2026-08-01T00:00:00Z",
      "periodEnd": "2026-09-01T00:00:00Z",
      "billingCycle": "monthly",
      "usedCredits": 1250
    }
  ],
  "maxResults": 20,
  "nextToken": "cursor_from_response"
}

行字段	类型	说明
`billingGroupId`	string	用量记录时捕获的计费组 ID
`billingGroupName`	string	当前或最后保存的计费组名称；可解析软删除计费组，改名也会影响历史展示
`isUnassigned`	boolean	用量是否归属于 `Unassigned`
`userId`	string	用户 ID
`memberName`	string	成员名称
`email`	string	成员邮箱；可能为空
`periodStart`	string	统计期间开始时间，ISO 8601 格式；用量行始终返回
`periodEnd`	string	统计期间结束时间，ISO 8601 格式；用量行始终返回
`billingCycle`	string	该用量行的计费周期，例如 `monthly` 或 `yearly`
`usedCredits`	number	该统计期间内归属于该用户和计费组的 Credits

列出用量统计期间

GET /v1/organizations/{organization_id}/billing-groups/usage/periods 按从新到旧顺序返回组织当前可用的全部统计期间。即使当前套餐月尚无用量，也会包含该期间。该接口不分页，但不承诺无限期保留历史期间。

成功响应（200 OK）

{
  "periods": [
    {
      "periodStart": "2026-08-01T00:00:00Z",
      "periodEnd": "2026-09-01T00:00:00Z"
    },
    {
      "periodStart": "2026-07-01T00:00:00Z",
      "periodEnd": "2026-08-01T00:00:00Z"
    }
  ]
}

错误

错误响应使用 OpenAPI 约定与规范中定义的通用结构。

HTTP 状态码	错误码	常见原因
400	`BadRequest`	请求格式错误、RFC 3339 时间无效、缺少必填字段，或对 `Unassigned` 执行不支持的操作
401	`Unauthorized`	API Key 缺失或无效
403	`Forbidden`	API Key 不属于目标组织
404	`NotFound`	操作所需的计费组或成员不存在
409	`AlreadyExists`	已存在同名的有效计费组

计费组成员列表接口对未知计费组 ID 返回空列表。如需通过 NotFound 判断资源是否存在，请使用操作类接口。

​前置条件

​关键行为

​数据模型

​BillingGroup

​统计期间

​API 参考

​列出计费组

​成功响应（200 OK）

​创建计费组

​请求体

​更新计费组

​请求体

​删除计费组

​设置计费组上限

​请求体

​分配单个成员

​请求体

​批量处理 Unassigned 成员

​请求体

​成功响应（200 OK）

​列出计费组成员

​成功响应（200 OK）

​获取计费组用量

​成功响应（200 OK）

​列出用量统计期间

​成功响应（200 OK）

​错误

前置条件

关键行为

数据模型

BillingGroup

统计期间

API 参考

列出计费组

成功响应（200 OK）

创建计费组

请求体

更新计费组

请求体

删除计费组

设置计费组上限

请求体

分配单个成员

请求体

批量处理 Unassigned 成员

请求体

成功响应（200 OK）

列出计费组成员

成功响应（200 OK）

获取计费组用量

成功响应（200 OK）

列出用量统计期间

成功响应（200 OK）

错误