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 查询单个成员
  • 更新成员角色: 设置组织管理员、组织成员、Config Admin 或 Directory 角色
  • 成员统计: 获取组织成员数量、席位使用等统计数据
  • 成员用量查询: 查询单个或批量成员的额度与使用情况（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"
}

10. 更新成员角色

PUT /v1/organizations/{organization_id}/members/{member_id}/role 将组织成员的角色设置为组织管理员、组织成员、Config Admin 或 Directory。适用于 CN / Global、Teams / Enterprise，复用管理台使用的 IAM 角色变更能力。

认证与权限

使用目标组织的 API Key：Authorization: Bearer <api_key>。API Key 必须属于路径指定的组织；服务账号凭证不能调用此接口。member_id 必须属于该组织。

路径参数

参数类型必填说明
organization_idstring是组织 ID
member_idstring是成员 ID，可通过成员查询接口获取，不是用户 ID

请求体

{
  "role": "org_admin"
}
字段类型必填说明
rolestring是org_admin：组织管理员；org_member：组织成员；org_config_admin：Config Admin；org_directory：Directory
role 不可省略、为 null 或为空字符串。不支持已废弃的 org_free_member 或其他角色。重复设置非计费角色时仍会执行 IAM 权益回收，可用于重试未完成的回收。

成功响应（200 OK）

直接返回更新后的成员详情，字段与获取成员详情接口一致。 
{
  "id": "member_abc123",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "org_admin",
  "status": "ENABLED",
  "joinedAt": "2026-09-01T08:00:00Z"
}

业务限制

  • 至少保留一名管理员（包括组织管理员和 Config Admin），具体角色切换限制与 Dashboard 共用 IAM 校验。
  • 已移除的成员不能变更角色；其他不可用成员状态由 IAM 拒绝。
  • Teams 升级 Enterprise 待生效期间禁止变更角色。
  • Config Admin 和 Directory 的新分配要求组织已开启 DirectoryRole 灰度，未开启时返回 403。两者为非计费角色，切换后沿用 IAM 释放席位、清理计费权益及撤销会话的流程；转回计费角色需有可用席位，失败时沿用 IAM 补偿流程。特殊账号限制与 Dashboard 一致。

错误响应

错误码HTTP 状态码说明
BadRequest400请求体格式错误、成员 ID 无效或成员状态不允许变更
InvalidRole400角色缺失或不在允许范围内
OrgMemberAdminCountLacked400不能移除最后一名管理员角色
OrganizationPendingUpgrade400组织正在等待 Teams 升级 Enterprise 生效
Unauthorized401凭证缺失或无效
Forbidden403凭证无权限，或目标新角色未开启组织灰度
UserNotTeamMember404成员不存在、已移除或不属于该组织
InternalError500服务内部错误
其他 IAM 业务错误沿用标准 OpenAPI 错误响应，包含 requestId、code、message。 
{
  "requestId": "req_abc123",
  "code": "InvalidRole",
  "message": "role must be org_admin, org_member, org_config_admin or org_directory"
}

调用示例

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

11. 批量创建邮件邀请

POST /v1/organizations/{organization_id}/members/emailInvitations 邀请用户加入组织。当前通过邮件发送邀请，被邀请人通过邮件链接注册或登录后接受邀请。

路径参数

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

邮件邀请前置条件

  • 创建、撤销、重发和删除邀请均受组织套餐限制。套餐过期、暂停、取消，或当前为已生效的免费套餐时，写操作会被拒绝；列表查询仍可使用。
  • 创建邀请时还需有可分配的席位。发送邀请不会预留席位，接受邀请时仍会检查并分配席位。
  • 邮箱域名已由其他组织管理时，不能向该邮箱发送邀请。若部署启用了邮箱域名校验（默认关闭），目标组织还须有已验证且启用的邮箱域名，受邀邮箱须与之匹配。
支持部分成功。每个邮箱的失败原因放在 failedEmails 中；即使所有邮箱都失败，也可能返回 200 OK。请求参数或组织前置条件不满足时，整个请求返回错误。

请求体

字段类型必填说明
emailsstring[]是每批 1 至 3000 个邮箱。去除首尾空白并转为小写；空字符串被忽略，处理后为空则报错。
rolestring否org_member 或 org_admin，默认 org_member。
inviterIdstring否邀请人的用户 UUID，用户必须存在。省略时使用组织创建者；创建者信息缺失时须显式提供。
expiresInHoursint32否有效期小时数，24 至 720；省略或超出该范围的 int32 值使用 168（7 天）；小数或超出 int32 范围的值会使请求体解析失败。

请求示例

{
  "emails": ["zhangsan@example.com", "invalid-email"],
  "role": "org_member"
}

成功响应（200 OK）

{
  "invitations": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "email": "zhangsan@example.com",
      "role": "org_member",
      "status": "PENDING",
      "expiresAt": "2026-10-22T08:00:00Z",
      "batchId": "770e8400-e29b-41d4-a716-446655440002",
      "createdAt": "2026-10-15T08:00:00Z",
      "updatedAt": "2026-10-15T08:00:00Z"
    }
  ],
  "failedEmails": [
    {
      "email": "invalid-email",
      "reason": "invalid email format"
    }
  ],
  "totalSent": 1,
  "totalFailed": 1
}

响应字段说明

字段类型说明
invitationsarray创建成功的邮件邀请对象，同一批次共享 batchId。无成功项时为空数组。
failedEmailsarray失败项，每项包含 email 和 reason；无失败项时为空数组。
totalSentint32创建成功的邀请数。邮件异步发送，此值不表示送达数量。
totalFailedint32失败项数量，包括校验失败和写入失败。

单个邮箱的失败原因

failedEmails[].reason 可能是错误码或文本，请保留原值以便排查。
reason说明
invalid email format邮箱格式无效。
duplicate email in batch规范化后在同一批次中重复。
pending invitation already exists for this email已有待接受的邀请。
this email has already joined the organization已有已接受的邀请记录。
OrgEmailInvitationUserInAnotherOrg用户已有组织成员关系，也可能已在当前组织中。
OrgEmailInvitationDomainOwnedByAnotherOrg邮箱域名由其他组织管理。
OrgEmailInvitationDomainNotMatched启用域名校验时，邮箱不匹配本组织的已验证域名。
internal_error_batch_write_failed批量写入失败。保留已成功项，仅针对失败项排查或重试。
根据 reason 解决失败原因后，通过创建接口重新提交需要重试的邮箱。不要重复提交已成功项；已有待接受邀请时，使用重发接口。

12. 列出邮件邀请

GET /v1/organizations/{organization_id}/members/emailInvitations

路径参数

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

查询参数

参数类型必填说明
statusstring否PENDING、JOINED、EXPIRED 或 CANCELLED。省略时查询全部状态。
batchIdstring否按创建响应中的批次 UUID 筛选。
maxResultsinteger否默认 20，最大 100。可解析为 int32 的正整数超过 100 时取 100；非正数或无法解析为 int32 时使用 20。
nextTokenstring否上一页返回的分页标记，首页不传。
status 不在上述枚举中，或 batchId 不是有效 UUID 时，返回 400 BadRequest。

成功响应（200 OK）

以下为最后一页： 
{
  "invitations": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "organizationId": "550e8400-e29b-41d4-a716-446655440000",
      "email": "zhangsan@example.com",
      "role": "org_member",
      "status": "PENDING",
      "expiresAt": "2026-10-22T08:00:00Z",
      "batchId": "770e8400-e29b-41d4-a716-446655440002",
      "createdAt": "2026-10-15T08:00:00Z",
      "updatedAt": "2026-10-15T08:00:00Z"
    }
  ],
  "maxResults": 20
}
invitations 是邀请数组，maxResults 是本次采用的每页数量。有下一页时返回 nextToken，后续请求原样传回；最后一页省略该字段。空列表返回 invitations: []。无效的 nextToken 会回到第一页。

邮件邀请对象

创建和列表响应中的 invitations[]、重发响应中的 invitation 使用相同结构。时间字段为 RFC 3339 字符串。
字段类型说明
idstring邀请 UUID，用于后续撤销、重发或删除。
organizationIdstring组织 ID。
emailstring受邀邮箱。
rolestring预分配角色，org_member 或 org_admin。
statusstringPENDING（待接受）、JOINED（已加入）、EXPIRED（已过期）、CANCELLED（已撤销）。
expiresAtstring过期时间。
joinedUserIdstring加入后的用户 ID，无值时省略。
joinedAtstring加入时间，无值时省略。
emailSentAtstring已记录的邮件发送时间，无值时省略。当前发送流程不保证更新此字段，不能用它判断邮件是否送达。
cancelledAtstring撤销时间，无值时省略。
batchIdstring批次 ID，无值时省略。
createdAtstring创建时间。
updatedAtstring更新时间。

13. 撤销邮件邀请

POST /v1/organizations/{organization_id}/members/emailInvitations/{invitation_id}/cancel

路径参数

参数类型必填说明
organization_idstring是组织 UUID。
invitation_idstring是邀请 UUID，取邀请对象的 id。
撤销、重发和删除邀请同样受组织套餐限制。 仅可撤销 PENDING 邀请。撤销后邀请失效，记录保留为 CANCELLED。无需请求体。

成功响应（200 OK）

id 为被撤销的邀请 ID： 
{
  "id": "660e8400-e29b-41d4-a716-446655440001"
}

14. 重发邮件邀请

POST /v1/organizations/{organization_id}/members/emailInvitations/{invitation_id}/resend

路径参数

参数类型必填说明
organization_idstring是组织 UUID。
invitation_idstring是邀请 UUID，取邀请对象的 id。
撤销、重发和删除邀请同样受组织套餐限制。 无需请求体，仅支持以下状态：
  • PENDING：复用原邀请，ID、链接和有效期不变。同一邀请的邮件发送使用 24 小时去重窗口。窗口内重复调用不会延长窗口，通常会跳过发送并返回 200 OK；窗口结束后的下一次发送尝试会开启新的 24 小时窗口。发送失败也可能占用该窗口。
  • EXPIRED：创建新邀请，保留邮箱、角色和邀请人，重新检查创建前置条件。新邀请有新的 ID、链接和批次 ID，有效期为默认 168 小时。创建成功后尝试删除旧记录；旧记录删除失败不影响成功响应。后续操作使用响应中的新 ID。
重发依据邀请的 status 分支处理，状态刷新可能有延迟。若 expiresAt 已过但仍返回 PENDING，重发不会延长有效期；需要新邀请时，先通过列表查询确认状态已变为 EXPIRED。 发送失败不会作为该接口的错误返回，200 OK 不代表邮件已送达。

成功响应（200 OK）

invitation 为本次使用的邀请对象： 
{
  "invitation": {
    "id": "660e8400-e29b-41d4-a716-446655440004",
    "organizationId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "zhangsan@example.com",
    "role": "org_member",
    "status": "PENDING",
    "expiresAt": "2026-10-22T08:00:00Z",
    "batchId": "770e8400-e29b-41d4-a716-446655440002",
    "createdAt": "2026-10-15T08:00:00Z",
    "updatedAt": "2026-10-15T08:00:00Z"
  }
}

15. 删除邮件邀请

DELETE /v1/organizations/{organization_id}/members/emailInvitations/{invitation_id}

路径参数

参数类型必填说明
organization_idstring是组织 UUID。
invitation_idstring是邀请 UUID，取邀请对象的 id。
撤销、重发和删除邀请同样受组织套餐限制。 无需请求体，可删除任意状态的邀请记录。待接受的邀请同时失效。删除 JOINED 记录不会移除组织成员；移除成员请使用删除成员。

成功响应（200 OK）

id 为被删除的邀请 ID： 
{
  "id": "660e8400-e29b-41d4-a716-446655440001"
}

错误码

错误码HTTP 状态码说明
BadRequest400请求参数无效（如 member_id 为空）；邀请接口：请求体无效、status / batchId 无效，或缺少组织订阅记录。
InvalidParameter400创建成员的 email 或 name 缺失或非法，或 userId 非法、与 email 同时使用；邀请接口：邮箱列表为空，或邀请人 / 邀请 ID 无效。inviterId is required 表示组织缺少创建者信息，需要显式传入邀请人。
InvalidPassword400密码缺失或不符合强度要求
InvalidRole400成员角色非法
EmailDomainRequired400组织未配置已验证且启用的邮箱域名
EmailDomainNotSupported400邮箱域名未在组织中启用
InsufficientSeats400组织没有可用席位
InvalidBatchQuotaRequest400批量用量查询的 JSON 请求体格式无效
InvalidAddOnCapFormat400addOnCap 格式无效
InvalidBatchAddOnCapRequest400批量 Add-On Cap 的 JSON 请求体格式无效
EmptyMemberIDs400memberIds 为空
TooManyMemberIDs400memberIds 超过 100 个
EmptyMemberIDAtIndex400memberIds 中存在空字符串
InsufficientMembers400组织成员数量不能低于最低要求
OrgEmailInvitationInviterNotFound400邀请人用户不存在，包括默认使用的组织创建者。
OrgEmailInvitationBatchSizeExceeded400批量邀请数量超过 3000。
OrgInvitationInsufficientSeats400创建邀请时组织没有可用席位。
OrgEmailInvitationNoVerifiedDomain400启用域名校验时，组织没有已验证且启用的域名。
OrgEmailInvitationDomainOwnedByAnotherOrg400重发邀请的邮箱域名由其他组织管理。
OrgEmailInvitationOrgMismatch400邀请不属于指定组织。
OrgEmailInvitationCannotCancel400邀请不是 PENDING 状态。
OrgEmailInvitationStatusNotResendable400邀请不是 PENDING 或 EXPIRED 状态。
OrgEmailInvitationCannotResend400过期邀请重建时未创建成功；订阅、席位等请求级失败会直接返回对应错误码。
Unauthorized401API Key 缺失或无效
Forbidden403无权限访问该组织
OrganizationPlanExpired403组织套餐过期、暂停、取消，或当前为已生效的免费套餐，禁止创建、撤销、重发和删除邀请。
NotFound404成员或邀请不存在。
UserNotTeamMember404用户不是该团队的成员
EmailAlreadyExists409邮箱已经注册
InternalError500服务器内部错误
请求级错误使用 requestId、code 和 message，与 200 OK 响应中的 failedEmails 分开处理。例如邀请人不存在时返回 400： 
{
  "requestId": "req_abc123",
  "code": "OrgEmailInvitationInviterNotFound",
  "message": "Inviter user does not exist, please provide a valid user id as inviter"
}
错误响应结构见 约定与规范 中的「错误响应」一节。

使用示例

列出成员

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"]
  }'

批量创建邮件邀请

curl -X POST "https://api.qoder.com/v1/organizations/org_xxx/members/emailInvitations" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"emails":["zhangsan@example.com","invalid-email"],"role":"org_member"}'

列出邮件邀请

curl --get "https://api.qoder.com/v1/organizations/org_xxx/members/emailInvitations" \
  -H "Authorization: Bearer <api_key>" \
  --data-urlencode "status=PENDING" \
  --data-urlencode "maxResults=20"

撤销邮件邀请

curl -X POST "https://api.qoder.com/v1/organizations/org_xxx/members/emailInvitations/660e8400-e29b-41d4-a716-446655440001/cancel" \
  -H "Authorization: Bearer <api_key>"

重发邮件邀请

各操作示例独立使用。将下面的 ID 替换为实际处于 PENDING 或 EXPIRED 状态的邀请 ID；已撤销的邀请不能重发。 
curl -X POST "https://api.qoder.com/v1/organizations/org_xxx/members/emailInvitations/660e8400-e29b-41d4-a716-446655440004/resend" \
  -H "Authorization: Bearer <api_key>"

删除邮件邀请

curl -X DELETE "https://api.qoder.com/v1/organizations/org_xxx/members/emailInvitations/660e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer <api_key>"
快速入门
组织管理
安全
购买与计费
OpenAPI
解决方案