服务商(ISV)接入
ISV授权流程
业务场景
钉钉的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就可以进行免登以及调用服务端接口
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开发微应用的时候如果必须要使用到企业通讯录，请按照以下流程进行申请：
1.登录钉钉开发者平台，点击顶部“入驻|登录”，若还未注册企业团队（且完成认证）的钉钉号，请点击入驻。若已完成认证，请点击“登录”（钉钉扫码）进入开发者后台。在左侧「成为服务商」，选择「应用服务商」，填写申请信息。钉钉小二会在5个工作日内审核，审核结果会通过钉钉小秘书发送给申请人。
2.通过审批后，会将申请人加入服务商沟通组织，在该组织的审批应用中发起“通讯录权限申请”。
3.将自己公司开发的微应用部署到钉钉云上，具体的上云步骤可查看钉钉云相关文档，按步骤完成。点击查看
4.钉钉的安全审核人员会审核微应用在钉钉云上的部署状态，审核通过后2个工作日之内，工作人员会开通该微应用的通讯录接口权限。
注意：ISV所获取到的通讯录权限仅包括数据拉取权限，不包括数据修改权限。
ISV接入相关接口调试：ISV接入调试工具