API 调用步骤详解

本指南旨在指导开发者从零开始，通过调用钉钉开放平台接口，完成从注册应用到接口调通的全流程操作。文档涵盖关键步骤、代码示例、注意事项及调试方法，确保开发者快速上手并成功调用API。

本示例是以企业内部应用为基础，通过调用接口获取通讯录中用户的详细信息为例，若是其他应用类型的应用，也可参考此文档。

前置工作

基础概念：已了解钉钉开放平台的基础概念及各产品块文档说明，详见基础概念文档说明。
接口频率限制：已了解API的调用频率限制，详见调用频次与限流文档说明。
开发者权限：具有开发者后台子管理员和开发者权限，也可以登录钉钉开发者完成新用户的注册与激活。
获取用户UserId：登录钉钉管理后台并在通讯录 > 成员管理下查看UserId，详见基础概念说明。

步骤一：创建钉钉应用

访问开发者后台，单击应用开发 > 钉钉应用 > 创建应用。

说明

填写应用信息，并单击保存。

配置项	是否必选	配置说明
应用名称	是	输入应用名称，应用名称最小长度为 2 个字符。
应用描述	是	简要描述应用提供的产品或服务，应用描述最小长度为 4 个字符。
应用图标	否	上传应用图标，图标要求 JPG/PNG 格式、240 px * 240 px 以上、1:1 、2 MB 以内的无圆角图标。

进入应用详情页，在基础信息 > 凭证与基础信息，查看应用凭证与基础信息。

保存应用的Client ID和Client Secret，用于后续接口调用使用。

说明

Client ID和Client Secret获取可参考基础概念中说明，获取后请妥善保管，避免泄露。

步骤二：配置权限

查找所需权限：根据接口文档，调用用户详情需成员信息读权限权限。

添加权限：访问开发者后台，找到已经创建的应用并进入应用详情，在权限管理中搜索成员信息读权限，点击立即申请。

步骤三：获取Access Token

在获取Access Token前，需要确定接口需要申请的是普通权限还是敏感权限，两种方式的获取方式不一样。

普通权限API

调用接口获取Token

访问获取企业内部应用的accessToken接口，通过右侧的API调试按钮打开服务端调试工具。
在调试工具中，替换appkey（参数值替换为提前获取的Client ID）和appSecret（参数值替换为提前获取的Client Secret）的值，并点击发起调试按钮。

重要

需要在登录状态下才能使用服务端调试台，且必须要绑定对应的应用。调用接口获取Token

也可直接复制下方代码，使用 cURL 命令，替换appkey（参数值替换为提前获取的Client ID）和appSecret（参数值替换为提前获取的Client Secret）的值后，直接发起调用，示例如下：

curl -X POST 'https://api.dingtalk.io/v1.0/oauth2/accessToken' \
  -H 'Content-Type: application/json' \
  -d '{
    "appKey": "替换为提前获取的Client ID",
    "appSecret": "替换为提前获取的Client Secret"
  }'

解析响应

接口调用成功后，会生成accessToken值，如下：

{
  "accessToken" : "fw8ef8we8f76e6f7s8dxxxx", # 核心凭证
  "expireIn" : 7200 # 有效期（2小时）
}

缓存与刷新

建议将access_token缓存至数据库或内存，并设置定时刷新（过期前10分钟）。
避免频繁调用获取Token接口，否则可能触发限流。

敏感权限API

第三方应用为了实现跨组织的数据互通与功能调用，必须经过严格的权限授权流程，需通过组织授权和个人授权两种机制获取目标企业的使用许可和用户数据访问权限。

申请接口权限

通过应用使用敏感权限文档内容，申请接口调用权限。

接入授权套件

申请敏感权限后，需要接入授权套件，用户在授权弹窗中同意授权时，返回authCode，然后调用获取用户token接口，换取用户级access_token。

步骤四：调用用户详情API

普通权限API

获取用户详情需要通过调用查询用户详情接口，获取方式可直接使用钉钉SDK或通过HTTP方式直接获取，可根据实际需求进行选择。

方式一：使用钉钉SDK（推荐）

若使用钉钉SDK进行调用，需要提前了解服务端 API 的差异，然后下载对应版本的SDK，详见服务端 API 差异详解文档介绍。

安装SDK（以Python为例）
pip install dingtalk-sdk

调用示例

# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiV2UserGetRequest("https://api.dingtalk.io/topapi/v2/user/get")

req.userid="zhangsan"  # 替换为实际用户ID
req.language="zh_CN"
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)

方式二：直接发起HTTP请求

curl -i 'https://api.dingtalk.io/topapi/v2/user/get' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -d '{"userid":"替换为实际用户ID","language":"zh_CN"}'

成功响应

若接口返回值中"errcode":"0"且"errmsg":"ok"，则代表接口调用成功。

{
        "errcode":"0",
        "result":{
                "extension":"{\"爱好\":\"旅游\",\"年龄\":\"24\"}",
                "unionid":"z21HjQliSzpw0YWxxxxx",
                "boss":"true",
                "role_list":{
                        "group_name":"职务",
                        "name":"总监",
                        "id":"100"
                },
                "exclusive_account":false,
                "manager_userid":"manager240",
                "admin":"true",
                "remark":"备注备注",
                "title":"技术总监",
                "hired_date":"1597573616828",
                "userid":"zhangsan",
                "work_place":"未来park",
                "dept_order_list":{
                        "dept_id":"2",
                        "order":"1"
                },
                "real_authed":"true",
                "dept_id_list":"[2,3,4]",
                "job_number":"4",
                "email":"test@xxx.com",
                "leader_in_dept":{
                        "leader":"true",
                        "dept_id":"2"
                },
                "mobile":"13800138000",
                "active":"true",
                "org_email":"test@xxx.com",
                "telephone":"010-86123456-2345",
                "avatar":"xxx",
                "hide_mobile":"false",
                "senior":"true",
                "name":"张三",
                "union_emp_ext":{
                        "union_emp_map_list":{
                                "userid":"5000",
                                "corp_id":"dingxxx"
                        },
                        "userid":"500",
                        "corp_id":"dingxxx"
                },
                "state_code":"86"
        },
        "errmsg":"ok"
}

错误处理

权限不足：检查成员信息读权限权限是否已申请。
用户不存在：确认userid是否有效且无拼写错误。
Token过期：刷新access_token后重试，并确认access_token有效且无拼写错误。

敏感权限API

通过authCode换取用户级access_token后，调用获取用户通讯录个人信息获取用户的昵称、unionId 等信息。若接口返回200，则代表接口执行成功，返回结果如下：

{
  "nick" : "zhangsan",
  "avatarUrl" : "https://xxx",
  "mobile" : "150xxxx9144",
  "openId" : "123",
  "unionId" : "z21HjQliSzpw0Yxxxx",
  "email" : "zhangsan@example.com",
  "stateCode" : "86"
}

API 调用指南

认证与授权

通讯录管理

日程

音视频

AI 表格

文档/文件

即时通信

前置工作

步骤一：创建钉钉应用

说明

说明

步骤二：配置权限

步骤三：获取Access Token

普通权限API

调用接口获取Token

重要

解析响应

缓存与刷新

敏感权限API

申请接口权限

接入授权套件

步骤四：调用用户详情API

普通权限API

方式一：使用钉钉SDK（推荐）

方式二：直接发起HTTP请求

成功响应

错误处理

敏感权限API

​前置工作

​步骤一：创建钉钉应用

​说明

​说明

​步骤二：配置权限

​步骤三：获取Access Token

​普通权限API

​调用接口获取Token

​重要

​解析响应

​缓存与刷新

​敏感权限API

​申请接口权限

​接入授权套件

​步骤四：调用用户详情API

​普通权限API

​方式一：使用钉钉SDK（推荐）

​方式二：直接发起HTTP请求

​成功响应

​错误处理

​敏感权限API

前置工作

步骤一：创建钉钉应用

说明

说明

步骤二：配置权限

步骤三：获取Access Token

普通权限API

调用接口获取Token

重要

解析响应

缓存与刷新

敏感权限API

申请接口权限

接入授权套件

步骤四：调用用户详情API

普通权限API

方式一：使用钉钉SDK（推荐）

方式二：直接发起HTTP请求

成功响应

错误处理

敏感权限API