钉钉H5接入流程

成功后示例 开发前准备： 1，开放平台注册申请权限 2，选择钉钉应用类型，创建应用，获取AppKey，AppSecret，CORP_ID 3，准备开发环境 静态页面、JS，CSS放在ngnix，本地接口用tomcat。（这个我在想flutter 如何能够放到里面不是太理解） 4，调试：钉钉的H5微应用调试只能“真机”调试，所以 建议 调试的时候使用 内网穿透工具 ； 5，JSAPI免登授权码  获取当前钉钉登录用户的账号信息，需要通过免登授权码换取 （这个需要后端api进行辅助 前端和后端才能进行通信）在开发者后台添加完大概就这样了, 其他信息:如 回调URL(在服务端搭好之后填写), 首页地址等, 后续可以修改.     1. 相关配置参数可参照上面 应用基础信息 那张图来一 一对应 .     2. 所有的关键信息 是存储在服务端的, 如我们的suiteKey/suiteSecret/suiteTicket/aesKey/token     3. 所以和钉钉相关的数据交互都是在服务端,后台完成的, 除了获取免登授权码     4. 我们的前端和我们的服务端交互过程中, corpId 由前端获取 , 传递给我们     5. 服务端和钉钉交互所使用的accessToken , 可以每次都去钉钉重新获取, 但是更建议在有效期内, 后端获取一次, 然后存储在前端, 每次的数据交互将token 传递给后端     6. 钉钉向我们服务器发送请求, 也就是钉钉应用里面的回调地址     7. 钉钉的所有消息都是通过回调通知我们的, 而且消息的结构是一致的 根据上面的相关说明将服务端放置在自己的公网服务器也好，或者使用相关的 内网穿透工具 也好  (自行解决) 总之, 现在要有一个可以 访问我们 服务端项目的 公网地址  确保你自己的服务器可以使用公网地址访问到,并且成功返回数据同时确保: 必须有回调地址借口用来接收钉钉发送的消息                                    (本文示例地址:/ding/callback) 必须有一个接收免登授权码和企业corpId 来返回用户信息的接口      (本文示例地址:/ding/login ) 公网可以访问的服务端地址, 接收钉钉发给我们的消息(回调地址)如：http://ding.lnexin.cn/server/ding/callback，我们自己的登录地址，如:http://ding.lnexin.cn/server/ding/login 在钉钉开发者平台创建配置好的一个H5微应用 确保服务端的参数和微应用的基础信息一致 完成上述步骤，在客户端依旧是没有应用入口的，如： 下面需要在开发者平台进行授权最后能在钉钉上使用了 基本就是这样一个流程 如果感觉不太详细 点击下面链接看就可以 以上文章通过读  https://www.cnblogs.com/applerosa/p/11509512.html

ISV 机制是为“应用市场”而设计的，按钉钉官方的想法，作为独立服务提供商，可以开发完应用之后，上架市场，需要的企业自己到市场上来采购应用。基于此，它的授权，通知的实现机制也就是现在这样，有些麻烦的样子了。用户“采购应用”， 或者对应用做任何的配置性的操作，都是在钉钉的服务中完成的，但是实际提供服务的，却是具体 ISV 开发的应用。所以，企业用户，钉钉，ISV 三方之间，钉钉的服务就是一个衔接的作用，这其间的“推送”也算 ISV 方式与普通的“微应用”方式最大的不同了。（推送那里就涉及 AES 加解密）。

建立连接

你可以使用以下两种方式，将钉钉微应用连接到你的企业应用：

1、企业应用服务器调用钉钉开放平台提供的接口，以钉钉微应用的身份给企业用户的钉钉账号推送消息，以下称 主动调用模式。

2、钉钉用户在使用企业提供的微应用H5页面时，该页面可以调用钉钉提供的JS接口，使用钉钉开放的终端能力和业务能力，以下称 JSAPI模式。

3、钉钉服务器把用户发送的消息或用户触发的事件推送给企业应用，由企业应用处理，以下称 回调模式。

主动调用

当企业应用服务器调用钉钉开放平台接口时，需使用https协议、Json数据格式、UTF8编码，访问域名为 https://oapi.dingtalk.com。

在每次主动调用钉钉开放平台接口时需要带上AccessToken参数。AccessToken参数由CorpID和CorpSecret换取。对于ISV来说，获取企业授权的access_token

CorpID是企业在钉钉中的标识，每个企业拥有一个唯一的CorpID；

CorpSecret是企业每个应用的凭证密钥。

CorpID及CorpSecret可以在钉钉为企业提供的管理后台中找到，由钉钉自动分配。

POST请求请在HTTP Header中设置 Content-Type:application/json，否则接口调用失败

主动调用的频率限制

当你获取到AccessToken时，你的微应用后台就可以成功调用钉钉后台所提供的各种接口或访问相应企业的资源或给成员发消息。

为了防止微应用的程序错误而引发钉钉服务器负载异常，默认情况下，每个服务端调用接口都有一定的频率限制，当超过此限制时，调用对应接口会收到相应错误码。

以下是当前默认的频率限制，钉钉后台可能会根据运营情况调整此阈值：

每个企业调用单个接口的频率不可超过1500次/分

每个ISV（应用提供商）调用单个接口的频率不可超过2000次/分

每个ISV（应用提供商）调用单个企业的单个接口频率不可超过1500次/分

每个套件调用单个企业的单个接口频率不可超过1000次/分

一、免登问题

1.如何在App及后台获取企业及用户相关信息

（1）微应用主页支持使用$CORPID$模板参数表示corpid，用户访问微应用的时候钉钉将把$CORPID$替换成用户所属企业的corpid，例如http://www.dingtalk.com/index?corpid=$CORPID$

（2）获取用户信息需要通过免登服务，详情http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.Bz74m4#免登服务

2.钉钉微应用OAuth2授权打开一个应用时提示对不起您无权限查看该页面

可能的原因：

(1)如果其他应用正常，或者企业其他人打开应用没问题，可能是缓存问题引起，请清除下缓存

(2)参数redirect_uri的值没有做url编码

(3)redirect_uri的域名和微应用的域名不一致

3.免登Code的时效性

免登授权码是一次性的，团队(未认证的企业)失效时间五分钟

二、JSAPI问题

1.jsapi权限校验失败，错误码080003是什么原因

请先按照文档，先检查参数agentid传值是否正确，agentId查看方式：

（1）如果是isv应用，需要通过http://open.dingtalk.com/doc/#10-获取企业的应用信息

（2）企业自建应用，通过oa后台查看http://open.dingtalk.com/doc/#开发环境准备

2.jsapi权限校验时返回{message:"权限校验失败"，errorcode:3}

（1）首先检查用来生成签名(signature)的jsapi_ticket是否过期（jsapi_ticket有效期为7200秒，而且当你请求了新的ticket之后，旧的ticket就失效了）

（2）其次检查生成签名的Url参数，与调用dd.config 所在的url是否一致

生成签名用的url需要去除hash部分，e.g. 如果当前页面url是http://abc.def/ghi/jkl?m=123&n=456#opq，则用于生成签名的url是http://abc.def/ghi/jkl?m=123&n=456，可以使用调试工具来生成jsapi_ticket和signature，并和你实际使用的进行对比

（3）提示权限校验失败，errorcode:3，错误码52019，请检查corpid是否正确

3.使用JSAPI返回签名或者Ticket获取失败

JSAPI返回失败主要有两种错误

（1）[错误码:52011] [jsapi ticket 读取失败]

a.确认agentId参数正确传入

b.确认以传入agentId对应的企业身份获取过jsapi_ticket,也就是调用过get_jsapi_ticket方法

c.确认agentId对应的企业身份获取的jsapi_ticket没有过期.即在两个小时的有效期之内

（2）[错误码:52013][签名校验失败]

a.确认agentId参数正确传入

b.oa后台设置uri和权限校验uri不一致(去掉hash部分)

c.确认获得的jsapi_ticket为最新的,没有其他服务同时调用get_jsapi_ticket方法,导致生成签名的jsapi_ticket过期

d.确认生成jsapi签名正确,可以使用debug工具进行调试https://debug.dingtalk.com/

4.ios 单页面应用更改url#后面的参数(如:localhost:8100/#/test1 变成 localhost:8100/#/test2)，调用jsapi无效

ios单页面应用更改url参数，导致调用jsapi无效问题，将在2.7版本随新版本发布；

若是老版本(2.7以前版本)，需要打开页面时重新授权，调用jspai即可正常

5.jspai 调用返回errCode7 错误原因

(1)请查看在dd.config的jsApiList中，是否已配置要使用的jsapi，未配置的话会报错

(2)ios 单页面应用提示 errCode7 Jsapi Should NOT CallselectorString

同问题5，单页面应用更改url参数，导致调用jsapi无效，老版本(2.7以前版本)需要重新授权，调用jsapi正常

(3)requestJsApis() not invoked,errorCode:7

dd.ready一定要在dd.config之后执行

6.如何获取JSAPI权限（需再详细些）

可以参照http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.XpRuM1#客户端开发文档，要使用的jsapi必须进行权限验证配置，在dd.config中进行配置，可参照http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.XpRuM1#权限验证配置-beta

7.工具栏颜色如何设置

在页面需要引入js文件的前提下，通过url参数设置导航栏颜色，参数名为dd_nav_bgcolor

比如微应用当前页面链接为：https://abc.xyz/，要设置的颜色为FF112233（前两位默认FF，后面6位112233是对应的色值），可设置页面url为：https://abc.xyz/?dd_nav_bgcolor=FF112233

8.device.geolocation.get 提示unauthorized errcode 4

用户设备禁用了手机的定位功能

9. 钉钉发送会话消息，cid如何获取

使用场景示例:用户在微应用中拉起本地聊天窗口列表(通过调用jsapi-获取会话信息)，选择某一个聊天窗口，微应用将收到钉钉返回的cid，通过这个cid会送会话消息。

a.前提条件：jsapi可使用，即已经配置到dd.config，且通过jsapi的权限校验

b.通过jsapi获取会话cid，详见http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.FDtb0f#获取会话信息

10.errorMessage:”err msg redirect_uri domain is not secure domain”,”errorCode”:”3”

在oa后台设置微应用首页地址(域名设置为可信域名，即可安全访问授权)

11.读取nfc芯片接口无法使用

[font=微软雅黑, 'Microsoft Yahei', 'Hiragino Sans GB', tahoma, arial, 宋体]目前nfc芯片接口只支持android(文档中已注明，请查看文档)

三、服务端API

1.调用管理通讯录接口返回43004，无效的HTTP HEADER Content-Type如何解决

管理通讯录的部分接口采用了POST请求，请求体使用JSON格式，请在HTTP请求头中设置Content-Type:application/json

2.上传文件不成功

使用multipart/form-data请求上传文件，需要附加文件标示信息，参数名为media；java示例代码为

HttpEntity requestEntity =MultipartEntityBuilder.create().addPart("media", new FileBody(file, ContentType.APPLICATION_OCTET_STREAM, file.getName())).build()

3.新建部门和员工信息为中文时，创建不成功

请检查编码格式，确认是utf-8编码

4.注册事件回调接口，每个corpid只能注册一个回调url吗

一个企业的一个套件，只能注册一个回调url

5.返回系统繁忙错误

(1)调试调用接口过程中出现，请先确保是否是JSON格式错误，比如POST时有的JSON里缺少了这种括号[ ]

(2)请检查url是否正确，如免登接口，通过code换取用户信息，/getuserinfo，实际应为/user/getuserinfo

(3)调用其他接口也返回系统繁忙，请您立刻在答疑群或论坛等反馈给钉钉人员

四、ISV接入问题

1.开发者平台创建套件校验url有效性问题

如果返回字符串不匹配，提示错误代码71009，可以通过以下常见问题确认具体原因：

a.可以通过将加密数据在本地解密下，看解密后的数据是否正确

b.查看是否是各字段名字错误，如timeStamp，却写成了timestamp

2.ISV接入回调接口没有suiteticket推送

注册套件之后，钉钉服务器会向填写的回调接口推送suite_ticket；接收到推送之后需要返回加密后的字符串“success”,如果不返回或返回错误，钉钉服务器将连续推送，直到推送次数超过100次，就不再推送；

此时需要进入开发者后台，进入套件管理页面，点击『重新推送』按钮，即可重新推送

3.回调地址接收钉钉服务器推送下来的数据，遇到计算解密文字错误

请查看加解密库和demo下载第二个步骤，见http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.FDtb0f#加解密库和demo下载

4.模拟测试企业发起授权所有套件，收不到临时授权码，而是change_auth

在开发者平台，目前授权行为只能发起一次，如已经收到临时授权码，模拟测试企业发起授权行为，收到change_auth事件；

测试企业解授权功能近期会上线，请关注文档及论坛更新

5.不存在的临时授权码

临时授权码只能使用一次，使用后再次使用会提示“不存在的临时授权码”

6. isv开发中，如果permanentCode没有存下来，如何获取到

目前没有办法获取，可以通过解除授权再次授权重新获取，解除授权功能暂时未开放，请在文档及论坛关注开放时间

7. 微应用性能测试提供的测试号码加不进去

微应用性能测试提供的3个测试号码，使用钉钉开放平台通讯录接口添加的话，有最多加入5个非认证企业限制；建议通过钉钉管理后台（https://oa.dingtalk.com/#/login）的通讯录进行添加

8.微应用性能测试报告中的图像中，显示无权查看该页面可能原因

请将在测试的h5地址直接在钉钉会话中打开，如找一个聊天会话，把要测试的h5地址直接贴在会话中，并点击打开

a.如果打开提示无权查看该页面，则是h5地址问题；

b.如果打开正常，请联系钉钉值班同学反馈；

10.IP白名单问题，返回errcode":60020",访问ip不在白名单之中

调用钉钉API的机器需要配置在开发者平台中配置白名单

11.如何解除开发者平台的钉钉账号绑定

暂未提供开发者平台、云市场与钉钉账号解绑功能，请关注官方文档及论坛，若提供会同步更新

12.第三方ISV的套件开发完，如何与钉钉接入合作，让其他企业授权使用套件

ISV开发完成套件后，需要对微应用进行性能评测等（http://open.dingtalk.com/doc/index.html?spm=a3140.7785475.0.0.rscFVO#微应用性能评测），以及在钉钉应用市场进行上架后，才可被其他企业用户搜索到，并进行购买授权等操作；

可关注文档对应用市场内容的更新，可发送邮件至邮件组open-dingtalk@list.alibaba-inc.com进行咨询

13.isv如何获取企业中用的mobile和email

如果在开发者后台勾选了邮箱字段，则可以获取用户的email；mobile暂不提供

14.isv demo中返回创建套件时返回解密文字或corpid或者suiteKey不匹配

(1)在 ENV文件中

[font='Helvetica Neue', Helvetica, Arial, sans-serif]public static final String CREATE_SUITE_KEY = "suite4xxxxxxxxxxxxxxx"//首次创建套件校验url时使用；

public static final String SUITE_KEY = ""//已有套件时使用

(2)IsvReceiveServlet中

dingTalkEncryptor = new DingTalkEncryptor(Env.TOKEN, Env.ENCODING_AES_KEY, Env.SUITE_KEY)

第三个参数使用，如果首次创建校验url使用 Env.CREATE_SUITE_KEY，即

dingTalkEncryptor = new DingTalkEncryptor(Env.TOKEN, Env.ENCODING_AES_KEY, Env. CREATE_SUITE_KEY)

如果已有套件，使用Env.SUITE_KEY，且在ENV文件中将public static final String SUITE_KEY = "xxxx"赋值，即

dingTalkEncryptor = new DingTalkEncryptor(Env.TOKEN, Env.ENCODING_AES_KEY, Env.SUITE_KEY)

五、通用问题

1.isv接入demo

最近收到isv接入demo存在加解密失败问题，这部分demo正在更新，近期会更新(http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.ai7Y3e#加解密库和demo下载)

2.钉钉https下使用oss Js SDK请求ERRSSLPROTOCOLERROR

https://bbs.aliyun.com/read/275103.html?spm=0.0.0.0.L7U6vv

六、常见需求及建议回复

1.发Ding的接口是否支持

钉钉不对外提供提供服务端ding接口

2.钉钉是否开放公告接口

钉钉暂不开放公告接口

3.钉钉是否提供审批、签到等微应用接口，便于第三方系统数据对接

目前只提供了管理日历接口接入，详见http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.ai7Y3e#管理日历接入指南；

其他暂未提供

4.钉钉产品如何与企业内部的ERP系统实现对接

(1)可以基于钉钉开放平台开发一个报表的微应用，钉钉提供免登机制获取用户信息，报表权限由你开发的微应用进行控制

(2)微应用是基于H5开发的，因此可以基于H5开发图标展示

(3)企业内部的文件可以通过钉盘进行存储，也可以存放在自己的服务器，在微应用内进行下载

以上实现均需开发微应用

---