钉钉集成配置
详细的钉钉集成配置指南,包括钉钉登录、审批同步、组织架构同步、消息推送等功能的完整配置步骤
钉钉集成是合同管理系统的重要特性,可以实现移动办公和高效协同。系统支持钉钉扫码登录(无需记忆密码)、审批同步(移动端随时审批)、组织架构同步(自动同步减少维护)、消息推送(待办和审批通知实时推送)等核心功能。
集成架构采用三方模式:钉钉App作为移动端与合同管理系统交互,系统通过钉钉开放平台的API与钉钉服务器通信。用户在钉钉App上扫码登录、审批操作、查看消息,系统验证授权、同步数据、发送消息,钉钉服务器返回Token、回调通知、推送消息并同步组织架构。
开始配置前,您需要确保已创建钉钉企业、拥有企业管理员权限。如果企业已完成认证会更好,虽然不是必需的。
配置过程中需要准备一些信息。企业CorpId是企业的唯一标识,可以在钉钉管理后台获取。AppKey和AppSecret是应用密钥ID和密钥,创建应用后系统会生成。AgentId是应用的标识符,也是创建应用时获得的。回调URL是系统提供的接收钉钉回调的地址。这些信息后面配置时都会用到。
创建钉钉企业内部应用
Section titled “创建钉钉企业内部应用”在应用详情页找到AppKey、AppSecret和AgentId并记录下来,后面配置会用到。特别注意AppSecret只显示一次,请妥善保管,如果遗失需要重新生成。
配置应用权限
Section titled “配置应用权限”在应用管理页面需要配置几类权限。
通讯录权限是必需的,包括通讯录部门信息读权限(读取部门信息)、通讯录用户读权限(读取员工信息)、通讯录部门成员读权限(读取部门成员)。配置路径是应用详情→权限管理→通讯录管理。
消息通知权限包括发送工作通知和发送待办通知,在应用详情→权限管理→消息通知中配置。
审批权限包括审批模板读取、创建审批实例、审批实例读取和审批实例回调,在应用详情→权限管理→审批中配置。
登录权限需要开启钉钉登录功能,在应用详情→登录与分享→钉钉登录中配置。
还需要添加IP白名单。进入应用管理页面,找到”IP白名单”设置,添加服务器的公网IP地址后保存配置。如果服务器IP是动态的,可以暂时不配置白名单,但生产环境强烈建议配置以提高安全性。
配置回调地址
Section titled “配置回调地址”首先设置服务器出口IP。在钉钉应用管理后台进入”开发配置”,找到”服务器出口IP”,添加您的服务器公网IP并保存。
然后配置事件订阅。回调URL格式为 https://your-domain.com/api/ddCallBack,加密方式可以选择普通模式或加密模式。需要订阅的事件包括审批任务开始(bpms_task_change)、审批任务结束(bpms_instance_change)和通讯录变更(org_dept_modify、org_emp_modify)。
在”事件订阅”页面,系统会生成一个Token和AES Key。记录下Token和EncodingAESKey,配置到合同管理系统中。点击”验证”按钮,钉钉会向回调地址发送测试请求。验证成功后保存配置即可。
登录合同管理系统,进入”系统设置”→“钉钉集成”。填写基础信息包括企业CorpId、AppKey、AppSecret和AgentId。配置回调参数包括回调Token和EncodingAESKey。点击”保存”后测试连接。
测试连接时系统会验证AppKey和AppSecret、获取AccessToken、测试通讯录API并显示连接结果。如果测试失败,请检查AppKey和AppSecret是否正确、IP白名单是否配置、网络是否能访问钉钉API。
钉钉登录配置
Section titled “钉钉登录配置”在系统设置中启用”钉钉登录”开关后,登录页会自动显示”钉钉扫码登录”按钮。配置账号绑定策略有三种方式:自动绑定(钉钉手机号匹配系统账号)、手动绑定(首次登录时选择系统账号)、强制绑定(必须先绑定才能登录)。配置完成后使用钉钉App扫码测试登录功能。
登录流程是这样的:用户打开登录页点击”钉钉登录”,页面显示二维码,用钉钉App扫码,系统获取钉钉用户信息,匹配或绑定系统账号,最后登录成功进入系统。
审批流程同步
Section titled “审批流程同步”要实现审批同步,首先需要在钉钉管理后台创建审批模板。登录钉钉管理后台,进入”工作台”→“审批”,创建自定义审批模板并记录模板的ProcessCode。
然后在合同管理系统的审批模板管理中配置模板映射。选择要同步的审批模板(比如销售合同审批),填写钉钉ProcessCode,启用钉钉同步。接着配置字段映射,将系统字段映射到钉钉表单组件,比如合同名称映射到TextField_1、合同金额映射到NumberField_1、签约方映射到TextField_2、合同附件映射到DDPhotoField_1。保存映射后,发起审批时会自动同步到钉钉。
审批同步是双向的。当在系统中发起审批时,系统调用钉钉API创建审批实例,推送到钉钉审批,审批人在钉钉App收到通知,系统记录钉钉审批ID。当审批人在钉钉App审批时,钉钉回调系统接口,系统更新审批状态,通知下一审批人,完成同步。
系统支持双向同步,确保数据一致性。在系统中审批会同步到钉钉更新钉钉审批状态,在钉钉中审批会回调系统更新系统审批状态。系统撤回审批会同步撤销钉钉审批实例,钉钉撤回审批会回调系统终止系统审批。无论在哪里操作,数据都会实时同步。
组织架构同步
Section titled “组织架构同步”在钉钉集成设置中启用”自动同步组织架构”。配置同步规则包括同步方式(增量同步推荐,或全量同步)、同步频率(每天凌晨2点或手动触发)、同步范围(全部部门或指定部门)。
配置字段映射时,部门映射将钉钉部门ID映射到系统部门外部ID、部门名称映射到部门名称、父部门ID映射到父部门关系。员工映射将钉钉UserID映射到系统员工外部ID、员工姓名映射到姓名、手机号映射到手机号、邮箱映射到邮箱、部门ID映射到部门归属。配置完成后点击”立即同步”执行首次全量同步。
增量同步是推荐的方式,只同步新增、修改、删除的数据,效率高对系统影响小,适合日常使用。全量同步会同步所有部门和员工数据,数据更完整但耗时较长,适合首次同步或数据修复。
当钉钉数据与系统数据冲突时,系统会自动处理。员工手机号重复时以钉钉数据为准更新系统。部门名称重复时保留两个部门并标记来源。员工已离职时系统标记为离职状态。部门已删除时系统软删除但数据保留。
消息推送设置
Section titled “消息推送设置”系统可以将消息推送到钉钉。审批通知场景包括收到新的审批任务、审批被驳回、审批超时提醒、审批通过完成。消息内容类似”您有一条新的审批待办,合同名称XX,合同金额XX元,发起人XX,请尽快处理”。
待办提醒包括合同到期提醒、档案借阅到期、任务截止日期、回款逾期提醒。消息内容类似”您有一份合同即将到期,合同名称XX,到期日期XX,请及时处理”。
业务通知场景包括合同签订成功、发货单创建、收款到账、重要业务变更。消息内容类似”合同已完成签订,合同编号XX,签约方XX,合同金额XX元”。
在钉钉集成设置中启用各类消息推送,配置推送规则包括推送时机(实时推送或定时汇总)、推送对象(责任人/抄送人/部门)、推送方式(工作通知或待办消息)。可以自定义消息模板,编辑消息文本,支持变量替换。配置完成后发送测试消息验证。
管理员登录钉钉App,进入”工作台”,点击”应用中心”,找到”合同管理系统”应用并添加。在钉钉管理后台的应用管理中设置”可见范围”,选择全公司、指定部门或指定人员。配置应用首页URL,设置应用点击后打开的页面地址。
在钉钉App中,用户可以查看待办审批、进行审批操作(同意/驳回)、查看合同列表和详情、接收消息通知、查看统计数据,实现随时随地移动办公。
常见问题排查
Section titled “常见问题排查”回调失败的症状是钉钉审批后系统状态未更新。排查步骤包括:测试回调URL是否可访问(curl -X POST https://your-domain.com/api/ddCallBack)、检查钉钉服务器IP是否在白名单中、查看系统日志(tail -f storage/logs/laravel.log)、验证Token和AESKey是否正确。
组织同步失败的解决方法包括:检查通讯录权限是否授予、查看同步日志定位错误、尝试手动触发全量同步、检查网络连接。
钉钉登录失败的排查清单包括:AppKey和AppSecret是否正确、钉钉登录权限是否开启、账号绑定配置是否正确、系统账号是否存在。
消息推送不成功的检查项包括:消息推送权限是否授予、AgentId是否正确、用户是否在应用可见范围内、推送配置是否启用。可以使用钉钉开放平台的”接口调试”功能测试API调用。
密钥安全方面,AppSecret不要硬编码在代码中,使用环境变量存储敏感信息,定期轮换AppSecret,限制AppSecret的访问权限。
回调验证方面,要验证回调请求的签名,检查请求来源IP,防止重放攻击,记录所有回调请求。
数据加密方面,使用HTTPS传输,启用回调加密模式,敏感数据加密存储。
扫码添加客服微信