165 lines
4.4 KiB
Markdown
165 lines
4.4 KiB
Markdown
# 企业微信客户同步问题修复指南
|
|
|
|
## 问题描述
|
|
|
|
同步企业微信客户时，能成功获取企业成员列表（207人），但无法获取任何客户数据，所有API调用都返回错误码 `48002: "api forbidden"`。
|
|
|
|
## 根本原因
|
|
|
|
企业微信应用未开启"客户联系"API权限。错误码 `48002` 表示API接口被禁用或未授权。
|
|
|
|
## 解决方案
|
|
|
|
### 方案一：开启API权限（推荐）
|
|
|
|
1. 登录企业微信管理后台
|
|
- 访问：https://work.weixin.qq.com/
|
|
- 使用管理员账号登录
|
|
|
|
2. 进入应用管理
|
|
- 点击"应用管理"
|
|
- 找到您正在使用的应用（使用 `external_pay_secret` 的应用）
|
|
|
|
3. 开启客户联系权限
|
|
- 在应用详情页面，找到"客户联系"权限设置
|
|
- 开启以下权限：
|
|
* ✓ 客户联系 - 获取客户列表
|
|
* ✓ 客户联系 - 获取客户详情
|
|
* ✓ 客户联系 - 获取客户数据统计（可选）
|
|
|
|
4. 配置可信IP
|
|
- 在应用设置中找到"企业可信IP"
|
|
- 添加您的服务器IP地址
|
|
- 保存配置
|
|
|
|
5. 等待生效
|
|
- 权限修改后可能需要几分钟生效
|
|
- 建议等待5-10分钟后再测试
|
|
|
|
### 方案二：升级企业微信版本
|
|
|
|
如果您的企业微信版本不支持客户联系API：
|
|
|
|
1. 检查当前版本是否支持"客户联系"功能
|
|
2. 如需要，升级到支持该功能的版本
|
|
3. 部分功能可能需要付费版本
|
|
|
|
### 方案三：使用替代方案
|
|
|
|
如果无法开启API权限：
|
|
|
|
1. 使用企业微信后台手动导出客户数据
|
|
2. 通过CSV导入到系统
|
|
3. 或使用企业微信的webhook回调功能（需要配置）
|
|
|
|
## 诊断工具
|
|
|
|
### 1. 运行权限检查命令
|
|
|
|
```bash
|
|
php think qywx:check-permissions
|
|
```
|
|
|
|
这个命令会：
|
|
- 检查应用配置是否正确
|
|
- 测试获取部门成员权限
|
|
- 测试获取客户列表权限
|
|
- 显示详细的错误信息和解决建议
|
|
|
|
### 2. 查看日志
|
|
|
|
日志文件位置：`runtime/log/`
|
|
|
|
关键日志信息：
|
|
```
|
|
企业微信-获取成员客户列表响应 userId=XXX: {"errcode":48002,"errmsg":"api forbidden"...}
|
|
```
|
|
|
|
如果看到 `errcode: 48002`，说明是权限问题。
|
|
|
|
## 代码改进
|
|
|
|
已对代码进行以下改进：
|
|
|
|
1. **更好的错误处理**
|
|
- `getExternalContactList()` 方法现在会检测 `48002` 错误
|
|
- 权限错误时返回 `false` 而不是空数组
|
|
- 同步逻辑会捕获权限错误并抛出明确的异常
|
|
|
|
2. **新增诊断方法**
|
|
- `WechatWorkService::checkAppPermissions()` - 检查应用权限
|
|
- `QywxCheckPermissions` 命令 - 完整的权限诊断工具
|
|
|
|
3. **改进的日志记录**
|
|
- 权限错误会记录更详细的信息
|
|
- 包含解决方案提示
|
|
|
|
## 测试步骤
|
|
|
|
1. 确认已开启API权限
|
|
2. 运行诊断命令：
|
|
```bash
|
|
php think qywx:check-permissions
|
|
```
|
|
|
|
3. 如果诊断通过，运行同步：
|
|
```bash
|
|
php think qywx:sync-customer
|
|
```
|
|
|
|
4. 检查同步结果：
|
|
- 查看日志文件
|
|
- 检查数据库表 `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` - 配置文件
|
|
|
|
## 联系支持
|
|
|
|
如果按照以上步骤仍无法解决：
|
|
|
|
1. 收集以下信息：
|
|
- 诊断命令的完整输出
|
|
- 最近的日志文件
|
|
- 企业微信应用的权限截图
|
|
|
|
2. 联系企业微信技术支持
|
|
- 官方文档：https://developer.work.weixin.qq.com/
|
|
- 开发者社区：https://developers.weixin.qq.com/community/business
|
|
|
|
---
|
|
|
|
最后更新：2024-04-11
|