238 lines
6.6 KiB
Markdown
238 lines
6.6 KiB
Markdown
# 企业微信客户联系API Demo
|
|
|
|
这是一个使用企业微信客户联系API的TypeScript示例项目，演示如何获取客户列表和客户详情。
|
|
|
|
## 功能特性
|
|
|
|
- ✅ 获取access_token（带自动缓存和过期管理）
|
|
- ✅ 获取配置了客户联系功能的成员列表
|
|
- ✅ 获取客户列表
|
|
- ✅ 获取客户详情
|
|
- ✅ 批量获取客户详情
|
|
- ✅ 支持分页获取（跟进人超过500人时）
|
|
- ✅ 完整的TypeScript类型定义
|
|
- ✅ 错误处理和响应验证
|
|
- ✅ 自动使用第一个成员获取客户列表
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
pg-demo/
|
|
├── src/
|
|
│ ├── main.ts # 主程序入口
|
|
│ ├── wechat-client.ts # 企业微信API客户端
|
|
│ └── types/
|
|
│ └── wechat.ts # TypeScript类型定义
|
|
├── .env.example # 环境变量配置示例
|
|
├── package.json
|
|
└── tsconfig.json
|
|
```
|
|
|
|
## 快速开始
|
|
|
|
### 1. 安装依赖
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### 2. 配置环境变量
|
|
|
|
复制 `.env.example` 为 `.env` 并填入实际的值：
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
编辑 `.env` 文件：
|
|
|
|
```env
|
|
WEIXIN_CORP_ID=your_corp_id
|
|
WEIXIN_CORP_SECRET=your_corp_secret
|
|
WEIXIN_EXTERNAL_USER_ID=your_external_user_id
|
|
```
|
|
|
|
### 3. 运行程序
|
|
|
|
```bash
|
|
# 自动使用第一个配置了客户联系功能的成员
|
|
pnpm start
|
|
|
|
# 或者指定特定的企业成员userid
|
|
pnpm start <userid>
|
|
```
|
|
|
|
**示例**:
|
|
```bash
|
|
# 自动使用第一个成员
|
|
pnpm start
|
|
|
|
# 指定特定成员
|
|
pnpm start zhangsan
|
|
```
|
|
|
|
程序会依次执行以下操作：
|
|
1. 获取access_token
|
|
2. 获取配置了客户联系功能的成员列表
|
|
3. 获取指定成员（或第一个成员）的客户列表
|
|
4. 获取第一个客户的详情
|
|
5. 批量获取所有客户详情
|
|
|
|
## 使用示例
|
|
|
|
### 获取配置了客户联系功能的成员列表
|
|
|
|
```typescript
|
|
import { WeChatClient } from './wechat-client';
|
|
|
|
// 创建客户端
|
|
const client = new WeChatClient({
|
|
corpId: process.env.WEIXIN_CORP_ID!,
|
|
corpSecret: process.env.WEIXIN_CORP_SECRET!,
|
|
});
|
|
|
|
// 获取配置了客户联系功能的成员列表
|
|
const followUserList = await client.getFollowUserList();
|
|
|
|
console.log('成员数量:', followUserList.follow_user?.length || 0);
|
|
console.log('成员ID列表:', followUserList.follow_user);
|
|
|
|
// 使用第一个成员获取客户列表
|
|
if (followUserList.follow_user && followUserList.follow_user.length > 0) {
|
|
const firstUserId = followUserList.follow_user[0];
|
|
const contactList = await client.getExternalContactList(firstUserId);
|
|
console.log('客户数量:', contactList.external_userid?.length || 0);
|
|
}
|
|
```
|
|
|
|
### 获取客户列表
|
|
|
|
```typescript
|
|
// 获取指定成员的客户列表
|
|
const contactList = await client.getExternalContactList('zhangsan');
|
|
|
|
console.log('客户数量:', contactList.external_userid?.length || 0);
|
|
console.log('客户ID列表:', contactList.external_userid);
|
|
```
|
|
|
|
### 获取客户详情
|
|
|
|
```typescript
|
|
// 获取单个客户的详细信息
|
|
const contactDetail = await client.getExternalContact('external_user_id');
|
|
|
|
console.log('客户姓名:', contactDetail.external_contact.name);
|
|
console.log('客户类型:', contactDetail.external_contact.type === 1 ? '微信用户' : '企业微信用户');
|
|
console.log('跟进人数量:', contactDetail.follow_user.length);
|
|
```
|
|
|
|
### 批量获取客户详情
|
|
|
|
```typescript
|
|
// 批量获取客户详情（支持分页）
|
|
const batchContacts = await client.batchGetExternalContact('zhangsan', undefined, 100);
|
|
|
|
console.log('本次返回客户数量:', batchContacts.external_contact_list?.length || 0);
|
|
```
|
|
|
|
### 自动分页获取所有客户
|
|
|
|
```typescript
|
|
// 自动分页获取所有客户详情
|
|
const allContacts = await client.batchGetExternalContactFull('zhangsan');
|
|
|
|
console.log('总客户数量:', allContacts.length);
|
|
allContacts.forEach((contact, index) => {
|
|
console.log(`${index + 1}. ${contact.name} (${contact.external_userid})`);
|
|
});
|
|
```
|
|
|
|
### 获取客户详情（支持跟进人分页）
|
|
|
|
当跟进人超过500人时，使用 `getExternalContactFull` 方法自动获取所有跟进人：
|
|
|
|
```typescript
|
|
const fullDetail = await client.getExternalContactFull('external_user_id');
|
|
console.log('总跟进人数量:', fullDetail.follow_user.length);
|
|
```
|
|
|
|
## API说明
|
|
|
|
### 获取配置了客户联系功能的成员列表
|
|
|
|
**接口地址**: `https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_follow_user_list`
|
|
|
|
**请求参数**:
|
|
- `access_token`: 调用接口凭证
|
|
|
|
**响应字段**:
|
|
- `follow_user`: 配置了客户联系功能的成员userid列表
|
|
|
|
### 获取客户列表
|
|
|
|
**接口地址**: `https://qyapi.weixin.qq.com/cgi-bin/externalcontact/list`
|
|
|
|
**请求参数**:
|
|
- `access_token`: 调用接口凭证
|
|
- `userid`: 企业成员的userid
|
|
|
|
**响应字段**:
|
|
- `external_userid`: 外部联系人的userid列表
|
|
|
|
### 获取客户详情
|
|
|
|
**接口地址**: `https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get`
|
|
|
|
**请求参数**:
|
|
- `access_token`: 调用接口凭证
|
|
- `external_userid`: 外部联系人的userid
|
|
- `cursor`: （可选）上次请求返回的next_cursor，用于分页
|
|
|
|
**响应字段**:
|
|
- `external_contact`: 外部联系人详情
|
|
- `name`: 名称
|
|
- `type`: 1-微信用户，2-企业微信用户
|
|
- `gender`: 0-未知，1-男性，2-女性
|
|
- `position`: 职位（仅企业微信用户）
|
|
- `corp_name`: 企业简称（仅企业微信用户）
|
|
- `follow_user`: 添加了此外部联系人的企业成员列表
|
|
- `userid`: 成员userid
|
|
- `remark`: 备注
|
|
- `description`: 描述
|
|
- `createtime`: 添加时间
|
|
- `tags`: 标签列表
|
|
|
|
### 批量获取客户详情
|
|
|
|
**接口地址**: `https://qyapi.weixin.qq.com/cgi-bin/externalcontact/batch/get_by_user`
|
|
|
|
**请求参数**:
|
|
- `access_token`: 调用接口凭证
|
|
- `userid`: 企业成员的userid
|
|
- `cursor`: （可选）上次请求返回的next_cursor，用于分页
|
|
- `limit`: 返回的最大记录数，最大值1000，默认值为100
|
|
|
|
**响应字段**:
|
|
- `external_contact_list`: 外部联系人详情列表
|
|
- `next_cursor`: 下一次分页的起始位置
|
|
|
|
## 权限要求
|
|
|
|
应用需要配置到「客户联系 > 可调用接口的应用」中，并具有「客户基础信息」权限。
|
|
|
|
## 注意事项
|
|
|
|
1. **access_token有效期**: 7200秒，客户端会自动缓存并提前5分钟刷新
|
|
2. **分页限制**: 当跟进人超过500人时，必须使用cursor参数分页获取
|
|
3. **字段限制**: 第三方应用无法获取头像、性别、备注手机号、unionid等字段
|
|
4. **external_userid**: 需要通过其他接口（如获取客户列表）获取
|
|
|
|
## 相关文档
|
|
|
|
- [企业微信API文档 - 获取客户详情](https://developer.work.weixin.qq.com/document/path/101215)
|
|
- [企业微信API文档 - 获取access_token](https://developer.work.weixin.qq.com/document/path/91039)
|
|
|
|
## 许可证
|
|
|
|
MIT
|