# 接入飞书

把飞书国内版的自建应用接到 Raise 后，成员可以用飞书扫码登录，Raise 还能从飞书只读同步部门和成员。

Raise 这边的设置在「我的组织」→「应用」→「协作平台」的飞书卡片里，通讯录同步在「组织结构」→「通讯录同步」。界面说明见[连接器与集成](/admin/connectors)。

> **注意**
>
> 飞书接入还没有对真实的飞书企业验证过，只在模拟器上测过。飞书开放平台里的菜单和权限名称，**以对方后台的最新说明为准**。国际版 Lark 不是这个接入。

## 开始前准备

- 一个能在飞书开发者后台创建企业自建应用的飞书账号。
- Raise 里「管理员」角色的账号。

## 创建自建应用

1. 在飞书开发者后台创建一个企业自建应用。具体菜单以对方后台的最新说明为准。
2. 在应用的「凭证与基础信息」里记下 App ID（`cli_` 开头）和 App Secret。
3. 在 Raise 的「协作平台」里，飞书卡片上点「连接飞书」，填写：

   | 字段 | 必填 | 填什么 |
   |---|---|---|
   | 「名称」 | 是 | 显示在登录页的按钮上，最多 60 个字符 |
   | 「应用 App ID」 | 是 | 第 2 步的 App ID。以 `cli_` 开头，整段 16–32 位，其余为字母或数字 |
   | 「Secret」 | 是 | 第 2 步的 App Secret。保存后不再显示，编辑时留空表示不改 |

4. 点「测试连接」，通过时提示「连接正常」「已取到凭证。」。
5. 点「连接」。

## 回调地址

扫码确认后，飞书要把浏览器送回 Raise，所以飞书应用里要登记 Raise 的回调地址。

1. 在 Raise 的飞书卡片上找到「授权回调域」，点复制按钮复制。
2. 在飞书应用的安全设置里登记重定向地址。飞书要的是完整的重定向 URL 还是只填域名，以对方后台的最新说明为准。

回调地址和授权时不一致时，登录会失败，提示「回调地址与授权时不一致」。

## 选择登录方式

对话框里「成员第一次扫码登录时」的两个开关和企业微信相同：

| 开关 | 说明 |
|---|---|
| 「首次登录自动创建账号」 | 打开后，第一次扫码的人自动建账号。关闭后只有已邀请的成员能登录 |
| 「按邮箱关联已有账号」 | 打开后按邮箱并入已有账号。只在邮箱由管理员维护、成员不能自改时打开，否则可被冒充 |

新建时还有「连接后立即在登录页提供扫码登录」。之后用卡片上的「停用登录」「启用登录」切换。

成员能不能用这个应用登录，取决于飞书应用的可用范围。不在范围内的人会看到「该用户没有使用此应用的权限」。

## 同步通讯录

飞书用应用自己的 App Secret 读通讯录，不需要另填一份通讯录 Secret。

1. 在飞书应用里开通通讯录的读取权限，并把要同步的部门放进权限范围和可用范围。具体权限名称以对方后台的最新说明为准。
2. 想用飞书的 user ID 作为成员标识时，还要开通「获取用户 user ID」权限。没有这个权限时，Raise 改用 open_id；登录和同步要用同一种，所以开通后两边都会用 user ID。
3. 到 Raise 的「组织结构」→「通讯录同步」，打开「自动同步」或点「立即同步」。

同步是单向、只读的，不会改动飞书。飞书没有主部门，Raise 取成员所在部门列表里的第一个当主部门。只挂在根部门、不在任何子部门里的人同步不到。任一页读取失败，整次同步失败，不会改动已有的部门和成员。

## 常见问题

#### 「测试连接」提示「应用 App ID 或 App Secret 不对，或应用已停用」？
核对「凭证与基础信息」里的两项，确认应用已启用。

#### 同步提示「没有权限查看该部门」或「没有权限查看该部门或成员」？
检查飞书应用的通讯录权限范围与可用范围，确认包含要同步的部门。

#### 提示「调用太频繁，被飞书限流了，稍后再试」？
等一会儿再同步。Raise 不会自动重试这一次。

## 目前不支持

- 向飞书推送消息、事件订阅、卡片审批、在飞书里免登。
- 国际版 Lark。