钉钉开发文档

获取授权信息

更新时间: 2019-2-14

获取授权企业corpId

应用通过以下两方式的任一种获取开通企业的corpId

企业授权开通应用的事件通知

企业管理员开通ISV应用时,钉钉会给ISV推送开通消息。可从事件消息内容中获取到corpId。
正确地处理此事件,可以及时初始化开通企业信息,当用户访问应用时应用的数据已经准备好;若没有处理或者处理失败,应用也可在用户第一次访问应用时进行企业数据初始化。

在用户访问应用时获取

在微应用的首页URL中使用CORPIDCORPIDCORPID做为参数占位符,当企业员工访问应用后,钉钉容器会将CORPIDCORPIDCORPID替换为当前访问的企业的corpId,前端可从URL中获取。

获取企业授权的凭证

企业授权凭证access_token用来后续调用钉钉服务端API。

请求方式:POST(HTTPS)
请求地址: https://oapi.dingtalk.com/service/get_corp_token?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{
	"auth_corpid":"auth_corpid_value",
}

请求参数说明:

参数 参数类型 必须 说明
accessKey URL参数 三方应用的suiteKey
timestamp URL参数 当前时间戳,单位是毫秒
suiteTicket URL参数 钉钉给应用推送的ticket,获取方式参考推送suite_ticket。测试应用可以随意填写。
signature URL参数 以timestamp+"\n"+suiteTicket为签名字符串,suiteSecret为签名密钥,使用算法HmacSHA256计算的签名值。注意:计算出签名以后,需要进行urlencode,才能把签名参数拼接到url中。签名计算说明
auth_corpid Http body 授权企业corpId,组装为JSON结构置于http post body部分

SDK请求示例(JAVA):

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_corp_token");
OapiServiceGetCorpTokenRequest req = new OapiServiceGetCorpTokenRequest();
req.setAuthCorpid("dingc365fcabbf733c3535c2f4657eb6378f");
OapiServiceGetCorpTokenResponse execute = client.execute(req,"suiteKey","suiteSecrect", "suiteTicket");

返回结果示例:

{
	"access_token":"xxxxxx",
	"expires_in":7200
}

返回结果说明:

参数 说明
access_token 授权方(企业)corp_access_token
expires_in access_token超时时间

获取授权信息

请求方式:POST(HTTPS)
请求地址: https://oapi.dingtalk.com/service/get_auth_info?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{
	"auth_corpid":"auth_corpid_value"
}

请求参数说明:

参数 参数类型 必须 说明
accessKey URL参数 应用的suiteKey
timestamp URL参数 当前时间戳,单位是毫秒
suiteTicket URL参数 钉钉给应用推送的ticket,测试应用可以随便填写
signature URL参数 以timestamp+"\n"+suiteTicket为签名字符串,suiteSecret为签名密钥,使用算法HmacSHA256计算的签名值。注意:计算出签名以后,需要进行urlencode,才能把签名参数拼接到url中。签名计算说明
auth_corpid Http body 授权企业方corpId,组装为JSON结构置于http post body部分

SDK请求示例(JAVA):

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_auth_info");
OapiServiceGetAuthInfoRequest req = new OapiServiceGetAuthInfoRequest();
req.setAuthCorpid("dingc365fcabbf733c3535c2f4657eb6378f");
OapiServiceGetAuthInfoResponse response = client.execute(req,"suiteKey","suiteSecrect", "suiteTicket");

返回结果示例:

{
   "auth_corp_info":{
	  "corp_logo_url":"http://xxxx.png",
	  "corp_name":"corpid",
	  "corpid":"auth_corpid_value",
	  "industry":"互联网",
	  "invite_code" : "1001",
	  "license_code": "xxxxx",
	  "auth_channel": "xxxxx",
	  "auth_channel_type": "xxxxx",
	  "is_authenticated":false,
	  "auth_level":0,
	  "invite_url":"https://yfm.dingtalk.com/invite/index?code=xxxx"
	},
	"auth_user_info":
    {
    	"userId":""
	},
    "auth_info":{
	"agent":[{
			"agent_name":"aaaa",
			"agentid":1,
			"appid":-3,
			"logo_url":"http://aaaaaa.com",
			"admin_list":["zhangsan","lisi"]
	}
	,{
			"agent_name":"bbbb",
			"agentid":4,
			"appid":-2,
			"logo_url":"http://vvvvvv.com",
			"admin_list":[]
	}]
	},
        "channel_auth_info": {
		"channelAgent": [
				{
					"agent_name": "应用1",
					"agentid": 36,
					"appid": 6,
					"logo_url": "http://i01.lw.test.aliimg.com/media/lALOAFWTc8zIzMg_200_200.png"
				},
				{
					"agent_name": "应用2",
					"agentid": 35,
					"appid": 7,
					"logo_url": "http://i01.lw.test.aliimg.com/media/lALOAFWTc8zIzMg_200_200.png"
				}]
		},
	 "errcode":0,
	"errmsg":"ok"
}

返回结果说明:

参数 说明
auth_corp_info 授权方企业信息
corpid 授权方企业id
invite_code 邀请码,只有自己邀请的企业才会返回邀请码,可用该邀请码统计不同渠道的拉新,否则值为空字符串
industry 企业所属行业
corp_name 授权方企业名称
license_code 序列号
auth_channel 渠道码
auth_channel_type 渠道类型,为了避免渠道码重复,可与渠道码共同确认渠道(可能为空。非空时当前只有满天星类型,值为STAR_ACTIVITY)
is_authenticated 企业是否认证
auth_level 企业认证等级,0:未认证,1:高级认证,2:中级认证,3:初级认证
invite_url 企业邀请链接
auth_user_info 授权方管理员信息
corp_logo_url 企业logo
auth_info 授权信息
agent 授权的应用信息
agentid 授权方应用id
channel_auth_info 授权的服务窗应用信息列表
agent_name 授权方应用名字
logo_url 授权方应用头像
appid 应用id
auth_info.agent.admin_list 对此微应用有管理权限的管理员userid

获取应用信息

该API用于获取已授权开通的企业的某个应用的基本信息,包括LOGO、名称、描述等。

请求方式:POST(HTTPS)
请求地址: https://oapi.dingtalk.com/service/get_agent?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{   
    "suite_key":"key_value",
    "auth_corpid":"auth_corpid_value",
    "agentid":541
}

请求参数说明:

参数 参数类型 必须 说明
accessKey URL参数 应用的suiteKey
timestamp URL参数 当前时间戳,单位是毫秒
suiteTicket URL参数 钉钉给应用推送的ticket,测试应用可以随便填写
signature URL参数 以timestamp+"\n"+suiteTicket为签名字符串,suiteSecret为签名密钥,使用算法HmacSHA256计算的签名值。注意:计算出签名以后,需要进行urlencode,才能把签名参数拼接到url中。签名计算说明

POST参数说明:

参数 说明
suite_key 应用套件key
auth_corpid 授权企业方corpid
agentid 授权企业方应用id

SDK请求示例(JAVA):

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_agent");
OapiServiceGetAgentRequest request = new OapiServiceGetAgentRequest();
request.setAuthCorpid("dingd610f0141e19fa4d35c2f4657eb637fxxxx");
request.setSuiteKey("suitezmpdnvsw4syq53g6xxx");
request.setAgentid("211164860xxxx");
OapiServiceGetAgentResponse response = client.execute(request, "suiteKey","suiteSecrect", "suiteTicket");

返回结果示例:

{
    "agentid":541,
    "name":"公告",
    "logo_url":"http://xxxxxxx/png",
    "description":"企业重要消息",
    "close":1,
    "errcode":0,
    "errmsg":"ok"
}

返回结果说明:

参数 说明
agentid 授权方企业应用id
name 授权方企业应用名称
logo_url 授权方企业应用头像
description 授权方企业应用详情
close 授权方企业应用是否被禁用(0:禁用 1:正常 2:待激活 )
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!