Skip to main content
OpenAPI

成员 API

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

文档说明

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

权限要求

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

概述

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

主要功能

  • 列出成员: 支持按用户 ID 或邮箱精确匹配和游标分页，可选包含已删除成员
  • 创建成员: 创建企业邮箱用户并加入组织，自动分配席位
  • 获取成员详情: 按成员 ID 查询单个成员
  • 成员统计: 获取组织成员数量、席位使用等统计数据
  • 成员用量查询: 查询单个或批量成员的额度与使用情况（Plan、资源包、总计）
  • 移除成员: 将成员从组织中移除
  • Add-On Cap 管理: 设置成员个人或批量的 Shared Add-On 额度上限

API 列表

1. 列出成员

GET /v1/organizations/{organization_id}/members 分页获取组织下的成员列表，支持按用户 ID 或邮箱精确匹配。

路径参数

参数类型必填说明
organization_idstring是组织 ID

查询参数

参数类型必填说明
userIdstring否按用户 UUID 精确匹配，不能与 email 同时使用
emailstring否邮箱精准查询
includeDeletedstring否设为 true 可包含已移除的成员
maxResultsinteger否每页数量（默认 20，最大 100）
nextTokenstring否分页游标
userId 必须是非空的标准 UUID。按 userId 或 email 精确匹配时，最多返回一个成员且不返回新的 nextToken；没有匹配成员时返回 200 OK 和空 members 数组。

成功响应 (200 OK)

默认查询（仅活跃成员）： 
{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_ghi789",
      "userId": "550e8400-e29b-41d4-a716-446655440001",
      "name": "王五",
      "role": "org_member",
      "status": "ENABLED",
      "joinedAt": "2025-07-10T14:30:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}
部分成员记录可能不返回 email 字段，集成时请按可选字段处理。
包含已删除成员（**includeDeleted=true**）： 
{
  "members": [
    {
      "id": "member_abc123",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "张三",
      "email": "zhangsan@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_def456",
      "userId": "550e8400-e29b-41d4-a716-446655440002",
      "name": "李四",
      "email": "lisi@example.com",
      "role": "org_member",
      "status": "DELETED",
      "joinedAt": "2025-03-15T10:00:00Z",
      "deletedAt": "2026-02-01T12:00:00Z"
    }
  ],
  "maxResults": 20
}
deletedAt 仅在成员已被删除时返回，活跃成员不包含此字段。未返回 nextToken 表示已到最后一页。

响应字段说明

字段类型说明
membersarray成员列表
members[].idstring成员 ID
members[].userIdstring用户 ID
members[].namestring成员名称
members[].emailstring成员邮箱（可能为空）
members[].rolestring角色名称（如 org_admin、org_member）
members[].statusstring成员状态：ENABLED（正常）、DISABLED（已停用）、UNACTIVATED（未激活）、APPROVE_PENDING（待审批）、APPROVE_DECLINED（审批拒绝）、DELETED（已移除）
members[].joinedAtstring加入时间（ISO 8601）
members[].deletedAtstring 或 null删除时间（ISO 8601），未删除时不返回
maxResultsint32本次请求的每页数量
nextTokenstring下一页游标，最后一页不返回

2. 获取成员详情

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

路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

成功响应 (200 OK)

活跃成员： 
{
  "id": "member_abc123",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "org_admin",
  "status": "ENABLED",
  "joinedAt": "2025-06-01T08:00:00Z"
}
已删除成员（**GetMember** 会自动包含已删除成员）： 
{
  "id": "member_def456",
  "userId": "550e8400-e29b-41d4-a716-446655440002",
  "name": "李四",
  "email": "lisi@example.com",
  "role": "org_member",
  "status": "DELETED",
  "joinedAt": "2025-03-15T10:00:00Z",
  "deletedAt": "2026-02-01T12:00:00Z"
}

响应字段说明

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

3. 创建成员

POST /v1/organizations/{organization_id}/members 创建新用户并加入当前组织。该接口只创建新账号；邮箱已注册时不会复用已有账号，也不会修改已有账号的密码。

路径参数

参数类型必填说明
organization_idstring是组织 ID

请求体（JSON）

{
  "email": "alice@example.com",
  "name": "Alice",
  "password": "StrongPassword123!",
  "role": "org_member"
}
字段类型必填说明
emailstring是新用户邮箱，邮箱域名必须已在组织中验证并启用
namestring是用户和成员展示名
passwordstring是初始密码，必须满足密码强度要求且不会在响应中返回
rolestring否成员角色，可选 org_member、org_admin，默认 org_member

成功响应（200 OK）

{
  "member": {
    "id": "member_abc123",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Alice",
    "email": "alice@example.com",
    "role": "org_member",
    "status": "ENABLED",
    "joinedAt": "2026-05-23T08:00:00Z"
  }
}

错误响应

错误码HTTP 状态码说明
InvalidParameter400email 或 name 缺失或非法
InvalidPassword400密码缺失或不符合强度要求
InvalidRole400角色不是 org_member 或 org_admin
EmailDomainRequired400组织未配置已验证且启用的邮箱域名
EmailDomainNotSupported400邮箱域名未在组织中启用
InsufficientSeats400组织没有可用席位
EmailAlreadyExists409邮箱已经注册

4. 获取成员统计

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

路径参数

参数类型必填说明
organization_idstring是组织 ID

成功响应 (200 OK)

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

响应字段说明

字段类型说明
totalMembersint32总成员数
billableMembersint32计费成员数
adminMembersint32管理员数量
purchasedSeatsint32已购买席位数
remainingSeatsint32剩余席位数

5. 删除成员

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

路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

成功响应 (200 OK)

成员在本周期有使用量（席位释放需等到周期结束）： 
{
  "id": "member_abc123",
  "hasBillingCycleUsage": true
}
成员在本周期无使用量（席位可立即释放）： 
{
  "id": "member_abc123",
  "hasBillingCycleUsage": false
}

响应字段说明

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

错误响应

成员不属于该团队 (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"
}

6. 获取成员用量

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

路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 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 表示用量已达上限。

响应字段说明

字段类型说明
userIdstring用户 ID
planQuotaobjectPlan 配额信息
resourcePackageQuotaobject资源包配额信息
totalQuotaobject总计配额信息（Plan + 资源包）
sharedQuotaobject 或 null组织共享包配额信息（如果成员所在组织无共享包，则该字段不返回）
lastResetAtstring上次重置时间（ISO 8601）
nextResetAtstring下次重置时间（ISO 8601）
statusstring用户状态：active 或 restricted
Quota Summary 字段说明
字段类型说明
usedValuefloat64已使用量
limitValuefloat64配额上限
unitstring单位（如 credits）

7. 批量获取成员用量

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

路径参数

参数类型必填说明
organization_idstring是组织 ID

请求体（JSON）

字段类型必填校验规则说明
memberIdsstring[]是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，不会部分成功。

响应字段说明

字段类型说明
quotasarray成员用量结果列表
quotas[].memberIdstring成员 ID
quotas[].userIdstring用户 ID
quotas[].planQuotaobjectPlan 配额信息；无数据时不返回
quotas[].resourcePackageQuotaobject资源包配额信息；无数据时不返回
quotas[].totalQuotaobject总计配额信息；无数据时不返回
quotas[].sharedQuotaobject组织共享包配额信息；无数据时不返回
quotas[].lastResetAtstring上次重置时间（ISO 8601）；无数据时不返回
quotas[].nextResetAtstring下次重置时间（ISO 8601）；无数据时不返回
quotas[].statusstringactive 或 restricted；无额度数据时不返回

8. 更新成员 Add-On Cap

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

路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID

请求参数 (JSON)

字段类型必填校验规则说明
addOnCapint64 或 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
}

响应字段说明

字段类型说明
memberIdstring成员 ID
emailstring成员邮箱
addOnCapint64 或 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"
}

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

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

路径参数

参数类型必填说明
organization_idstring是组织 ID

请求参数 (JSON)

字段类型必填校验规则说明
addOnCapint64 或 null否非负整数或 null额度上限，null 或省略表示不限制，0 表示禁用
memberIdsstring[]是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。

响应字段说明

字段类型说明
membersarray更新结果列表，与请求中 memberIds 顺序一致
members[].memberIdstring成员 ID
members[].previousAddOnCapint64更新前的额度上限；之前无限制时不返回

错误响应

addOnCap 格式无效 (400) 
{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}
memberIds 为空 (400) 
{
  "requestId": "req_abc123",
  "code": "EmptyMemberIDs",
  "message": "memberIds must not be empty"
}
memberIds 超过 100 个 (400) 
{
  "requestId": "req_abc123",
  "code": "TooManyMemberIDs",
  "message": "memberIds must not exceed 100"
}

错误码

错误码HTTP 状态码说明
BadRequest400请求参数无效（如 member_id 为空）
InvalidParameter400创建成员的 email 或 name 缺失或非法，或 userId 非法、与 email 同时使用
InvalidPassword400密码缺失或不符合强度要求
InvalidRole400成员角色非法
EmailDomainRequired400组织未配置已验证且启用的邮箱域名
EmailDomainNotSupported400邮箱域名未在组织中启用
InsufficientSeats400组织没有可用席位
InvalidBatchQuotaRequest400批量用量查询的 JSON 请求体格式无效
InvalidAddOnCapFormat400addOnCap 格式无效
InvalidBatchAddOnCapRequest400批量 Add-On Cap 的 JSON 请求体格式无效
EmptyMemberIDs400memberIds 为空
TooManyMemberIDs400memberIds 超过 100 个
EmptyMemberIDAtIndex400memberIds 中存在空字符串
InsufficientMembers400组织成员数量不能低于最低要求
Unauthorized401API Key 缺失或无效
Forbidden403无权限访问该组织
NotFound404成员不存在
UserNotTeamMember404用户不是该团队的成员
EmailAlreadyExists409邮箱已经注册
InternalError500服务器内部错误
错误响应结构见 约定与规范 中的「错误响应」一节。

使用示例

列出成员

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>"

按用户 ID 精确搜索成员

curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members?userId=550e8400-e29b-41d4-a716-446655440000" \
  -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 POST "https://api.qoder.com/v1/organizations/org_xxx/members" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","name":"Alice","password":"StrongPassword123!","role":"org_member"}'

获取成员统计

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"]
  }'
快速入门
组织管理
安全
购买与计费
OpenAPI
解决方案