获取授权信息
获取授权企业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×tamp=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×tamp=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×tamp=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:待激活 ) |