108 lines
10 KiB
Markdown
108 lines
10 KiB
Markdown
> 本文由 [简悦 SimpRead](http://ksria.com/simpread/) 转码， 原文地址 [developer.work.weixin.qq.com](https://developer.work.weixin.qq.com/document/path/96260) 获取部门成员详情 最后更新：2024/07/24
|
||
|
||
应用只能获取可见范围内的成员信息，且每种应用获取的字段有所不同，在返回结果说明中会逐个说明。企业通讯录安全特别重要，企业微信持续升级加固通讯录接口的安全机制，以下是关键的变更点：
|
||
|
||
* 从 2022 年 6 月 20 号 20 点开始，除通讯录同步以外的基础应用（如客户联系、微信客服、会话存档、日程等），以及新创建的自建应用与代开发应用，调用该接口时，不再返回以下字段：头像、性别、手机、邮箱、企业邮箱、员工个人二维码、地址，应用需要通过 [oauth2 手工授权](#15232)的方式获取管理员与员工本人授权的字段。
|
||
|
||
* **【重要】**从 2022 年 8 月 15 日 10 点开始，“企业管理后台 - 管理工具 - 通讯录同步” 的新增 IP 将不能再调用此接口，企业可通过「[获取成员 ID 列表](#40412)」和「[获取部门 ID 列表](#36259)」接口获取 userid 和部门 ID 列表。[查看调整详情](#40802)。
|
||
|
||
**请求方式：**GET（**HTTPS**）
|
||
**请求地址：**https://qyapi.weixin.qq.com/cgi-bin/user/list?access_token=ACCESS_TOKEN&department_id=DEPARTMENT_ID
|
||
|
||
**参数说明：**
|
||
|
||
<table><thead><tr><th>参数</th><th>必须</th><th>说明</th></tr></thead><tbody><tr><td>access_token</td><td>是</td><td>调用接口凭证</td></tr><tr><td>department_id</td><td>是</td><td>获取的部门 id</td></tr></tbody></table>
|
||
|
||
> 如需获取该部门及其子部门的所有成员，需先获取该部门下的子部门，然后再获取子部门下的部门成员，逐层递归获取。
|
||
|
||
**权限说明：**
|
||
|
||
应用须拥有指定部门的查看权限。
|
||
|
||
**返回结果：**
|
||
|
||
```
|
||
{
|
||
"errcode": 0,
|
||
"errmsg": "ok",
|
||
"userlist": [{
|
||
"userid": "zhangsan",
|
||
"name": "李四",
|
||
"department": [1, 2],
|
||
"order": [1, 2],
|
||
"position": "后台工程师",
|
||
"mobile": "13800000000",
|
||
"gender": "1",
|
||
"email": "zhangsan@gzdev.com",
|
||
"biz_mail":"zhangsan@qyycs2.wecom.work",
|
||
"is_leader_in_dept": [1, 0],
|
||
"direct_leader":["lisi"],
|
||
"avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
|
||
"thumb_avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/100",
|
||
"telephone": "020-123456",
|
||
"alias": "jackzhang",
|
||
"status": 1,
|
||
"address": "广州市海珠区新港中路",
|
||
"english_name" : "jacky",
|
||
"open_userid": "xxxxxx",
|
||
"main_department": 1,
|
||
"extattr": {
|
||
"attrs": [
|
||
{
|
||
"type": 0,
|
||
"name": "文本名称",
|
||
"text": {
|
||
"value": "文本"
|
||
}
|
||
},
|
||
{
|
||
"type": 1,
|
||
"name": "网页名称",
|
||
"web": {
|
||
"url": "http://www.test.com",
|
||
"title": "标题"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"qr_code": "https://open.work.weixin.qq.com/wwopen/userQRCode?vcode=xxx",
|
||
"external_position": "产品经理",
|
||
"external_profile": {
|
||
"external_corp_name": "企业简称",
|
||
"wechat_channels": {
|
||
"nickname": "视频号名称",
|
||
"status": 1
|
||
},
|
||
"external_attr": [{
|
||
"type": 0,
|
||
"name": "文本名称",
|
||
"text": {
|
||
"value": "文本"
|
||
}
|
||
},
|
||
{
|
||
"type": 1,
|
||
"name": "网页名称",
|
||
"web": {
|
||
"url": "http://www.test.com",
|
||
"title": "标题"
|
||
}
|
||
},
|
||
{
|
||
"type": 2,
|
||
"name": "测试app",
|
||
"miniprogram": {
|
||
"appid": "wx8bd80126147dFAKE",
|
||
"pagepath": "/index",
|
||
"title": "miniprogram"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}]
|
||
}
|
||
```
|
||
|
||
**参数说明 :**
|
||
|
||
<table><thead><tr><th>参数</th><th>说明</th></tr></thead><tbody><tr><td>errcode</td><td>返回码</td></tr><tr><td>errmsg</td><td>对返回码的文本描述内容</td></tr><tr><td>userlist</td><td>成员列表</td></tr><tr><td>userid</td><td>成员 UserID。对应管理端的账号</td></tr><tr><td>name</td><td>成员名称；第三方不可获取，调用时返回 userid 以代替 name；代开发自建应用需要管理员授权才返回；对于非第三方创建的成员，第三方通讯录应用也不可获取；未返回名称的情况需要通过<a href="#17172" rel="nofollow">通讯录展示组件</a>来展示名字</td></tr><tr><td>mobile</td><td>手机号码，代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>department</td><td>成员所属部门 id 列表，仅返回该应用有查看权限的部门 id。对授权了 “组织架构信息” 的第三方应用或授权了 “组织架构信息”-“部门及父部门 ID、部门负责人” 的代开发应用，返回成员所属的全部部门 id 列表</td></tr><tr><td>order</td><td>部门内的排序值，默认为 0。数量必须和 department 一致，数值越大排序越前面。值范围是 [0, 2^32)</td></tr><tr><td>position</td><td>职务信息；代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>gender</td><td>性别。0 表示未定义，1 表示男性，2 表示女性。第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段。注：不可获取指返回值为 0</td></tr><tr><td>email</td><td>邮箱，代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>biz_mail</td><td>企业邮箱，代开发自建应用不返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>is_leader_in_dept</td><td>表示在所在的部门内是否为部门负责人。0 - 否；1 - 是。是一个列表，数量必须与 department 一致。第三方通讯录应用或者授权了 “组织架构信息 - 应用可获取企业的部门组织架构信息 - 部门负责人” 权限的第三方应用和代开发应用可获取；对于非第三方创建的成员，第三方通讯录应用不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>direct_leader</td><td>直属上级 UserID，返回在应用可见范围内的直属上级列表，最多有 1 个直属上级；第三方通讯录应用或者授权了 “组织架构信息 - 应用可获取可见范围内成员组织架构信息 - 直属上级” 权限的第三方应用和代开发应用可获取；对于非第三方创建的成员，第三方通讯录应用不可获取；上游企业不可获取下游企业成员该字段；代开发自建应用不可获取该字段</td></tr><tr><td>avatar</td><td>头像 url。 第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>thumb_avatar</td><td>头像缩略图 url。第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>telephone</td><td>座机。代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>alias</td><td>别名；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>extattr</td><td>扩展属性，字段详见<a href="#54430" rel="nofollow">成员扩展属性</a>。代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>status</td><td>激活状态: 1 = 已激活，2 = 已禁用，4 = 未激活，5 = 退出企业。<br>已激活代表已激活企业微信或已关注微信插件（原企业号）。未激活代表既未激活企业微信又未关注微信插件（原企业号）。</td></tr><tr><td>qr_code</td><td>员工个人二维码，扫描可添加为外部联系人 (注意返回的是一个 url，可在浏览器上打开该 url 以展示二维码)；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>external_profile</td><td>成员对外属性，字段详情见<a href="#13450" rel="nofollow">对外属性</a>；代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>external_position</td><td>对外职务，如果设置了该值，则以此作为对外展示的职务，否则以 position 来展示。代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>address</td><td>地址。代开发自建应用需要管理员授权才返回；第三方仅通讯录应用可获取；对于非第三方创建的成员，第三方通讯录应用也不可获取；上游企业不可获取下游企业成员该字段</td></tr><tr><td>open_userid</td><td>全局唯一。对于同一个服务商，不同应用获取到企业内同一个成员的 open_userid 是相同的，最多 64 个字节。仅第三方应用可获取</td></tr><tr><td>main_department</td><td>主部门，仅当应用对主部门有查看权限时返回。</td></tr></tbody></table> |