成员 API - Qoder

文档说明

本文面向需在组织外系统化管理成员与配额的集成方。调用前请完成 获取 API Key，并阅读 约定与规范。

权限要求

使用有效的 API Key（Authorization: Bearer）。
API Key 必须属于目标组织，且调用者权限需覆盖相应操作（以产品为准）。

概述

成员管理 API 提供组织成员的查询、统计、用量查看、移除以及 Add-On Cap 管理功能。所有接口通过 API Key 进行鉴权，需将 Key 对应到目标组织。

主要功能

列出成员: 支持关键词搜索和游标分页，可选包含已删除成员
获取成员详情: 按成员 ID 查询单个成员
成员统计: 获取组织成员数量、席位使用等统计数据
成员用量查询: 查询单个或批量成员的额度与使用情况（Plan、资源包、总计）
移除成员: 将成员从组织中移除
Add-On Cap 管理: 设置成员个人或批量的 Shared Add-On 额度上限

API 列表

1. 列出成员

GET /v1/organizations/{organization_id}/members 分页获取组织下的成员列表，支持按关键词搜索。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID

查询参数

参数	类型	必填	说明
`email`	string	否	邮箱精准查询
`includeDeleted`	string	否	设为 `true` 可包含已移除的成员
`maxResults`	integer	否	每页数量（默认 20，最大 100）
`nextToken`	string	否	分页游标

成功响应 (200 OK)

默认查询（仅活跃成员）：

{
  "members": [
    {
      "id": "member_abc123",
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_ghi789",
      "name": "王五",
      "role": "org_member",
      "status": "ENABLED",
      "joinedAt": "2025-07-10T14:30:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}

部分成员记录可能不返回 email 字段，集成时请按可选字段处理。

包含已删除成员（**includeDeleted=true**）：

{
  "members": [
    {
      "id": "member_abc123",
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_def456",
      "name": "李四",
      "email": "lisi@example.com",
      "role": "org_member",
      "status": "DELETED",
      "joinedAt": "2025-03-15T10:00:00Z",
      "deletedAt": "2026-02-01T12:00:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}

deletedAt 仅在成员已被删除时返回，活跃成员不包含此字段。nextToken 为空字符串表示已到最后一页。

响应字段说明

字段	类型	说明
`members`	array	成员列表
`members[].id`	string	成员 ID
`members[].name`	string	成员名称
`members[].email`	string	成员邮箱（可能为空）
`members[].role`	string	角色名称（如 `org_admin`、`org_member`）
`members[].status`	string	成员状态：`ENABLED`（正常）、`DISABLED`（已停用）、`UNACTIVATED`（未激活）、`APPROVE_PENDING`（待审批）、`APPROVE_DECLINED`（审批拒绝）、`DELETED`（已移除）
`members[].joinedAt`	string	加入时间（ISO 8601）
`members[].deletedAt`	string 或 null	删除时间（ISO 8601），未删除时不返回
`maxResults`	int32	本次请求的每页数量
`nextToken`	string	下一页游标，为空表示最后一页

2. 获取成员详情

GET /v1/organizations/{organization_id}/members/{member_id} 获取单个成员的详细信息。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID
`member_id`	string	是	成员 ID

成功响应 (200 OK)

活跃成员：

{
  "id": "member_abc123",
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "org_admin",
  "status": "ENABLED",
  "joinedAt": "2025-06-01T08:00:00Z"
}

已删除成员（**GetMember** 会自动包含已删除成员）：

{
  "id": "member_def456",
  "name": "李四",
  "email": "lisi@example.com",
  "role": "org_member",
  "status": "DELETED",
  "joinedAt": "2025-03-15T10:00:00Z",
  "deletedAt": "2026-02-01T12:00:00Z"
}

响应字段说明

同「列出成员」中的 members[] 字段。

3. 获取成员统计

GET /v1/organizations/{organization_id}/members/statistics 获取组织成员相关的统计数据。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID

成功响应 (200 OK)

{
  "totalMembers": 50,
  "billableMembers": 45,
  "adminMembers": 3,
  "purchasedSeats": 100,
  "remainingSeats": 55
}

响应字段说明

字段	类型	说明
`totalMembers`	int32	总成员数
`billableMembers`	int32	计费成员数
`adminMembers`	int32	管理员数量
`purchasedSeats`	int32	已购买席位数
`remainingSeats`	int32	剩余席位数

4. 删除成员

DELETE /v1/organizations/{organization_id}/members/{member_id} 将成员从组织中移除。移除前会检查成员在当前计费周期内是否有使用量。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID
`member_id`	string	是	成员 ID

成功响应 (200 OK)

成员在本周期有使用量（席位释放需等到周期结束）：

{
  "id": "member_abc123",
  "hasBillingCycleUsage": true
}

成员在本周期无使用量（席位可立即释放）：

{
  "id": "member_abc123",
  "hasBillingCycleUsage": false
}

响应字段说明

字段	类型	说明
`id`	string	被删除成员的 ID
`hasBillingCycleUsage`	bool	该成员在当前计费周期内是否有使用量（影响席位释放时间）

错误响应

成员不属于该团队 (404)

{
  "requestId": "req_abc123",
  "code": "UserNotTeamMember",
  "message": "User is not a member of this team"
}

成员数量不足 (400)

{
  "requestId": "req_abc123",
  "code": "InsufficientMembers",
  "message": "The number of organization members cannot be less than the minimum requirement"
}

5. 获取成员用量

GET /v1/organizations/{organization_id}/members/{member_id}/quota 查询指定成员的完整使用情况，包括 Plan 配额、资源包配额、总计配额和组织共享包配额。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID
`member_id`	string	是	成员 ID

成功响应 (200 OK)

有组织共享包、状态正常：

{
  "userId": "user_abc123",
  "planQuota": {
    "quotaSummary": {
      "usedValue": 350.5,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "resourcePackageQuota": {
    "quotaSummary": {
      "usedValue": 100.0,
      "limitValue": 500.0,
      "unit": "credits"
    }
  },
  "totalQuota": {
    "quotaSummary": {
      "usedValue": 450.5,
      "limitValue": 1500.0,
      "unit": "credits"
    }
  },
  "sharedQuota": {
    "quotaSummary": {
      "usedValue": 200.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z",
  "status": "active"
}

无组织共享包、用量已超限：

{
  "userId": "user_def456",
  "planQuota": {
    "quotaSummary": {
      "usedValue": 1000.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "totalQuota": {
    "quotaSummary": {
      "usedValue": 1000.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z",
  "status": "restricted"
}

当组织没有共享包时 sharedQuota 不返回；当成员没有资源包时 resourcePackageQuota 不返回。status 为 restricted 表示用量已达上限。

响应字段说明

字段	类型	说明
`userId`	string	用户 ID
`planQuota`	object	Plan 配额信息
`resourcePackageQuota`	object	资源包配额信息
`totalQuota`	object	总计配额信息（Plan + 资源包）
`sharedQuota`	object 或 null	组织共享包配额信息（如果成员所在组织无共享包，则该字段不返回）
`lastResetAt`	string	上次重置时间（ISO 8601）
`nextResetAt`	string	下次重置时间（ISO 8601）
`status`	string	用户状态：`active` 或 `restricted`

Quota Summary 字段说明

字段	类型	说明
`usedValue`	float64	已使用量
`limitValue`	float64	配额上限
`unit`	string	单位（如 `credits`）

6. 批量获取成员用量

POST /v1/organizations/{organization_id}/members/batchGetQuota 一次查询多个成员的额度与使用情况。查询范围与获取成员用量一致。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID

请求体（JSON）

字段	类型	必填	校验规则	说明
`memberIds`	string[]	是	1–100 个非空成员 ID	需要查询用量的成员列表

{
  "memberIds": ["member_abc123", "member_def456"]
}

成功响应（200 OK）

{
  "quotas": [
    {
      "memberId": "member_abc123",
      "userId": "user_abc123",
      "planQuota": {
        "quotaSummary": {
          "usedValue": 350.5,
          "limitValue": 1000.0,
          "unit": "credits"
        }
      },
      "resourcePackageQuota": {
        "quotaSummary": {
          "usedValue": 100.0,
          "limitValue": 500.0,
          "unit": "credits"
        }
      },
      "totalQuota": {
        "quotaSummary": {
          "usedValue": 450.5,
          "limitValue": 1500.0,
          "unit": "credits"
        }
      },
      "sharedQuota": {
        "quotaSummary": {
          "usedValue": 200.0,
          "limitValue": 1000.0,
          "unit": "credits"
        }
      },
      "lastResetAt": "2026-03-01T00:00:00Z",
      "nextResetAt": "2026-04-01T00:00:00Z",
      "status": "active"
    },
    {
      "memberId": "member_def456",
      "userId": "user_def456"
    }
  ]
}

quotas 数组与 memberIds 的顺序一致，重复的成员 ID 也会按原顺序返回。成员没有额度记录时，该项仅返回 memberId 和 userId。只要有任一成员不属于该组织，整个请求返回 404 NotFound，不会部分成功。

响应字段说明

字段	类型	说明
`quotas`	array	成员用量结果列表
`quotas[].memberId`	string	成员 ID
`quotas[].userId`	string	用户 ID
`quotas[].planQuota`	object	Plan 配额信息；无数据时不返回
`quotas[].resourcePackageQuota`	object	资源包配额信息；无数据时不返回
`quotas[].totalQuota`	object	总计配额信息；无数据时不返回
`quotas[].sharedQuota`	object	组织共享包配额信息；无数据时不返回
`quotas[].lastResetAt`	string	上次重置时间（ISO 8601）；无数据时不返回
`quotas[].nextResetAt`	string	下次重置时间（ISO 8601）；无数据时不返回
`quotas[].status`	string	`active` 或 `restricted`；无额度数据时不返回

7. 更新成员 Add-On Cap

PUT /v1/organizations/{organization_id}/members/{member_id}/addon-cap 更新成员的 Shared Add-On 额度上限（基于 Big Model Credits 配额）。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID
`member_id`	string	是	成员 ID

请求参数 (JSON)

字段	类型	必填	校验规则	说明
`addOnCap`	int64 或 null	是	非负整数或 null	额度上限，`null` 表示不限制，`0` 表示禁用

请求示例

设置额度上限：

{
  "addOnCap": 1000
}

设置为不限制：

{
  "addOnCap": null
}

成功响应 (200 OK)

{
  "memberId": "member_abc123",
  "email": "zhangsan@example.com",
  "addOnCap": 1000
}

不限制时：

{
  "memberId": "member_abc123",
  "email": "zhangsan@example.com",
  "addOnCap": null
}

响应字段说明

字段	类型	说明
`memberId`	string	成员 ID
`email`	string	成员邮箱
`addOnCap`	int64 或 null	当前额度上限，`null` 表示不限制

错误响应

addOnCap 格式无效 (400)

{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}

成员不属于该团队 (404)

{
  "requestId": "req_abc123",
  "code": "UserNotTeamMember",
  "message": "User is not a member of this team"
}

8. 批量更新成员 Add-On Cap

POST /v1/organizations/{organization_id}/batchUpdateAddOnCap 批量更新指定成员的 Shared Add-On 额度上限（基于 Big Model Credits 配额）。单次请求最多 100 个成员，所有成员设置为相同的额度上限。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID

请求参数 (JSON)

字段	类型	必填	校验规则	说明
`addOnCap`	int64 或 null	是	非负整数或 null	额度上限，`null` 表示不限制，`0` 表示禁用
`memberIds`	string[]	是	1～100 个非空字符串	需要更新的成员 ID 列表

请求示例

批量设置额度上限：

{
  "addOnCap": 1000,
  "memberIds": ["member_abc123", "member_def456"]
}

批量设置为不限制：

{
  "addOnCap": null,
  "memberIds": ["member_abc123"]
}

成功响应 (200 OK)

{
  "members": [
    {
      "memberId": "member_abc123",
      "previousAddOnCap": 500
    },
    {
      "memberId": "member_def456",
      "previousAddOnCap": null
    }
  ]
}

previousAddOnCap 为 null 表示该成员之前未设置限制（无限制）。

响应字段说明

字段	类型	说明
`members`	array	更新结果列表，与请求中 `memberIds` 顺序一致
`members[].memberId`	string	成员 ID
`members[].previousAddOnCap`	int64 或 null	更新前的额度上限，`null` 表示之前未设置限制

错误响应

addOnCap 格式无效 (400)

{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}

memberIds 为空 (400)

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "memberIds must not be empty"
}

memberIds 超过 100 个 (400)

{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "memberIds must not exceed 100"
}

错误码

错误码	HTTP 状态码	说明
`BadRequest`	400	请求参数无效（如 member_id 为空、addOnCap 为负数）
`InvalidBatchQuotaRequest`	400	批量用量查询的 JSON 请求体格式无效
`InvalidAddOnCapFormat`	400	addOnCap 格式无效
`InsufficientMembers`	400	组织成员数量不能低于最低要求
`Unauthorized`	401	API Key 缺失或无效
`Forbidden`	403	无权限访问该组织
`NotFound`	404	成员不存在
`UserNotTeamMember`	404	用户不是该团队的成员
`InternalError`	500	服务器内部错误

错误响应结构见约定与规范中的「错误响应」一节。

使用示例

列出成员

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members?maxResults=20" \
  -H "Authorization: Bearer <api_key>"

按邮箱精准搜索成员

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members?email=zhangsan@example.com" \
  -H "Authorization: Bearer <api_key>"

列出成员（包含已移除）

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members?includeDeleted=true" \
  -H "Authorization: Bearer <api_key>"

获取成员详情

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"

获取成员统计

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/statistics" \
  -H "Authorization: Bearer <api_key>"

删除成员

curl -X DELETE "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"

更新成员 Add-On Cap

curl -X PUT "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/addon-cap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "addOnCap": 1000
  }'

获取成员用量

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/quota" \
  -H "Authorization: Bearer <api_key>"

批量获取成员用量

curl -X POST "https://api.qoder.com/v1/organizations/org_xxx/members/batchGetQuota" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "memberIds": ["member_abc123", "member_def456"]
  }'

批量更新成员 Add-On Cap

curl -X POST "https://api.qoder.com/v1/organizations/org_xxx/batchUpdateAddOnCap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "addOnCap": 1000,
    "memberIds": ["member_abc123", "member_def456"]
  }'

​文档说明

​权限要求

​概述

​主要功能

​API 列表

​1. 列出成员

​路径参数

​查询参数

​成功响应 (200 OK)

​响应字段说明

​2. 获取成员详情

​路径参数

​成功响应 (200 OK)

​响应字段说明

​3. 获取成员统计

​路径参数

​成功响应 (200 OK)

​响应字段说明

​4. 删除成员

​路径参数

​成功响应 (200 OK)

​响应字段说明

​错误响应

​5. 获取成员用量

​路径参数

​成功响应 (200 OK)

​响应字段说明

​6. 批量获取成员用量

​路径参数

​请求体（JSON）

​成功响应（200 OK）

​响应字段说明

​7. 更新成员 Add-On Cap

​路径参数

​请求参数 (JSON)

​请求示例

​成功响应 (200 OK)

​响应字段说明

​错误响应

​8. 批量更新成员 Add-On Cap

​路径参数

​请求参数 (JSON)

​请求示例

​成功响应 (200 OK)

​响应字段说明

​错误响应

​错误码

​使用示例

​列出成员

​按邮箱精准搜索成员

​列出成员（包含已移除）

​获取成员详情

​获取成员统计

​删除成员

​更新成员 Add-On Cap

​获取成员用量

​批量获取成员用量

​批量更新成员 Add-On Cap

文档说明

权限要求

概述

主要功能

API 列表

1. 列出成员

路径参数

查询参数

成功响应 (200 OK)

响应字段说明

2. 获取成员详情

路径参数

成功响应 (200 OK)

响应字段说明

3. 获取成员统计

路径参数

成功响应 (200 OK)

响应字段说明

4. 删除成员

路径参数

成功响应 (200 OK)

响应字段说明

错误响应

5. 获取成员用量

路径参数

成功响应 (200 OK)

响应字段说明

6. 批量获取成员用量

路径参数

请求体（JSON）

成功响应（200 OK）

响应字段说明

7. 更新成员 Add-On Cap

路径参数

请求参数 (JSON)

请求示例

成功响应 (200 OK)

响应字段说明

错误响应

8. 批量更新成员 Add-On Cap

路径参数

请求参数 (JSON)

请求示例

成功响应 (200 OK)

响应字段说明

错误响应

错误码

使用示例

列出成员

按邮箱精准搜索成员

列出成员（包含已移除）

获取成员详情

获取成员统计

删除成员

更新成员 Add-On Cap

获取成员用量

批量获取成员用量

批量更新成员 Add-On Cap