# 接入企业微信

把企业微信的自建应用接到 Raise 后，成员可以用企业微信扫码登录；还可以从企业微信同步通讯录、导入外部联系人、同步打卡与排班，接收企业微信的事件，把审批通过的单据记到经营里，并把消息中心的消息推到成员的企业微信。

Raise 这边的设置都在「我的组织」→「应用」→「协作平台」的企业微信卡片里，界面说明见[连接器与集成](/admin/connectors)。本页讲企业微信后台要做的事，以及做完后在 Raise 里填什么。

> **注意**
>
> 企业微信的消息推送、客户联系同步、考勤同步和事件回调目前只在模拟器上验证过，界面上也有「尚未对真实企业微信验证」的提示。下面写到的企业微信后台菜单名称来自公开文档，**以对方后台的最新说明为准**。

## 开始前准备

- 一个企业微信管理员账号，能在企业微信管理后台创建自建应用。
- Raise 里「管理员」角色的账号。只有管理员能修改「协作平台」。
- 向平台管理员要到本平台的出口 IP（配置「企业可信 IP」时要用）。

## 创建自建应用

1. 在企业微信管理后台「应用管理」里创建一个自建应用。
2. 记下「我的企业」页底部的企业 ID（corpid）。
3. 打开刚建的应用，记下它的 AgentId 和 Secret。
4. 在 Raise 的「协作平台」里，企业微信卡片上点「连接企业微信」，填写：

   | 字段 | 必填 | 填什么 |
   |---|---|---|
   | 「名称」 | 是 | 显示在登录页的按钮上，最多 60 个字符 |
   | 「企业 ID」 | 是 | 第 2 步的企业 ID，6–64 位字母、数字、下划线或连字符 |
   | 「应用 AgentId」 | 是 | 第 3 步的 AgentId，是数字 |
   | 「Secret」 | 是 | 第 3 步的 Secret。保存后不再显示，编辑时留空表示不改 |

5. 先完成下面的[授权回调域](#callback-domain)和[企业可信 IP](#trusted-ip)，再点「测试连接」。通过时提示「连接正常」「已取到凭证。」。
6. 点「连接」。

> **提示**
>
> 每个组织只能连接一个企业微信。已经连接的，点卡片上的「编辑」修改。

## 设置授权回调域

1. 在 Raise 的企业微信卡片上找到「授权回调域」，点代码块的复制按钮复制域名。「连接企业微信」对话框里也会写明要设成哪个域名。
2. 在企业微信管理后台打开这个自建应用，进入「网页授权及 JS-SDK」（企业微信授权登录）。
3. 把授权回调域设为刚复制的域名，保存。

## 加入企业可信 IP

1. 在企业微信管理后台打开这个自建应用，找到应用详情里的「企业可信 IP」。
2. 把本平台的出口 IP 全部加进去，保存。出口 IP 由部署方决定，「协作平台」页面不显示，请向平台管理员索取。

出口 IP 没加时，「测试连接」会报「本平台的出口地址不在应用的「企业可信 IP」里」，推送会报错误码 60020。

## 选择登录方式

「连接企业微信」和「编辑」对话框里有一组「成员第一次扫码登录时」的开关：

| 开关 | 打开时 | 什么时候打开 |
|---|---|---|
| 「首次登录自动创建账号」 | 成员第一次扫码时自动建账号。成员在企业微信里须有邮箱 | 想让企业微信里的人都能直接登录时。关闭后只有已邀请的成员能登录 |
| 「按邮箱关联已有账号」 | 扫码的人按邮箱并入 Raise 里已有的账号 | 仅当企业微信里的邮箱由管理员维护、成员不能自改时打开，否则可被冒充 |
| 「连接后立即在登录页提供扫码登录」 | 连接后登录页马上出现企业微信扫码登录 | 只在新建时出现。之后用卡片上的「停用登录」「启用登录」切换 |

## 填写通讯录同步 Secret

同步部门和成员需要一份通讯录专用的 Secret，应用自己的 Secret 不够。

1. 在企业微信管理后台「管理工具 - 通讯录同步」里取得专用 Secret，并确认它的权限范围包含要同步的部门。
2. 在 Raise 的企业微信卡片上点「编辑」，在「通讯录同步 Secret（可选）」里粘贴，保存。保存后卡片上显示「已设置」。
3. 到「组织结构」→「通讯录同步」打开自动同步或点「立即同步」。同步规则见[组织架构与门店](/admin/org-structure)。

没有读取通讯录的权限时，同步会报「没有读取通讯录的权限，检查「管理工具 - 通讯录同步」里的权限范围」。

## 填写客户联系 Secret

导入外部联系人、做渠道活码需要「客户联系」的专用 Secret。

1. 在企业微信管理后台「客户联系」里取得专用 Secret。
2. 在同一处的「可调用接口的应用」里勾选这个自建应用。
3. 在 Raise 的企业微信卡片上点「编辑」，在「客户联系 Secret（可选）」里粘贴，保存。也可以在「客户联系同步」面板点「填写 Secret」。
4. 在「客户联系同步」面板打开「自动同步」或点「立即同步」。

## 同步打卡与排班

1. 在企业微信管理后台取得打卡的专用 Secret，并在可调用应用里勾选这个自建应用。代码里记的位置是「应用管理 → 打卡」，这条路径尚待核实，以对方后台的最新说明为准。
2. 在 Raise 的「考勤与排班同步」面板点「填写 Secret」，在「打卡 Secret」里粘贴，点「保存 Secret」。
3. 选「同步间隔」（30 分钟到每天）和「回看天数」（1–31 天，排班另往后取 14 天），打开「自动同步」或点「立即同步」。

员工须先通过通讯录同步对上 Raise 账号，没有对上的会跳过并计数。

## 接收事件回调

事件回调让 Raise 及时收到通讯录变更、审批状态变化和外部联系人变更。

1. 在 Raise 的「事件回调」面板点「生成 Token 和密钥」。
2. 弹窗里显示「回调 URL」、Token 和 EncodingAESKey，各有复制按钮。提示「只显示这一次，现在就复制」，复制后点「我已复制保存」。
3. 在企业微信管理后台把这三项填进「接收事件服务器」。自建应用的「接收消息」、「通讯录同步」、「客户联系」各有一处，用到哪项就填哪处。
4. 订阅事件：通讯录变更、审批状态变化（审批映射需要）、外部联系人变更（用客户联系时）。
5. 在企业微信保存。验证通过后，Raise 面板上的状态变成「已验证」。

回调 URL 要能从公网访问（https，证书有效）。读审批详情还需要应用有「审批」接口权限，且「企业可信 IP」里有本平台的出口地址。

> **注意**
>
> 点「重新生成」后旧的 Token 和密钥立即失效，企业微信的事件会被拒绝，直到在企业微信里换成新的并重新验证。

## 审批模板映射

审批通过后在[经营](/apps/biz)里自动记一笔。需要先完成[事件回调](#events)并订阅审批状态变化。

1. 在企业微信的审批模板里找到模板 ID（TemplateId）和金额控件的 ID（形如 `Money-1500000000000`）。如果要按某个控件取往来方，也记下那个控件的 ID。
2. 在 Raise 的「审批模板映射」面板点「添加映射」，填写「模板 ID」「名称」「入账方式」「金额控件 ID」，按需填写「往来方控件 ID（可选）」「分类（可选）」「付款期限（天，可选）」。
3. 点「保存」。

只有「通过」的审批按映射记账，同一张只入账一次；没有映射的模板只记录。

## 消息推送

推送前，在企业微信管理后台确认这个自建应用：

1. 「可见范围」包含要收消息的成员。
2. 「企业可信 IP」里有本平台的出口地址（缺了会报错误码 60020）。
3. 「网页授权及 JS-SDK」里设了可信域名（本平台的工作台域名）。

然后在 Raise 的「通知」面板：

1. 在「推送哪些消息」里勾选要推的种类，设「每人每天最多推送」和「免打扰时间」（北京时间）。
2. 点「发一条测试消息给我」。成功时显示「企业微信已接收」，失败时显示「没有发出去」及原因。

成员要先关联企业微信账号才收得到：同步一次通讯录，或等成员扫码登录。成员点开推送的卡片会先到登录页，要扫码登录一次。

## 常见问题

#### 「测试连接」提示「连不上或设置不对」，怎么查？
看提示后面括号里的原因：「企业 ID 不对」「应用 Secret 不对」「本平台的出口地址不在应用的「企业可信 IP」里」「调用太频繁，被企业微信限流了，稍后再试」。按原因改对应的设置，再测一次。

#### 同步提示「没有读取通讯录的权限」？
在企业微信「管理工具 - 通讯录同步」里检查专用 Secret 的权限范围，确认包含要同步的部门。

#### 事件回调一直是「待验证」？
确认回调 URL、Token、EncodingAESKey 三项都原样填进了企业微信并已保存。忘了 Token 或密钥，只能点「重新生成」后重填。

#### 「通知」面板说还没有成员关联企业微信账号？
推送发不出去。先在「组织结构」→「通讯录同步」同步一次成员，或等成员扫码登录。