钉钉企业开发的一些总结

概述

钉钉是阿里巴巴集团下的，给企业使用的，沟通协同工具。使企业办公智能，方便企业管理。现在很多企业都在使用。阿里抢占不了微信的个人用户，所以去抢占企业用户了，非常成功的成为企业的交流，管理工具了。它针对是企业的，所以不能以沟通工具的眼光看，不然你会觉得它太反人类了。它由上而下的钉钉消息和可以看见你是否阅读，让管理者窃喜，让员工颤抖。

github项目laravel使用钉钉示例
如果觉得我的github上的示例对你有所帮助的话，给个星星吧！谢谢！

开发前准备

注册钉钉企业账号，手机号为主管理员
分配管理员
认证企业（可以不认证，认证功能更强大，测试的话可以不认证）
钉钉的corpid 和 secret获取地址：
钉钉开发者平台》开发账号管理下：http://open-dev.dingtalk.com

资料

钉钉开发文档：https://open-doc.dingtalk.com
钉钉开源代码模板：https://github.com/open-dingtalk
钉钉管理后台：https://oa.dingtalk.com
钉钉开发者后台：http://open-dev.dingtalk.com
钉钉视频教程：https://yq.aliyun.com/video/TagSearch/cid_0-tagid_17106?spm=0.0.0.0.Sp9Nec
服务端api调试工具：https://debug.dingtalk.com/
jsapi调试工具：https://wsdebug.dingtalk.com/?spm=a219a.7629140.0.0.dQEzxF

自定义企业首页（配合视频）
文档：https://yq.aliyun.com/articles/71162?spm=a2c4e.11153959.0.0.13666b60WZuI43
开源项目：https://github.com/icepy/index-oa-template

企业应用接入钉钉之php篇（配合视频）
开源项目：https://github.com/open-dingtalk/openapi-demo-php

开发流程

先过一遍钉钉官网：快速入门
看完上面的：自定义企业首页（配合视频），企业应用接入钉钉之php篇（配合视频）
配合钉钉的服务端API，你就可以开始钉钉之旅了。
根据功能各种调用接口就是了。

注意事项

【时间】
api接口获取的日期时间时以毫秒为单位的时间戳。
处理：date(‘Y-m-d’, hiredDate/1000)

【字段】
获取的字段为空的时候，不会返回字段。
处理：isset(fieldValue)?fieldValue:null

【排班】
导入
（1）排班更新的钉钉中没有的人员不会报错，只是不会加入到排班。有userid的话会报错不在考勤组。
（2）部门填错也可以正常更新。应该是根据userid来同步的，部门只是方便人员查看。
（3）有时候导入排班的时候，导入没有生效。发现是登陆已经过期了，需要重新登陆。然而钉钉并没有任何提示。
（4）导入排班的时候，将已经排班的改为空值，将不会生效，不会更新。

【接口参数】
有默认的最好设置默认值，方便自己检查错误。

【考勤机】
考勤机打卡产生的数据，有可能会有重复数据。就是一个人打一次卡，有可能会产生两条一样的打卡数据（id不同）。

第三方web网站扫码登陆

在钉钉开发者平台》自助工具》创建扫码登陆应用授权。
名称和描述都会显示在钉钉扫码之后的授权页面的
授权页面logo：建议使用压缩图片，增加用户体验，，快。
回调域名：你的网站地址

第一种方式：直接跳转到钉钉提供的二维码页面
用户点击使用钉钉扫码登陆后，直接跳转到钉钉提供的扫码登陆页面（https://oapi.dingtalk.com/connect/qrconnect?appid=APPID&response_type=code&scope=snsapi_login&state=STATE&redirect_uri=REDIRECT_URI），会直接弹出一个页面扫码登陆页面。
当然其中的参数得换成自己的。appid, state, redirect_uri。
redirect_uri ：你将处理用户登陆的路由。

第二种方式：将二维码嵌入到自己的网页
按照官方步骤来。
goto参数填入自己构造的url。（url格式：https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=APPID&response_type=code&scope=snsapi_login&state=STATE&redirect_uri=REDIRECT_URI&loginTmpCode=loginTmpCode
）
拿到loginTmpCode参数后跳转到构造的url。（url格式：https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=APPID&response_type=code&scope=snsapi_login&state=STATE&redirect_uri=REDIRECT_URI&loginTmpCode=loginTmpCode）

参考官方文档:https://open-doc.dingtalk.com/docs/doc.htm?spm=a219a.7629140.0.0.eaNsz5&treeId=168&articleId=104882&docType=1

接口注意事项

【企业考勤组详情接口】
结果字段解析：
班次id : class_id
班次设置id：class_setting_id
备注：修改班次的时候class_id 不会变，class_setting_id会改变。

【获取打卡结果】
请求地址：https://oapi.dingtalk.com/attendance/list?access_token=ACCESS_TOKEN

参数字段解析：
userIdList : 传入需要获取考勤用户的的userid。传空（’'或array()都行）获取全部user的考勤。随便传什么都是获取全部user的考勤信息。。。。
workDateFrom，workDateFrom ：获取的考勤结果时间跨度不能超过7天
offset，limit ：结果只能分段获取。（一次最多50条）。
实测：虽然设置了limit(50)，但是还是获取超过了50条。

返回结果字段解析：
timeResult：Normal:正常;Early:早退;Late:迟到;SeriousLate:严重迟到；Absenteeism:旷工迟到；NotSigned:未打卡。
userCheckTime ：实际打卡时间，但是没有打卡怎么也会有打卡时间。。。

结果分析：
是经过钉钉处理过的数据。
删除用户将不在获取用户的考勤信息。
考勤组的更改，排班的更改都会生成新的考勤数据。

【获取打卡详情】
请求地址：https://oapi.dingtalk.com/attendance/listRecord?access_token=ACCESS_TOKEN

返回结果字段分析：
打卡失败返回的数据：invalidRecordType，invalidRecordMsg等
isLegal ：是否合法（是否早退，迟到等）
timeResult ：时间结果是否正常
locationResult：位置是否正常
sourceType：打卡数据方式
sourceType=BOSS 表示老板改签;实际是管理员都就可以修改。

结果分析：

原始的打卡数据
获取所有的打卡情况。包括已经删除的用户。
要获取接口数据的话，不能使用管理员直接修改考勤记录，不然获取不到修改的考勤数据。
补卡的话会生成一条补考的考勤记录，考勤数据在workDateFrom内的话补卡的数据就在，补卡workDate日期时间和考勤数据一样的，
修改某人的排班，会使打卡记录id改变。

[boss修改打卡数据]
只能在钉钉后台体现.
接口获取只知道修改了boss修改了结果,却不知道修改了什么。
注意：所以我们最好先限定这个boss的人数。

【获取部门成员（详情）】
请求地址：https://oapi.dingtalk.com/user/list?access_token=ACCESS_TOKEN&department_id=1

参数字段解析：
department_id ：获取成员只能通过部门来获取。

【获取企业角色列表】
请求地址：https://oapi.dingtalk.com/topapi/role/list?access_token=ACCESS_TOKEN
返回参数：
nextCursor ：下次拉取数据的游标（并没有返回这个值，只返回了hasMore字段）
问题：难道是要size=20超过之后才返回nextCursor这个字段？

【获取企业中角色下的员工列表】
请求地址：https://oapi.dingtalk.com/topapi/role/simplelist?access_token=ACCESS_TOKEN
返回参数：
nextCursor ：下次拉取数据的游标（并没有返回这个值，只返回了hasMore字段）
问题：难道是要size=20超过之后才返回nextCursor这个字段？

【批量获取审批实例】
地址：dingtalk.smartwork.bpms.processinstance.list

Q: 如何获取流程模板唯一标识process_code？
A: 进入OA后台》选择审批》创建模板。进入创建模板页面后，在浏览器地址栏中带有的字段processCode就是流程模板唯一标识。

Q: 审批是否有时间限制？
A: 审批是没有时间限制的哦，以最后一个审批人审批结束为完成，若审批人长时间未审批。

拓展

钉钉企业开发快速入门
钉钉企业开发接口调用的总结
laravel使用钉钉

希望对大家有一定的帮助。

更多知识程序猿：apeit