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

# 成员 API

> 列出与查询组织成员、统计、配额与 Add-On Cap 等接口说明。

## 文档说明

本文面向需在组织外系统化管理成员与配额的集成方。调用前请完成 **[获取 API Key](/zh/account/teams/openapi/get-api-key)**，并阅读 **[约定与规范](/zh/account/teams/openapi/conventions)**。

### 权限要求

* 使用有效的 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)

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

```json theme={null}
{
  "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**`**）：**

```json theme={null}
{
  "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)

**活跃成员：**

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

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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

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

```json theme={null}
{
  "id": "member_abc123",
  "hasBillingCycleUsage": true
}
```

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

```json theme={null}
{
  "id": "member_abc123",
  "hasBillingCycleUsage": false
}
```

#### 响应字段说明

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

#### 错误响应

**成员不属于该团队 (404)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "UserNotTeamMember",
  "message": "User is not a member of this team"
}
```

**成员数量不足 (400)**

```json theme={null}
{
  "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)

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

```json theme={null}
{
  "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"
}
```

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

```json theme={null}
{
  "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`

一次查询多个成员的额度与使用情况。查询范围与[获取成员用量](#5-获取成员用量)一致。

#### 路径参数

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

#### 请求体（JSON）

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

```json theme={null}
{
  "memberIds": ["member_abc123", "member_def456"]
}
```

#### 成功响应（200 OK）

```json theme={null}
{
  "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` 表示禁用 |

#### 请求示例

**设置额度上限：**

```json theme={null}
{
  "addOnCap": 1000
}
```

**设置为不限制：**

```json theme={null}
{
  "addOnCap": null
}
```

#### 成功响应 (200 OK)

```json theme={null}
{
  "memberId": "member_abc123",
  "email": "zhangsan@example.com",
  "addOnCap": 1000
}
```

**不限制时：**

```json theme={null}
{
  "memberId": "member_abc123",
  "email": "zhangsan@example.com",
  "addOnCap": null
}
```

#### 响应字段说明

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

#### 错误响应

**addOnCap 格式无效 (400)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}
```

**成员不属于该团队 (404)**

```json theme={null}
{
  "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 列表              |

#### 请求示例

**批量设置额度上限：**

```json theme={null}
{
  "addOnCap": 1000,
  "memberIds": ["member_abc123", "member_def456"]
}
```

**批量设置为不限制：**

```json theme={null}
{
  "addOnCap": null,
  "memberIds": ["member_abc123"]
}
```

#### 成功响应 (200 OK)

```json theme={null}
{
  "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)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}
```

**memberIds 为空 (400)**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "memberIds must not be empty"
}
```

**memberIds 超过 100 个 (400)**

```json theme={null}
{
  "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      | 服务器内部错误                              |

错误响应结构见 [约定与规范](/zh/account/teams/openapi/conventions) 中的「错误响应」一节。

***

## 使用示例

### 列出成员

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

### 按邮箱精准搜索成员

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

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

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

### 获取成员详情

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"
```

### 获取成员统计

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/statistics" \
  -H "Authorization: Bearer <api_key>"
```

### 删除成员

```bash theme={null}
curl -X DELETE "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"
```

### 更新成员 Add-On Cap

```bash theme={null}
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
  }'
```

### 获取成员用量

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/quota" \
  -H "Authorization: Bearer <api_key>"
```

### 批量获取成员用量

```bash theme={null}
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

```bash theme={null}
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"]
  }'
```