# 企业微信客户联系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