## 所需权限
<table> <thead> <tr> <td><p><b>所需权限</b></p></td> <td><p><b>资源</b></p></td> <td><p><b>Scope</b></p></td> <td><p><b>资源服务</b></p></td> </tr> </thead> <tbody> <tr> <td><p>用户与部门管理（管理）</p></td> <td><p>user-directory</p></td> <td><p>admin.v1.user-directory.manage</p></td> <td><p>qwenwork-biz-service</p></td> </tr> </tbody> </table>

```
HELPCODEESCAPE-http
POST /api/openapi/v1/users
```

## 公共请求头
适用《通过 API 配置 QwenWork 管理后台》的"认证与请求头"章节：`Authorization` 必填，`X-Request-Id` 可选；当前接口所需 Scope 见本页。

`Idempotency-Key` 是否适用及必填性以本页请求参数为准，不能用追踪标识替代幂等键。

## 邮箱可信域名规则
非空邮箱必须精确匹配组织当前已验证且未删除的可信域名；没有可信域名时返回 `422 directory_user_email_domain_not_verified`。不支持通配符或父域名继承。 没有可信域名时请省略 email，改用账号、手机号或工号；已有密码及账号的要求继续适用。 此项收紧零域名下原有写入规则。调用方应在升级前配置并验证域名，或按上述方式移除邮箱输入。 独立启用账号、授予席位及已有登录会话不因本次变更而新增限制。

## 第三方 ID 绑定
可选传入第三方 ID，在创建事务中绑定。非空值去首尾空白后最多 255 个字符，区分大小写；省略、null、空字符串或纯空白表示不绑定。

组织内已被其他用户占用时返回 409 / `directory_user_third_party_id_conflict`。

创建幂等键复用时必须保持同一 ID；此字段不替代既有账号、邮箱、手机号、工号四选一规则。

## 请求参数
请求体：必填；Content-Type：application/json。
<table> <thead> <tr> <td><p><b>名称</b></p></td> <td><p><b>位置</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> <td><p><b>示例</b></p></td> </tr> </thead> <tbody> <tr> <td><p>Idempotency-Key</p></td> <td><p>header</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>幂等键，用于避免重复提交</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>third_party_user_id</p></td> <td><p>body</p></td> <td><p>string \| null</p></td> <td><p>否</p></td> <td><p>创建时绑定；省略、null 或空白不绑定。</p></td> <td><p>"crc-user-001"</p></td> </tr> <tr> <td><p>account</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>提供初始密码或企业启用密码登录时必填。</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>department_ids</p></td> <td><p>body</p></td> <td><p>array \| null</p></td> <td><p>否</p></td> <td><p>当前组织内的部门，最多 200 项且不可重复</p></td> <td><p>\["\&lt;string\&gt;"\]</p></td> </tr> <tr> <td><p>email</p></td> <td><p>body</p></td> <td><p>string · email</p></td> <td><p>否</p></td> <td><p>邮箱</p></td> <td><p>"developer@example.com"</p></td> </tr> <tr> <td><p>initial_password</p></td> <td><p>body</p></td> <td><p>string · password</p></td> <td><p>否</p></td> <td><p>企业启用密码登录时必填；提供密码时必须同时提供非空账号。密码为 8--1024 个可打印、非空格 ASCII 字符，必须包含英文大写、小写字母及数字，特殊字符可选。</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>job_number</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>工号</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>name</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>姓名</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>phone</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>手机号</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>seat_status</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>席位授权</p></td> <td><p>"unassigned"</p></td> </tr> </tbody> </table>

## 请求示例
将 \<BASE_URL\> 替换为企业部署的千问办公 API 服务地址，并填写实际参数。示例中的占位值不能直接用于请求。

```
HELPCODEESCAPE-curl
curl --request POST \
  --url '<BASE_URL>/api/openapi/v1/users' \
  --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": "developer@example.com",
  "initial_password": "<string>",
  "job_number": "<string>",
  "name": "<string>",
  "phone": "<string>",
  "seat_status": "unassigned"
}'
```

## 响应状态表
本表描述业务服务返回；网关自行生成的响应以网关契约为准，本轮未验证部署网关返回。
<table> <thead> <tr> <td><p><b>HTTP 状态码</b></p></td> <td><p><b>触发条件</b></p></td> <td><p><b>响应结构引用</b></p></td> <td><p><b>客户端处理建议</b></p></td> </tr> </thead> <tbody> <tr> <td><p>201</p></td> <td><p>用户创建成功</p></td> <td><p>见本文"响应结果"</p></td> <td><p>保存返回的 qid；后续用它定位用户。</p></td> </tr> <tr> <td><p>400</p></td> <td><p>请求或依赖请求被拒绝</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构</p></td> <td><p>检查 code 与请求，不原样重试。</p></td> </tr> <tr> <td><p>401</p></td> <td><p>认证信息缺失或无效</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构</p></td> <td><p>核对凭据后重试。</p></td> </tr> <tr> <td><p>403</p></td> <td><p>Scope、授权范围或准入条件不满足</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构</p></td> <td><p>核对权限与目标资源。</p></td> </tr> <tr> <td><p>404</p></td> <td><p>目标用户或关联资源不存在</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构</p></td> <td><p>核对资源 ID 和当前状态。</p></td> </tr> <tr> <td><p>409</p></td> <td><p>业务状态或唯一字段冲突</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构; 见本文"字段冲突"</p></td> <td><p>按 code 和详情处理冲突，再决定是否重试。</p></td> </tr> <tr> <td><p>422</p></td> <td><p>参数或业务校验失败</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构</p></td> <td><p>修正参数后重试。</p></td> </tr> <tr> <td><p>503</p></td> <td><p>依赖不可用或写入后的同步尚未确认</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构; 见本文"已提交与同步恢复"</p></td> <td><p>先查询当前状态；仅有 committed=true 才确认已提交，按恢复信息处理。</p></td> </tr> <tr> <td><p>default</p></td> <td><p>其他未单列的业务服务错误</p></td> <td><p>见《通过 API 配置 QwenWork 管理后台》的"通用错误"结构</p></td> <td><p>保留状态码、code 与请求标识；不要推断已提交或已回滚。</p></td> </tr> </tbody> </table>

`Cache-Control: no-store`。

## 响应结果
本节仅描述返回信息，不增加请求参数。`sync_management` 仅在存在同步归属记录时返回；无记录时省略。它不是创建或更新用户时必须填写的对象。

历史来源快照需独立的 `admin.v1.directory-sync-runs.read` 权限；旧记录无执行 ID 或快照时，不以当前配置替代历史信息。
<table> <thead> <tr> <td><p><b>名称</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> <td><p><b>示例</b></p></td> </tr> </thead> <tbody> <tr> <td><p>account</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>账号</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>created_at</p></td> <td><p>string · date-time</p></td> <td><p>是</p></td> <td><p>用户创建时间。</p></td> <td><p>"2026-09-19T01:00:00Z"</p></td> </tr> <tr> <td><p>credential</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>密码生命周期信息，不包含密码或哈希。</p></td> <td><p><code>-</code></p></td> </tr> <tr> <td><p>department_ids</p></td> <td><p>array \| null</p></td> <td><p>是</p></td> <td><p>所属部门（部门 ID 列表）</p></td> <td><p>\["\&lt;string\&gt;"\]</p></td> </tr> <tr> <td><p>departments</p></td> <td><p>array</p></td> <td><p>是</p></td> <td><p>部门详情；无部门时为空数组。</p></td> <td><p><code>-</code></p></td> </tr> <tr> <td><p>email</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>邮箱</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>email_domain_valid</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>IAM 当前组织邮箱域校验结果。</p></td> <td><p>false</p></td> </tr> <tr> <td><p>job_number</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>工号</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>last_active_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>IAM 最近活跃时间；无记录时省略，不等同于最近业务使用时间。</p></td> <td><p>"2026-09-23T01:00:00Z"</p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>姓名</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>phone</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>手机号</p></td> <td><p>"\&lt;string\&gt;"</p></td> </tr> <tr> <td><p>phone_number_masked</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>脱敏电话。</p></td> <td><p><code>-</code></p></td> </tr> <tr> <td><p>qid</p></td> <td><p>string · uuid</p></td> <td><p>是</p></td> <td><p>QID</p></td> <td><p>"\&lt;uuid\&gt;"</p></td> </tr> <tr> <td><p>seat_status</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>席位授权 取值："assigned"、"unassigned"</p></td> <td><p>"assigned"</p></td> </tr> <tr> <td><p>source</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>IAM 实际创建来源；外部 ID 不代表同步来源。 取值："directory-sync"、"manual"</p></td> <td><p>"manual"</p></td> </tr> <tr> <td><p>status</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>用户状态 取值："active"、"disabled"、"pending"</p></td> <td><p>"pending"</p></td> </tr> <tr> <td><p>sync_management</p></td> <td><p>object</p></td> <td><p>否</p></td> <td><p>仅有同步归属记录时返回；不是请求参数。</p></td> <td><p><code>-</code></p></td> </tr> <tr> <td><p>third_party_user_id</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>第三方用户 ID；未设置时为空字符串。</p></td> <td><p>"external-001"</p></td> </tr> <tr> <td><p>updated_at</p></td> <td><p>string · date-time</p></td> <td><p>是</p></td> <td><p>更新时间</p></td> <td><p>"2026-08-27T10:00:00Z"</p></td> </tr> </tbody> </table>

### credential

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>credential_version</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>凭证版本。</p></td> </tr> <tr> <td><p>first_login_completed_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>首次登录完成时间；未完成时省略。</p></td> </tr> <tr> <td><p>must_change_password</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>是否需要修改密码。</p></td> </tr> <tr> <td><p>password_state</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>密码状态：unset 未设置、initial 初始密码、active 已生效；可选值：unset, initial, active 取值："active"、"initial"、"unset"</p></td> </tr> <tr> <td><p>password_updated_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>密码更新时间；无记录时省略。</p></td> </tr> </tbody> </table>

### departments\[\]

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>external_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>部门外部 ID；未设置时省略。</p></td> </tr> <tr> <td><p>id</p></td> <td><p>string · uuid</p></td> <td><p>是</p></td> <td><p>部门 ID。</p></td> </tr> <tr> <td><p>is_primary</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>是否为主部门。</p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>部门名称。</p></td> </tr> <tr> <td><p>path</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>部门路径。</p></td> </tr> </tbody> </table>

### sync_management

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>config_revision</p></td> <td><p>integer · int64</p></td> <td><p>否</p></td> <td><p>来源配置版本。</p></td> </tr> <tr> <td><p>created_by_sync</p></td> <td><p>boolean</p></td> <td><p>否</p></td> <td><p>权威创建来源；true 时 source=directory-sync，外部 ID 不代表同步来源。</p></td> </tr> <tr> <td><p>external_id</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>同步来源中的标识符。</p></td> </tr> <tr> <td><p>managed</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>是否由同步管理用户字段。</p></td> </tr> <tr> <td><p>managed_fields</p></td> <td><p>array</p></td> <td><p>是</p></td> <td><p>受管理的公开字段名称；使用 phone/job_number/department_ids。</p></td> </tr> <tr> <td><p>managed_org_unit_ids</p></td> <td><p>array \| null</p></td> <td><p>否</p></td> <td><p>受管理的部门 ID。</p></td> </tr> <tr> <td><p>run_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>来源执行 ID；通过 directory-sync/runs/{runId} 查询。</p></td> </tr> <tr> <td><p>source_id</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>同步来源 ID；通过 directory-sources 查配置，directory-sync/runs 查执行详情。</p></td> </tr> <tr> <td><p>source_type</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>同步来源类型。</p></td> </tr> </tbody> </table>

## 响应示例
`201`

```
HELPCODEESCAPE-json
{
  "account": "<string>",
  "department_ids": [
    "<string>"
  ],
  "email": "<string>",
  "job_number": "<string>",
  "name": "<string>",
  "phone": "<string>",
  "qid": "<uuid>",
  "email_domain_valid": false,
  "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"
}
```

## 特殊响应
### 字段冲突

复用结构：见《通过 API 配置 QwenWork 管理后台》的"公共错误字段"结构

仅用于 409 的唯一字段冲突；其他业务冲突可能只有通用错误。
<table> <thead> <tr> <td><p><b>名称</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> <td><p><b>示例</b></p></td> </tr> </thead> <tbody> <tr> <td><p>code</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>该分支必有的业务错误码。</p></td> <td><p>"request_rejected"</p></td> </tr> <tr> <td><p>details</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>仅在该错误分支有结构化详情时出现。</p></td> <td><p><code>-</code></p></td> </tr> </tbody> </table>

#### details

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>conflicts</p></td> <td><p>array</p></td> <td><p>是</p></td> <td><p>唯一字段冲突列表；不包含提交或恢复详情。</p></td> </tr> </tbody> </table>

#### details.conflicts\[\]

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>field</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>相关的公开请求字段名。</p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>冲突用户姓名；超出应用授权范围时省略。</p></td> </tr> <tr> <td><p>user_id</p></td> <td><p>string · uuid</p></td> <td><p>否</p></td> <td><p>相关用户 ID；冲突详情中超出授权范围时省略。</p></td> </tr> </tbody> </table>

### 响应示例 --- 409

```
HELPCODEESCAPE-json
{
  "error": "Conflict",
  "detail": "Third-party ID already exists.",
  "code": "directory_user_third_party_id_conflict",
  "details": {
    "conflicts": [
      {
        "field": "third_party_user_id"
      }
    ]
  }
}
```

### 已提交与同步恢复

复用结构：见《通过 API 配置 QwenWork 管理后台》的"公共错误字段"结构

仅在 details.committed=true 时使用。recovery 与 results 至少有一项；两者可以同时存在。没有该详情的 503 不证明写入已提交或回滚。
<table> <thead> <tr> <td><p><b>名称</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> <td><p><b>示例</b></p></td> </tr> </thead> <tbody> <tr> <td><p>code</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>该分支必有的业务错误码。 取值："iam_openapi_execution_unavailable"</p></td> <td><p>"iam_openapi_execution_unavailable"</p></td> </tr> <tr> <td><p>details</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>仅在该错误分支有结构化详情时出现。</p></td> <td><p><code>-</code></p></td> </tr> </tbody> </table>

#### details

至少包含字段：`recovery` / `results`
<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>committed</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>固定为 true：本地写入已提交，不代表同步成功。 取值：true</p></td> </tr> <tr> <td><p>recovery</p></td> <td><p>object</p></td> <td><p>否</p></td> <td><p>总体或该用户的同步恢复信息。</p></td> </tr> <tr> <td><p>results</p></td> <td><p>array</p></td> <td><p>否</p></td> <td><p>逐用户同步结果；可与总体 recovery 同时存在。</p></td> </tr> </tbody> </table>

#### details.recovery

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>automatic_retry</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>是否由系统自动重试。</p></td> </tr> <tr> <td><p>next_retry_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>下次重试时间；未安排时省略。</p></td> </tr> <tr> <td><p>requires_action</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>是否需要调用方或管理员处理。</p></td> </tr> <tr> <td><p>state</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>恢复状态：succeeded、processing、retrying、action_required、unconfirmed。 取值："action_required"、"processing"、"retrying"、"succeeded"、"unconfirmed"</p></td> </tr> </tbody> </table>

#### details.results\[\]

<table> <thead> <tr> <td><p><b>字段</b></p></td> <td><p><b>类型</b></p></td> <td><p><b>必填</b></p></td> <td><p><b>说明</b></p></td> </tr> </thead> <tbody> <tr> <td><p>code</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>稳定业务错误码；没有业务码时可省略。</p></td> </tr> <tr> <td><p>recovery</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>总体或该用户的同步恢复信息。</p></td> </tr> <tr> <td><p>user_id</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>本条同步结果的用户 ID。</p></td> </tr> </tbody> </table>

#### details.results\[\].recovery

复用结构：见本文"details.recovery"

用户写入等待与重试规则见API 首页"错误处理"中的"用户写入的同步等待与重试"。

### 响应示例 --- 503

```
HELPCODEESCAPE-json
{
  "error": "Service Unavailable",
  "detail": "The write was saved; synchronization is pending.",
  "code": "iam_openapi_execution_unavailable",
  "details": {
    "committed": true,
    "recovery": {
      "state": "processing",
      "automatic_retry": false,
      "requires_action": false
    }
  }
}
```