钉钉的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 |
在注册成为钉钉开发者和创建套件&微应用之后,你就可以开始开发了。
当您在钉钉开发者后台创建套件时,需要验证回调URL的有效性并在该回调地址中处理接收suite_ticket的逻辑,然后就可以开发您的套件(微应用)了。
创建套件之后,需要注册测试企业模拟管理员授权应用,可以在『授权管理』中进行授权操作。授权成功后,需要立即激活套件(调用激活接口)才能在测试企业的工作面板中看到该应用,从用户授权至套件激活整体应在5s内完成,确保测试企业可以正常使用套件中的功能。
以下是从授权套件到获取企业的access_token的过程,有了企业的access_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服务端做定时器主动更新,而不是依赖钉钉的定时推送) |
如果企业开通应用,点击同意授权之后,钉钉会向ISV通过回调向ISV推送一个该企业的临时授权码。
临时授权码数据示例:
{ "SuiteKey": "suitexxxxxx", "EventType": "tmp_auth_code", "TimeStamp": 1234456, "AuthCode": "adads" }
该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 | 授权方企业名称 |
该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" }
企业的授权凭证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超时时间 |
该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 |
钉钉已经支持企业管理员动态调整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->管理->选择应用->设置->授权使用范围。
获取企业授权的通讯录权限范围请查看通讯录权限范围。
获取企业的access_token以后,可以通过前端免登服务换取登录用户的用户信息,例如userid等。
获取userid和企业的access_token以后,可以通过调用通讯录管理的user/get接口来获取当前登录用户的基本信息,参见文档。
应用服务商(ISV)默认无管理通讯录的权限,只有user/get接口调用权限。
ISV开发微应用的时候如果必须要使用到企业通讯录,请按照以下流程进行申请:
1.登录钉钉开发者平台,点击顶部“入驻|登录”,若还未注册企业团队(且完成认证)的钉钉号,请点击入驻。若已完成认证,请点击“登录”(钉钉扫码)进入开发者后台。在左侧「成为服务商」,选择「应用服务商」,填写申请信息。钉钉小二会在5个工作日内审核,审核结果会通过钉钉小秘书发送给申请人。
2.通过审批后,会将申请人加入服务商沟通组织,在该组织的审批应用中发起“通讯录权限申请”。
3.将自己公司开发的微应用部署到钉钉云上,具体的上云步骤可查看钉钉云相关文档,按步骤完成。点击查看
4.钉钉的安全审核人员会审核微应用在钉钉云上的部署状态,审核通过后2个工作日之内,工作人员会开通该微应用的通讯录接口权限。
注意:ISV所获取到的通讯录权限仅包括数据拉取权限,不包括数据修改权限。
ISV接入相关接口调试:ISV接入调试工具