获取企微外部联系人列表

分页列出企业微信侧的外部联系人（客户），并把同一个客户在两套体系里的身份一次带出：对应的平台会员身份（uid、脱敏手机号）、系统归属员工（staff_uid / staff_name），以及企业微信上的跟进员工（qiye_friend_staff / qiye_friend_staff_list，可多人）。支持按客户名称、外部联系人 ID、unionid、添加时间区间筛选，分页输出。

信息

只读查询：本接口只查询客户名册，不落库、不改动任何数据，可安全轮询与重复调用。

GET/api/getQiyeExternalUserList

核心语义

1. 范围：返回企业微信外部联系人档案中未删除的客户，按添加时间、记录 ID 倒序（最新在前）。
2. 含未注册成会员的客户：客户加了企业微信好友但还没注册成为平台会员时，uid = 0、phone 为空、staff_uid / staff_name 为空——这正是本接口要能列出来的对象，属正常数据。
3. 会员身份稳定：客户通过 unionid 关联平台会员。同一 unionid 历史上可能对应多条会员记录，本接口固定取会员编号最小的一条，保证同一客户每次调用返回的会员身份一致，不随分页与排序变化。
4. 手机号固定脱敏：phone 一律输出 130****0351 形式，与平台对外输出个人信息的规范一致，不可通过参数关闭。需要完整手机号请用 uid 走 获取会员列表。客户未填手机号、或数据不完整（不足以脱敏）时，phone 为空字符串，不会输出「看着像号码」的残缺值。
5. 两套员工口径不是一回事，请勿互相替代：
   • staff_uid / staff_name：平台系统里该会员的唯一归属销售，统计口径与销售名下会员用的就是这个。staff_uid = 0 表示还没有归属销售。
   • qiye_friend_staff / qiye_friend_staff_list：企业微信好友关系上的跟进员工，一个客户可能对应多人。只统计「当前仍是好友」的员工，已被删除好友关系的不计入。
   • 二者经常不是同一人。
6. 员工姓名的取值与回落：staff_name 取员工真实姓名，真实姓名为空时回退显示账号名（此时姓名看起来不像人名，属正常）。staff_name 为空但 staff_uid 有值，表示归属的员工账号已被删除——可与「没有归属销售」区分开。qiye_friend_staff_list[].name 查不到员工姓名时回落显示该员工的 userid，用于区分「没有数据」与「数据异常」。
7. 跟进员工已去重：同一「客户-员工」关系在库里可能有多条历史（重复添加、多条渠道码各留一条），接口按 userid 去重并保留首次出现顺序，姓名串中不会重复出现同一个人；因此这里表达的是「当前有哪些员工在跟进」，不含「某员工添加过几次」的历史次数。
8. 契约：code 恒为 0；成功时 msg 为空、data 为结果对象；失败时 msg 非空、data 为空数组。业务成功与否以 msg 判定。

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由 获取访问令牌 获得
external_userid	String	外部联系人 ID	选填	不筛选	精确匹配
unionid	String	微信 unionid	选填	不筛选	精确匹配
name	String	客户名称	选填	不筛选	模糊匹配，传关键词即可
starttime	String	添加时间筛选起点	选填	不限	支持秒级/毫秒级时间戳、YYYY-MM-DD、YYYY-MM-DD HH:mm:ss；闭区间
endtime	String	添加时间筛选终点	选填	不限	写法同 starttime；仅给到日期时自动含当天全天（至 23:59:59）；闭区间
pageNum	Number	页码	选填	1	从 1 开始
pageSize	Number	每页条数	选填	20	最大 100（超出按 100 返回；传 0 或负数按 20 处理）

所有筛选条件均为「传了才生效」，都不传即返回全量客户（按分页）。时间戳同时接受 13 位毫秒级，自动换算。

CURL

V1（GET）

curl --location --request GET 'https://open.xinduobang.cn/api/getQiyeExternalUserList?token=YOUR_TOKEN&pageSize=20&pageNum=1'

V1（POST）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeExternalUserList' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'name=张三' \
--data-urlencode 'starttime=2026-10-01' \
--data-urlencode 'endtime=2026-11-09' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=50'

V2（appid 为 V2 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeExternalUserList' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Timestamp: 1770000000' \
--header 'X-Nonce: 3f9c1a7b2e6d4058' \
--header 'X-Signature: <computed_hmac_sha256>' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'unionid=oXXXXXXXXXXXXXXXXXXXXXXX' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=20'

信息

V2 签名算法及 X-Signature 计算方式见 V2 接入示例。

成功响应

{
  "code": 0,
  "msg": "",
  "data": {
    "total": 1024,
    "pageNum": 1,
    "pageSize": 2,
    "list": [
      {
        "id": 12,
        "external_userid": "wmXXXXexternaluserid01",
        "unionid": "oXXXXXXXXXXXXXXXXXXXXXXX",
        "name": "示例客户A",
        "addtime": 1762670000,
        "addtime_str": "2025-11-09 14:33:20",
        "uid": 10001,
        "phone": "130****0351",
        "staff_uid": 2818,
        "staff_name": "sales01",
        "qiye_friend_staff": "张丽（华东销售组），王强（市场一部）",
        "qiye_friend_staff_list": [
          { "userid": "zhangli", "name": "张丽（华东销售组）" },
          { "userid": "wangqiang", "name": "王强（市场一部）" }
        ]
      },
      {
        "id": 11,
        "external_userid": "wmXXXXexternaluserid02",
        "unionid": "",
        "name": "示例客户B",
        "addtime": 1762504800,
        "addtime_str": "2025-11-07 16:40:00",
        "uid": 0,
        "phone": "",
        "staff_uid": 0,
        "staff_name": "",
        "qiye_friend_staff": "张丽（华东销售组）",
        "qiye_friend_staff_list": [
          { "userid": "zhangli", "name": "张丽（华东销售组）" }
        ]
      }
    ]
  }
}

上例中两条记录的对照关系：第一条已打通会员，phone 按 130****0351 脱敏，staff_uid=2818 且该员工未填真实姓名，故 staff_name 回退为账号名 sales01；第二条 unionid 为空（客户未授权、尚未关联到会员），因此 uid=0、phone 与 staff_* 均为空，但企业微信侧的跟进员工依然返回。

data 字段说明

键	类型	说明
total	Number	符合条件的客户总条数（用于计算总页数）
pageNum	Number	当前页码
pageSize	Number	每页条数
list	Array	外部联系人列表，按添加时间、记录 ID 倒序（最新在前）

list[] 字段说明

字段	类型	说明
id	Number	客户档案记录主键
external_userid	String	外部联系人 ID（企业微信侧客户唯一标识）
unionid	String	微信 unionid；客户未授权/未打通时为空字符串
name	String	客户名称（企业微信侧展示名）
addtime	Number	添加时间（unix 时间戳，秒级）
addtime_str	String	添加时间的可读格式 YYYY-MM-DD HH:mm:ss
uid	Number	关联的平台会员编号；未关联到会员时为 0
phone	String	会员手机号，固定脱敏（如 130****0351）；无手机号或未关联会员时为空字符串
staff_uid	Number	系统归属员工编号；0 表示无归属销售
staff_name	String	系统归属员工姓名，真实姓名为空时回退账号名；staff_uid 有值但此处为空串，表示归属员工账号已删除
qiye_friend_staff	String	企业微信跟进员工姓名串，多个用中文逗号（，）分隔；无跟进员工时为空字符串
qiye_friend_staff_list	Array	企业微信跟进员工明细列表，与 qiye_friend_staff 顺序一致；无数据时为空数组 []
qiye_friend_staff_list[].userid	String	跟进员工的企业微信 userid
qiye_friend_staff_list[].name	String	跟进员工姓名；查不到姓名时回落显示该员工的 userid

失败响应

契约下 code 恒为 0，失败通过非空 msg 与空 data 标识。

{ "code": 0, "msg": "endtime格式错误：2026-13-45", "data": [] }

错误文案	说明
starttime格式错误：xxx	starttime 无法解析为时间戳或日期字符串
endtime格式错误：xxx	endtime 无法解析为时间戳或日期字符串

注意事项

• 空值都是正常数据：unionid、phone、staff_uid / staff_name、qiye_friend_staff 取不到时返回空字符串或 0，请一律按「可能为空」解析，勿假设必有值。
• 不要把两套员工互相替代：staff_* 是平台系统内的唯一归属销售，qiye_friend_staff 是企业微信好友关系上的跟进员工（一对多），来源与含义不同，统计口径请以 staff_* 为准。
• name 模糊匹配：按关键词包含匹配；名称中的特殊符号可能被作为通配符处理，建议传客户名称正文，避免传入 %、_ 等符号。
• 时间筛选为闭区间：starttime、endtime 均含边界；endtime 仅写到日期时自动补到当天 23:59:59。
• 翻页建议按 total 计算页数：Math.ceil(total / pageSize)；本接口返回总条数，无需靠「返回空页」判断结束。

相关接口

• 获取访问令牌（取 token）：获取访问令牌
• 取会员完整信息（uid / 完整手机号）：获取会员列表
• 客户所在群与各群人数：获取企业外部群列表
• 按群看具体成员（含已退群）：获取群成员明细
• 同一客户的回调事件原文：查询企微消息回调记录

变更记录

日期	变更
2026-11-09	首次发布：/api/getQiyeExternalUserList（GET/POST，筛选参数全部可选）。分页列出企业微信外部联系人，每条同时带出关联的平台会员身份（uid、脱敏 phone）、系统归属员工（staff_uid / staff_name）与企业微信跟进员工（qiye_friend_staff / qiye_friend_staff_list，可多人、已去重）；支持客户名称模糊、external_userid / unionid 精确、添加时间区间筛选，按添加时间倒序分页输出，含尚未注册成会员的客户