---
tags: [企业微信, 集成, 配置]
date: 2026-07-29
---

## 凭证

| 参数 | 值 |
|------|-----|
| 企业 ID (CorpID) | `wwa979fc0ebcce602a` |
| 应用 ID (AgentID) | `1000008` |
| 应用 Secret | `3QIxJQfqFgACBBcybmyc_I-mOoFvicH-Y6hdQ09ldLk` |
| Token（回调验证） | `dc56c68beba4c06984ce17c6342cacb1` |
| EncodingAESKey（回调加密） | `WngnBCzsdXlPcdNBVG6l7auYMokMvuM94jMunTdSEHM` |
| 回调 URL | `http://api.zilanlife.com/wecom/callback` |
| 服务端 IP | `59.51.140.250` |
| 可信域名 | `api.zilanlife.com` |
| DeepSeek API Key | `sk-8a62671966e1470bb1a6b223a9a549fa` |
| 回调服务端口 | `18790`（仅 127.0.0.1） |

---

## 一、配置步骤

### 1. 创建自建应用

登录 [work.weixin.qq.com](https://work.weixin.qq.com) → 应用管理 → 创建应用

### 2. 创建子域名并配置服务器

**DNS（用户操作）**：A 记录 `api.zilanlife.com` → `47.109.158.218`

⚠️ `api.zilanlife.com` 走 Nginx 80 端口（HTTP），不需要额外开放端口。`/wecom/callback` 路径反代到内网 `127.0.0.1:18790`。

**Nginx（Hermes 在 aliyun2 执行）**：
```bash
cat > /www/server/panel/vhost/nginx/api.zilanlife.com.conf << 'EOF'
server {
    listen 80;
    server_name api.zilanlife.com;
    root /www/wwwroot/api.zilanlife.com;
    index index.html;

    location /wecom/callback {
        proxy_pass http://127.0.0.1:18790;
        proxy_set_header Host $host;
        proxy_read_timeout 60s;
    }
}
EOF
mkdir -p /www/wwwroot/api.zilanlife.com
nginx -t && nginx -s reload
```

### 3. 验证域名归属

1. 企业微信应用详情页 → 网页授权及JS-SDK → 可信域名 → 输入 `api.zilanlife.com`
2. 下载验证文件 `WW_verify_j5y70gNGnVqhnH4d.txt`
3. 上传到服务器：
```bash
echo 'j5y70gNGnVqhnH4d' > /www/wwwroot/api.zilanlife.com/WW_verify_j5y70gNGnVqhnH4d.txt
```
4. 确认 `http://api.zilanlife.com/WW_verify_j5y70gNGnVqhnH4d.txt` 可访问
5. 点击验证通过

### 4. 配置 IP 白名单

应用详情页 → 企业可信 IP → 添加 `59.51.140.250`

⚠️ 必须先完成域名验证才能操作。

### 5. 配置接收消息

应用详情页 → 接收消息 → 设置API接收：

| 字段 | 值 |
|------|-----|
| URL | `http://api.zilanlife.com/wecom/callback` |
| Token | `dc56c68beba4c06984ce17c6342cacb1` |
| EncodingAESKey | `WngnBCzsdXlPcdNBVG6l7auYMokMvuM94jMunTdSEHM` |

消息事件勾选：用户发送的普通消息

### 6. 部署回调服务

Python 脚本路径：`/data/wecom_callback.py`（aliyun2）

依赖安装：
```bash
pip3 install pycryptodome
```

启动命令：
```bash
nohup python3 /data/wecom_callback.py > /data/wecom_callback.log 2>&1 &
```

重启命令：
```bash
pkill -f wecom_callback.py
nohup python3 /data/wecom_callback.py > /data/wecom_callback.log 2>&1 &
```

---

## 二、回调服务架构

```
员工在企微发消息
    ↓
企微 POST 加密 XML → api.zilanlife.com/wecom/callback
    ↓
Nginx 反代 → 127.0.0.1:18790（Python 服务）
    ↓
1. URL 验证（GET）：解密 echostr → 返回明文
2. 接收消息（POST）：解密消息体 → DeepSeek AI → 加密回复
```

### 核心功能

1. **URL 验证**：GET 请求，解密 `echostr` 参数并返回明文（企业微信首次配置时调用）
2. **消息接收**：POST XML 加密体，解密后得到用户消息
3. **AI 回复**：调 DeepSeek API 生成回复
4. **加密发送**：加密回复 XML，通过 HTTP 响应直接返回

### 加密/解密

- 算法：AES-256-CBC，IV 为 AES Key 前 16 字节
- 明文结构：`16字节随机串 + 4字节消息长度(big-endian) + 消息内容 + Corpid`
- PKCS7 填充到 32 字节倍数

---

## 三、API 参考

### 主动发消息

```python
POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={TOKEN}
{
    "touser": "WuXingdeYeKong",
    "msgtype": "text",
    "agentid": 1000008,
    "text": {"content": "消息内容"}
}
```

### 获取通讯录

```python
GET https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token={TOKEN}&department_id=1&fetch_child=1
```
- 返回 155 人
- `userid` 如 `WuXingdeYeKong`，不一定是姓名拼音
- 申亮 = `WuXingdeYeKong`

### Access Token

- 接口：`GET /cgi-bin/gettoken?corpid=...&corpsecret=...`
- 有效期：7200 秒（2 小时）
- 需缓存复用

---

## 四、诗词 API

- 端点：`http://47.109.158.218:1279/api/v1/poems/random`
- 搜索：`http://47.109.158.218:1279/api/v1/poems/search?q=关键词`
- ⚠️ 搜索按内容不按作者，搜"李白"返回提及的诗，非李白所作
- 按作者找：用 random 随机抽取直到命中

---

## 五、踩坑记录

| 坑 | 现象 | 解决 |
|----|------|------|
| 未配可信域名 | IP 白名单无法添加 | 先验证域名，再配 IP |
| IP 未加白 | 通讯录/user API 返回 60020 | 应用详情 → 企业可信 IP |
| `userIds` 参数无效 | user/list 返回所有人 | 拉全量客户端建映射 |
| 回调 Key 不一致 | URL 验证失败 | Token/EncodingAESKey 需与后台严格一致 |
| DeepSeek Key 错误 | 401 Authorization Required | 使用正确的 sk-xxx key |
| 搜索按内容不按作者 | 搜"李白"返回马致远 | random 抽到命中为止 |

---

## 七、消息模板

### 签单前复盘表 — 设计师通知

**数据来源**：销帮帮 formId=7539701，2026年，模板创建（text_12=ef4570ef...），排除关联客户已删除的记录

**业务术语**：
- `模板创建` = 销帮帮 text_12 值为模板创建 UUID
- 对外展示为「未填写」（业务语境：记录已创建但未完善）

**卡片格式**（手机端适配，分割线不超过 5 个 ━）：

```
📊 {设计师名} — 2026年签单前复盘表
━━━━━
📝 未填写  {N} 条
━━━━━
请在规定范围时间内登录销帮帮填写完毕！
```

**示例**：
```
📊 陈叶婷 — 2026年签单前复盘表
━━━━━
📝 未填写  5 条
━━━━━
请在规定范围时间内登录销帮帮填写完毕！
```

**流程**：
1. 销帮帮 API 拉取 formId=7539701，筛选 text_12=模板创建
2. 过滤 addTime >= 2026-01-01
3. customer/detail 校验每条 text_2，排除 code=100404
4. 按 ownerId 分组统计，id2name 查姓名
5. **姓名映射**（销帮帮→企微）后查 userid，逐人发送

**API 调取条件**：
```json
{
  "corpid": "xbb8abca6c277b846dab5e0c8a52fe9506e",
  "formId": 7539701,
  "conditions": [
    {"attr": "text_12", "value": ["ef4570ef-5460-7b62-b888-b3295f475e51"], "symbol": "equal"}
  ],
  "pageSize": 100, "page": 1
}
```
然后客户端过滤 `addTime >= 2026-01-01`，再逐条 `customer/detail` 排除 `code=100404`。

**发送规则**：
- 按设计师分组，每人一条卡片（只含自己的数量）
- 姓名映射转换后查企微 userid
- 赵耀跳过（企微无此人）
- 每条间隔 ≥ 0.5 秒（避免企微频率限制）

**姓名映射**：

| 销帮帮 | 企业微信 | userid |
|--------|----------|--------|
| 胡华玉 | 胡玉 | WeiXiaoXiangYang |
| 陈明先 | 陈想 | ChenXiang |
| 王飞 | 王习僧 | b5ed7c2b0034f08e6ae8e87d758b39a6 |
| 赵耀 | ❌ 不存在 | — |

---

## 八、已验证功能

- ✅ Token 获取
- ✅ 通讯录读取（155 人）
- ✅ 主动发送消息
- ✅ 诗词 → 企微发送
- ✅ 接收消息回调 + URL 验证
- ✅ 员工消息 → DeepSeek AI → 自动回复