# 接入钉钉

把钉钉的企业内部应用接到 Raise 后，成员可以用钉钉扫码登录，Raise 还能从钉钉只读同步部门和成员。

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

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

## 开始前准备

- 一个能在钉钉开放平台创建企业内部应用的钉钉管理员账号。
- Raise 里「管理员」角色的账号。

## 创建企业内部应用

1. 在钉钉开放平台创建一个企业内部应用。具体菜单以对方后台的最新说明为准。
2. 记下三项：钉钉管理后台的企业 CorpId（以 `ding` 开头）、应用的 Client ID（原 AppKey）、应用的 Client Secret（原 AppSecret）。
3. 在 Raise 的「协作平台」里，钉钉卡片上点「连接钉钉」，填写：

   | 字段 | 必填 | 填什么 |
   |---|---|---|
   | 「名称」 | 是 | 显示在登录页的按钮上，最多 60 个字符 |
   | 「企业 CorpId」 | 是 | 以 `ding` 开头的 10–64 位字母或数字。Raise 用它区分是哪家企业 |
   | 「应用 AppKey」 | 是 | 应用的 Client ID（原 AppKey），6–64 位字母或数字 |
   | 「Secret」 | 是 | 应用的 Client Secret（原 AppSecret）。保存后不再显示，编辑时留空表示不改 |

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

> **提示**
>
> 取令牌时钉钉不核对 CorpId，所以 CorpId 填错了「测试连接」也可能通过。请照钉钉管理后台原样复制。

## 回调地址

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

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

## 选择登录方式

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

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

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

只有企业内的成员能用钉钉登录。外部联系人扫码会被拒绝。

## 同步通讯录

钉钉用应用自己的凭据读通讯录，不需要另填一份通讯录 Secret。

1. 在钉钉应用里开通通讯录的读取权限，并把要同步的部门和成员放进应用的可见范围。具体权限名称以对方后台的最新说明为准。
2. 到 Raise 的「组织结构」→「通讯录同步」，打开「自动同步」或点「立即同步」。

同步是单向、只读的，不会改动钉钉。钉钉没有主部门，Raise 取成员所在部门列表里的第一个当主部门。离职的人在下一次同步里不再出现，Raise 只停用他的账号，账号和数据保留。人数多时会逐个读取直属上级，同步会慢一些。

## 常见问题

#### 「测试连接」提示 AppKey 或 AppSecret 不对？
提示可能是「应用 AppKey 不对」「AppKey 或 AppSecret 不对」「应用 Secret 不对，或鉴权失败」。核对 Client ID 和 Client Secret，注意不要把两者填反。

#### 同步提示「部门不在应用的可见范围」或「员工不在应用的可见范围」？
在钉钉应用里把这些部门和员工加进可见范围，再同步一次。

#### 同步提示「没有调用该接口的权限，检查应用的通讯录权限」？
在钉钉应用里开通通讯录的读取权限。

## 目前不支持

- 钉钉工作通知、事件回调、卡片审批、在钉钉里免登。