文档中心 > 上架应用市场

业务场景

钉钉的ISV应用是以套件来管理的,一个套件下可创建多个微应用。

通过调用钉钉提供的套件授权接口,在企业用户授权开通套件时,开发者需要为企业主动激活套件,企业可以在授权后直接使用该套件下的应用。

钉钉开放平台将验证API的请求来源IP,只有在套件IP白名单列表中的才被允许。

ISV在获取企业通讯录时,只能获取授权范围内的企业通讯录数据。

suite_ticket:用来换取suite_access_token,获取方式为钉钉服务端向ISV套件的回调地址推送

涉及到如下接口:

接口名 接口
获取套件访问Token https://oapi.dingtalk.com/service/get_suite_token
获取企业授权的永久授权码 https://oapi.dingtalk.com/service/get_permanent_code
获取企业授权的access_token https://oapi.dingtalk.com/service/get_corp_token
获取企业授权信息 https://oapi.dingtalk.com/service/get_auth_info
获取企业授权的通讯录权限范围(按照部门进行授权) https://oapi.dingtalk.com/auth/scopes
获取企业的应用信息 https://oapi.dingtalk.com/service/get_agent
激活授权套件 https://oapi.dingtalk.com/service/activate_suite

应用授权整体流程

ISV创建套件

注册成为钉钉开发者创建套件&微应用之后,你就可以开始开发了。

当您在钉钉开发者后台创建套件时,需要验证回调URL的有效性并在该回调地址中处理接收suite_ticket的逻辑,然后就可以开发您的套件(微应用)了。

企业管理员授权套件

创建套件之后,需要注册测试企业模拟管理员授权应用,可以在『授权管理』中进行授权操作。授权成功后,需要立即激活套件(调用激活接口)才能在测试企业的工作面板中看到该应用,从用户授权至套件激活整体应在5s内完成,确保测试企业可以正常使用套件中的功能。

套件授权流程图

以下是从授权套件到获取企业的access_token的过程,有了企业的access_token就可以进行免登以及调用服务端接口

Mou icon

1.获取应用套件令牌Token

使用场景

该API用于获取应用套件令牌(suite_access_token)

1.每次获取suite_access_token的时候,都会拿到suite_access_token的过期时间。在使用这个suite_access_token的时候,需要先判断一下suite_access_token是否过期(例如差10分钟过期,或者已经过期了),如果发现suite_access_token即将过期需要再来获取一下suite_access_token,获取suite_access_token的时候要加锁(防止多个请求同时都在更新suite_access_token)。

2.每次获取corp_access_token的时候,都会拿到corp_access_token的过期时间。在使用这个corp_access_token的时候,需要先判断一下corp_access_token是否过期(例如差10分钟过期或者已经过期了),如果发现corp_access_token即将过期需要再来获取一下corp_access_token,获取corp_access_token的时候要加锁。

3.有些ISV更新suite_access_token是依赖suiteticket推送来更新的,不建议这样来实现。钉钉的suite_access_token是不定时推送的,依赖suite_access_token的推送会引起suitetoken失效,导致程序出现异常。

接口说明

接口调用请求说明
https请求方式: POST
https://oapi.dingtalk.com/service/get_suite_token

POST数据示例

{
	"suite_key":"key_value",
 	"suite_secret": "secret_value",
	"suite_ticket": "ticket_value"
}

请求参数说明

参数 说明
suite_key 套件key,开发者后台创建套件后获取
suite_secret 套件secret,开发者后台创建套件后获取
suite_ticket 钉钉推送的ticket

返回结果示例

{
	"suite_access_token":"61W3mEpU66027wgNZ_MhGHNQDHnFATkDa9-2llqrMBjUwxRSNPbVsMmyD-yq8wZETSoE5NQgecigDrSHkPtIYA",
	"expires_in":7200
}

结果参数说明

参数 说明
suite_access_token 应用套件access_token
expires_in 有效期7200秒,过期之前要主动更新(建议ISV服务端做定时器主动更新,而不是依赖钉钉的定时推送)

2.获取企业授权的临时授权码

使用场景

如果企业开通应用,点击同意授权之后,钉钉会向ISV通过回调向ISV推送一个该企业的临时授权码

临时授权码数据示例:

{
  "SuiteKey": "suitexxxxxx",
  "EventType": "tmp_auth_code",
  "TimeStamp": 1234456,
  "AuthCode": "adads"
}

3.获取企业授权的永久授权码

使用场景

该API用于使用临时授权码换取企业的永久授权码,并可通过该永久授权码换取该企业授权信息、企业access_token。请将永久授权码存储下来,以后该企业的corp_access_token每次更新都需要使用。

注:临时授权码使用一次后即失效

接口说明

接口调用请求说明
https请求方式: POST
https://oapi.dingtalk.com/service/get_permanent_code?suite_access_token=xxxx

POST数据示例

{
	"tmp_auth_code": "value"
}

请求参数说明

参数 说明
tmp_auth_code 回调接口(tmp_auth_code)获取的临时授权码

返回结果示例

{
	"permanent_code": "xxxx",
	"ch_permanent_code": "xxxx", // 如果该套件下存在服务窗应用,会返回ch_permanent_code,代表服务窗应用永久授权码
	"auth_corp_info":
	{
		"corpid": "xxxx",
		"corp_name": "name"
	}
}

结果参数说明

参数 说明
permanent_code 永久授权码
ch_permanent_code 企业服务窗永久授权码,如果该套件下存在服务窗应用,会返回
auth_corp_info 授权方企业信息
corpid 授权方企业id
corp_name 授权方企业名称

4.激活套件

使用场景

该API适用于当企业用户授权开通套件时,为授权方企业激活套件。如果ISV未调用此接口,则企业用户无法使用ISV套件。

注意:为企业激活该套件之后,就可以在钉钉客户端的工作面板上面看到该应用。

接口说明

信息接口调用请求说明

https请求方式: POST

https://oapi.dingtalk.com/service/activate_suite?suite_access_token=xxxx

POST数据示例

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

请求参数说明

参数 说明
suite_key 套件key
auth_corpid 授权方corpid
permanent_code 永久授权码,从get_permanent_code接口中获取

返回结果示例

{
	"errcode":0,
	"errmsg":"ok"
}

5.获取企业授权的凭证

使用场景

企业的授权凭证access_token可以用来调用企业相关的数据接口。

接口说明

接口调用请求说明

https请求方式: POST
https://oapi.dingtalk.com/service/get_corp_token?suite_access_token=xxxx

POST数据示例

{
	"auth_corpid":"auth_corpid_value",
	"permanent_code":"code_value"
}

请求参数说明

参数 说明
auth_corpid 授权方corpid
permanent_code 永久授权码,通过get_permanent_code获取

返回结果示例

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

结果参数说明

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

6.获取企业基本信息

使用场景

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

接口说明

接口调用请求说明

https请求方式: POST

https://oapi.dingtalk.com/service/get_auth_info?suite_access_token=xxxx

注意,是suite_access_token,不是授权方(企业)的access_token

POST数据示例

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

请求参数说明

参数 说明
auth_corpid 授权方corpid
suite_key 套件key

返回结果示例

{
   "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 ,agentId会在前端签名校验的时候使用到。
channel_auth_info 授权的服务窗应用信息列表
agent_name 授权方应用名字
logo_url 授权方应用头像
appid 套件中的应用id
auth_info.agent.admin_list 对此微应用有管理权限的管理员userid

7.获取企业授权的权限范围

钉钉已经支持企业管理员动态调整ISV开发者用到的token可获取到的企业通讯录范围,在ISV开发者获取到可以访问企业通讯录接口的token后,正式获取通讯录数据前,首先应该调用本接口,获取当前token的授权范围,再依次遍历本接口返回的部门id列表,调用通讯录相应接口,另外在套件收到【向ISV推送授权变更消息】回调后,也需要调用本接口来同步通讯录数据。

举例如下,某企业的通讯录包含两个部门和三个员工,分别是部门A(员工甲、员工乙)和部门B(员工丙)。

在企业对ISV的套件授权时,管理员可以选择只授权一部分通讯录数据给ISV。针对本例,假设只授权了员工甲及部门B,当ISV再调用/department/list接口时,部门A和部门B的id都不再返回,会返回错误(部门不在授权范围内)。这会导致ISV无法获取管理员授予的全部数据,这时ISV应该调用/auth/scopes接口获取管理员授予的全部数据范围,接口会返回部门B的id及员工甲的userid,然后ISV再通过/department/list?id={部门B的id}获取部门B的子部门,通过/user/get接口获取员工甲的详细信息。

另外需要注意的是,如果ISV通过企业会话发送消息,接收者是未授权的员工userid或部门id,也会返回错误(员工或部门不在授权范围内)。

为了方便ISV平滑迁移,我们暂定在2017年4月10日之后新创建的套件默认采用按部门授权的策略,之前创建的套件如需要开启,请通过工单形式提供suiteKey,由我们手动开启。另外需要注意的是,在正式套件开启前,一定要先建立一个测试套件,对功能完整测试后,再申请对正式套件开启。

在套件开启按部门授权功能后,企业管理员可以在如下位置进行授权范围的调整:钉钉客户端->工作TAB->管理->选择应用->设置->授权使用范围。

获取企业授权的通讯录权限范围请查看通讯录权限范围

8.通过免登获取用户信息

使用场景

获取企业的access_token以后,可以通过前端免登服务换取登录用户的用户信息,例如userid等。

获取userid和企业的access_token以后,可以通过调用通讯录管理的user/get接口来获取当前登录用户的基本信息,参见文档

应用服务商(ISV)默认无管理通讯录的权限,只有user/get接口调用权限。

ISV通讯录权限获取流程:

isv_flow

ISV开发微应用的时候如果必须要使用到企业通讯录,请按照以下流程进行申请:

1.登录钉钉开发者平台,点击顶部“入驻|登录”,若还未注册企业团队(且完成认证)的钉钉号,请点击入驻。若已完成认证,请点击“登录”(钉钉扫码)进入开发者后台。在左侧「成为服务商」,选择「应用服务商」,填写申请信息。钉钉小二会在5个工作日内审核,审核结果会通过钉钉小秘书发送给申请人。

2.通过审批后,会将申请人加入服务商沟通组织,在该组织的审批应用中发起“通讯录权限申请”。

3.将自己公司开发的微应用部署到钉钉云上,具体的上云步骤可查看钉钉云相关文档,按步骤完成。点击查看

4.钉钉的安全审核人员会审核微应用在钉钉云上的部署状态,审核通过后2个工作日之内,工作人员会开通该微应用的通讯录接口权限。

注意:ISV所获取到的通讯录权限仅包括数据拉取权限,不包括数据修改权限。

ISV接入相关接口调试:ISV接入调试工具

FAQ

Ticker推送失败 计算解密文字corpid不匹配

返回
顶部