Risemap绑定飞书说明文档
更新于 2026年6月22日
| 适用对象 企业管理员、飞书开发者后台管理员、Risemap 系统管理员。 |
|---|
| 安全提醒 App Secret、Verification Token、Encrypt Key 属于敏感凭证，请仅在授权人员范围内流转，不要在群聊、截图或外部工单中明文暴露。 |
|---|
本文档用于指导客户在飞书开放平台创建企业自建应用，并在 Risemap 系统中完成飞书插件绑定。优化版对原文档进行了编号修正、术语统一、流程重组，并补充了检查清单和常见问题。
文档信息
| 项目 | 内容 |
|---|---|
| 系统 | Risemap |
| 平台 | 飞书开放平台 / 企业自建应用 |
| 默认主页地址 | https://risemap.cn |
| 默认发布版本 | 1.0.0 |
| 可用范围 | 建议设置为全部员工，或按客户实际组织范围授权 |
目录
**1. **配置总览
**2. **准备工作
**3. **创建飞书企业自建应用
**4. **添加应用能力
**5. **配置网页应用主页地址
**6. **开通权限
**7. **配置事件与回调
**8. **发布应用版本
**9. **在 Risemap 中绑定飞书插件
**10. **能力开启与验证
**11. **验收清单与常见问题
1. 配置总览
整体接入分为两个阶段：先在飞书开放平台创建并发布企业自建应用，再回到 Risemap 系统插件中心填写应用凭证并开启所需能力。
| 阶段 | 操作位置 | 核心动作 | 完成标志 |
|---|---|---|---|
| 阶段一 | 飞书开放平台 | 创建企业自建应用，添加机器人、网页应用，开通权限，配置事件回调并发布版本 | 应用版本发布并由企业管理员审批通过 |
| 阶段二 | Risemap 系统 | 进入系统配置 - 插件中心 - 飞书，填写 App ID / App Secret，并按需开启能力 | 飞书插件保存成功，能力状态启用 |
| 阶段三 | 联合验证 | 检查授权、回调、组织架构、审批、考勤等能力是否可用 | Risemap 可正常获取飞书数据或收到事件通知 |
| 建议顺序 先完成飞书应用发布与审批，再配置 Risemap 插件。否则 Risemap 端保存成功后，实际调用飞书接口仍可能因权限未生效而失败。 |
|---|
2. 准备工作
**1. 打开飞书开放平台：**访问飞书开放平台应用管理页。
**2. 登录开发者账号：**建议使用客户企业管理员或具备应用开发权限的账号。
**3. 确认企业权限：**确认当前账号可创建企业自建应用、开通权限、发布版本并提交管理员审批。
**4. 准备 Risemap 管理员账号：**后续需要登录 Risemap 系统配置中的插件中心。
飞书开放平台地址：https://open.feishu.cn/app
3. 创建飞书企业自建应用
进入飞书开放平台后，选择“企业自建应用”，点击“创建企业自建应用”。按页面要求填写应用名称、描述，并选择合适的应用图标。
**• 应用名称：**建议使用“Risemap”或“Risemap 业务系统”，便于员工识别。
**• 应用描述：**建议说明该应用用于 Risemap 与飞书组织架构、审批、考勤、消息等能力对接。
**• 应用图标：**可使用 Risemap 品牌图标或客户认可的系统图标。
图 1 创建企业自建应用弹窗
创建成功后，点击应用卡片进入详情页。
图 2 企业自建应用列表
图 3 应用详情页，后续需要在此处查看 App ID 和 App Secret
4. 添加应用能力
进入应用详情页后，依次添加以下应用能力：
| 能力 | 用途 | 是否建议开启 |
|---|---|---|
| 机器人 | 用于向飞书会话发送消息、通知、交互卡片等 | 建议开启 |
| 网页应用 | 用于在飞书客户端内打开 Risemap 相关页面或入口 | 建议开启 |
图 4 添加应用能力，选择机器人与网页应用
5. 配置网页应用主页地址
在“网页应用”配置中，将桌面端主页地址设置为：
如果客户使用了私有化部署或专属域名，应替换为客户实际可访问的 Risemap 域名。
| 注意 主页地址必须是可从飞书客户端访问的 HTTPS 地址。若使用内网域名，需要确保客户网络环境和飞书客户端均可访问。 |
|---|
图 5 网页应用桌面端主页地址配置
6. 开通权限
权限开通建议按能力分组处理，避免漏选。每类权限均需要分别检查“应用身份权限”和“用户身份权限”两个 Tab。
| 权限生效 开通权限后通常还需要重新发布应用版本，并由企业管理员审批后才会正式生效。 |
|---|
| 权限类型 | 搜索关键词 | 应用身份权限 | 用户身份权限 | 说明 |
|---|---|---|---|---|
| 考勤权限 | attendance | 全选 9 个权限 | 全选 4 个权限 | 用于同步或查询飞书考勤相关数据 |
| 组织架构权限 | contact | 全选 43 个权限 | 全选 29 个权限 | 用于同步部门、用户、用户组等组织架构数据 |
| 审批权限 | approval | 全选 17 个权限 | 全选 9 个权限 | 用于读取或处理飞书审批相关数据 |
6.1 开通考勤权限
**1. **点击“开通权限”。
**2. **输入关键词 attendance。
**3. **在“应用身份权限”Tab 中全选 9 个权限并确认开通。
**4. **再次点击“开通权限”，输入 attendance。
**5. **在“用户身份权限”Tab 中全选 4 个权限并确认开通。
6.2 开通组织架构权限
**1. **点击“开通权限”。
**2. **输入关键词 contact
**3. **在“应用身份权限”Tab 中全选 43 个权限并确认开通。
**4. **再次点击“开通权限”，输入 contact。
**5. **在“用户身份权限”Tab 中全选 29 个权限并确认开通。
6.3 开通审批权限
**1. **点击“开通权限”。
**2. **输入关键词 approval。
**3. **在“应用身份权限”Tab 中全选 17 个权限并确认开通。
**4. **再次点击“开通权限”，输入 approval。
**5. **在“用户身份权限”Tab 中全选 9 个权限并确认开通。
图 6 权限管理入口
图 7 搜索并开通权限示例
7. 配置事件与回调
在“事件与回调”中配置回调方式。该配置用于飞书在审批、组织架构、机器人等事件发生时，将事件推送到 Risemap 服务端。
**1. **进入“事件与回调”。
**2. **选择事件配置或回调配置。
**3. **填写 Risemap 提供的回调地址。
**4. **按系统要求配置 Verification Token、Encrypt Key 等校验参数。
**5. **保存配置，并确保飞书平台校验通过。
| 回调地址 原始文档截图中未展示完整回调地址。正式交付时建议在此处补充“客户专属回调地址”的获取位置和格式。 |
|---|
图 8 事件配置入口
图 9 回调配置页面
8. 发布应用版本
完成能力、权限、事件回调配置后，需要创建并发布应用版本。
**1. **点击页面顶部的“创建版本”。
**2. **版本号建议填写 1.0.0。
**3. **其他版本说明可按客户实际情况填写。
**4. **将可用范围设置为“全部员工”，或按客户实际需要选择指定部门/成员。
**5. **点击保存后，等待企业管理员审批通过。
| 关键点 飞书应用发布后，当前配置才会正式生效。若后续又新增权限或修改回调配置，需要重新发布版本并审批。 |
|---|
图 10 创建应用版本入口
图 11 版本信息与可用范围配置
图 12 保存并提交审批
9. 在 Risemap 中绑定飞书插件
飞书应用发布并审批通过后，登录 Risemap 管理后台，进入“系统配置 - 插件中心”，打开“飞书”插件。
图 13 Risemap 插件中心中的飞书插件
在插件配置页中填写飞书开放平台的应用凭证。
| 字段 | 填写内容 | 来源 | 注意事项 |
|---|---|---|---|
| App ID | 飞书开放平台应用详情页中的 App ID | 飞书开放平台 - 应用详情 - 凭证与基础信息 | 原文档中的“aphid”应修正为“App ID” |
| App Secret | 飞书开放平台应用详情页中的 App Secret | 飞书开放平台 - 应用详情 - 凭证与基础信息 | 敏感信息，不要公开截图或发送给无关人员 |
| Verification Token | 如 Risemap 插件页要求填写，则填写飞书事件回调 Token | 飞书开放平台 - 事件与回调 | 用于校验事件来源 |
| Encrypt Key | 如启用加密回调，则填写飞书事件回调加密 Key | 飞书开放平台 - 事件与回调 | 应与飞书端保持一致 |
图 14 Risemap 飞书插件配置页
图 15 飞书开放平台中查看 App ID 与 App Secret
保存后，根据客户实际需要开启对应能力。
图 16 在 Risemap 中按需开启飞书能力
10. 能力开启与验证
保存飞书插件配置后，可在 Risemap 中进入各能力配置页进行启用和验证。不同客户可按需开启，不一定全部启用。
| 能力方向 | 建议验证项 | 验证结果 |
|---|---|---|
| 基础连接 | App ID / App Secret 保存成功，系统可正常获取 tenant_access_token | 接口调用不报鉴权错误 |
| 组织架构 | 可同步部门、用户信息 | Risemap 中可看到飞书组织数据 |
| 审批 | 可读取审批定义或审批实例 | 审批相关功能正常 |
| 考勤 | 可读取考勤组、考勤记录或相关配置 | 考勤相关功能正常 |
| 事件回调 | 飞书事件推送可到达 Risemap | 回调日志正常，无签名或解密失败 |
图 17 插件能力配置页示例一
图 18 插件能力配置页示例二
图 19 插件配置校验提示示例
图 20 数据或能力列表验证示例
11. 验收清单与常见问题
11.1 上线前检查清单
| 检查项 | 是否完成 | 备注 |
|---|---|---|
| 已创建企业自建应用 | □ | 应用名称与图标符合客户要求 |
| 已添加机器人能力 | □ | 用于消息通知或交互 |
| 已添加网页应用能力 | □ | 主页地址已配置为实际 Risemap 地址 |
| 考勤权限已开通 | □ | attendance 权限已检查应用身份和用户身份 |
| 组织架构权限已开通 | □ | contact 权限已检查应用身份和用户身份 |
| 审批权限已开通 | □ | approval 权限已检查应用身份和用户身份 |
| 事件回调已配置并校验通过 | □ | 回调地址、Token、Encrypt Key 一致 |
| 应用版本已发布并审批通过 | □ | 可用范围已确认 |
| Risemap 插件已保存 App ID / App Secret | □ | 敏感信息未外泄 |
| 已完成能力验证 | □ | 组织、审批、考勤、回调按需验证 |
11.2 常见问题
| 问题 | 可能原因 | 处理建议 |
|---|---|---|
| Risemap 保存成功但调用飞书接口失败 | 飞书权限未发布生效、应用未审批、App Secret 填写错误 | 检查应用版本是否已发布并审批；重新复制 App ID / App Secret；确认权限已开通 |
| 提示权限不足 | 只开通了应用身份权限，漏开用户身份权限，或版本未重新发布 | 按 attendance/contact/approval 分别检查两个 Tab，并重新发布版本 |
| 事件回调校验失败 | 回调地址不可访问、Token 或 Encrypt Key 不一致、HTTPS 证书异常 | 确认公网可访问、证书有效，飞书端和 Risemap 端参数一致 |
| 飞书客户端打不开 Risemap 页面 | 主页地址配置错误、域名不可访问、客户内网限制 | 确认主页地址为 HTTPS，并从飞书客户端所在网络测试访问 |
| 看不到应用入口 | 应用版本未审批通过或可用范围不包含当前用户 | 检查应用发布状态和可用范围 |