钉钉开发文档

获取授权信息

更新时间: 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:待激活 ）
以上内容是否对您有帮助：
在文档使用中是否遇到以下问题（多选）：
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码／图片示例
  • 太简单／步骤待完善
手机号
更多建议
提交成功，感谢您的反馈！
@2019 阿里巴巴旗下网站：钉钉©️浙 B2-20080224-16