钉钉开发文档

定制服务商开发E应用

更新时间: 2019-4-17

基本介绍

钉钉上的企业或组织除了使用钉钉提供的通用基础功能外,为满足办公场景中的个性化需求,可以基于钉钉的开放能力,自主开发应用,供企业或组织内部使用。但部分企业内部没有开发团队,因此需要寻找定制服务商在钉钉上为企业做开发,实现企业的需求。

主要场景:将企业自己的HR、CRM、OA、客户管理、业务管理等系统接入钉钉;重新开发一款应用,供该企业内部员工使用等,实现移动化办公。

准备工作

  1. 定制服务商在钉钉开放平台申请定制服务商认证,并通过审核;非认证的定制服务商无法被企业授权进行开发。

  2. 定制服务商与企业已沟通,确定了企业的需求与即将开发的应用,供企业内部使用。

  3. 定制服务商需要将自己的corpid提供给企业,作为授权的唯一凭证。

开发流程

以下将完整描述创建应用、定制服务商为企业开发应用的流程。

创建应用基础信息

登录钉钉开发者后台,选择"应用开发"->"企业内部开发"->"E应用",点击"创建应用",开始创建企业自建应用。
image.png

填写应用基本信息。包括应用名称、logo和简介等。
选择开发方式:
(1)企业内部自主开发(企业内部有开发团队,自行开发应用)。
(2)授权给钉钉认证服务商开发(企业内部没有开发团队,需要企业外部的服务商进行开发)。

image.png

接下来,要配置定制应用的开发信息。
选择授权给服务商开发,则需要继续填写以下信息:

image.png
定制服务的corpId:由服务商提供,是该服务商的唯一标记,用于验证服务商信息。注意,若服务商未通过钉钉服务商认证,说明该服务商资质未通过审核,不建议选择,无法为企业开发应用。

服务器出口IP:需要定制服务商提供,该IP专门给该企业使用,不能和其它的应用服务器IP重复,可保证定制服务商开发的应用服务器只给当前企业使用,也保证企业的应用体验与稳定性。

可使用范围:企业内哪些员工可以使用该应用,建议在开发阶段设置为仅开发人员可使用该应用,等定制服务商开发完,发布上线后,再修改成正常的可见范围。

应用权限设置
为了保证企业的数据安全与应用稳定,请根据应用的功能,对服务商可在应用内使用的权限,进行合理的分配。
其中,通讯录权限,需要选择授权的范围,表示:服务商可获取哪些人员的通讯录信息。建议开发期间,根据需要,合理授权。

点击确认授权,即可创建应用。

定制服务商开发应用

创建应用后,服务商需要登录自己的开发者后台,查看并开始开发应用。
定制服务商登录到开发者后台中,点击【服务管理】—【定制服务商】—【定制应用列表】 ,查看被授权的定制应用。

找到需要开发的应用,查看应用信息。

获取应用开发信息准备开发。
从应用信息中获取customKey, customSecret。

添加开发人员(定制服务商的企业内部人员)。

设置体验组织企业,开发阶段可以将应用安装到体验组织进行测试(详细的开发流程可阅读钉钉开发文档)

准备开发环境

  • 下载IDE

  • 定制服务商开发登录IDE

开发E应用

1.获取免登授权码

接口说明:

dd.getAuthCode
名称 类型 描述
authCode string 免登授权码(authCode) ,5分钟有效,且只能使用一次

使用说明:
该接口为前端JSAPI,直接在应用页面的onLoad方法里面调用即可。

客户端 Android iOS PC
支持说明 4.5及以上支持 4.5及以上支持 不支持

获取authCode示例:

dd.getAuthCode({
    success:(res)=>{
        dd.alert({content: res.authCode})
    },
    fail: (err)=>{
        dd.alert({content: JSON.stringify(err)})
    }
})

2.获取当前企业

接口说明:

app.globalData.corpId

3.获取accessToken

请求方式: 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 定制应用的customKey
timestamp 当前时间戳,单位是毫秒
suiteTicket 可以随意填写
signature 以timestamp+"\n"+suiteTicket为签名字符串,customSecret为签名密钥,使用算法HmacSHA256计算的签名值。签名计算说明

POST参数说明:

参数 说明
auth_corpid 授权方corpid, E应用中通过app.globalData.corpId获取

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,"customKey","customSecret", "suiteTicket");

返回结果示例:

{
	"access_token":"xxxxxx",
	"expires_in":7200
}
参数 说明
access_token 授权方(企业)corp_access_token
expires_in 授权方(企业)corp_access_token超时时间

4.获取免登用户基本信息

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/user/getuserinfo?access_token=access_token&code=authCode
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
code String 免登授权码

SDK请求示例(JAVA):

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/getuserinfo");
OapiUserGetuserinfoRequest request = new OapiUserGetuserinfoRequest();
request.setCode(requestAuthCode);
request.setHttpMethod("GET");
OapiUserGetuserinfoResponse response = client.execute(request, accessToken);
String userId = response.getUserid();

返回结果

{
    "userid": "****",
    "sys_level": 1,
    "errmsg": "ok",
    "is_sys": true,
    "deviceId": "***",
    "errcode": 0
}

5.获取用户详情

通过access_token和userid获取免登用户的信息。

请求方式:GET(HTTPS)
请求地址https://oapi.dingtalk.com/user/get?access_token=access_token&userid=userid
参数说明

参数 参数类型 必须 说明
access_token String 调用接口凭证
userid String 用户userid

SDK请求示例(JAVA)

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/user/get");
OapiUserGetRequest request = new OapiUserGetRequest();
request.setUserid(userId);
request.setHttpMethod("GET");
OapiUserGetResponse response = client.execute(request, accessToken);

返回结果

{
    "orderInDepts": "{}",
    "position": "",
    "remark": "",
    "department": [
        54962
    ],
    "unionid": "***",
    "tel": "",
    "userid": "***",
    "isSenior": false,
    "workPlace": "",
    "isBoss": false,
    "name": "***",
    "errmsg": "ok",
    "stateCode": "86",
    "avatar": "https://static.dingtalk.com/media/***.jpg",
    "errcode": 0,
    "jobnumber": "0001",
    "isLeaderInDepts": "{54962231:false}",
    "email": "***",
    "roles": [
        {
            "id": ***,
            "name": "主管理员",
            "groupName": "默认",
            "type": 101
        }
    ],
    "active": true,
    "isAdmin": true,
    "openId": "***",
    "mobile": "***",
    "isHide": false
}

6.获取定制应用基本信息和授权企业信息

请求方式: POST(HTTPS)
请求地址: https://oapi.dingtalk.com/service/get_auth_info?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体:

{
	"auth_corpid":"auth_corpid"
}

请求参数说明:

参数 必须 说明
accessKey 定制应用的customKey
timestamp 当前时间戳,单位是毫秒
suiteTicket 可以随便填写
signature 通过timestamp+"\n"+suiteTicket为签名字符串, customSecrect为签名密钥,使用算法HmacSHA256计算的签名值。签名计算说明
auth_corpid 授权方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",
	},
    "auth_info":{
	"agent":[{
			"agent_name":"aaaa",
			"agentid":1,
			"logo_url":"http://aaaaaa.com"}]
	}
	 "errcode":0,
	"errmsg":"ok"
}

结果参数说明:

参数 说明
auth_corp_info 授权方企业信息
corpid 授权方企业id
corp_name 授权方企业名称
corp_logo_url 企业logo
auth_info 授权信息
agent 授权的应用信息
agentid 授权方应用id
agent_name 授权方应用名字
logo_url 授权方应用头像
以上内容是否对您有帮助:
在文档使用中是否遇到以下问题(多选):
  • 内容错误
  • 更新不及时
  • 链接错误
  • 缺少代码/图片示例
  • 太简单/步骤待完善
手机号
更多建议
提交成功,感谢您的反馈!