Skip to main content

设置用户席位

为指定用户分配或回收千问办公席位。此接口只修改席位授权，不改变用户的启用状态和部门归属。

  • Scope：admin.v1.user-seats.manage
  • 权限项：用户席位管理（user-seats）
  • 权限类型：管理
  • 接口：PUT/api/openapi/v1/users/{userId}/seat
IAM 在受理新的授席操作前校验权威容量。无剩余席位时返回 HTTP 409 和 directory_user_seat_capacity_exceeded，不登记新的授席任务，审批申请保持待处理。 若预检后容量被其他操作耗尽，中心的明确容量拒绝同样返回该错误并停止席位目标自动重试， 不会把 IAM 实际席位标记为已授权。已提交的审批事实不回滚，应先查询申请和用户席位状态。 释放或增加席位后重新提交授席操作；有幂等键的已完成操作使用新键，已批准的申请通过用户授席接口处理。 网络超时等未知结果仍沿用 HTTP 503 和 iam_openapi_execution_unavailable，已保存的任务继续核验恢复； 组织余量为零时仍检查该用户在中心是否已经拥有席位，避免误判已成功但响应丢失的授予。 重复提交未确认的同一目标不会重置已有重试进度。只有中心确认授予成功后，IAM 才更新实际席位。

认证与请求头

使用应用 API Key 调用。当前接口只校验上方独立 Scope；读取、管理与执行权限互不隐含。
名称位置类型必填说明示例
Authorizationheaderstring是应用 API Key，使用 Bearer 方式传递。Bearer qwk_***
X-Request-Idheaderstring否可选的调用追踪标识；未传入时由服务端生成。req-20260831-001

请求参数

名称位置类型必填说明示例
userIdpathstring · uuid必填用户 ID"<uuid>"
authorizedbodyboolean必填席位授权false

请求示例

curl --request PUT \
  --url 'https://example.invalid/api/openapi/v1/users/<userId>/seat' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "authorized": false
}'

响应

200 OK

名称类型必填说明示例
accountstring否账号"<string>"
department_idsarray ｜ null是所属部门（部门 ID 列表）["<string>"]
emailstring否邮箱"<string>"
job_numberstring否工号"<string>"
namestring是姓名"<string>"
phonestring否手机号"<string>"
qidstring · uuid是QID"<uuid>"
seat_statusstring是席位授权"assigned"
sourcestring是来源"manual"
statusstring是用户状态"pending"
updated_atstring · date-time是更新时间"2026-08-27T10:00:00Z"
third_party_user_idstring是第三方用户 ID；未设置时为空字符串。"external-001"
departmentsarray是部门详情；无部门时为空数组。-
credentialobject是密码生命周期信息，不包含密码或哈希。-
created_atstring · date-time是用户创建时间。"2026-09-19T01:00:00Z"
last_active_atstring · date-time否IAM 最近活跃时间；无记录时省略，不等同于最近业务使用时间。"2026-09-23T01:00:00Z"

credential 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
credential_versioninteger · int64是凭证版本。
first_login_completed_atstring · date-time否首次登录完成时间；未完成时省略。
must_change_passwordboolean是是否需要修改密码。
password_statestring是密码状态：unset 未设置、initial 初始密码、active 已生效；可选值：unset, initial, active
password_updated_atstring · date-time否密码更新时间；无记录时省略。

departments[] 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
external_idstring否部门外部 ID；未设置时省略。
idstring · uuid是部门 ID。
is_primaryboolean是是否为主部门。
namestring是部门名称。
pathstring是部门路径。
{
  "account": "<string>",
  "department_ids": [
    "<string>"
  ],
  "email": "<string>",
  "job_number": "<string>",
  "name": "<string>",
  "phone": "<string>",
  "qid": "<uuid>",
  "seat_status": "assigned",
  "source": "manual",
  "status": "pending",
  "updated_at": "2026-08-27T10:00:00Z",
  "third_party_user_id": "external-001",
  "departments": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Engineering",
      "path": "Company/Engineering",
      "external_id": "external-dept",
      "is_primary": true
    }
  ],
  "credential": {
    "password_state": "active",
    "must_change_password": false,
    "credential_version": 2
  },
  "created_at": "2026-09-19T01:00:00Z",
  "last_active_at": "2026-09-23T01:00:00Z"
}

default Flat business error

名称类型必填说明示例
codestring否Stable business error code"<string>"
detailstring是Human-readable error description"<string>"
detailsOpenapiErrorDetails否错误详情-
errorstring是Stable HTTP error type"<string>"

details 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
committedboolean否本地写入是否已提交；不表示下游同步成功
fieldstring否校验失败的请求字段
reasonstring否校验失败的原因代码
recoveryobject否同步恢复状态与重试信息
resultsarray<object> ｜ null否各用户的处理结果
suggestionstring否建议使用的规范化值

details.recovery 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
automatic_retryboolean是是否自动重试
next_retry_atstring · date-time否下次重试时间
requires_actionboolean是是否需要人工处理
statestring是同步恢复状态；可选值：succeeded, processing, retrying, action_required, unconfirmed

details.results[] 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
codestring否Stable business error code
recoveryobject是同步恢复状态与重试信息
user_idstring是用户 ID

details.results[].recovery 字段

以下必填性针对对象存在时的子字段；父对象可否省略或为 null，以上层字段表为准。
字段类型必填说明
automatic_retryboolean是是否自动重试
next_retry_atstring · date-time否下次重试时间
requires_actionboolean是是否需要人工处理
statestring是同步恢复状态；可选值：succeeded, processing, retrying, action_required, unconfirmed
{
  "code": "<string>",
  "detail": "<string>",
  "details": {
    "field": "<string>",
    "reason": "<string>",
    "suggestion": "<string>"
  },
  "error": "<string>"
}

提交与同步结果

本地业务提交后最多等待 10 秒，同步确认成功立即返回本接口原成功响应，不固定等待满 10 秒。 同步仍在处理时保留 HTTP 503 / iam_openapi_execution_unavailable，增加已提交状态和恢复结果。 committed=true 表示本地写入已执行，不表示同步已完成；不要据此重新创建一笔写操作。 已有幂等键的操作应复用原键及原请求；先通过现有查询接口核对业务状态。 提交前校验失败仍返回原错误；确定业务拒绝保留相应状态和错误码，已提交的拒绝结果同样携带提交信息。 传输中断且没有收到提交证据时，不能推断已回滚。 错误示例（已提交、同步处理中）： 
{
  "error": "ServiceUnavailable",
  "code": "iam_openapi_execution_unavailable",
  "detail": "The operation was saved; review synchronization results before submitting another write.",
  "details": {
    "committed": true,
    "results": [{
      "user_id": "46ba2b7d-0a1d-50c4-a309-e1be8fb310f3",
      "recovery": { "state": "processing", "automatic_retry": false, "requires_action": false }
    }]
  }
}
recovery.state 为 succeeded、processing、retrying、action_required 或 unconfirmed。 automatic_retry 与 requires_action 描述实际恢复安排；next_retry_at 仅在已安排自动重试时提供。 results[].code 可选，用于解释需处理原因；结果待确认不等于操作未执行。