如何用企业微信实现让微信收到通知实时通知

企业微信「应用消息」收单通知 --- 接入与踩坑记录

场景：小程序下单成功（支付成功）后，给老板/店员发微信通知。

采用方案：企业微信「应用消息」（免费、不限量）。

本文是按本项目实际落地整理出的完整步骤 + 网址 + 报错/坑位，可直接照着操作。

〇、整体流程总览

复制代码

① 企业微信后台建自建应用 → ② 拿到 企业ID/AgentId/Secret → ③ 配置可信域名+可信IP
→ ④ 后台填入三参数 → ⑤ 配收信人 → ⑥ 支付成功触发 → ⑦ 企业微信收到消息

文章目录

[企业微信「应用消息」收单通知 --- 接入与踩坑记录](#企业微信「应用消息」收单通知 — 接入与踩坑记录)
- 〇、整体流程总览
- 一、第一步：准备一个企业微信（你的企业）
- 二、第二步：创建自建应用
- 三、第三步：拿到三个参数（含网址）
- [四、第四步（最大坑位，务必按序）：可信域名 → 可信IP](#四、第四步（最大坑位，务必按序）：可信域名 → 可信IP)
- - [4.1 设置可信域名](#4.1 设置可信域名)
  - [4.2 配置企业可信IP](#4.2 配置企业可信IP)
- 五、第五步：后端接入并填参数
- - [5.1 接口地址（官方 API）](#5.1 接口地址（官方 API）)
  - [5.2 刷新 token（建议缓存，避免每次都取）](#5.2 刷新 token（建议缓存，避免每次都取）)
  - [5.3 发送一条文本消息（Node 示例）](#5.3 发送一条文本消息（Node 示例）)
- [六、第六步：项目 UI 配置](#六、第六步：项目 UI 配置)
- 七、第七步：部署、验证与收信
- - [7.1 想让消息在【个人微信】出现：必须先关注「微信插件」](#7.1 想让消息在【个人微信】出现：必须先关注「微信插件」)
  - [7.2 验证清单](#7.2 验证清单)
- 八、关键坑位速查

一、第一步：准备一个企业微信（你的企业）

管理后台（网页版）：https://work.weixin.qq.com
- 需用「企业登录」，账号是你当管理员的那个企业（不是被拉进去当成员的企业）。
- 没有管理员企业就点官网「企业注册」新建一个（免费），名称填公司/店铺名。
想先看清目录/成员，也可在侧边「通讯录」查看。

二、第二步：创建自建应用

路径：应用管理 →（子菜单）应用管理 → 自建 → 创建应用
填应用名称（如"订单提醒"）、选图标。
在「设置应用可见范围」里，勾选要接收通知的成员/部门 （如你的工作室），点确定。
- 也可以以后改：应用详情 → 可见范围。

三、第三步：拿到三个参数（含网址）

企业ID（CorpID）
- 路径：我的企业 → 企业信息（地址：work.weixin.qq.com/wework_admin 左侧「我的企业」）
- 它是一串以 ww 开头的 18 位字符串。
AgentId（应用ID）
- 路径：应用管理 →（子菜单）应用管理 → 点开你的自建应用 → 详情「基本信息」
- 纯数字（本项目为 1000002）。
Secret（应用密钥）
- 同一应用详情页 → 点「查看」→ 用管理员身份验证后复制（本项目形如 MnGm...）。

⚠️ Secret 属敏感信息：只放进发信服务器配置，不要贴到截图、上传到 git、写进前端。

四、第四步（最大坑位，务必按序）：可信域名 → 可信IP

企微 2023 后不先设「可信域名」就点不进「企业可信IP」配置，而这俩是发送消息是否被拦的关键。

4.1 设置可信域名

路径：应用详情 → 开发者接口 → 设置可信域名
需要你的域名（要求 ICP 备案主体与企业主体一致/相关联）。
页面上会要求做域名归属校验 ：给一个校验文件名 WW_verify_xxxx.txt（内容一串随机字符）。
- 把该文件放到域名根目录 ，让企微能访问到 https://你的域名/WW_verify_xxxx.txt。
- 本项目因为 nginx 把整个域名反代到了后端(3006,Express)，根路径没有这个文件会 404。解决：在 nginx 该域名配置里精确匹配放行 （如下），再 nginx -s reload：
  复制代码
```
location = /WW_verify_xxxx.txt { root /www/wecom_verify; }
```
  即把校验文件放到 /www/wecom_verify/ 目录。
- 自测：curl -s https://你的域名/WW_verify_xxxx.txt 应返回 200，body 就是那串校验字符。
确认能访问后，回到弹窗点「确定」，企微即完成校验。

4.2 配置企业可信IP

路径：应用详情 → 开发者接口 → 企业可信IP
填入发信服务器（本项目后端所在机器）的公网 IP），英文逗号分隔可多条，保存。
否则发送时会报 60020 not allow to access from your ip。

五、第五步：后端接入并填参数

5.1 接口地址（官方 API）

换取 token：GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=CorpID&corpsecret=Secret
发送消息：POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=TOKEN

5.2 刷新 token（建议缓存，避免每次都取）

js 复制代码

// GET gettoken 返回 { access_token, expires_in }
// token 有效期约 7200 秒

5.3 发送一条文本消息（Node 示例）

js 复制代码

const https = require('https');

async function sendWeComApp({ corpid, agentid, secret, touser, content }) {
  // 1. 取 token
  const token = await httpGet(`https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=${corpid}&corpsecret=${secret}`)
    .then(j => { if (j.errcode !== 0) throw new Error('gettoken失败: ' + j.errmsg); return j.access_token; });

  // 2. 发消息
  const body = JSON.stringify({
    touser,                 // 成员用户ID，或 @all = 应用可见范围全部成员
    msgtype: 'text',
    agentid: Number(agentid),
    text: { content },
    safe: 0,
  });
  const r = await httpPost(`https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=${token}`, body);
  if (r.errcode !== 0) throw new Error('send失败: ' + r.errmsg);
  return r;
}

touser 取值：
- 定向单人 → 该成员的用户ID ：企微后台 通讯录 → 点成员 → 账号 字段（本项目王健为 WangJian_1）。
- 全可见范围 → @all（容易让用户看起来像"群发"）。

六、第六步：项目 UI 配置

打开本项目后台 → 用户与管理员 → 企业微信通知设置：
- 填 企业ID / AgentId / Secret → 保存 → 点「发送测试消息」验证。
同页 值班人员管理：
- 新增值班人员 → 收信人填成员用户ID（如 WangJian_1）或 @all → 启用。
数据库结构：
- wecom_config（id=1 单行）：存 corpid, agentid, secret
- duty_staff：name, remark, send_key(收信人ID或@all), notify_type, enabled
代码位置：
- server/notify.js：sendWeComApp() 发送、notifyNewPaidOrder() 按启用的收信人逐个推送
- server/routes/admin.js：/admin/wecom-config、/admin/duty-staff/*、/admin/wecom-config/test
- server/routes/order.js：支付成功 时触发 ------ 微信支付 pay-success、余额全额抵扣 use-balance
触发时机约定：仅在支付成功（真正收款）后通知，未付款不通知、不重复。

七、第七步：部署、验证与收信

部署：paramiko SFTP 只传代码文件，保留 .env、water_shop.db、node_modules、uploads/、certs/；pm2 restart water-shop（改表结构后必须重启）。

7.1 想让消息在【个人微信】出现：必须先关注「微信插件」

企业微信「应用消息」最终默认落到企业微信 App ；要让它在个人微信 里出现，成员需要先关注发信企业的「微信插件」 ：
1. 管理员到后台 我的企业 → 微信插件，开启并在「邀请关注」处把二维码给成员（二维码 7 天有效，过期重新生成）；
2. 成员用个人微信（不是企业微信 App）扫该二维码，关注「企业微信插件」，即完成"个人微信 ↔ 该企业"绑定；
3. 绑定后，该企业的工作消息/通知才有可能透传到成员微信。
⚠️ 关键：扫码绑定的必须是你自己企业里「我的企业 → 微信插件」的二维码，别扫成别的企业/公众号的。
⚠️ 仍需注意：即使关注了微信插件，自建应用 message/send 消息很可能仍不透传到个人微信，只显示在企业微信 App。
因此本项目这套的保证是"企业微信 App 一定能收到 "；若必须"个人微信稳定弹出"，需另走认证公众号（不在本文范围）。

7.2 验证清单

后台「发送测试消息」收到 → 说明三参数 + 可信IP 都对。
定向发某个成员 → 确认只有该成员收到 （如误以为群发，检查收信人是否 @all）。
支付成功一单 → 后台「订单管理」状态正常，同时收到通知。

八、关键坑位速查

报错/现象	原因	处理
`60020 not allow to access from your ip`	发信IP不在可信IP	企业可信IP加服务器公网IP
无法配置可信IP，提示先设可信域名	可信域名还没配	先配可信域名并过归属校验
`WW_verify_xxx.txt` 访问 404	被 nginx 反代吞掉	加 `location =` 精确匹配读取本地文件
看起来"发给所有成员"	收信人填了 `@all`	定向填成员用户ID
只在企业微信App收到，个人微信没有	应用消息只到企微App；且需先在微信插件里关注	见 §7.1：先让成员扫企微插件二维码；仍不透传则需改用认证公众号