釘釘企業開發的一些總結
概述
釘釘是阿里巴巴集團下的，給企業使用的，溝通協同工具。使企業辦公智慧，方便企業管理。現在很多企業都在使用。阿里搶佔不了微信的個人使用者，所以去搶佔企業使用者了，非常成功的成為企業的交流，管理工具了。它針對是企業的，所以不能以溝通工具的眼光看，不然你會覺得它太反人類了。它由上而下的釘釘訊息和可以看見你是否閱讀，讓管理者竊喜，讓員工顫抖。
開發前準備
- 註冊釘釘企業賬號，手機號為主管理員
- 分配管理員
- 認證企業（可以不認證，認證功能更強大，測試的話可以不認證）
釘釘的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
開發流程
注意事項
【時間】
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）
介面注意事項
【企業考勤組詳情介面】
結果欄位解析：
班次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: 審批是沒有時間限制的哦，以最後一個審批人審批結束為完成，若審批人長時間未審批。
希望對大家有一定的幫助。