钉钉开放平台接口文档0201.docx

目录

建立连接 2
主动调用 3
获取AccessToken 3
回调模式 5
管理多媒体文件 5
上传媒体文件 12
获取媒体文件 13
发送消息 15
发送接口说明 15
消息类型及数据格式 16
text消息 16
image消息 17
voice消息 18
video消息 18
file消息 19
办公消息 20
免登服务 21
使用标准OAUTH2.0 HTTP 302跳转方式获取CODE 22
通过CODE换取用户身份 23
获取jsapi_ticket 24

欢迎你，钉钉微应用的开发者，我们很期待你成为钉钉微应用的开发者；
微应用是 钉钉 为连接企业办公打造的移动入口，通过微应用你可以将企业的业务审批，内部系统，生成，协作，管理，上下游沟通连接到钉钉，更简单和低成本实现企业移动化； 结合钉钉的基础通信能力，让企业应用更活跃，员工更高效，移动化成本更低。
此文档很适合于
a) 企业的IT部，了解钉钉如何连接你所在企业的办公。
b) 软件开发服务商，了解如何通过钉钉为您的客户提供定制的企业办公软件，提升你的服务价值。

建立连接
你可以使用以下三种方式，将钉钉微应用连接到你的企业应用：
1、企业应用服务器调用钉钉开放平台提供的接口，以钉钉微应用的身份给企业用户的钉钉账号推送消息，以下称主动调用模式。
2、钉钉开放平台把钉钉用户发送的消息或触发的事件推送给企业应用服务器，由企业应用处理，以下称回调模式(暂未开放)。
3、钉钉用户在使用企业提供的微应用H5页面时，该页面可以调用钉钉提供的原生接口，使用钉钉开放的终端能力，以下称JSAPI模式。
主动调用
当企业应用服务器调用钉钉开放平台接口时，需使用https协议、Json数据格式、UTF8编码，访问域名为，数据包不需要加密。
在每次主动调用钉钉开放平台接口时需要带上AccessToken参数。AccessToken参数由CorpID和Secret换取。
CorpID是企业在钉钉中的标识，每个企业拥有一个唯一的CorpID；Secret是企业每个应用的凭证密钥。
CorpID及Secret可以在钉钉为企业提供的管理后台中找到，由钉钉自动分配。
获取AccessToken
AccessToken是企业访问钉钉开放平台接口的全局唯一票据，调用接口时需携带AccessToken。
AccessToken需要用CorpID和Secret来换取，不同的Secret会返回不同的AccessToken。正常情况下AccessToken有效期为7200秒，有效期内重复获取返回相同结果，并自动续期。
· 请求说明
Https请求方式: GET

· 参数说明
参数
必须
说明
corpid
是
企业Id
corpsecret
是
企业应用的凭证密钥
· 返回说明
a)正确的Json返回结果:
{
"errcode": 0,
"errmsg": "ok"
"access_token": "fw8ef8we8f76e6f7s8df8s",
}
参数
说明
errcode
错误码
errmsg
错误信息
access_token
获取到的凭证
b)错误的Json返回示例:
{
"errcode": 43003,
"errmsg": "require https"
}

回调模式(暂未开放)
暂未开放。
管理通讯录
管理部门
获取部门列表
· 请求说明
Https请求方式: GET

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
· 返回结果
{
"errcode": 0,
"errmsg": "ok",
"department": [
{
"id": 2,
"name": "来往事业部",
"parentid": 1
},
{
"id": 3
"name": "服务端开发组",
"parentid": 2
}
]
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
department
部门列表数据。以部门的order字段从小到大排列
id
部门id
name
部门名称
parentid
父亲部门id。根部门为1

管理成员
获取成员
· 请求说明
Https请求方式: GET

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
userid
是
员工在企业内的UserID，企业用来唯一标识用户的字段。
· 返回结果
{
"errcode": 0,
"errmsg": "ok",
"userid": "zhangsan",
"name": "张三",
"department": [1, 2],
"position": "工程师",
"mobile": "13912345678",
"email": "zhangsan@alibaba-",
"openId": "HUHIujjg8*7",
"avatar": "
"extattr": {"attrs":[{"name":"爱好","value":"旅游"},{"name":"卡号","value":"1234567234"}]}
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
userid
员工UserID。对应管理端的帐号
name
成员名称
department
成员所属部门id列表
position
职位信息
mobile
手机号码
email
邮箱
openId
钉钉开放平台ID
avatar
头像url。
extattr
扩展属性

获取部门成员
· 请求说明
Https请求方式: GET

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
department_id
是
获取的部门id
fetch_child
否
1/0：是否递归获取子部门下面的成员
· 返回结果
{
"errcode": 0,
"errmsg": "ok",
"userlist": [
{
"userid": "zhangsan",
"name": "张三"
}
]
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
userlist
成员列表
userid
员工UserID。对应管理端的帐号
name
成员名称

获取部门成员(详情)
· 请求说明
Https请求方式: GET

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
department_id
是
获取的部门id
fetch_child
否
1/0：是否递归获取子部门下面的成员
· 返回结果
{
"errcode": 0,
"errmsg": "ok",
"userlist": [
{
"userid": "zhangsan",
"name": "张三",
"department": [1, 2],
"position": "工程师",
"mobile": "15913215421",
"email": "zhangsan@alibaba-",
"openId": "HJHJYT*Y8887",
"avatar": "
"status": 1,
"extattr": {"attrs":[{"name":"爱好","value":"旅游"},{"name":"卡号","value":"1234567234"}]}
}
]
}
参数
说明
errcode
返回码
errmsg
对返回码的文本描述内容
userlist
成员列表
userid
员工UserID。对应管理端的帐号
name
成员名称
department
成员所属部门id列表
position
职位信息
mobile
手机号码
email
邮箱
openId
开放平台openId
avatar
头像url。
extattr
扩展属性

管理多媒体文件
企业在使用接口时，对多媒体文件、多媒体消息的获取和调用等操作，是通过media_id来进行的。通过本接口，企业可以上传或下载多媒体文件。
上传媒体文件
用于上传图片、语音、视频等媒体资源文件以及普通文件（如doc，ppt），接口返回媒体资源标识ID：media_id。请注意，media_id是可复用的，同一个media_id可用于消息的多次发送。
· 请求说明
Https请求方式: POST

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
type
是
媒体文件类型，分别有图片（image）、语音（voice）、视频（video），普通文件(file)
media
是
form-data中媒体文件标识，有filename、filelength、content-type等信息
· 返回说明
{
"errcode": 0,
"errmsg": "ok"
"type": "image",
"media_id": "@dsa8d87y7c8d8c",
"created_at": "13912345678"
}
参数
说明
errcode
错误码
errmsg
错误信息
type
媒体文件类型，分别有图片（image）、语音（voice）、视频（video）,普通文件(file)
media_id
媒体文件上传后获取的唯一标识
created_at
媒体文件上传时间戳
· 上传的媒体文件限制
图片（image）:1MB，支持JPG格式
语音（voice）：2MB，播放长度不超过60s，支持AMR格式
视频（video）：10MB，支持MP4格式
普通文件（file）：10MB
获取媒体文件
通过media_id获取图片、语音、视频等文件，协议和普通的http文件下载完全相同。
· 请求说明
Https请求方式: GET

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
media_id
是
媒体文件id
· 返回结果
和普通的http下载相同，请根据http头做相应的处理。
a)正确时返回：
{
HTTP/1.1 200 OK
Connection: close
Content-Type: image/jpeg
Content-disposition: attachment; filename="MEDIA_ID.jpg"
Date: Sun, 04 Jan 2015 12:00:00 GMT
Cache-Control: no-cache, must-revalidate
Content-Length: 1234567

Xxxx
}
b)错误时返回（这里省略了HTTP首部）：
{
"errcode": 40004,
"errmsg": "invalid media_id"
}
发送消息
企业可以主动发消息给员工，消息量不受限制。
调用接口时，使用Https协议、JSON数据包格式，数据包不需做加密处理。
目前支持文本、图片、语音、视频、文件等消息类型。
发送接口说明
· 请求说明
Https请求方式: POST

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
· 返回结果
如果收件人、部门或标签不存在，发送仍然执行，但返回无效的部分。
{
"errcode": 0,
"errmsg": "ok",
"invaliduser": "UserID1|UserID2",
"invalidparty":"PartyID1"
}

消息类型及数据格式
text消息
{
"touser": "UserID1|UserID2|UserID3",
"toparty": "PartyID1|PartyID2",
"msgtype": "text",
"agentid": "1",
"text": {
"content": "张三的请假申请"
}
}
参数
必须
说明
touser
否
员工ID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向该企业应用的全部成员发送
toparty
否
部门ID列表，多个接收者用‘|’分隔。当touser为@all时忽略本参数
msgtype
是
消息类型，此时固定为：text
agentid
否
企业应用id，这个值代表以哪个应用的名义发送消息，如果不填，则以当前获取accesstoken的应用作为发消息的应用。
content
是
消息内容

image消息
{
"touser": "UserID1|UserID2|UserID3",
"toparty": "PartyID1|PartyID2",
"msgtype": "image",
"agentid": "1",
"image": {
"media_id": "MEDIA_ID"
}
}
参数
必须
说明
touser
否
员工ID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向该企业应用的全部成员发送
toparty
否
部门ID列表，多个接收者用‘|’分隔。当touser为@all时忽略本参数
msgtype
是
消息类型，此时固定为：image
agentid
否
企业应用id，这个值代表以哪个应用的名义发送消息，如果不填，则以当前获取accesstoken的应用作为发消息的应用。
media_id
是
图片媒体文件id，可以调用上传媒体文件接口获取

voice消息
{
"touser": "UserID1|UserID2|UserID3",
"toparty": "PartyID1|PartyID2",
"msgtype": "voice",
"agentid": "1",
"voice": {
"media_id": "MEDIA_ID"
}
}
参数
必须
说明
touser
否
员工ID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向该企业应用的全部成员发送
toparty
否
部门ID列表，多个接收者用‘|’分隔。当touser为@all时忽略本参数
msgtype
是
消息类型，此时固定为：voice
agentid
否
企业应用id，这个值代表以哪个应用的名义发送消息，如果不填，则以当前获取accesstoken的应用作为发消息的应用。
media_id
是
语音文件id，可以调用上传媒体文件接口获取

video消息
{
"touser": "UserID1|UserID2|UserID3",
"toparty": "PartyID1|PartyID2",
"msgtype": "video",
"agentid": "1",
"video": {
"media_id": "MEDIA_ID"
}
}
参数
必须
说明
touser
否
员工ID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向该企业应用的全部成员发送
toparty
否
部门ID列表，多个接收者用‘|’分隔。当touser为@all时忽略本参数
msgtype
是
消息类型，此时固定为：video
agentid
否
企业应用id，这个值代表以哪个应用的名义发送消息，如果不填，则以当前获取accesstoken的应用作为发消息的应用。
media_id
是
视频媒体文件id，可以调用上传媒体文件接口获取

file消息
{
"touser": "UserID1|UserID2|UserID3",
"toparty": "PartyID1|PartyID2",
"msgtype": "file",
"agentid": "1",
"file": {
"media_id": "MEDIA_ID"
}
}
参数
必须
说明
touser
否
员工ID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向该企业应用的全部成员发送
toparty
否
部门ID列表，多个接收者用‘|’分隔。当touser为@all时忽略本参数
msgtype
是
消息类型，此时固定为：file
agentid
否
企业应用id，这个值代表以哪个应用的名义发送消息，如果不填，则以当前获取accesstoken的应用作为发消息的应用。
media_id
是
媒体文件id，可以调用上传媒体文件接口获取
办公消息
{
"touser": "UserID1|UserID2|UserID3",
"toparty": "PartyID1|PartyID2",
"msgtype": "office",
"agentid": "1",
"office": {
"content": "张三的请假申请",
"url": "
}
}
参数
必须
说明
touser
否
员工ID列表（消息接收者，多个接收者用‘|’分隔）。特殊情况：指定为@all，则向该企业应用的全部成员发送
toparty
否
部门ID列表，多个接收者用‘|’分隔。当touser为@all时忽略本参数
msgtype
是
消息类型，此时固定为：office
agentid
否
企业应用id，这个值代表以哪个应用的名义发送消息，如果不填，则以当前获取accesstoken的应用作为发消息的应用。
content
是
消息摘要
url
是
客户端点击消息时跳转到的H5地址

免登服务
通过免登服务，在企业微应用的H5中，可以获取当前使用钉钉的用户身份及相关信息。
通过此接口获取用户身份会有一定的时间开销。对于频繁获取用户身份的场景，建议采用如下方案：
1、用户跳转到企业页面时，企业校验是否有代表用户身份的cookie，此cookie由企业生成
2、如果没有获取到cookie，调用下述服务，获取用户身份后，由企业生成代表用户身份的cookie
3、根据cookie获取用户身份，进入相应的页面
使用标准OAUTH2.0 HTTP 302跳转方式获取CODE
在钉钉用户访问企业的H5时，如果企业应用服务器未从cookie中发现用户信息，则需要构造一个连接，通过HTTP 302跳转方式，让钉钉用户访问钉钉开放平台授权网址，构造的地址如下

钉钉开放平台授权服务器在判断当前用户属于当前企业时，会再次通过HTTP 302跳转回企业应用的H5，并在H5的URL后面追加参数code=CODE&state=STATE
· 参数说明
参数
必须
说明
appid
是
企业的CorpID
redirect_uri
是
授权后重定向的回调链接地址，请使用urlencode对链接进行处理
response_type
是
返回类型，此时固定为：code
scope
是
应用授权作用域，此时固定为：snsapi_base
state
否
重定向后会带上state参数，企业可以填写a-zA-Z0-9的参数值，长度不可超过128个字节
#ding_redirect
是
钉钉终端使用此参数判断是否需要带上身份信息

举例如下，假如企业的H5地址是

企业的CORPID是ding12345678
企业自定义的state是abcd1234

当钉钉用户在访问微应用内的H5时，企业自有服务器发现cookie中无法读取到用户信息时，需要构造如下链接并进行HTTP 302跳转

假如点击链接的当前钉钉用户属于当前企业(ding12345678)，则会HTTP 302跳到如下url

通过CODE换取用户身份
企业应用的服务器在拿到CODE后，需要将CODE发送到钉钉开放平台接口，如果验证通过，则返回CODE对应的用户信息。
· 请求说明
Https请求方式：GET

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
code
是
通过H5的url参数获取到的CODE
· 返回结果
a)正确时返回示例如下：
{
"errcode": 40029,
"errmsg": "invalid code"
"userId":"USERID",
"deviceId":"DEVICEID"
}
参数
说明
userId
员工在企业内的UserID
deviceId
手机设备号,由钉钉在安装时随机产生
出错时返回示例如下：
{
"errcode": 40029,
"errmsg": "invalid code"
}
获取jsapi_ticket(暂未开放)
企业在使用微应用中的JS API时，需要先从钉钉开放平台接口获取jsapi_ticket生成签名数据，并将最终签名用的部分字段及签名结果返回到H5中，JS API底层将通过这些数据判断H5是否有权限使用JS API。
· 请求说明
Https请求方式：GET

· 参数说明
参数
必须
说明
access_token
是
调用接口凭证
type
是
这里是固定值，jsapi
· 返回结果
a)正确时返回示例如下：
{
"errcode":0,
"errmsg":"ok",
"ticket":"dsf8sdf87sd7f87sd8v8ds0vs09dvu09sd8vy87dsv87",
"expires_in":7200
}
参数
说明
errcode
错误码
errmsg
错误信息
ticket
用于JS API的临时票据
expires_in
票据过期时间
出错时返回示例如下：
{
"errcode": 45009,
"errmsg": "接口调用超过限制"
}