钉钉开发文档

获取企业信息

更新时间: 2018-8-6

通过本小节的阅读,您可以了解到,企业授权开通应用后,应用获取企业信息的流程。

前置条件:企业已经授权开通应用。
开通方式:企业管理员通过应用市场选择应用,并授权开通;或者开发者在开发者后台点击开通测试应用。

1 获取corpId

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

image.png

1.a 开通应用之时,企业授权开通应用事件的回调通知

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

企业授权开通应用事件数据示例

{
  "SuiteKey": "suitexxxxxx",
  "EventType": "tmp_auth_code",
  "TimeStamp": 1234456,
  "AuthCorpId": "dingxxxxadads"
}

1.b 开通应用之后,在用户第一次访问应用时获取

企业员工访问应用时通过前端获取当前访问企业的corpId。此种方式一般用于测试应用或者用于开通事件处理失败的补偿。
通过前端JSAPI dd.corpId获取并传递到服务端。

2 获取企业基本信息

2.1获取企业授权的凭证

企业授权凭证access_token用来后续调用钉钉服务端API。
应用能够获取到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超时时间

2.2 获取企业基本信息

该API用于通过企业的corpId获取企业的基本信息。

服务端API请求说明

请求方式: 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为签名字符串, suiteSecrect为签名秘钥,使用算法HmacSHA256计算的签名值。签名计算说明
auth_corpid Http body 授权方corpId,组装为JSON结构置于http post body部分

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_auth_info");
OapiServiceGetAuthInfoRequest req1 = new OapiServiceGetAuthInfoRequest();
req1.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

温馨提示:
为了快速体验测试应用开发流程,您可以忽略开通事件回调方式(1.a小节)。