第三方集成

第三方集成把柠檬ERP 接入企业自己的钉钉、企业微信或飞书：员工可以用手机扫码登录、在钉钉 / 企业微信 / 飞书的工作台中点开系统自动登录，审批待办、到期提醒、预警等站内消息同时推送到员工的钉钉 / 企业微信 / 飞书和工作群，管理员还可以同步通讯录，把平台成员与系统账号对应起来。本页面向系统管理员。

支持的平台与能力

三个平台都通过「企业自建应用」接入，每个平台可以单独启用，也可以同时启用多个。

能力	钉钉	企业微信	飞书	说明
扫码登录	支持	支持	支持	登录页「其他登录方式」中点击平台图标，用手机 App 扫码确认后登录
应用内免登	支持	支持	支持	在平台工作台中打开应用、点击消息中的链接时自动登录
应用消息	工作通知	应用消息	机器人消息卡片	站内消息同时推送给已绑定的成员，带「查看详情」按钮
群机器人	支持（可加签）	支持（不支持加签）	支持（可加签）	按消息类别把消息发到一个工作群
通讯录同步	支持	支持	支持	按手机号把平台成员绑定到已有账号，可选自动创建部门和账号
成员绑定	支持	支持	支持	管理员手工填写成员 userid 绑定，或员工在个人中心自行扫码绑定

先绑定，才能登录和收消息

平台成员和系统账号之间要有「绑定关系」：用平台账号登录时按绑定关系找到对应的系统账号，推送消息时也只推送给已绑定的成员。绑定有三种方式：同步通讯录按手机号自动绑定、管理员在成员绑定中手工绑定、员工在个人中心自行绑定。

页面入口

系统管理 → 第三方集成

页面顶部是钉钉、企业微信、飞书三张平台卡片，点击卡片切换要配置的平台。卡片上显示「已启用」或「未启用」，以及已开启的功能摘要：未启用时为「未配置」，启用后按开启情况显示「登录 · 消息推送 · 群机器人」。

卡片下方有两个页签：

• 应用配置：填写应用凭证、系统访问地址，开关各项功能，设置群机器人，右侧是该平台的「接入步骤」；
• 成员绑定：同步通讯录，查看和维护系统用户与平台成员的绑定关系。

权限

权限	可以做什么
第三方集成（菜单）	查看各平台的配置和成员绑定列表
集成配置修改	保存配置、「测试连接」「测试群机器人」。没有此权限时表单只读，不显示底部按钮
通讯录同步与绑定	「同步通讯录」、手工绑定、修改、解除绑定。没有此权限时不显示这些按钮

初始数据中只有超级管理员拥有本菜单（配置中包含应用密钥）。SaaS 模式下本菜单属于「基础平台」，新租户的租户管理员按套餐获得，可以为本租户配置集成；需要其他人维护时在角色管理中授权。

准备工作

开始之前，请先确定系统访问地址：员工在浏览器或手机上打开柠檬ERP 前端页面的地址，例如 https://erp.example.com。平台授权后会跳回这个地址，消息中的链接也指向这个地址，所以员工的手机和电脑必须能访问它（员工在公司外使用手机时需要外网可访问），建议使用 HTTPS。

填写系统访问地址并保存后，「应用配置」页签中会显示两个地址，点击右侧的复制图标即可复制，在平台中登记：

地址	格式	用途
回调地址	系统访问地址/im-callback，例如 https://erp.example.com/im-callback	扫码登录、应用内免登、个人中心绑定时，平台授权后跳回的页面。在平台中登记为重定向 URL / 回调
应用首页	系统访问地址/im-login?platform=平台&tenant=租户ID，例如 https://erp.example.com/im-login?platform=DINGTALK&tenant=1	在平台工作台中点开应用时进入的地址，会自动登录后进入首页。在平台中登记为应用首页 / 主页

每个平台的「应用配置」页签右侧都有「接入步骤」提示，内容与下文一致。

钉钉

1. 用管理员账号登录钉钉开发者后台（open-dev.dingtalk.com），创建「企业内部应用」。
2. 在「凭证与基础信息」中复制 Client ID（原 AppKey）和 Client Secret（原 AppSecret），在应用详情中查看 AgentId。
3. 在「权限管理」中开通：通讯录部门信息读权限、成员信息读权限、个人手机号信息、根据 unionId 获取成员 userId（通讯录个人信息读权限）。
4. 在「安全设置 → 重定向 URL」中填写上面的回调地址。
5. 在「网页应用」中把应用首页（PC 端和移动端）设为上面的应用首页地址，成员在工作台点开即自动登录。
6. 发布应用并设置可见范围（通讯录同步只能读到可见范围内的部门和成员），再回到柠檬ERP 保存配置、测试连接。

需要记录的参数：Client ID、Client Secret、AgentId。

企业微信

1. 在企业微信管理后台「应用管理 → 自建」中创建应用，复制 AgentId 和 Secret；在「我的企业」页面底部查看 企业ID。
2. 在应用中设置「网页授权及 JS-SDK → 可信域名」和「企业微信授权登录 → Web 网页 → 授权回调域」，都填写系统访问地址的域名（不含 https:// 和路径）。
3. 「应用主页」设为上面的应用首页地址；在「企业可信 IP」中加入柠檬ERP 服务器访问外网时的出口 IP（服务器调用企业微信接口需要）。
4. 把成员加入应用的可见范围。
5. 回到柠檬ERP 保存配置、测试连接。

需要记录的参数：企业ID（CorpID）、AgentId、应用 Secret。

企业微信的手机号

2022 年 6 月后新建的企业微信自建应用读取通讯录时不返回手机号，此时同步通讯录无法按手机号自动绑定（这些成员会计入「未绑定」）。请在成员绑定中手工填写成员的「账号」，或让员工在个人中心自行扫码绑定。

飞书

1. 在飞书开放平台（open.feishu.cn）创建「企业自建应用」，复制 App ID 和 App Secret，并在「添加应用能力」中开启机器人（发送应用消息需要）。
2. 在「权限管理」中开通：获取用户 user ID、获取通讯录基本信息（以应用身份读取通讯录）、获取用户手机号、获取用户邮箱、以应用的身份发消息。
3. 在「安全设置 → 重定向 URL」中添加上面的回调地址。
4. 在「网页应用」中把桌面端和移动端主页设为上面的应用首页地址。
5. 设置通讯录权限范围后创建版本并发布，再回到柠檬ERP 保存配置、测试连接。

需要记录的参数：App ID、App Secret。

应用配置

字段说明

不同平台「应用凭证」中的字段不同：

平台	应用凭证字段
钉钉	Client ID（原 AppKey）、Client Secret（原 AppSecret）、AgentId
企业微信	企业ID（CorpID）、AgentId、应用 Secret
飞书	App ID、App Secret

全部字段：

字段	说明
启用 X 集成	总开关，默认关闭。关闭时该平台的登录、消息推送、群机器人、通讯录同步都不可用；打开后下方带红色星号的字段为必填
应用凭证	见上表。启用时必填：钉钉的 Client ID、飞书的 App ID、企业微信的企业ID；钉钉和企业微信的 AgentId（只能填数字，否则提示「AgentId 应为数字」）。企业ID、应用标识不超过 64 个字符，AgentId 不超过 32 个字符
密钥（Client Secret / 应用 Secret / App Secret）	启用时必填，不超过 128 个字符。密钥保存后不会再显示，输入框提示「已设置，留空表示不修改」；需要更换时直接输入新密钥
系统访问地址	启用时必填。外网可访问的前端地址，格式为 http(s)://域名[:端口][/路径]，例如 https://erp.example.com；末尾的 / 会自动去掉。格式不对时提示「系统访问地址格式不正确，应为 http(s)😕/域名[:端口][/路径]」
回调地址、应用首页	只读，保存了系统访问地址后显示，用于在平台中登记，见准备工作
扫码登录与免登	默认开启。登录页显示该平台的登录方式；从平台工作台、消息中打开系统时自动登录。关闭后登录页不再显示该平台图标，用平台账号登录会提示「未开启 X 登录」（个人中心仍可绑定，消息推送不受影响）
消息推送	默认开启。审批待办、到期提醒、预警等站内消息同时推送给已绑定的成员，见消息推送
同步通讯录时自动创建部门和账号	默认关闭。关闭时同步通讯录只按手机号绑定已有账号；开启后按平台的部门树建立部门，并为没有账号的成员开通账号（登录名为手机号，初始密码见参数设置），见同步通讯录
群机器人 → Webhook 地址	选填，留空不推送到群。在工作群的「群设置 → 机器人 → 添加自定义机器人」后复制。地址必须以该平台的机器人地址开头，否则提示「X群机器人的 Webhook 地址应以 … 开头」：钉钉 https://oapi.dingtalk.com/robot/send，企业微信 https://qyapi.weixin.qq.com/cgi-bin/webhook/send，飞书 https://open.feishu.cn/open-apis/bot/v2/hook/。地址按密码方式显示，可点眼睛图标查看
群机器人 → 加签密钥	只有钉钉和飞书有此项（企业微信群机器人没有加签）。机器人安全设置选择「加签」时填写，不加签可不填。保存后不再显示；已设置时输入框右侧有「清除」勾选框，勾选并保存即删除已保存的加签密钥
群机器人 → 推送的消息类别	勾选「审批」「提醒」「预警」「系统」中要发到群里的类别，默认只勾选「预警」

保存配置

1. 点击顶部要配置的平台卡片。
2. 打开「启用 X 集成」开关，填写应用凭证和系统访问地址。
3. 按需开关各项功能、填写群机器人。
4. 点击 保存，提示「已保存」。保存后页面显示回调地址和应用首页，把它们登记到平台中（见准备工作）。

未启用时也可以保存（不校验必填项），便于分步填写。修改配置后系统会自动清除缓存的平台访问令牌，新的凭证立即生效。

测试连接

配置已启用并保存后，点击 测试连接：系统用保存的凭证重新向平台获取访问令牌，验证凭证是否正确。

• 当前登录的管理员还没有绑定该平台账号时，提示「连接成功（你还没有绑定 X 账号，未发送测试消息）」；
• 已绑定时，再向管理员本人发送一条标题为「集成测试」的应用消息，提示「连接成功，已向你的 X 发送一条测试消息」，可以顺便确认消息推送是否正常；
• 凭证错误、权限不足时提示平台返回的错误，格式为「X 返回错误（错误码）：错误原因」；服务器无法访问平台时提示「X 接口调用失败，请检查网络：…」。

测试群机器人

填写并保存了 Webhook 地址后，点击 测试群机器人，系统向群里发送一条「群机器人测试」消息，提示「已发送，请到群里查看」。没有保存 Webhook 地址时按钮不可用。

机器人的安全设置

钉钉、飞书的自定义机器人必须选择一种安全设置：选择「加签」时把密钥填到「加签密钥」中；选择「自定义关键词」时，只有标题或内容中包含关键词的消息才能发出（测试消息的标题是「群机器人测试」，正文含「ERP」）；选择「IP 地址」时把服务器的出口 IP 加入白名单。企业微信群机器人不需要安全设置。

成员绑定

「成员绑定」页签列出系统中的用户（不含供应商、经销商等门户账号）及其在当前所选平台上绑定的成员。切换顶部的平台卡片即切换要查看的平台。

查询与列表

查询条件	说明
全部 / 已绑定 / 未绑定	按绑定状态筛选
关键字	按用户名、姓名、手机号或成员 userid 模糊查询

列	说明
用户	姓名（没有时为用户名），下方灰色小字为用户名
部门	用户所属部门
手机号	系统用户的手机号，同步通讯录时按它匹配
绑定成员	「已绑定」标签、成员在平台中的姓名和 userid；未绑定显示「未绑定」
绑定时间	建立绑定的时间
操作	未绑定：「绑定」；已绑定：「修改」「解除绑定」

右上方显示最近一次同步的时间和结果，例如「最近同步 2026-10-17 09:00:00：成员 18 人：之前已绑定 0，按手机号绑定 16，新建账号 0，未绑定 2」。

手工绑定

手机号不一致、平台不返回手机号（如新建的企业微信应用）时，可以手工填写成员的 userid 绑定：

1. 在列表中找到用户，点击 绑定（已绑定的点击 修改）。
2. 在弹出的「绑定 X 成员」对话框中填写 成员 userid（必填，最多 64 个字符）。输入框下方提示了 userid 在平台中的位置：
   • 钉钉：钉钉管理后台「通讯录 → 成员管理」中成员详情的 userid；
   • 企业微信：企业微信管理后台「通讯录」中成员详情的「账号」；
   • 飞书：飞书管理后台「组织架构 → 成员与部门」中成员详情的「用户 ID」。
3. 点击 确定，提示「已绑定」。

规则：

• 平台未启用时不能绑定，提示「未启用 X 集成」；
• 一个平台成员只能绑定一个用户，一个用户在每个平台上也只能绑定一个成员。该成员已绑定其他用户时提示「该 X 账号已绑定用户「用户名」，请先解除绑定」；用户已绑定其他成员时，「修改」后改为新填写的成员；
• 系统不会向平台核实手工填写的 userid 是否存在，填错时该员工无法用平台登录、也收不到消息，请仔细核对。手工绑定的记录没有成员姓名，列表中只显示 userid。

解除绑定

点击 解除绑定，确认「确定解除绑定？解除后该成员不能再用平台账号登录，也收不到消息推送」后提示「已解除绑定」。解除绑定不影响系统账号本身。下次同步通讯录时，如果手机号仍然匹配，该成员会被重新自动绑定。

同步通讯录

在「成员绑定」页签点击 同步通讯录（配置未启用时按钮不可用），确认后系统从平台读取应用可见范围（通讯录权限范围）内的部门和成员，按以下规则处理。成员较多时需要等待一段时间（最长 3 分钟）。

自动绑定规则

对通讯录中的每个成员依次处理：

1. 该成员在本平台已绑定系统用户：跳过，计入「之前已绑定」（不会改变已有的绑定）。
2. 按手机号查找系统用户（不含门户账号）：手机号只比较数字，去掉 +86 / 86 国家码和空格、横线等符号。恰好找到一个用户、且该用户在本平台还没有绑定其他成员时，自动绑定，计入「按手机号绑定」。
3. 找不到用户时，如果开启了「同步通讯录时自动创建部门和账号」，为该成员开通账号并绑定，计入「新建账号」。
4. 其余情况计入「未绑定」：平台没有返回手机号且未开启自动创建、系统中没有这个手机号的用户且未开启自动创建、多个用户使用同一手机号（无法确定对应关系，不自动绑定）、匹配到的用户已绑定了其他成员。

自动创建部门和账号

只有开启「同步通讯录时自动创建部门和账号」时才会执行：

• 部门：平台的根部门（企业本身）对应系统的顶级部门（没有顶级部门时提示「请先在部门管理中建立顶级部门」）；其他部门按平台的部门树逐级对应：同一上级下已有同名部门时直接对应，否则新建（启用状态，排序取平台中的顺序）。对应关系会被记住，之后在平台中给部门改名，再次同步时系统中的部门名称也随之修改；
• 账号：登录名优先使用成员的手机号；没有手机号或手机号已被其他账号用作登录名时，使用「平台_成员 userid」，如 dingtalk_zhangsan、wecom_zhangsan、feishu_ou123（重复时加 _2、_3）。姓名、手机号、邮箱取平台中的信息，部门为成员所在的第一个部门对应的系统部门；密码为「参数设置 → 密码策略 → 初始密码」，首次登录要求修改；
• 不删除、不停用：同步只增加部门、账号和改名，不会删除系统中的部门，也不会停用账号。员工离职请在人事中办理离职或在用户管理中停用；
• 账号数受租户套餐的账号上限限制，达到上限时停止开通，其余成员计入「未绑定」，并提示「未能继续开通账号：…」。

新账号没有角色

自动创建的账号不分配任何角色，登录后看不到业务菜单。同步后请在用户管理或角色管理中为新账号分配岗位角色；新建的部门也需要在部门管理中设置负责人（审批流程中的部门主管依赖它）。

同步结果

同步完成后弹出「同步完成」对话框：

项目	含义
通讯录成员	本次读取到的成员人数
按手机号绑定	本次按手机号绑定到已有账号的人数
新建账号	本次新开通账号并绑定的人数
之前已绑定	在本次同步之前就已绑定的人数
新建部门 N 个	本次新建的部门数（只在有新建时显示）
黄色提示	未全部完成的原因，如账号数达到套餐上限
未绑定 N 人	没有绑定的成员，列出姓名（最多 50 个，超出时显示「等」），可在列表中手工绑定

同步结果同时保存为「最近同步」信息，显示在成员绑定页签右上方。可以多次同步，已绑定的成员不会重复处理。

消息推送

哪些消息会推送

所有站内消息（审批、提醒、预警、系统四类，见我的消息）在写入后都会按以下规则推送，每个已启用的平台分别处理：

推送方式	条件	接收人	消息形式
应用消息	开启了「消息推送」	收到这条站内消息的用户中，已绑定该平台的成员；没有绑定的用户只收到站内消息	钉钉：工作通知卡片；企业微信：应用消息文本卡片；飞书：机器人发送的消息卡片。标题和内容与站内消息一致，卡片带「查看详情」（企业微信为「详情」）按钮
群机器人	填写了 Webhook 地址，且消息类别在「推送的消息类别」中	机器人所在的工作群	标题、内容加「查看详情」链接；同一条消息发给多人时，群里只发一次

• 消息在业务操作成功保存后异步推送，不会拖慢业务操作；业务操作失败回滚时不会推送；
• 「查看详情」打开的是应用内免登入口，在平台中点开后自动登录并进入消息关联的页面（例如待审批的单据），没有关联页面时进入首页；
• 每天只提醒一次的定时提醒，在平台中同样每天只推送一次；
• 推送的标题和内容与站内消息相同，按生成时的中文发送，「查看详情」按钮文字也是中文，不随用户的界面语言变化。在平台中点开后进入的系统页面使用该设备浏览器中的语言设置（见语言切换）。

推送失败

推送失败（凭证失效、成员不在应用可见范围、机器人被移出群、网络不通等）只记录在服务器日志中，不会重试，也不影响站内消息：员工仍可以在系统的「我的消息」中看到。收不到推送时请按常见问题逐项检查，并用「测试连接」「测试群机器人」验证。

扫码登录与应用内免登

以下是员工使用时的流程，详细说明见登录与账号。

扫码登录：登录页的「其他登录方式」中显示已启用并开启了「扫码登录与免登」的平台图标（SaaS 模式下填写租户名称后才显示）。点击图标跳转到平台的授权页面，用手机上的钉钉 / 企业微信 / 飞书扫码确认后回到系统，按绑定关系登录。

应用内免登：在平台的工作台中打开柠檬ERP 应用，或点击推送消息中的「查看详情」，页面显示「正在进入 X…」，在平台客户端内自动完成授权并登录，然后进入对应页面；该浏览器中已经登录过且登录未过期时直接进入。

成员没有绑定系统用户时，登录失败并提示「该 X 账号（userid）还没有绑定系统用户，请先用账号密码登录，在个人中心绑定，或联系管理员同步通讯录」，这次失败会记入登录日志（用户名记为「X:userid」）。平台账号登录成功也记入登录日志，提示为「钉钉登录成功」「企业微信登录成功」「飞书登录成功」。

用平台账号登录与账号密码登录一样受账号状态约束：停用的账号不能登录；供应商、经销商门户账号不能用平台账号登录；密码仍是初始密码或已过期时，登录后同样要求先修改密码。

多租户

开启 SaaS 多租户时：

• 每个租户在自己的「第三方集成」中接入自己企业的钉钉 / 企业微信 / 飞书应用，配置、绑定关系、同步的部门和账号都只属于本租户；
• 登录页按填写的租户名称显示该租户启用的登录方式；应用首页和消息链接中带有租户 ID（tenant=…），在平台中打开时直接进入对应租户，租户停用或过期时提示「租户不存在或已停用」；
• 「应用首页」地址因租户而异，请以本租户页面上显示的为准。

安全注意事项

• 密钥只写不读：应用密钥和加签密钥保存后不再返回给页面，操作日志中也会隐藏应用密钥、Webhook 地址和加签密钥。Webhook 地址本身就是向群里发消息的凭证，请不要外泄；怀疑泄露时在平台中重置密钥或重新生成机器人，再到这里更新；
• 授权校验：每次授权都带有一次性的随机校验码，10 分钟内有效，使用一次即作废，超时或重复使用提示「授权已过期，请重新操作」；登录后跳转的页面只允许是系统内的页面；
• 回调地址要一致：平台只会跳回在平台中登记的回调地址，系统访问地址变更后，要同时修改平台中的重定向 URL / 可信域名和应用首页；
• 建议系统访问地址使用 HTTPS；部署要求（外网访问、服务器出口、多台服务器共用 Redis 等）请转告运维人员，参见开发文档的生产环境配置；
• 演示环境中保存配置、测试连接、同步通讯录等操作都会被拦截。

常见问题

现象	原因与处理
「测试连接」按钮是灰色的	配置还没有启用并保存。打开「启用 X 集成」开关并保存后再测试
「同步通讯录」按钮是灰色的	同上，配置未启用
同步后很多成员「未绑定」	平台没有返回手机号（企业微信新应用、钉钉 / 飞书未开通手机号权限），或系统用户没有填写手机号、手机号不一致、多个用户手机号相同。补全用户手机号后重新同步，或手工绑定
登录页没有出现平台图标	配置未启用或关闭了「扫码登录与免登」；SaaS 模式下还没有填写租户名称或租户名称不正确
扫码后提示「没有收到授权码，可能是取消了授权」	在平台的授权页面取消了授权，或回调地址登记不正确
提示「请先在第三方集成中填写系统访问地址」	系统访问地址为空，填写并保存

更多问题见常见问题 → 第三方集成。