4.4 KiB
4.4 KiB
企业微信客户同步问题修复指南
问题描述
同步企业微信客户时，能成功获取企业成员列表（207人），但无法获取任何客户数据，所有API调用都返回错误码 48002: "api forbidden"。
根本原因
企业微信应用未开启"客户联系"API权限。错误码 48002 表示API接口被禁用或未授权。
解决方案
方案一：开启API权限（推荐）
-
登录企业微信管理后台
- 访问：https://work.weixin.qq.com/
- 使用管理员账号登录
-
进入应用管理
- 点击"应用管理"
- 找到您正在使用的应用（使用
external_pay_secret的应用）
-
开启客户联系权限
- 在应用详情页面，找到"客户联系"权限设置
- 开启以下权限：
- ✓ 客户联系 - 获取客户列表
- ✓ 客户联系 - 获取客户详情
- ✓ 客户联系 - 获取客户数据统计（可选）
-
配置可信IP
- 在应用设置中找到"企业可信IP"
- 添加您的服务器IP地址
- 保存配置
-
等待生效
- 权限修改后可能需要几分钟生效
- 建议等待5-10分钟后再测试
方案二：升级企业微信版本
如果您的企业微信版本不支持客户联系API：
- 检查当前版本是否支持"客户联系"功能
- 如需要，升级到支持该功能的版本
- 部分功能可能需要付费版本
方案三：使用替代方案
如果无法开启API权限：
- 使用企业微信后台手动导出客户数据
- 通过CSV导入到系统
- 或使用企业微信的webhook回调功能（需要配置）
诊断工具
1. 运行权限检查命令
php think qywx:check-permissions
这个命令会：
- 检查应用配置是否正确
- 测试获取部门成员权限
- 测试获取客户列表权限
- 显示详细的错误信息和解决建议
2. 查看日志
日志文件位置：runtime/log/
关键日志信息：
企业微信-获取成员客户列表响应 userId=XXX: {"errcode":48002,"errmsg":"api forbidden"...}
如果看到 errcode: 48002，说明是权限问题。
代码改进
已对代码进行以下改进：
-
更好的错误处理
getExternalContactList()方法现在会检测48002错误- 权限错误时返回
false而不是空数组 - 同步逻辑会捕获权限错误并抛出明确的异常
-
新增诊断方法
WechatWorkService::checkAppPermissions()- 检查应用权限QywxCheckPermissions命令 - 完整的权限诊断工具
-
改进的日志记录
- 权限错误会记录更详细的信息
- 包含解决方案提示
测试步骤
-
确认已开启API权限
-
运行诊断命令：
php think qywx:check-permissions -
如果诊断通过，运行同步：
php think qywx:sync-customer -
检查同步结果：
- 查看日志文件
- 检查数据库表
la_qywx_external_contact - 在管理后台查看客户列表
常见问题
Q1: 权限已开启，但仍然报错48002
A:
- 等待5-10分钟让权限生效
- 清除企业微信access_token缓存：删除缓存键
qywx_access_token - 检查服务器IP是否在可信IP列表中
Q2: 找不到"客户联系"权限选项
A:
- 您的企业微信版本可能不支持此功能
- 需要升级到企业版或专业版
- 联系企业微信客服确认
Q3: 部分成员能获取客户，部分不能
A:
- 检查成员是否有"客户联系"权限
- 在企业微信后台为成员分配权限
- 确认成员确实有添加客户
Q4: 同步速度很慢
A:
- 这是正常的，因为需要逐个成员获取客户列表
- 207个成员 × 每个成员的客户数 = 大量API调用
- 建议设置定时任务，每小时或每天同步一次
相关文件
server/app/adminapi/logic/qywx/CustomerLogic.php- 同步逻辑server/app/common/service/wechat/WechatWorkService.php- API服务server/app/command/QywxSyncCustomer.php- 同步命令server/app/command/QywxCheckPermissions.php- 诊断命令（新增）server/config/project.php- 配置文件
联系支持
如果按照以上步骤仍无法解决：
-
收集以下信息：
- 诊断命令的完整输出
- 最近的日志文件
- 企业微信应用的权限截图
-
联系企业微信技术支持
最后更新：2024-04-11