wip

2026-01-12 18:01:04 +08:00
commit 94784ee1ec
39 changed files with 2847 additions and 0 deletions
@@ -0,0 +1,237 @@
+# 企业微信客户联系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