适用对象 企业管理员、钉钉开放平台管理员、Risemap 系统管理员。

安全提醒 AgentId、Client Secret、AppSecret、Stream 配置等属于敏感凭证，请仅在授权人员范围内流转，不要在群聊、截图或外部工单中明文暴露。

本文档用于指导客户在钉钉开放平台创建企业内部应用，并在 Risemap 系统中完成钉钉插件绑定。优化版对原文档进行了编号修正、术语统一、流程重组，并补充了检查清单和常见问题。

文档信息

项目	内容
系统	Risemap
平台	钉钉开放平台 / 企业内部应用
默认主页地址	https://www.risemap.cn
默认发布版本	1.0.0
可见范围	建议设置为全部员工，或按客户实际组织范围授权

---

目录

1. 配置总览

2. 准备工作

3. 创建钉钉企业内部应用

4. 添加应用能力

5. 查看并保存应用凭证

6. 配置网页应用

7. 开通接口权限

8. 配置事件订阅

9. 发布应用版本

10. 在 Risemap 中绑定钉钉插件

11. Risemap 能力配置与验证

12. 验收清单与常见问题

---

1. 配置总览

整体接入分为两个阶段：先在钉钉开放平台创建并发布企业内部应用，再回到 Risemap 系统插件中心填写应用凭证并开启所需能力。

阶段	配置位置	主要动作	输出结果
第一阶段	钉钉开放平台	创建企业内部应用、添加网页应用和机器人能力、开通接口权限、配置事件订阅、发布版本	获得可用的钉钉企业内部应用
第二阶段	Risemap 系统配置	进入插件中心，填写钉钉应用凭证，保存后按需开启组织架构、考勤、审批、消息等能力	Risemap 与客户钉钉企业完成绑定
第三阶段	Risemap / 钉钉	验证组织架构同步、考勤数据同步、事件推送、免登或消息能力	确认接入成功，可交付客户使用

关键术语

术语	说明	配置用途
企业内部应用	客户企业在钉钉开放平台创建的自建应用，仅服务于本企业内部员工。	用于承载 Risemap 与钉钉之间的接口权限和事件订阅。
AgentId	钉钉应用在企业内的应用标识。	Risemap 绑定时通常需要填写，用于识别具体应用。
Client ID / AppKey	应用身份凭证之一，页面可能显示为 Client ID 或 AppKey。	用于后端换取接口访问凭证。
Client Secret / AppSecret	应用密钥，属于敏感信息。	用于后端鉴权；只允许管理员或服务端配置人员查看和录入。
Stream 模式推送	钉钉事件订阅的一种推送方式。	建议使用 Stream 模式，无需额外配置公网回调地址。

2. 准备工作

正式配置前，请先确认以下条件已经具备。

1. 准备一个具备钉钉开放平台管理权限的账号，建议使用客户企业管理员或已授权的开发者账号。

2. 打开钉钉开放平台，地址：https://open-dev.dingtalk.com/。

3. 确认当前企业允许创建企业内部应用，并可进行权限申请、事件订阅和版本发布。

4. 准备 Risemap 管理员账号，后续需要进入“系统配置 - 插件中心 - 钉钉”完成绑定。

5. 准备客户实际访问的 Risemap 域名。公有云可使用 https://www.risemap.cn；私有化部署请替换为客户专属域名。

安全提醒 Client Secret、AppSecret、事件订阅 Token 等均属于敏感信息。整理交付文档时，截图中的密钥应打码；不要把真实密钥写入 Word、截图、群聊或邮件正文。

3. 创建钉钉企业内部应用

登录钉钉开放平台后，进入应用管理页面，选择需要接入的企业，创建或进入已有的企业内部应用。

1. 进入钉钉开放平台控制台。

2. 在应用列表中点击“创建应用”或进入已有应用。

3. 应用名称建议填写“Risemap”或“Risemap 业务系统”，便于客户管理员和员工识别。

4. 应用描述建议写明：用于 Risemap 与钉钉组织架构、考勤、审批、消息等能力对接。

图 1 钉钉开放平台应用列表，点击创建或进入企业内部应用

4. 添加应用能力

进入应用详情页后，在“添加应用能力”中添加 Risemap 接入所需能力。建议至少添加以下能力：

应用能力	是否必选	用途说明
网页应用	必选	用于在钉钉端打开 Risemap 页面，支持 PC 或移动端入口。
机器人	建议开启	用于后续消息通知、审批提醒、待办提醒等扩展能力。

如果客户暂时只使用组织架构或考勤同步，也建议保留机器人能力，避免后续启用消息通知时重新发布应用。

图 2 添加应用能力，选择“网页应用”和“机器人”

5. 查看并保存应用凭证

在应用详情页的“凭证与基础信息”区域，查看并保存应用凭证。后续 Risemap 插件绑定需要使用这些信息。

字段	页面可能显示名称	填写位置 / 用途	安全要求
AgentId	AgentId / 企业内部应用 AgentId	填写到 Risemap 钉钉插件配置中，用于标识当前企业应用。	可内部配置使用，不建议公开。
Client ID	Client ID / AppKey	用于服务端获取钉钉接口访问凭证。	只允许管理员或后端配置人员查看。
Client Secret	Client Secret / AppSecret	用于服务端鉴权，和 Client ID 配套使用。	敏感密钥，必须打码保存，禁止外传。

填写提醒 如果页面展示的是“Client ID / Client Secret”，Risemap 插件中若仍显示“AppKey / AppSecret”，通常可按对应关系填写：Client ID 对应 AppKey，Client Secret 对应 AppSecret。

图 3 在应用详情页查看 AgentId、Client ID/AppKey、Client Secret/AppSecret

6. 配置网页应用

进入“网页应用”配置页面，配置 PC 端和移动端首页地址。

配置项	建议值	说明
PC 端首页地址	https://www.risemap.cn	用于员工在钉钉 PC 客户端打开 Risemap。私有化部署时填写客户实际域名。
移动端首页地址	https://www.risemap.cn	用于员工在钉钉移动端打开 Risemap。可与 PC 端保持一致，也可填写移动端专属入口。
管理后台地址	按需配置	如果钉钉页面要求填写，可填写客户实际管理后台入口；不使用时可保持未配置。

1. 在左侧菜单进入“网页应用”。

2. 点击“网页应用配置”右侧的编辑按钮。

3. 填写移动端首页地址和 PC 端首页地址。

4. 保存配置后，检查页面是否显示最新地址。

域名提醒 截图中的地址为示例地址。正式交付时必须使用客户真实可访问域名，并确保该域名已配置 HTTPS。

图 4 配置网页应用首页地址，PC 端与移动端地址建议保持一致

7. 开通接口权限

在左侧菜单进入“权限管理”，按 Risemap 需要的能力开通接口权限。建议先开通基础权限、通讯录权限和考勤权限；审批或消息能力可按客户实际需求补充。

7.1 推荐权限清单

权限分组	权限名称	权限点 code	用途说明
基础	调用企业 API 时需要具备的基本权限	qyapi_base	调用钉钉企业接口的基础权限，通常默认开通。
基础	调用 SNS API 时需要具备的基本权限	snsapi_base	用于登录、身份识别等场景，通常默认开通。
通讯录	企业员工手机号信息	fieldMobile	用于读取员工手机号，便于 Risemap 账号匹配。
通讯录	通讯录部门信息读取权限	qyapi_get_department_list	用于同步部门组织架构。
通讯录	成员信息读取权限	qyapi_get_member	用于同步员工基础信息。
通讯录	根据手机号获取成员基本信息权限	qyapi_get_member_by_mobile	用于手机号反查员工身份。
通讯录	通讯录部门成员读取权限	qyapi_get_department_member	用于读取部门下员工列表。
考勤	考勤组查询权限	qyapi_attendance_group_read	用于读取考勤组、排班等基础信息。
考勤	考勤组管理权限	qyapi_attendance_group_manage	用于考勤组相关管理能力，按业务需要开启。
考勤	考勤数据读取权限	qyapi_get_attendance_data	用于同步员工打卡和考勤统计数据。
考勤	钉钉考勤机人员管理权限	qyapi_dingtalk_attendance_manage	用于考勤机人员维护或查询场景。
考勤	考勤授权信息读取权限	Attendance.Permission.Read	用于读取考勤写入或操作授权信息。
考勤	考勤打卡记录写权限	Pro.AttendanceRecord.Write	用于上传或写入打卡记录；仅在业务需要时开启。

7.2 开通步骤

1. 进入“权限管理”页面。

2. 按权限名称或 code 搜索需要开通的权限。

3. 勾选对应权限后点击申请或开通。

4. 如页面提示需要企业管理员审批，提交审批后等待通过。

5. 权限状态显示为“已开通”后，再继续配置事件订阅和版本发布。

图 5 权限管理第一页，包含基础、通讯录和部分考勤权限

图 6 权限管理第二页，包含考勤授权、考勤记录写入等权限

8. 配置事件订阅

事件订阅用于让钉钉在员工打卡、考勤数据变更等事件发生后，将事件推送给 Risemap。建议使用 Stream 流方式推送，便于服务端稳定接收钉钉事件。

8.1 推送方式

推送方式	建议	说明
Stream 模式推送	推荐	应用通过长连接方式接收钉钉事件，通常无需配置公网 HTTP 回调地址，部署和联调更简单。
HTTP 回调	按需使用	需要提供公网可访问的回调地址，并处理验签、加解密、重试等逻辑。

1. 进入左侧菜单“事件订阅”。

2. 在“推送方式”中选择“Stream 模式推送”。

3. 保存后检查连接状态，页面显示接入或验证通过后再开启具体事件。

图 7 事件订阅页面，推送方式选择 Stream 模式

8.2 考勤事件开通

根据当前 Risemap 钉钉接入场景，建议优先开启考勤相关事件。截图中已开启“员工打卡事件”和“考勤日报统计变更事件”。

事件名称	建议状态	用途说明
员工打卡事件	必选	员工完成打卡后推送事件，用于实时同步打卡记录。
考勤日报统计变更事件	必选	考勤日报统计数据发生变化后推送，用于更新统计结果。
管理员修改考勤结果	可选	管理员修正考勤结果后同步变更，适用于对考勤准确性要求较高的客户。
员工排班变更事件	可选	员工排班变化后同步，适用于需要排班联动的场景。
请假、加班、出差、外出状态变更事件	可选	如 Risemap 需要联动请假、加班、出差、外出等状态，可开启。

图 8 开启考勤事件，至少开启员工打卡事件和考勤日报统计变更事件

事件开通建议 不要一次性开启所有事件。先开启 Risemap 当前实际使用的事件，完成联调后再按客户需求逐步增加，避免无用事件造成日志和数据处理压力。

9. 发布应用版本

权限、网页应用和事件订阅配置完成后，需要创建并发布应用版本。未发布或未审批通过的配置不会对企业员工生效。

1. 进入左侧菜单“版本管理与发布”。

2. 点击“创建新版本”。

3. 首次发布版本号建议填写 1.0.0。

4. 版本说明可填写“接入 Risemap，支持组织架构、考勤、事件订阅等能力”。

5. 可见范围选择“全部员工”或客户指定范围。若用于全公司接入，建议选择“全部员工可见”。

6. 保存并提交发布。若需要管理员审批，等待审批通过后生效。

图 9 版本管理与发布页面，查看已创建版本

图 10 创建第一个版本，发布范围选择全员可见

10. 在 Risemap 中绑定钉钉插件

钉钉开放平台配置完成并发布后，回到 Risemap 管理后台完成插件绑定。绑定完成后，系统才能调用钉钉接口并开启考勤、审批、组织架构等能力。

10.1 进入插件中心

1. 使用管理员账号登录 Risemap 管理后台。

2. 在左侧菜单进入“插件中心”。

3. 在插件列表中找到“钉钉”插件卡片。

4. 点击钉钉卡片，进入插件详情与配置页面。

图 11 Risemap 插件中心，选择钉钉插件进入配置页面

10.2 填写钉钉应用凭证

进入钉钉插件详情后，先在“凭证配置”页签中填写钉钉开放平台复制的应用凭证。

Risemap 字段	钉钉开放平台字段	说明
AppKey	Client ID / AppKey	应用身份凭证之一，用于换取接口访问凭证。
AppSecret	Client Secret / AppSecret	应用密钥，属于敏感信息，录入后应打码展示。
AgentId	AgentId / 企业内部应用 AgentId	企业内部应用标识，用于识别当前钉钉应用。

1. 将钉钉开放平台中的 Client ID 或 AppKey 填入 Risemap 的 AppKey。

2. 将 Client Secret 或 AppSecret 填入 Risemap 的 AppSecret。

3. 将 AgentId 填入 Risemap 的 AgentId。

4. 确认字段无多余空格后，点击“保存凭证”。

安全提醒 AppSecret / Client Secret 为高敏感密钥，只允许管理员或后端配置人员查看。截图、培训材料和客户交付文档中必须打码处理。

图 12 钉钉插件凭证配置，填写 AppKey、AppSecret 和 AgentId

10.3 开启可用能力

凭证保存成功后，在“可用能力”区域按客户实际需求开启能力开关。建议先开启当前必须使用的能力，完成联调后再逐步增加其他能力。

能力名称	建议状态	开启后作用
考勤打卡	按需开启	用于从钉钉拉取员工打卡数据，并支持考勤数据同步。
三方审批	按需开启	用于对接钉钉审批能力或在 Risemap 中展示三方审批状态。
组织架构同步	按需开启	用于同步钉钉部门、员工、手机号等组织架构信息。

配置建议 如果客户只购买或启用了部分模块，不需要一次性打开全部能力。能力开关打开后，需确保钉钉开放平台已开通对应接口权限，否则功能页可能显示异常或同步失败。

11. Risemap 能力配置与验证

钉钉插件保存凭证并开启能力后，需要在 Risemap 中逐项完成同步和验证。建议按“凭证配置 -> 考勤同步 -> 用户绑定 -> 三方审批”的顺序检查。

11.1 考勤数据同步

进入“考勤同步”页签后，可以按日期范围从钉钉拉取员工打卡数据。

1. 选择开始日期和结束日期。

2. 点击“立即同步”。

3. 等待同步任务完成后，进入考勤相关页面检查打卡记录是否已更新。

4. 如果同步结果为空，优先确认员工当天是否存在真实打卡记录，以及钉钉开放平台考勤权限是否已开通。

11.2 考勤配置同步

考勤配置同步用于从钉钉拉取班次、考勤组、成员绑定等基础配置。建议在首次接入或客户修改钉钉考勤规则后执行。

1. 进入“考勤同步”页签中的“考勤配置同步”区域。

2. 点击“同步考勤配置”。

3. 同步完成后，检查班次、考勤组、成员绑定等数据是否与钉钉一致。

图 13 考勤同步页面，支持同步考勤打卡数据和考勤配置

11.3 用户绑定管理

用户绑定用于维护钉钉用户与 Risemap 系统员工之间的对应关系。未完成绑定的用户可能无法接收审批通知、考勤通知或完成免登识别。

状态	含义	处理方式
已绑定	钉钉用户已匹配到系统员工。	无需处理，可继续验证考勤和审批能力。
未绑定	钉钉用户未匹配到系统员工。	检查手机号、员工编码或姓名是否一致，必要时手动绑定。
考勤绑定未完成	考勤维度未完成映射。	重新同步用户或考勤配置后再次检查。

1. 进入“用户绑定”页签。

2. 点击“同步用户”，拉取最新钉钉用户。

3. 通过姓名或手机号搜索目标员工。

4. 重点检查“考勤绑定”和“用户绑定”两列状态。

5. 对未绑定用户进行补充绑定或修正员工基础资料后重新同步。

图 14 用户绑定管理页面，查看钉钉用户与系统员工绑定状态

11.4 三方审批验证

如果在可用能力中开启了“三方审批”，需要进入“三方审批”页签检查配置状态。页面中的绿色检查项表示系统已识别到对应配置。

检查项	说明	通过标准
凭证配置	检查 AppKey、AppSecret、AgentId 是否已保存。	显示已完成或绿色通过。
三方审批已启用	检查 Risemap 插件能力开关是否已打开。	能力开关已开启，页签可正常访问。
回调地址已配置	检查钉钉事件或审批回调是否已配置。	页面提示回调已配置，服务端日志无回调错误。
详情链接已配置	检查审批详情跳转地址是否可用。	钉钉审批消息可跳转到正确 Risemap 页面。
已同步用户	检查员工绑定情况。	已绑定用户数量符合客户实际员工数据。

验证提醒 截图中显示“已绑定 20 人，未绑定 6 人”属于示例状态。正式验收时需要结合客户实际员工数量判断，未绑定人员应补充处理，避免审批通知或考勤数据无法准确关联。

图 15 三方审批配置检查，确认凭证、回调、详情链接和用户绑定状态

11.5 验证顺序建议

完成以上配置后，建议按下表顺序进行联调，便于快速定位问题。

顺序	验证内容	通过标准
1	保存凭证	凭证保存成功，无鉴权失败提示。
2	同步组织架构 / 用户	部门、员工、手机号等基础数据可同步。
3	同步考勤配置	班次、考勤组、成员绑定与钉钉一致。
4	同步考勤数据	指定日期能拉取到真实打卡记录。
5	检查用户绑定	关键员工均为已绑定状态。
6	验证三方审批	页面检查项通过，审批详情和通知链路可用。

12. 验收清单与常见问题

12.1 上线前检查清单

检查项	状态
□ 已创建钉钉企业内部应用，应用名称和描述清晰。	待确认
□ 已添加网页应用能力。	待确认
□ 已按需添加机器人能力。	待确认
□ 已保存 AgentId、Client ID/AppKey、Client Secret/AppSecret，并对密钥打码。	待确认
□ 已配置 PC 端与移动端首页地址。	待确认
□ 已开通通讯录、考勤、审批等实际需要的接口权限。	待确认
□ 已配置事件订阅，并按需开启考勤事件。	待确认
□ 已创建并发布应用版本，可见范围符合客户要求。	待确认
□ 已在 Risemap 插件中心填写钉钉应用凭证并保存成功。	待确认
□ 已按客户需求开启考勤打卡、三方审批、组织架构同步等能力。	待确认
□ 已执行用户同步，并处理未绑定用户。	待确认
□ 已执行考勤配置同步和考勤数据同步。	待确认
□ 若启用三方审批，已检查凭证、回调地址、详情链接和用户绑定状态。	待确认

12.2 常见问题排查

问题现象	可能原因	处理建议
Risemap 保存钉钉配置失败	AgentId、AppKey 或 AppSecret 填写错误。	回到钉钉开放平台复制最新凭证，确认没有多余空格或复制错字段。
接口提示权限不足	对应权限未开通，或开通后版本未发布生效。	在权限管理中确认权限状态为已开通，再重新发布版本并等待审批通过。
组织架构同步不到手机号	未开通企业员工手机号信息权限，或员工手机号字段为空。	开通手机号读取权限后重新同步员工数据，并检查钉钉通讯录信息。
考勤配置同步失败	考勤权限不足，或钉钉企业未配置班次 / 考勤组。	确认考勤权限已开通，并在钉钉后台检查考勤组配置。
考勤数据读取为空	员工无打卡记录、日期范围不正确、考勤权限未开通。	使用有真实打卡记录的员工测试，并确认日期范围与钉钉数据一致。
用户绑定显示未绑定	手机号、员工编码或姓名无法匹配。	修正系统员工资料或钉钉通讯录资料后重新同步，必要时手动绑定。
三方审批页显示配置未就绪	三方审批能力未开启、回调地址未配置、详情链接缺失或用户未绑定。	按页面检查项逐一补齐配置，然后重新进入页面确认状态。
事件订阅收不到数据	Stream 未连接、事件未开启、应用版本未发布或审批未通过。	检查 Stream 状态、事件开关和版本发布状态，再查看服务端日志。

文档维护提醒 若钉钉开放平台页面、字段名称或 Risemap 插件页面发生调整，请以实际系统页面为准，并同步更新本文档截图和说明。