常见问题

Q：开发对接过程中遇到问题如何咨询？
请打开钉钉扫码进群

Q：如何添加钉钉平台的机构CorpID实现授权绑定？
1.在手机钉钉工作台中搜索【魔点门禁】微应用并开通；登录钉钉开放平台-开发者后台，获取CorpID。

2.在开放平台应用详情，点击添加机构；输入CorpID，提交申请授权。

3.机构管理员打开手机钉钉上的“魔点门禁”微应用，点击右上角>更多>授权协议>同意授权。

Q：提示“没有接口调用权限”，如何解决？
(1)请检查请求路径是否有误：例如大小写错误、字符错误等。
(2)如请求路径没有问题，请确认是否已申请该接口权限或者确认该接口是否已到期。

Q：如何使用回调接口？
先注册回调，回调类型取决于实际需求，回调地址需支持公网访问。
以人脸识别开门记录回调为例，注册回调的类型为 REC_SUCCESS；实际产生刷脸开门记录后，我们会访问您注册的回调地址，请求传送相应的信息
【人脸识别开门记录回调】调用流程

【访客预约记录回调说明】调用流程

Q：没收到回调信息如何排查？
存在以下三种可能性：
(1)没有注册回调，即未提供回调类型和回调地址。
(2)回调接口注册的callbackTag与实际需要触发的业务不符。比如实际业务要识别回调，需注册“REC_SUCCESS”，但注册了其它类型。
(3)回调接口注册的callbackUrl地址无法访问，请确认。如还未解决，请加入魔点开发者交流群（钉钉群号34405002515）联系技术人员处理。

Q：回调信息是否有重试机制？
当业务消息回调给用户的callbackUrl 未成功，魔点系统会自动触发周期为11次、时长为24小时的重试机制，间隔为1分钟, 1分钟, 3分钟, 5分钟, 20分钟, 30分钟, 1小时, 2小时, 4小时, 8小时, 8小时。

Q：回调信息验签机制是怎么样的？
选择是否验签，并不影响业务回调的信息内容。
魔点提供了回调签名校验的机制如下：
（1）计算用户云端本地签名值：
signature = BASE64(HMACSHA1(nonce + orgId + signVersion + timestamp + bodyMd5, orgAuthKey))
（2） 参数说明：
其中nonce、orgId、signVersion、timestamp 通过魔点云端发送的回调请求Query参数中获取；
其中bodyMd5 = MD5(bodyStr)，MD5为MD5加密32位小写。bodyStr为魔点云端发送的回调请求中Body报文里原始字符串，需要直接将body报文转成String，不能进行Json反序列化之后再转换成String，否则会出现数据中字段顺序不一致的情况，从而导致验签不通过；body报文转成String。
Java语言参考
其中orgAuthKey为orgId对应的orgAuthKey，也就是获取accessToken对应的orgAuthKey。
（3）签名比对：
用户云端本地签名值signature计算完成，与魔点云端发送的回调请求Query参数中获取的签名值signature进行比较，一致则验签通过，不一致则验签未通过。

Q：如何调用三方鉴权接口？

Q：调用三方鉴权接口自定义文案，语音通报有效果，屏显没有效果是什么原因
存在设备包版本过低的可能，请先在设备端操作升级，如升级失败或无法升级，再联系售后人员。

Q：接口中人脸图片如何上传？
参数类型是File，参数值是一个图片，二进制文件，需要用post multipart/form-data的方式上传。

Q：接口中人脸图片有何限制？
人脸图片大小不能超过2M，图片的像素需要小于1920X1920。
人员和成员相关接口的人脸图片，人脸图片中人脸的像素大小至少为200X200，并非整体图片像素大小。

Q：元石开放V5接口文档如何获取？
当前处于业务变革期，受多方因素限制元石开放文档无法平铺展示，短期内麻烦开发者跳转至语雀查看元石接口文档，文档更新后会有更新记录，请关注！
更新记录：2024-7-1首版文档上传

公有云文档附件：《元石开放V5.0接口文档》
私有化文档附件：元石开放V5.0私有化接口文档