读取授权部门的成员列表

取某一个部门的成员 userid 与基础名称，供应用通知等内部流程使用。

官方资料核对 2026-10-15示例代码，未进行真实接口实测

接入准备

当前应用拥有指定部门的查看权限；可见范围和通讯录数据权限需独立核对。
本例使用自建应用 Token；不能用新增通讯录同步 IP 绕过 2022 年起的接口调整。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

WECOM_ACCESS_TOKEN: 下面获取令牌操作的 access_token；必须与 AgentId 对应同一应用。
WECOM_DEPARTMENT_ID: 要读取的部门 ID；1 为示例，请核实真实目标及授权。

export WECOM_ACCESS_TOKEN='replace_with_app_access_token'
export WECOM_DEPARTMENT_ID='1'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

01
先按内部应用通知场景取得 Token。
02
在管理后台通讯录确认目标部门 ID，保存为 WECOM_DEPARTMENT_ID。
03
读取当前部门成员；如需子部门，先获取子部门列表，再按部门逐个调用，不添加已不在当前文档中的 fetch_child 参数。

调用 01

获取部门成员

当前官方定义只接收 department_id，不会自动递归全部子部门。

GET

https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=${WECOM_ACCESS_TOKEN}&department_id=${WECOM_DEPARTMENT_ID}

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置	类型 / 必填	说明
`access_token`Query	string必填	具有目标部门查看权限的本应用令牌。
`department_id`Query	integer必填	目标部门 ID。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=${WECOM_ACCESS_TOKEN}&department_id=${WECOM_DEPARTMENT_ID}"

import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=${WECOM_ACCESS_TOKEN}&department_id=${WECOM_DEPARTMENT_ID}")
headers = {

}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
if isinstance(result, dict) and "errcode" in result and result["errcode"] != 0:
    raise SystemExit("平台返回业务错误，请结合下方排错说明检查响应")

// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=${WECOM_ACCESS_TOKEN}&department_id=${WECOM_DEPARTMENT_ID}");
const headers = Object.fromEntries(
  Object.entries({}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));
if (Object.hasOwn(result, "errcode") && result["errcode"] !== 0) {
  throw new Error('平台返回业务错误，请结合下方排错说明检查响应');
}

返回示例

按官方字段整理的节选示意，使用虚构 ID，不是实测结果。userlist 中的 userid 可用于 touser；没有姓名不应推断为接口失败。以下为结构示意，非本站实测结果。

{
  "errcode": 0,
  "errmsg": "ok",
  "userlist": [
    {
      "userid": "example_member",
      "name": "测试成员",
      "department": [
        1
      ]
    }
  ]
}

常见错误与排查

errcode 非 0成员列表读取失败: 根据 errmsg 核对部门 ID、Token 的应用归属及部门查看权限。

调用注意

本端点没有 cursor/page 参数；单次只读取指定部门，递归由调用方逐部门处理。
第三方应用或代开发的 name 返回规则不同；open_userid 仅特定第三方场景返回，不要假设所有字段均存在。
2022-08-15 起，通讯录同步新增 IP 不能调用此接口，官方建议改用成员 ID 列表/部门 ID 列表；本例不使用通讯录同步 Secret。

获取部门成员

注意事项

只取当前应用获授权范围；不提供微信个人好友或任意企业通讯录。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

01
获取 access_token核验日期 2026-10-15
02
获取部门成员核验日期 2026-10-15

企业微信的其他调用手册

向群推送文本通知获取令牌并发送内部应用通知

← 返回企业微信的全部功能