如何调用旧版服务端API

文档格式约定

每个接口文档会按照如下格式提供信息：

• 请求方式：接口使用的HTTP方法和请求协议。所有接口都使用HTTPS协议。

• 请求地址：接口的请求地址。钉钉服务端接口的访问域名为https://oapi.dingtalk.com。请求参数使用“&”分隔。请求地址中的大写单词是需要替换的变量值。

• 请求包体/参数说明：提供请求参数示例及说明，参数说明包括字段含义、取值范围，开发者在设计数据结构时，应参考该定义范围。

• 返回结果/参数说明：提供返回参数示例及说明。

  重要

  • 所有接口在调用失败时都会返回errcode和errmsg。开发者可根据errcode和errmsg排查问题。

  • 请不要仅根据errmsg判断调用是否成功。当请求返回结果中返回了errcode且不为0时可判断为请求失败。errmsg是对errcode的说明，供开发者参考排查问题。

  • 我们对接口的返回字段做了简化处理，如果字段的值为空或者null，将不返回该字段。

接口调用流程

如下图所示，在调用钉钉服务端接口前，您需要完成以下准备工作：

1. 创建一个钉钉应用，获取AppKey和AppSecret等，详情请参考应用类型介绍。

   • 第三方个人应用请参考开发流程介绍。

2. 添加接口调用权限。

   • 应用创建后默认只开放登录和消息通知接口的调用权限。

   • 其他接口权限，您需要根据开发场景，进行添加。详细信息请参考添加接口调用权限。

3. 获取企业内部应用的访问凭证access_token。根据第1步获取的AppKey和AppSecret，调用接口获取企业内部应用的accessToken，通过access_token来鉴权调用者身份。

   说明

   为便于开发者调用，钉钉提供了2个版本的获取企业内部应用accessToken接口。开发者可以根据实际情况选择任一版本使用。推荐调用新版服务端API。

   • 以调用旧版服务端API为例，调用获取第三方个人应用的access_token。

4. 查看各产品模块的文档，调用服务端接口。如通讯录管理等。

调试工具

钉钉开放平台提供了API Explorer和SDK方便开发者调用服务端API。

• API Explorer调试工具：

  API Explorer是可视化在线API调用工具，可实时查看API请求和返回结果。

SDK 下载

钉钉开放平台提供了 SDK，方便开发者调用服务端 API。

• 服务端API提供了Java、PHP、Python、.NET SDK供开发者使用，旧版服务端SDK下载。