*钉钉、专有钉钉、政务钉钉、浙政钉对接文档*

浙政钉 为规范浙政钉整体架构体系，按照统分结合原则，由省政府办公厅统一设计整体工作界面和系统框架，统筹指导全省统建应用建设，各单位根据自身业务特点分别建设自建应用，最终形成全省统一的政府系统掌上协同办公平台。

专有钉钉 原名政务钉钉，有更开放的设计能力、集成能力、更结构化协同产品、更定制化开发平台。支持专有化部署，数据落本地，更安全、客户可对该产品持牌运营、结构化编排，协助构建本地应用中心、提供移动应用全面安全保障体系。

简单来说，开发阶段使用的都是专有钉钉的环境（测试环境），开发完毕由业主提交浙政钉应用上架，把测试环境改为浙政钉（正式环境）即可。

*各环境域名/登录域名*

1. *免登*

免登流程：

\1. 首先需要在专有钉钉开发者后台建一个测试应用，用于配置我们后台的网址，也可 获取到我们后边调用接口要用到的ak、sk，应用创建完需要发布应用，如需修改应 用需要先下架然后修改完毕再重新发布应用。

\2. 前端获取免登授权码authCode（用于获取人员信息接口传参，有效期5分钟，且 只能用一次）

https://openplatform-portal.dg-work.cn/portal/#/helpdoc?docKey=kfzn&slug=kpkrae

\3. 后端获取应用access_token(正常情况下 access_token 有效期为7200秒)

\4. 根据免登授权码和access_token调用获取用户信息接口获取用户信息

判断免登逻辑：通过获取用户信息我们可以拿到用户的accountId(浙政钉用户唯一 标识)和lastName(浙政钉用户)姓名；我们这里是维护了一张accountId和我们系统 的user表，先根据accountId去查询出userId

（1）如果userId不为空，说明该人的浙政钉信息和我们系统的信息可以关联上， 然后根据userId从我们系统查出该人的userName,根据userName进行免登， 返回HttpResult.success，否则返回HttpResult.error，前端跟状态码判断是否 免登录。

（2）如果userId为空，我们根据lastName去查询我们系统的人员表，这里可能会 重名的情况，我们的处理方法是取第一个，如果我们系统人员存在该人，返回 HttpResult.success，否则返回HttpResult.error，前端跟状态码判断是否免登录。

开发测试阶段建议让前端搞一个vConsole,用于获取authCode，方便用于后端开发测试阶段测试。

*1.获取应用access_token（调⽤接⼝凭证）*

接口名：/gettoken.json

所在目录：企业内应用免登

调用方式：POST（HTTPS）

请求参数

接口文档地址：

https://openplatform-portal.dg-work.cn/backendManage/#/docs?apiType=serverapi&docKey=2674862

*2获取用户信息*

接口名：/rpc/oauth2/dingtalk_app_user.json

所在目录：企业内应用免登

调用方式：POST（HTTPS）

请求参数

接口文档地址：

https://openplatform-portal.dg-work.cn/backendManage/#/docs?apiType=serverapi&docKey=2674834

2. *扫码免登*

*扫码免登流程：*

\1. 首先到开放平台的开发者中心创建扫码登录应用

\2. 创建完应用，可以复制应用标识（作为构造登录页面client_id的参数值），点击详情进入应用配置页面，配置应用基础信息

\3. 点击应用配置，配置回调地址（系统应用首页地址）

\4. 构造登录页面（需注意环境域名，测试环境需配置构造登录页面专 有钉钉域名，浙政钉需配置构造登录页面浙政钉域名）

\5. 获取应用access_token，逻辑同上述免登获取应用access_token（注意：这里的ak、sk应用扫码应用的ak、sk）

\6. 服务端通过临时授权码获取授权用户的个人信息

\7. 判断是否免登可参考上述免登逻辑，代码基本上大差不差，维护的浙政钉人员信息表和系统人员信息表可用同一个。

*坑：如果需要同时实现免登和扫码，建议一个模块写一个，不要一个模块同时写扫码和免登，这样很容易导致在调用接口的时候获取应用参数混乱。*

*获取授权用户的个人信息*

服务端通过临时授权码获取授权用户的个人信息

*请求方式：POST（HTTPS）*

*接口名 /rpc/oauth2/getuserinfo_bycode.json*

注意：请使用接口域名调用接口，不能使用登录域名调接口。

请求参数

扫码免登逻辑可参考上述免登逻辑

接口文档地址：

https://openplatform-portal.dg-work.cn/portal/#/helpdoc?docKey=kfzn&slug=engk1k

3. *获取浙政钉组织和用户体系*

\1. 获取通讯录权限范围（用于获取到当前租户可查看范围的组织code）

\2. 根据通讯录权限范围分页获取下⼀级组织 Code 列表（获取所有的组织code）

\3. 批量根据组织Code查询详情得到所有组织详情（获取所有的组织详情）

\4. 根据组织code批量查询组织下人员详情得到所有的人员和任职信息（获取所有组织下的人员详情）

这里说一下用户体系结构，在我们系统是一个人员只能有一个部门，但是在浙政钉一个人员人可以有多个任职部门，我们取的是浙政钉人员的主职。

注意：每调用一次浙政钉接口都需要初始化ExecutableClient一次，这里使用的ak、sk用免登应用的即可。

*获取通讯录权限范围*

获取到的json，deptVisibleScopes则为当前租户可查看的组织code范围。

接口名：/auth/scopesV2

所在目录：获取通讯录用户信息

调用方式：GET（HTTPS）

请求参数

tenantId：获取方式

\1. 通过获取用户详情/rpc/oauth2/dingtalk_app_user.json这个接口返回的realmId即是租户ID。
2.进入管理工作台，任意界面右击，查看网页源码，其中realmId即是租户ID

接口文档地址：

https://openplatform-portal.dg-work.cn/backendManage/#/docs?apiType=serverapi&docKey=2674967

*分页获取下⼀级组织 Code 列表*

接口名：/mozi/organization/pageSubOrganizationCodes

所在目录：获取通讯录部门信息

调用方式：POST（HTTPS）

请求参数

根据组织code递归循环读取下一级组织code列表，确保获取出全部的组织code（这里建议把数据存缓存）

注意：PageSize最大为100

接口文档地址：

https://openplatform-portal.dg-work.cn/backendManage/#/docs?apiType=serverapi&docKey=2674857

*批量根据组织Code查询详情得到所有组织详情*

接口名：/mozi/organization/listOrganizationsByCodes

所在目录：获取通讯录部门信息

调用方式：POST（HTTPS）

请求参数

注意上传的组织code List最大为100，这里可以先拿到所有的组织code，然后循环每100调用一次获取通讯录部门信息接口。

接口文档地址：

https://openplatform-portal.dg-work.cn/backendManage/#/docs?apiType=serverapi&docKey=2674850

*查询组织下人员详情*

该接口可以根据组织code获取到组织下所有人员的人员信息和任职信息，这里建议在数据库建一个人员详情表再建一个人员的任职表，这样组织表、人员信息表和任职表关联关系为组织表的组织organization_code关联任职表的组织organization_code，组织表员工employee_code关联人员信息表employee_code。

这里需要先调用一次接口拿到总条数totalSize,然后根据总条数分页，一页一页取数据。

接口名：/mozi/organization/pageOrganizationEmployeePositions

所在目录：获取通讯录用户信息

调用方式：GET（HTTPS）

请求参数

接口文档地址：

https://openplatform-portal.dg-work.cn/backendManage/#/docs?apiType=serverapi&docKey=2674970

*工作人员accountId即账号(UID)怎么获取*

accountId是确定浙政钉人员信息的唯一字段。

accountId=账号(UID)，可以通过接口获取或者管理工作台后台查看：

\1. 根据authCode获取用户信息，/rpc/oauth2/dingtalk_app_user.json，接口可以获取accountId

\2. 管理工作台-工作人员管理，点击对应人员的详情，可以查看uid，如下图

\3. 也可以通过员工 Code 列表获取员⼯账号 ID：
https://openplatform-portal.dg-work.cn/#/docs?apiType=serverapi&docKey=2674854

注意：

\1. 如果应用信息配置在全局变量，建议每个模块尽量配置一个应用信息，否则 使用应用配置信息的时候很容易会读取紊乱。

\2. 每调用一次浙政钉接口都需要初始化ExecutableClient一次。

\3. 专有钉钉与浙政钉环境不同，要注意环境读取正确。

\4. 调用接口报错访问ip不在白名单，在应用配置处把访问ip添加到服务器出口 ip处即可（浙政钉环境需找管理员添加出口ip）。

\5. 为什么获取不到员工手机号和短号：经过大数据局评估，处于安全考虑，目 前暂时无法提供获取人员信息返回手机号的功能。

\6. 获取浙政钉组织结构和人员结构的时候，如果接口504，建议把权限范围、所 有组织code、人员和任职信息缓存起来。

\7. 建议多一点日志打印，特别是对getClient.get()、intelligentGetClient.get()的打 印，方便后期浙政钉上架后的bug排查。

政钉接口都需要初始化ExecutableClient一次。

\3. 专有钉钉与浙政钉环境不同，要注意环境读取正确。

\4. 调用接口报错访问ip不在白名单，在应用配置处把访问ip添加到服务器出口 ip处即可（浙政钉环境需找管理员添加出口ip）。

\5. 为什么获取不到员工手机号和短号：经过大数据局评估，处于安全考虑，目 前暂时无法提供获取人员信息返回手机号的功能。

\6. 获取浙政钉组织结构和人员结构的时候，如果接口504，建议把权限范围、所 有组织code、人员和任职信息缓存起来。

\7. 建议多一点日志打印，特别是对getClient.get()、intelligentGetClient.get()的打 印，方便后期浙政钉上架后的bug排查。