身份验证

身份验证免登是指用户进入应用后，无需输入钉钉用户名和密码，应用程序可自动获取当前用户身份，进而登录系统的流程。身份验证的服务端API主要分为五部分，如下图所示：

• 钉钉应用内免登实现企业内部或第三方企业应用免登，即企业员工在钉钉内使用企业内部应用或第三方企业应用时无需输入账号和密码。可通过以下步骤实现：

1. 1. 获取JSAPI免登授权码。
      
   2. 获取用户userId。
      
   3. 获取用户详情。
      

• 管理后台免登应用管理后台免登指管理员在钉钉管理后台对应用进行设置和管理时，无需输入该应用的账号和密码，可直接登录应用的管理后台。可通过以下步骤实现：

1. 1. 获取免登授权码。
      
   2. 获取管理员身份信息。
      

• 扫码登录实现扫码登录第三方网站。扫码登录指钉钉客户端扫码并确认登录web系统，在系统内获取正在访问用户的钉钉身份，无需输入账号密码的开发流程。提供了以下两种方式：

• • 直接使用钉钉提供的扫码登录页面。
    
  • 开发者可以将钉钉的登录二维码内嵌到自己的网站中，让用户进行扫码登录。
    

• 钉钉内免登
  实现钉钉内免登第三方网站。钉钉内免登第三方网站指用户在钉钉客户端内点击H5网站链接时，无需输入账号密码系统自动获取正在访问用户钉钉身份。
  
• 密码登录
  实现使用钉钉账号登录第三方网站。通过手动输入钉钉的账号密码，登录第三方独立的web系统，并获得正在访问用户的钉钉身份。
  

通讯录管理

通讯录是开发者接入钉钉时最常用到的一批接口，主要包含四大类接口，如下图所示：

说明

在调用通讯录相关接口前，请先添加对应的通讯录权限。开发者可以调用通讯录接口，将通讯录数据写到钉钉中，用于获取钉钉通讯录。如果企业想实时接收通讯录变更，可以注册钉钉的通讯录回调，实时接收通讯录的回调内容。

• 用户管理
  包括增删改用户的接口，还可以获取部门下的用户，获取用户详情，获取管理员列表，跟进unionId获取userId，获取企业人数等接口。
  
• 部门管理
  包括增删改部门，获取部门ID列表，获取部门详情，获取部门上级部门，获取用户上级部门等接口。
  
• 角色管理
  角色分为角色和角色组，所以我们有增加删除修改角色，增加删除角色组合员工，获取角色组，获取角色列表和详情，获取角色下的员工列表等接口。
  
• 外部联系人管理
  包括增删改外部联系人，获取外部联系人列表，详情，和标签列表等接口。
  

消息通知

消息通知主要分为三部分，如下图所示：

• 工作通知消息是以企业工作通知会话中某个微应用的名义推送到员工的通知消息，例如审批通知，任务通知等。说明

• • 该接口是异步接口，接口返回成功并不表示用户一定会收到消息，需要通过 “查询工作通知消息的发送结果”接口查询是否发送成功。
    
  • 工作通知消息也有一些限流规则，具体规则可参考调用频率限制。
    

• 群会话消息
  是指可以调用接口，以系统名义向群里推送群聊消息。与之配合的是对应的创建群，更新群，获取群人员列表等服务端API接口。
  
• 普通会话消息
  是指可以调用接口，以系统名义向群里推送群聊消息。与之配合的是对应的创建群，更新群，获取群人员列表等服务端API接口。
  

智能办公

智能办公包含以下七个部分，如下图所示：

• 智能工作流
  包括发起审批实例，创建更新模板，创建更新待办，获取审批详情，审批回调，审批跳转，待办任务等接口。
  
• 考勤
  可以获取考勤数据，获取请假数据，获取考勤组信息，获取排班信息等。
  
• 日志
  可以获取日志数据，日志的已读、未读、评论、点赞等信息，获取日志模板。
  
• 签到
  可以获取用户的签到记录
  
• 智能填表
  可以获取企业智能填表的一些数据，还可以获取填表的一些模板。
  
• 智能人事
  可查询待入职员工，查询在职员工，查询离职员工，还有获取花名册信息，添加待入职员工等接口。
  
• 公告
  可以获取用户公告数据，包括公告的时间等。
  

如何调用服务端API

要调用API需要以下三个基础条件：

• 钉钉应用
  钉钉应用作为您调用API时的身份，有AppKey和AppSecret用于验证您的身份。可以在钉钉开放平台的应用开发页面创建应用，创建应用成功后，系统会自动生成AppKey和AppSecret。
  
• API
  在调用相关接口时，需要明确您即将需要调用的API相关参数定义。
  
• 相关权限
  在调用相关接口前，您可能需要先申请对应的接口权限。您可以登陆钉钉开放平台，选择您创建的应用，选择权限管理，添加相应接口权限。
  

可通过以下步骤，完成服务端API接口的调用：

1. 获取access_token。调用服务端API，首先要获取access_token。调用access_token的请求方式为GET（HTTPS），请求地址如下图所示，要输入两个参数appkey和appsecret。

说明

• • 正常情况下access_token的有效期是7200秒，有效期内重复获取会返回相同结果，并且自动续期。
    
  • POST请求必须在HTTP Header中设置对应的Content-Type:application/json。钉钉官方提供了统一的Java、PHP、.NET、Python对应的SDK，可参考服务端SDK下载。
    

1. 调用相关API接口。可通过以下方式调用服务端API接口：说明为了防止企业和ISV的应用程序错误从而引发钉钉服务器负载异常，默认情况下，每个服务端调用接口都会有一定的频率限制。当超过此限制时，调用接口会收到对应的错误码。限流规则可参考调用频率限制。

• • 方式一：使用API文档中提供的SDK示例代码进行调用。

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/gettoken");
OapiGettokenRequest request = new OapiGettokenRequest();
request.setAppkey("appkey");
request.setAppsecret("appsecret");
request.setHttpMethod("GET");
OapiGettokenResponse response = client.execute(request);
System.out.println(response.getBody());

• • 方式二：自行编辑HTTP(s)请求来调用API。

请求方式: GET/POST(HTTPS)
请求地址: https://oapi.dingtalk.com/gettoken?appkey=appkey&appsecret=appsecret
请求包体:
...
参数说明:
...
SDK请求示例:
...
返回结果
...

• • • 请求方式：接口有HttpGet/HttpPost两种方式。所有的请求都为HTTPS协议。
      
    • 请求地址：都以oapi.dingtalk.com开头。
      
    • 参数说明：包括字段含义、取值范围。比如HttpPost的请求包体就是request body的方式。
      
    • SDK请求示例：使用SDK时调用接口的Java代码示例。
      
    • 返回结果：钉钉所有接口的返回结果里都有errcode、errmsg。开发者需根据errcode是否为0判断是否调用成功。errcode为0表示调用成功，不为零表示失败，会生成对应的errmsg。开发平台文档上还有全局错误码，针对每个echo都会有一个对应解决方案的描述。