## 所需权限
<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>directory-sync-config</p></td> <td><p>admin.v1.directory-sync-config.manage</p></td> <td><p>qwenwork-biz-service</p></td> </tr> </tbody> </table>

```
HELPCODEESCAPE-http
PUT /api/openapi/v1/directory-sync/sources/{sourceId}
```

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

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

## 请求参数
请求体：必填；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>sourceId</p></td> <td><p>path</p></td> <td><p>string · uuid</p></td> <td><p>是</p></td> <td><p>数据源 ID</p></td> <td><p><code>"\&lt;uuid\&gt;"</code></p></td> </tr> <tr> <td><p>Idempotency-Key</p></td> <td><p>header</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>幂等键，用于避免重复提交 minLength=1 maxLength=128</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>config_revision</p></td> <td><p>body</p></td> <td><p>integer · int64</p></td> <td><p>否</p></td> <td><p>配置版本号 minimum=1</p></td> <td><p><code>1</code></p></td> </tr> <tr> <td><p>credentials</p></td> <td><p>body</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>default_seat</p></td> <td><p>body</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>新用户默认申请席位</p></td> <td><p><code>false</code></p></td> </tr> <tr> <td><p>deletion_alert_email</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>告警邮箱 maxLength=320</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>deletion_alert_enabled</p></td> <td><p>body</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>删除告警</p></td> <td><p><code>false</code></p></td> </tr> <tr> <td><p>deletion_alert_threshold</p></td> <td><p>body</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>删除告警阈值 minimum=0</p></td> <td><p><code>0</code></p></td> </tr> <tr> <td><p>deletion_policy</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>离职处理 取值："deactivate_and_reclaim_seat"、"deactivate_only"、"delete_user"</p></td> <td><p><code>"delete_user"</code></p></td> </tr> <tr> <td><p>initial_scim_token</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>初始 SCIM Token maxLength=255</p></td> <td><p><code>"\&lt;string\&gt;"</code></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>来源名称 maxLength=255</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>schedule</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>同步频率 取值："daily"、"every_6_hours"、"manual"</p></td> <td><p><code>"manual"</code></p></td> </tr> <tr> <td><p>schedule_anchor_at</p></td> <td><p>body</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>同步时间（北京时间）</p></td> <td><p><code>"2026-08-27T10:00:00Z"</code></p></td> </tr> <tr> <td><p>settings</p></td> <td><p>body</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>source_type</p></td> <td><p>body</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>数据源类型 取值："dingtalk"、"entra_id"、"feishu"、"openldap"、"scim"、"wecom"、"windows_ad"</p></td> <td><p><code>"dingtalk"</code></p></td> </tr> </tbody> </table>

### body.credentials 字段

<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>agent_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>应用 Agent ID（仅写入） maxLength=512</p></td> </tr> <tr> <td><p>app_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>应用 ID（仅写入） maxLength=512</p></td> </tr> <tr> <td><p>app_secret</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>应用密钥（仅写入） maxLength=4096</p></td> </tr> <tr> <td><p>bind_dn</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>LDAP 绑定 DN（仅写入） maxLength=2048</p></td> </tr> <tr> <td><p>bind_password</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>LDAP 绑定密码（仅写入） maxLength=4096</p></td> </tr> <tr> <td><p>client_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>客户端 ID（仅写入） maxLength=512</p></td> </tr> <tr> <td><p>client_secret</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>客户端密钥（仅写入） maxLength=4096</p></td> </tr> <tr> <td><p>corp_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>企业 ID（仅写入） maxLength=512</p></td> </tr> <tr> <td><p>secret</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>认证密钥（仅写入） maxLength=4096</p></td> </tr> <tr> <td><p>tenant_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>租户 ID（仅写入） maxLength=512</p></td> </tr> </tbody> </table>

### body.settings 字段

<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>connection</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>连接配置</p></td> </tr> <tr> <td><p>department_mapping</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>部门映射</p></td> </tr> <tr> <td><p>mapping</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>成员映射</p></td> </tr> <tr> <td><p>scope</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>同步范围</p></td> </tr> <tr> <td><p>wecom</p></td> <td><p>object</p></td> <td><p>否</p></td> <td><p>企业微信部署与地址配置</p></td> </tr> </tbody> </table>

### body.settings.connection 字段

<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>client_name</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>SCIM Client maxLength=255</p></td> </tr> <tr> <td><p>tls_enabled</p></td> <td><p>boolean</p></td> <td><p>否</p></td> <td><p>启用 TLS</p></td> </tr> <tr> <td><p>url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>服务器地址 maxLength=2048</p></td> </tr> </tbody> </table>

### body.settings.department_mapping 字段

<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（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>部门名称（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>order</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>排序（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>parent_external_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>上级第三方部门 ID（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>status</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>状态（来源字段） maxLength=128</p></td> </tr> </tbody> </table>

### body.settings.mapping 字段

<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>account</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>账号（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>department_external_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>所属部门的第三方部门 ID（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>email</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>邮箱（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>employee_no</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>工号（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>external_id</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>第三方用户 ID（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>用户姓名（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>phone</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>手机号（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>status</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>状态（来源字段） maxLength=128</p></td> </tr> </tbody> </table>

### body.settings.scope 字段

<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>base_dn</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>Base DN maxLength=2048</p></td> </tr> <tr> <td><p>mode</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>同步范围类型；可选值：all, departments, base_dn, administrative_units 取值："administrative_units"、"all"、"base_dn"、"departments"</p></td> </tr> <tr> <td><p>org_unit_external_ids</p></td> <td><p>array\&lt;string\&gt; \| null</p></td> <td><p>否</p></td> <td><p>范围部门（第三方部门 ID 列表） maxItems=200</p></td> </tr> <tr> <td><p>org_unit_filter</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>部门过滤器 maxLength=2048</p></td> </tr> <tr> <td><p>user_filter</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>用户过滤器 maxLength=2048</p></td> </tr> </tbody> </table>

### body.settings.wecom 字段

<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>api_base_url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>企业微信 API 基础地址 maxLength=2048</p></td> </tr> <tr> <td><p>authorization_url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>企业微信授权地址 maxLength=2048</p></td> </tr> <tr> <td><p>deployment</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>企业微信部署类型；可选值：standard, private 取值："private"、"standard"</p></td> </tr> </tbody> </table>

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

```
HELPCODEESCAPE-curl
curl --request PUT \
  --url '<BASE_URL>/api/openapi/v1/directory-sync/sources/<sourceId>' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: <UNIQUE_REQUEST_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "config_revision": 1,
  "credentials": {
    "agent_id": "<string>",
    "app_id": "<string>",
    "app_secret": "<string>",
    "bind_dn": "<string>",
    "bind_password": "<string>",
    "client_id": "<string>",
    "client_secret": "<string>",
    "corp_id": "<string>",
    "secret": "<string>",
    "tenant_id": "<string>"
  },
  "default_seat": false,
  "deletion_alert_email": "<string>",
  "deletion_alert_enabled": false,
  "deletion_alert_threshold": 0,
  "deletion_policy": "delete_user",
  "initial_scim_token": "<string>",
  "name": "<string>",
  "schedule": "manual",
  "schedule_anchor_at": "2026-08-27T10:00:00Z",
  "settings": {
    "connection": {
      "client_name": "<string>",
      "tls_enabled": false,
      "url": "<string>"
    },
    "department_mapping": {
      "external_id": "<string>",
      "name": "<string>",
      "order": "<string>",
      "parent_external_id": "<string>",
      "status": "<string>"
    },
    "mapping": {
      "account": "<string>",
      "department_external_id": "<string>",
      "email": "<string>",
      "employee_no": "<string>",
      "external_id": "<string>",
      "name": "<string>",
      "phone": "<string>",
      "status": "<string>"
    },
    "scope": {
      "base_dn": "<string>",
      "mode": "all",
      "org_unit_external_ids": [
        "<string>"
      ],
      "org_unit_filter": "<string>",
      "user_filter": "<string>"
    }
  },
  "source_type": "dingtalk"
}'
```

## 响应状态表
<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>200</p></td> <td><p>请求成功</p></td> <td><p>见本文"响应结果"</p></td> <td><p>读取响应结果。</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>

## 响应结果
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> </tr> </thead> <tbody> <tr> <td><p>config_revision</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>配置版本号</p></td> <td><p><code>0</code></p></td> </tr> <tr> <td><p>connection_status</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>连接状态</p></td> <td><p><code>"\&lt;string\&gt;"</code></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><code>"2026-08-27T10:00:00Z"</code></p></td> </tr> <tr> <td><p>created_by_email</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>创建人邮箱</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>created_by_name</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>创建人</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>credential_configured</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>是否已配置凭据</p></td> <td><p><code>false</code></p></td> </tr> <tr> <td><p>default_seat</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>新用户默认申请席位</p></td> <td><p><code>false</code></p></td> </tr> <tr> <td><p>deletion_alert_email</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>告警邮箱</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>deletion_alert_enabled</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>删除告警</p></td> <td><p><code>false</code></p></td> </tr> <tr> <td><p>deletion_alert_threshold</p></td> <td><p>integer · int64</p></td> <td><p>是</p></td> <td><p>删除告警阈值</p></td> <td><p><code>0</code></p></td> </tr> <tr> <td><p>deletion_policy</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>离职处理</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>external_id_field</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>第三方用户 ID 映射字段</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>external_id_field_locked</p></td> <td><p>boolean</p></td> <td><p>是</p></td> <td><p>第三方用户 ID 映射是否已锁定</p></td> <td><p><code>false</code></p></td> </tr> <tr> <td><p>id</p></td> <td><p>string · uuid</p></td> <td><p>是</p></td> <td><p>数据源 ID</p></td> <td><p><code>"\&lt;uuid\&gt;"</code></p></td> </tr> <tr> <td><p>last_activity_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>最近活动时间</p></td> <td><p><code>"2026-08-27T10:00:00Z"</code></p></td> </tr> <tr> <td><p>last_connected_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>最近连接时间</p></td> <td><p><code>"2026-08-27T10:00:00Z"</code></p></td> </tr> <tr> <td><p>last_connection_error_code</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>最近连接错误码</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>modified_at</p></td> <td><p>string · date-time</p></td> <td><p>是</p></td> <td><p>更新时间</p></td> <td><p><code>"2026-08-27T10:00:00Z"</code></p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>来源名称</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>next_run_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>下次同步时间</p></td> <td><p><code>"2026-08-27T10:00:00Z"</code></p></td> </tr> <tr> <td><p>schedule</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>同步频率</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>schedule_anchor_at</p></td> <td><p>string · date-time</p></td> <td><p>否</p></td> <td><p>同步时间（北京时间）</p></td> <td><p><code>"2026-08-27T10:00:00Z"</code></p></td> </tr> <tr> <td><p>settings</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>source_type</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>数据源类型</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>status</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>状态</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>updated_by_email</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>更新人邮箱</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> <tr> <td><p>updated_by_name</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>更新人</p></td> <td><p><code>"\&lt;string\&gt;"</code></p></td> </tr> </tbody> </table>

### settings

<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>connection</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>连接配置</p></td> </tr> <tr> <td><p>department_mapping</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>部门映射</p></td> </tr> <tr> <td><p>mapping</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>成员映射</p></td> </tr> <tr> <td><p>scope</p></td> <td><p>object</p></td> <td><p>是</p></td> <td><p>同步范围</p></td> </tr> <tr> <td><p>wecom</p></td> <td><p>object</p></td> <td><p>否</p></td> <td><p>企业微信部署与地址配置</p></td> </tr> </tbody> </table>

#### settings.connection

<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>client_name</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>SCIM Client maxLength=255</p></td> </tr> <tr> <td><p>tls_enabled</p></td> <td><p>boolean</p></td> <td><p>否</p></td> <td><p>启用 TLS</p></td> </tr> <tr> <td><p>url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>服务器地址 maxLength=2048</p></td> </tr> </tbody> </table>

#### settings.department_mapping

<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（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>部门名称（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>order</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>排序（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>parent_external_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>上级第三方部门 ID（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>status</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>状态（来源字段） maxLength=128</p></td> </tr> </tbody> </table>

#### settings.mapping

<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>account</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>账号（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>department_external_id</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>所属部门的第三方部门 ID（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>email</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>邮箱（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>employee_no</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>工号（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>external_id</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>第三方用户 ID（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>name</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>用户姓名（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>phone</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>手机号（来源字段） maxLength=128</p></td> </tr> <tr> <td><p>status</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>状态（来源字段） maxLength=128</p></td> </tr> </tbody> </table>

#### settings.scope

<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>base_dn</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>Base DN maxLength=2048</p></td> </tr> <tr> <td><p>mode</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>同步范围类型；可选值：all, departments, base_dn, administrative_units 取值："administrative_units"、"all"、"base_dn"、"departments"</p></td> </tr> <tr> <td><p>org_unit_external_ids</p></td> <td><p>array\&lt;string\&gt; \| null</p></td> <td><p>否</p></td> <td><p>范围部门（第三方部门 ID 列表） maxItems=200</p></td> </tr> <tr> <td><p>org_unit_filter</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>部门过滤器 maxLength=2048</p></td> </tr> <tr> <td><p>user_filter</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>用户过滤器 maxLength=2048</p></td> </tr> </tbody> </table>

#### settings.wecom

<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>api_base_url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>企业微信 API 基础地址 maxLength=2048</p></td> </tr> <tr> <td><p>authorization_url</p></td> <td><p>string</p></td> <td><p>否</p></td> <td><p>企业微信授权地址 maxLength=2048</p></td> </tr> <tr> <td><p>deployment</p></td> <td><p>string</p></td> <td><p>是</p></td> <td><p>企业微信部署类型；可选值：standard, private 取值："private"、"standard"</p></td> </tr> </tbody> </table>

## 三方成员自定义字段映射
钉钉、飞书、企业微信允许在 `settings.mapping` 的 `external_id`、`name`、`email`、`phone`、`employee_no`、`account`、`status` 中填写自定义来源路径。部门及成员关系保持原规则，其他来源不扩展。
<table> <thead> <tr> <td><p><b>来源</b></p></td> <td><p><b>示例</b></p></td> </tr> </thead> <tbody> <tr> <td><p>普通成员字段</p></td> <td><p>user.profile.identifier</p></td> </tr> <tr> <td><p>钉钉扩展属性</p></td> <td><p>user.extension\["成本中心"\]</p></td> </tr> <tr> <td><p>飞书自定义属性（按字段 ID）</p></td> <td><p>user.custom_attrs\["C-123"\].value.text</p></td> </tr> <tr> <td><p>企业微信扩展属性（按名称）</p></td> <td><p>user.extattr.attrs\["员工编号"\].text.value</p></td> </tr> </tbody> </table>

完整路径最多 128 个字符，支持对象点路径及双引号括号键；不支持脚本、通配符或数组下标。只读取当前成员接口已返回的标量，配置不会授予字段读取权限，也不会新增逐人补查。

缺失／空白／不适用类型沿用现有空值保留规则；同 ID／名称出现冲突值时不选取任意一项。状态沿用通用状态值规则，不执行自定义转换。第三方 ID 缺失或冲突按原校验与清理保护处理。

原预设、历史别名和企微 `employee_no` 工号兼容逻辑保持。路径无效返回既有 422 来源配置错误；Scope、权限、接口结构及并发版本规则不变。

## 响应示例
```
HELPCODEESCAPE-json
{
  "config_revision": 0,
  "connection_status": "<string>",
  "created_at": "2026-08-27T10:00:00Z",
  "created_by_email": "<string>",
  "created_by_name": "<string>",
  "credential_configured": false,
  "default_seat": false,
  "deletion_alert_email": "<string>",
  "deletion_alert_enabled": false,
  "deletion_alert_threshold": 0,
  "deletion_policy": "<string>",
  "external_id_field": "<string>",
  "external_id_field_locked": false,
  "id": "<uuid>",
  "last_activity_at": "2026-08-27T10:00:00Z",
  "last_connected_at": "2026-08-27T10:00:00Z",
  "last_connection_error_code": "<string>",
  "modified_at": "2026-08-27T10:00:00Z",
  "name": "<string>",
  "next_run_at": "2026-08-27T10:00:00Z",
  "schedule": "<string>",
  "schedule_anchor_at": "2026-08-27T10:00:00Z",
  "settings": {
    "connection": {
      "client_name": "<string>",
      "tls_enabled": false,
      "url": "<string>"
    },
    "department_mapping": {
      "external_id": "<string>",
      "name": "<string>",
      "order": "<string>",
      "parent_external_id": "<string>",
      "status": "<string>"
    },
    "mapping": {
      "account": "<string>",
      "department_external_id": "<string>",
      "email": "<string>",
      "employee_no": "<string>",
      "external_id": "<string>",
      "name": "<string>",
      "phone": "<string>",
      "status": "<string>"
    },
    "scope": {
      "base_dn": "<string>",
      "mode": "all",
      "org_unit_external_ids": [
        "<string>"
      ],
      "org_unit_filter": "<string>",
      "user_filter": "<string>"
    }
  },
  "source_type": "<string>",
  "status": "<string>",
  "updated_by_email": "<string>",
  "updated_by_name": "<string>"
}
```

## 企业微信私有化配置
企业微信保持 `source_type: "wecom"`。`settings.wecom` 为可选对象：`deployment` 为 `standard` 或 `private`， `api_base_url` 为私有化企微的 HTTPS API 基础地址；`authorization_url` 为可选授权地址。 未配置时使用标准版固定地址；更新省略 `settings.wecom` 时保留原配置。 私有化服务须兼容企微协议且能由服务端直接访问，禁止明文 HTTP、跳过证书校验或失败时回退公网地址。 连接测试、部门读取和同步复用该地址；原属性映射、Scope 和同步策略不变。 消息回调凭据在管理控制台单独配置，不通过本接口读取或写入。