HC 物联网系统对接协议_hc物联网第三方云平台对接协议

HC 物联网系统对接协议

说明

代码：https://gitee.com/java110/MicroCommunityThings

官网：http://www.homecommunity.cn/

开发前必读

协议规范设计

第三方调用开放接口时，需使用 https 协议、Json 数据格式、UTF8 编码

注：建议封装统一的 API 请求接口，便于进行 token 容错处理，以及相关日志打
印等

请求参数：默认使用 json 方式（access_token 必须传至http header 中）

通用响应报文格式：

   {
   "code":0,
   "msg":"返回码描述内容",
   "data": {}
   }
1
2
3
4
5

通用响应报文字段说明：

通用错误码说明

授权认证-获取access_token

根据 appId+appSecret 换取 access_token。access_token 是平台全局接口的唯一凭证，调用其他接口均需传 access_token
参数到Http header 中 如 access_token 12312312。

请求方式：GET

请求地址： /extApi/auth/getAccessToken?appId=APPID&appSecret=APPSECRET

注：此处标注大写的单词 APPID 和 APPSECRET，为需要替换的变量，根据实际获取值更新。其它接口也采用相同的标注，不
再说明。

请求参数:

响应参数:

响应示例:

    {
        "code":0,
        "msg":"成功",
        "data":{
            "access_token": "225262e8b548b77f76f018d218291647",
            "expires_in": 7200
            }
    }
1
2
3
4
5
6
7
8

参考代码：

    //@Java110Synchronized 为分布式全局锁 根据 实际替换为自己的全局锁代码
    @Java110Synchronized(value = "hc_get_token")
    public static String get(RestTemplate restTemplate,boolean refreshAccessToken) {
        //先从缓存中获取是否存在access_token
        String token = CommonCache.getValue(IotConstant.HC_TOKEN);
        if (!StringUtil.isEmpty(token) && !refreshAccessToken) {
            return token;
        }
        HttpHeaders headers = new HttpHeaders();
        HttpEntity httpEntity = new HttpEntity(headers);
        String url = IotConstant.getUrl(IotConstant.GET_TOKEN_URL.replace("APP_ID", IotConstant.getAppId()).replace("APP_SECRET", IotConstant.getAppSecret()));
        ResponseEntity<String> tokenRes = restTemplate.exchange(url, HttpMethod.GET, httpEntity, String.class);

        if (tokenRes.getStatusCode() != HttpStatus.OK) {
            throw new IllegalArgumentException("获取token失败" + tokenRes.getBody());
        }
        JSONObject tokenObj = JSONObject.parseObject(tokenRes.getBody());

        if (!tokenObj.containsKey("code") || ResultVo.CODE_OK != tokenObj.getInteger("code")) {
            throw new IllegalArgumentException("获取token失败" + tokenRes.getBody());
        }

        token = tokenObj.getJSONObject("data").getString("access_token");
        int expiresIn = tokenObj.getJSONObject("data").getInteger("expires_in");

        CommonCache.setValue(IotConstant.HC_TOKEN, token, expiresIn - 200);

        return token;
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

1.小区资源操作

1.1 新增小区

请求方式： POST

请求地址：/extApi/community/addCommunity

请求参数：

请求示例：

{
    "name": "HC小区",
    "address": "青海省西宁市",
    "cityCode": "510104",
    "extCommunityId": "702020042194860039",
    "taskId": "102020042194860045"
}
1
2
3
4
5
6
7

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

1.2 修改小区

请求方式： POST

请求地址：/extApi/community/updateCommunity

请求参数：

请求示例：

{
    "name": "HC小区",
    "address": "青海省西宁市",
    "cityCode": "510104",
    "extCommunityId": "702020042194860039",
    "taskId": "102020042194860045"
}
1
2
3
4
5
6
7

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

1.3 删除小区

请求方式： POST

请求地址：/extApi/community/deleteCommunity

请求参数：

请求示例：

{
    "extCommunityId": "702020042194860039",
    "taskId": "102020042194860045"
}
1
2
3
4

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

2.设备资源操作

2.1 新增设备

请求方式： POST

请求地址：/extApi/machine/addMachine

请求参数：

请求示例：

{
    "machineCode": "101010",
    "machineName": "HC门禁",
    "machineTypeCd": "9999",
    "extMachineId": "702020042194860037",
    "extCommunityId": "702020042194860039",
    "hmId": "702020042194860039",
    "taskId": "102020042194860045"
}
1
2
3
4
5
6
7
8
9

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

2.2 修改设备

请求方式： POST

请求地址：/extApi/machine/updateMachine

请求参数：

请求示例：

{
    "machineCode": "101010",
    "machineName": "HC门禁",
    "machineTypeCd": "9999",
    "extMachineId": "702020042194860037",
    "extCommunityId": "702020042194860039",
    "hmId": "702020042194860039",
    "taskId": "102020042194860045"
}
1
2
3
4
5
6
7
8
9

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

2.3 删除设备

请求方式： POST

请求地址：/extApi/machine/deleteMachine

请求参数：

请求示例：

{
    "extMachineId": "702020042194860037",
    "taskId": "102020042194860045"
}
1
2
3
4

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

2.4 远程开门

请求方式： POST

请求地址：/extApi/machine/openDoor

请求参数：

请求示例：

{
    "machineCode": "101010",
    "taskId": "102020042194860045"
}
1
2
3
4

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

2.5 重启设备

请求方式： POST

请求地址：/extApi/machine/restartMachine

请求参数：

请求示例：

{
    "machineCode": "101010",
    "taskId": "102020042194860045"
}
1
2
3
4

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

3.用户资源操作

3.1 添加用户

请求方式： POST

请求地址：/extApi/user/addUser

请求参数：

请求示例：

{
    "userId": "702020042194860037",
    "faceBase64": "base64",
    "startTime": "2020-12-01 00:00:00",
    "endTime": "2020-12-31 00:00:00",
    "name": "张三",
    "idNumber": "63216111111111111",
    "personType": "2002",
    "machineCode": "101010",
    "taskId": "102020042194860045"
}
1
2
3
4
5
6
7
8
9
10
11

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

3.2 编辑用户

请求方式： POST

请求地址：/extApi/user/updateUser

请求参数：

请求示例：

{
    "userId": "702020042194860037",
    "faceBase64": "base64",
    "startTime": "2020-12-01 00:00:00",
    "endTime": "2020-12-31 00:00:00",
    "name": "张三",
    "idNumber": "63216111111111111",
    "machineCode": "101010",
    "taskId": "102020042194860045"
}
1
2
3
4
5
6
7
8
9
10

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

3.3 删除用户

请求方式： POST

请求地址：/extApi/user/deleteUser

请求参数：

请求示例：

{
    "userId": "702020042194860037",
    "machineCode": "101010",
    "taskId": "102020042194860045"
}
1
2
3
4
5

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

3.4 清空用户

请求方式： POST

请求地址：/extApi/user/clearUser

请求参数：

请求示例：

{
    "machineCode": "101010",
    "taskId": "102020042194860045"
}
1
2
3
4

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":{
       "taskId": "102020042194860045"
    }
}
1
2
3
4
5
6
7

4. 开门记录资源

4.1 开门上报

说明：HC物联网系统将开门记录上报第三方平台，需要物联网平台配置

请求方式： POST

请求地址：第三方平台提供

请求参数：

请求示例：

{
    "userId": "702020042194860037",
    "userName": "张三",
    "machineCode": "101010",
    "openTypeCd": "1000",
    "similar": "100",
    "photo": "base64,xxx",
    "dateTime": "2020-12-27 00:00:00",
    "extCommunityId": "702020042194860039",
    "recordTypeCd": "8888"
}
1
2
3
4
5
6
7
8
9
10
11

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":""
}
1
2
3
4
5

4.2 指令上报执行结果

说明：当和物联网系统异步交互时 或者物联网系统采用mqtt 协议时，执行结果 需要异步方式上报，需要物联网系统配置地址

请求方式： POST

请求地址：第三方平台提供

请求参数：

请求示例：

{
    "taskId": "702020042194860037",
    "code": 0,
    "msg": "成功"
}
1
2
3
4
5

返回示例：

{
    "code":0,
    "msg":"成功",
    "data":""
}
1
2
3
4
5