做企业微信二次开发的朋友应该都遇到过这种需求运营部门跑过来说“把最近添加的客户数据拉出来我们要做分析”或者老板一拍脑袋要求“新来的销售直接分一批客户跟一下你写个程序自动同步”。这时候你就得去翻 API 文档找到那个获取外部联系人列表的接口再对着返回结构做一遍字段清洗。今天这篇就把这条链路完整讲透——我以企业微信客户联系 API 为例从身份认证、核心接口拆解、Python 实战代码到常见报错排查、增量同步落库一次性梳理清楚。这篇文章适合两类人一类是刚接触企业微信 API 的开发者照着本文能跑通“员工—客户”全量列表另一类是已经在做客户管理、CRM 集成的后端同学可以重点看同步策略和报错排查部分。理解了这套“认证—列表—详情—落库”的骨架之后换到钉钉、飞书或者自建 CRM思路都是一样的。1. 外部联系人 API 到底解决什么问题场景先行1.1 “外部联系人”不是普通用户列表很多第一次接触的人会把“外部联系人”和企业微信通讯录里的“成员”搞混。企业微信里的成员是内部员工通过user/list这类通讯录接口读取而外部联系人指的是员工通过企业微信添加的微信用户、其他企业微信用户——说白了就是你的客户。这个区别决定了接口体系完全不同内部通讯录走“通讯录管理”这套 API客户数据走“客户联系”这套 API。后面这一切代码都建立在“客户联系”这个能力域之上。如果你的企业微信后台没有开通客户联系功能或者员工没有添加过任何客户那这个接口拉出来的列表就是空的这不是代码问题是数据源本身没有产生数据。1.2 四个真实业务场景为什么非要通过 API 拉外部联系人而不是让运营手工导出我在实际项目里遇到的典型需求有四个客户归集与数据仓库建设把散落在各销售手里的客户统一收拢到一个数据平台做客户总量、行业分布、添加来源的分析。离职继承与客户分配员工离职后他名下的客户需要批量转移给其他同事新客进入后要按规则自动分配给销售。这部分操作虽然有管理后台入口但批量分配必须走 API。客户全量同步到 CRM企业微信和内部 CRM 系统打通客户加进来后自动在 CRM 建联系人后续的跟进记录、商机阶段都在 CRM 里管理。风险监控与流失预警通过定时拉取客户列表和详情对比前后两次数据发现某个客户删除了员工微信流失或者超过 N 天没有互动主动触发预警。1.3 为什么必须用 API 而不是手工导出管理后台确实能导出客户列表但手工导出有几个硬伤数据是静态快照无法做增量更新单次导出有数量限制客户多了就很痛苦导出响应慢而且没法跟业务系统联动。API 方式下你可以定时跑全量同步、按事件触发生成新客通知也能把客户数据直接推进数据仓库跟订单表、工单表做关联分析。一句话API 获取外部联系人列表是企业微信客户数据和业务系统之间的一座标准桥梁不管后面要做什么这第一步都得走通。2. 动手前的三个前置条件身份认证、权限配置与接口边界2.1 corpid 和 secret 从哪来调企业微信 API 的第一步永远是先拿身份凭证。你需要在企业微信管理后台拿到两个东西corpid和secret。corpid是企业的唯一标识在管理后台“我的企业—企业信息”页面能看到格式是一串以ww开头或纯数字的字符串。secret则要分清楚很多人第一次就死在这里客户联系 API 用的 secret不是自建应用的 secret而是“客户联系”这个功能模块自己的 secret。正确的获取路径是管理后台 → 客户联系 → 客户 → API 页面在里面创建一个 secret。创建之后它会显示一次一定要复制保存好关掉页面再想看就麻烦很多。这个 secret 和你在“应用管理—自建应用”里看到的 secret 是两码事二者权限范围完全不一样。2.2 可信 IP 白名单特别容易漏的一步拿到 corpid 和 secret 之后很多人直接开始写代码调gettoken结果 token 拿到了但一调客户列表接口就报错提示 IP 不在白名单。这是因为“客户联系 API”同样受企业微信的可信 IP 控制。你需要在同一个“客户联系—API”配置页面里把服务器出口 IP 加到白名单。这个 IP 是你的后端服务访问外网时的公网 IP不是你本机内网 IP。最简单的确认方法是找一台最终要部署代码的服务器在服务器上执行curl ifconfig.me拿到公网 IP再填进去。本地调试时如果本机公网 IP 和服务器不一致需要把两个都加进白名单否则换环境跑就会莫名其妙报错。2.3 access_token7200 秒的有效期应该缓存而不是每次现取调用任何客户联系接口之前都要先通过gettoken接口换取access_tokenGET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpidCORPIDcorpsecretSECRET正常情况下返回{ errcode: 0, errmsg: ok, access_token: accesstoken000001, expires_in: 7200 }expires_in固定 7200 秒。很多人图省事每次都调一次 gettoken这在低频率下没太大问题但企业微信对 gettoken 接口本身有调用频率限制频繁调用会导致后面的请求失败。另一个更隐蔽的问题是多个服务实例同时刷新 token后刷新的会把先刷新的 token 顶掉结果服务 A 拿着旧 token 去请求就报 42001。我的建议是做一个进程内的 TokenManager用一个模块级变量缓存 token记录过期时间距离过期时间剩余 5 分钟以上就直接返回缓存的 token否则才重新获取。后面实战代码里会给完整实现。2.4 两个最基础的概念userid 与 external_userid在客户联系 API 里有两类 ID 贯穿始终userid是企业成员的内部 ID对应“哪个员工”。external_userid是这个客户在你们企业体系里的外部联系人 ID对应“哪个客户”。注意同一个微信用户添加了你们企业的两个不同员工他的external_userid是同一个还是两个答案是在同一企业下这个客户只有一个external_userid但两个员工会各自维护一段跟进关系备注、标签、添加时间都可能不同。所以在设计数据表时external_userid是客户主键但“员工与客户之间的关系”需要单独一张表存。这个模型理解对了后面做数据建模就不会乱。2.5 接口频率限制与调用边界企业微信客户联系接口有频率限制具体数值在官方文档的动态调整里。实操中我的经验是单个接口的并发控制在每秒几次以内全量同步任务放在低峰期加个重试机制遇到限流错误码就退避重试基本不会出问题。批量获取详情时不要一次拉太多合理分批。3. 核心接口拆解从“员工维度”到“客户维度”的调用链路3.1 第一步获取通讯录成员列表客户联系 API 的数据结构是“员工 → 客户”所以第一步永远是拿到员工列表。有两个接口可以选user/list返回成员详细信息字段多但重。user/simplelist只返回 userid、name、部门等基础字段够用且响应快。GET https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_tokenACCESS_TOKENdepartment_id1fetch_child1这里的department_id填 1 表示根部门fetch_child1表示递归获取子部门的成员。一个常见误区是只填根部门不递归结果只拿到少数几个部门的人。除非你有明确的部门隔离需求否则建议fetch_child1拉全量。3.2 第二步按员工拉取客户列表拿到员工 userid 列表后逐个员工调externalcontact/listGET https://qyapi.weixin.qq.com/cgi-bin/externalcontact/list?access_tokenACCESS_TOKENuseridUSERID返回结构{ errcode: 0, errmsg: ok, external_userid: [ woAJ2GCAAA..., woAJ2GCBBB... ] }这个接口只返回该员工名下的客户 ID 列表不含客户昵称、备注这些信息。它的特点是逻辑简单适合数据量不大比如几百个员工、每人几十个客户的情况。如果员工很多、客户总量到了几十万级别逐个员工请求会非常慢这时候就要用下面的批量接口。3.3 第三步获取客户详情拿到了external_userid列表接着调用externalcontact/get获取每个客户的详细信息GET https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get?access_tokenACCESS_TOKENexternal_useridEXTERNAL_USERID返回的关键字段如下{ errcode: 0, errmsg: ok, external_contact: { external_userid: woAJ2GCAAA..., name: 张三, type: 1, avatar: http://..., gender: 1, unionid: oAAAA... }, follow_user: [ { userid: rocky, remark: 重要客户-李总, createtime: 1520423160000, add_way: 4 } ] }external_contact是客户本身的属性follow_user是跟进人列表。这里有一个细节一个客户可以被多个员工同时添加所以follow_user是一个数组每个元素记录这个员工给客户备注的 remark、添加时间createtime、添加来源add_way。如果你要做“员工跟进状态”分析这个数组就是核心数据。3.4 更高效的批量方案batch/get_by_user员工数量多的时候推荐用externalcontact/batch/get_by_user一次传入多个员工 userid同时返回这些员工的客户列表和跟进信息并且支持游标分页POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/batch/get_by_user?access_tokenACCESS_TOKEN Content-Type: application/json { userid_list: [zhangsan, lisi], cursor: , limit: 1000 }返回结构里包含external_contact_list和next_cursor。next_cursor不为空就继续传进去翻页直到为空表示拉完。用这个接口代替第三步的逐个详情请求可以把请求量从“客户总数”降为“员工批次数量”性能提升显著。不过要注意批量接口返回的跟进信息是精简版某些完整字段还是依赖详情接口具体以官方文档为准实操时先跑一两个员工对一下字段确认满足需求再切换到批量方案。3.5 客户群列表外部联系人的另一个维度客户联系 API 里还有一套客户群相关的接口externalcontact/groupchat/list和externalcontact/groupchat/get。如果你们的业务形态是“客户群运营”需要把群维度的数据也拉下来可以走这一组。它的分页方式和批量客户接口一样用next_cursor如果只是获取客户列表这组接口可以先跳过但建议了解因为后续做客户分层运营时大概率会用到。4. Python 实战从零跑通“员工—客户”全量列表4.1 环境准备我本地的环境是 Python 3.10 requests 库。如果还没装 requests先执行pip install requests pandaspandas 不是必须的但用来做数据整理和导出 CSV 非常方便。整个脚本只需要三个配置项CORP_ID 你的corpid CONTACT_SECRET 客户联系secret不是应用secret BASE_URL https://qyapi.weixin.qq.com/cgi-bin4.2 封装 TokenManager先解决 access_token 的缓存问题import time import requests _token_cache { token: None, expires_at: 0 } def get_access_token(): if _token_cache[token] and _token_cache[expires_at] time.time() 300: return _token_cache[token] resp requests.get( f{BASE_URL}/gettoken, params{corpid: CORP_ID, corpsecret: CONTACT_SECRET}, timeout10 ) data resp.json() if data.get(errcode) ! 0: raise RuntimeError(f获取access_token失败: {data}) _token_cache[token] data[access_token] _token_cache[expires_at] time.time() data[expires_in] return _token_cache[token]逻辑很简单过期前 5 分钟就复用缓存否则重新获取。为什么留 5 分钟缓冲因为网络请求本身有延迟卡在临界点上容易拿到已过期的 token。4.3 获取成员列表def get_all_staff(): access_token get_access_token() resp requests.get( f{BASE_URL}/user/simplelist, params{ access_token: access_token, department_id: 1, fetch_child: 1 }, timeout10 ) data resp.json() if data.get(errcode) ! 0: raise RuntimeError(f获取成员列表失败: {data}) return data.get(userlist, [])返回的userlist里每一项至少包含userid和name我一般只取userid因为客户接口只需要userid。4.4 拉取客户列表与详情接下来是核心流程遍历员工拉客户 ID再拉客户详情。这里我用一种分批 容错的方式不会因为某一个员工异常导致整个任务挂掉def fetch_customer_ids_by_staff(userid): access_token get_access_token() resp requests.get( f{BASE_URL}/externalcontact/list, params{access_token: access_token, userid: userid}, timeout10 ) data resp.json() if data.get(errcode) ! 0: raise RuntimeError(f获取员工{userid}的客户列表失败: {data}) return data.get(external_userid, []) def fetch_customer_detail(external_userid): access_token get_access_token() resp requests.get( f{BASE_URL}/externalcontact/get, params{access_token: access_token, external_userid: external_userid}, timeout10 ) data resp.json() if data.get(errcode) ! 0: raise RuntimeError(f获取客户{external_userid}详情失败: {data}) return data然后把这些函数组织成一个主流程def build_all_customers(): staff_list get_all_staff() result [] for staff in staff_list: userid staff[userid] try: external_ids fetch_customer_ids_by_staff(userid) except Exception as e: print(f员工 {userid} 客户列表拉取失败: {e}) continue for ext_id in external_ids: try: detail fetch_customer_detail(ext_id) contact detail.get(external_contact, {}) for follow in detail.get(follow_user, []): result.append({ staff_userid: follow.get(userid, userid), external_userid: ext_id, customer_name: contact.get(name), customer_type: contact.get(type), customer_gender: contact.get(gender), remark: follow.get(remark), add_way: follow.get(add_way), createtime: follow.get(createtime), unionid: contact.get(unionid), }) except Exception as e: print(f客户 {ext_id} 详情拉取失败: {e}) continue return result注意我在follow_user的循环里用的是follow.get(userid, userid)不直接用外层员工 userid是因为一个客户可能被多个员工添加详情里的follow_user才是真实跟进关系的记录。4.5 落地保存CSV SQLite数据拉下来不保存等于白干。最简单的方案是导出 CSV用 pandas 几行搞定import pandas as pd rows build_all_customers() df pd.DataFrame(rows) df.to_csv(external_customers.csv, indexFalse, encodingutf-8-sig)需要说明的是createtime是毫秒级时间戳你想变成可读日期的话建议用如下方式转换df[create_time] pd.to_datetime(df[createtime], unitms)比起 CSV我更推荐同步到 SQLite 或 MySQL后面做增量更新、去重、关联查询都方便import sqlite3 conn sqlite3.connect(customers.db) df.to_sql(staff_customer_relation, conn, if_existsreplace, indexFalse) conn.close()4.6 执行效果检查脚本跑完后我一般会做三件事验证结果是否可信看总行数企业微信管理后台的客户联系人总数应该和这个数字对得上对不上就说明有漏拉或重复。抽查某位销售找一位客户数量明确的销售数一数脚本拉出来的客户数跟他手机企业微信里的客户数是否一致。检查add_way分布正常情况下来源分布应该集中在扫码、名片搜索、群聊等如果有大量异常来源值说明字段映射写错了。这三步都过了基本可以确认数据是准的再往上做同步和落库就有把握了。5. 实测中的典型报错与排查链路5.1 错误码先看这张表我整理了一份客户联系 API 最常见的错误码对照排查时先对号入座错误码含义最常见的诱因40001不合法的 secret复制错了 secret或混用了应用 secret 和客户联系 secret40013不合法的 corpidcorpid 少复制了字符或填成了 secret40014不合法的 access_tokentoken 被新的 token 顶掉或缓存逻辑有误41001缺少 access_token请求里压根没带 token 参数42001access_token 过期token 过期需要重新获取48002API 接口无权限这个 secret 没有对应接口的权限60011管理端无权限当前 token 的凭证没有管理相应数据的权限60020访问 IP 不在白名单可信 IP 没配或配错5.2 案例获取 token 成功但拉列表提示 60011有一次我写好了代码gettoken 返回正常但一调externalcontact/list就报 60011。当时我一度怀疑是数据权限问题翻了一圈文档发现60011 通常意味着这个 secret 对应的凭证对目标数据没有管理权限。最后定位到原因我用的是某个自建应用的 secret而不是客户联系模块自己的 secret。应用 secret 的权限范围是应用自己并不包含客户联系的数据域。换回客户联系 secret 后问题解决。排查链路其实很简单先去管理后台确认当前 secret 是在哪个页面创建的。客户联系 API 必须用“客户联系”模块里的 secret。检查这个 secret 对应的凭证是否被重置过重置后旧 secret 立即失效。5.3 案例40001 不合法的 secret多半是复制错凭证40001 是我见过最多的报错绝大部分原因是复制错了 secret有人把 corpid 当成 secret 填有人把应用的 secret 和客户联系的 secret 搞混还有人创建 secret 之后没点保存就去复制页面跳走再回来复制到的是一个隐藏的残缺值。排查方法先把配置打印出来对照管理后台逐字符确认。secret 通常是一串较长的 base64 风格字符一般来说以特定前缀开头凡是感觉“短了半截”的基本都是复制丢了字符。5.4 案例42001 access_token 过期缓存设计出了问题42001 报错出现在“一开始跑得好好的跑了一段时间后突然大量出现”的场景。根因几乎都是多实例并发刷新 token多个进程同时发现本地缓存过期各自去调 gettoken后刷新的 token 把前面的顶掉了拿着旧 token 的请求就全部报 42001。解决思路有几种单实例场景用我上面的 TokenManager 就够了加个线程锁更稳。多实例场景把 token 存到 Redis 或数据库用分布式锁保证同时只有一个实例刷新 token。最粗暴但有效的办法对 42001 做一次“重试”捕获错误后强制清掉缓存重新获取 token再重放当前请求。我倾向于在代码里统一做一次 42001 自动重试这在长任务里能省非常多麻烦。def request_with_retry(method, url, **kwargs): for _ in range(2): resp requests.request(method, url, **kwargs) data resp.json() if data.get(errcode) 42001: _token_cache[token] None _token_cache[expires_at] 0 token get_access_token() url update_token_in_url(url, token) continue return data return data5.5 案例IP 不在白名单60020 看起来像权限错误实际上就是网络准入问题。你调 gettoken 可能没问题但调数据接口时报错就是因为 gettoken 接口除了需要白名单部分请求不校验调用 IP而真正读取企业数据时企业微信会校验请求来源 IP 是否在可信范围内。处理方式去“客户联系—API”页面查看当前已配置的可信 IP。用curl ifconfig.me拿当前服务的公网 IP对比是否在白名单里。如果走了代理、CDN、NAT 网关出口 IP 可能是另一个需要找网络同事确认实际出口公网 IP。5.6 分页与数据丢失next_cursor 的处理批量接口没有一次性返回全部数据的说法必须翻页。常见的数据丢失案例就是只取第一页没判断next_cursor或者判断条件写错。我见过最典型的错误写法判断if next_cursor:作为继续翻页条件但企业微信返回的next_cursor可能不是我们预期的“下一页标记”某些接口要求传cursor为空字符串表示第一页后续用返回的next_cursor。正确姿势是写一个 while 循环当next_cursor为空字符串时才退出同时对翻页次数做一个上限保护避免极端情况下死循环。6. 进阶增量同步、数据落库与客户流失感知6.1 为什么不能一直全量拉全量拉接口最大的问题是随着客户量增长耗时和频率限制风险都在增加。而且全量拉下来的数据只能反映“当前时刻”的状态你想知道昨天新增了多少客户、哪些客户被删了、哪个销售的客户备注改了就无能为力了。更合理的方案是首次全量初始化之后跑增量同步。6.2 基于 createtime 的增量同步思路企业微信客户关系里的createtime是员工添加客户的时间单位是毫秒。增量同步的逻辑是记录上次同步的时间戳last_sync_time。每次拉取客户列表后判断createtime last_sync_time的记录是新增客户。更新客户备注、标签变化以重复调用详情接口覆盖更新为准。对于客户删除员工流失的情况列表接口不会再返回这条记录需要靠快照对比来识别。快照对比的做法很简单每次同步把“员工—客户”关联关系的主键集合存下来下次同步时对比上一次的集合缺失的键就是流失记录。如果客户量大可以用把主键存数据库临时表通过 SQL 的NOT IN或 LEFT JOIN 对比差异。6.3 表结构建议根据前面讲的客户模型至少需要三张表CREATE TABLE customer ( external_userid TEXT PRIMARY KEY, name TEXT, type INTEGER, gender INTEGER, avatar TEXT, unionid TEXT, updated_at TIMESTAMP ); CREATE TABLE staff_customer_relation ( id INTEGER PRIMARY KEY AUTOINCREMENT, staff_userid TEXT, external_userid TEXT, remark TEXT, add_way INTEGER, createtime INTEGER, is_delete INTEGER DEFAULT 0, UNIQUE(staff_userid, external_userid) ); CREATE TABLE sync_log ( id INTEGER PRIMARY KEY AUTOINCREMENT, sync_time TIMESTAMP, full_sync INTEGER, stat TEXT );customer表存客户本身staff_customer_relation存员工与客户的关系sync_log记录每次同步的结果统计做数据核查时非常有用。员工维度单独有通讯录接口不需要在这套表里重复维护。6.4 客户流失与删除事件的感知除了快照对比企业微信还提供了客户流失回调事件可以在客户删除员工或成员删除客户时通过回调实时感知。回调接入比轮询复杂一些需要配置接收消息服务器并处理加解密但对中大规模企业来说这是做流失预警最高效的方式。如果你还没准备好接回调至少要做到全量同步时保留上一份快照脚本里自动对比差异并输出流失列表。我实际项目中就是用这个方式发现了一个重要客户被销售误删的记录及时挽回来了。6.5 定时任务的工程化建议增量同步上线后建议按以下节奏调度每 15 分钟或每小时拉一次增量客户数据更新staff_customer_relation。每天凌晨全量同步一次修正可能的漏拉和脏数据。每周把客户快照归档用于历史趋势分析。同步脚本本身要支持幂等同一批数据重复跑不会产生重复记录。这也是我把staff_customer_relation加上联合唯一索引的原因用INSERT OR REPLACE或INSERT ... ON CONFLICT DO UPDATE来写库。最后再补充一句外部联系人列表这类 API看起来只是几个接口的调用真正决定项目成败的往往是数据模型设计和异常处理。先把单员工的客户列表跑通确认字段、确认数量、确认权限再写全量循环是最稳妥的推进方式。我每次接这类需求都这么干省下的排查时间不是一点半点。
