Skip to main content

更新用户接口

修改指定用户的姓名、联系方式、工号、账号或部门归属。只更新传入的字段，至少提供一项；部门列表整体替换，空列表归入根部门。此接口的请求字段不包含账号状态和席位状态。

  • Scope：admin.v1.user-directory.manage
  • 权限项：用户与部门管理（user-directory）
  • 权限类型：管理
  • 接口：PATCH/api/openapi/v1/users/{userId}

邮箱可信域名规则

非空邮箱必须精确匹配组织当前已验证且未删除的可信域名；没有可信域名时返回 422 directory_user_email_domain_not_verified。不支持通配符或父域名继承。 本接口按合并后的完整资料校验：省略 email 会保留原值，即使仅修改姓名或部门，只要结果仍有非空邮箱， 也必须满足域名规则。可以显式提交 "email": "" 清空，但仍须保留账号、手机号或工号至少一种有效身份。 此项收紧零域名下原有写入规则。调用方应在升级前配置并验证域名，或按上述方式移除邮箱输入。 独立启用账号、授予席位及已有登录会话不因本次变更而新增限制。

第三方 ID 补绑

可选传入第三方 ID，仅允许给未绑定用户补绑，或重复提交相同 ID。非空值去首尾空白后最多 255 个字符，区分大小写。省略或 null 保留写入时的最新绑定；空字符串或纯空白返回 422。替换已有绑定返回 409 / directory_user_third_party_id_rebind_forbidden；被同组织其他用户占用返回 409 / directory_user_third_party_id_conflict。仅传此字段即可补绑，其他资料保持原值；仍执行已有完整资料校验、用户范围与受管对象限制。

认证与请求头

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

请求参数

名称位置类型必填说明示例
userIdpathstring · uuid必填用户 ID"<uuid>"
Idempotency-Keyheaderstring否幂等键，用于避免重复提交"<string>"
third_party_user_idbodystring ｜ null否仅补绑或同值重试；省略/null 保留，禁止改绑与清空。"crc-user-001"
accountbodystring否账号"<string>"
department_idsbodyarray ｜ null否当前组织内的部门，最多 200 项且不可重复["<string>"]
emailbodystring否邮箱"<string>"
job_numberbodystring否工号"<string>"
namebodystring否姓名"<string>"
phonebodystring否手机号"<string>"

请求示例

curl --request PATCH \
  --url 'https://example.invalid/api/openapi/v1/users/<userId>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "third_party_user_id": "crc-user-001",
  "account": "<string>",
  "department_ids": [
    "<string>"
  ],
  "email": "<string>",
  "job_number": "<string>",
  "name": "<string>",
  "phone": "<string>"
}'

响应

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 可选，用于解释需处理原因；结果待确认不等于操作未执行。