# 鑫潼ICC平台接口文档

## 接口环境变量

host：222.243.55.92，端口：1443
clientId：xtzdapp
clientSecret：1c7e440a-660c-4a5d-a7b8-82b58d9dca4e
username：XTZD接口
password：Xtzdkj\@20260801
version：1.0.0

## 接口鉴权认证

大华ICC平台采用OAuth2 鉴权认证。
OAuth2是目前最流行的授权机制，是一种安全机制保障的方案。数据的所有者告诉系统，同意授权第三方应用进入系统，获取这些数据。系统从而产生一个短期的进入令牌（Access\_token）和刷新该令牌的凭证（Refresh\_token），用来代替密码，供第三方应用使用。客户端认证模式常用于微服务间交互，该模式Access\_token有效期一般较长,两小时，且没有Refresh\_token，过期可以直接认证获取匿名令牌。
授权模式：密码认证模式，密码模式在客户端基础上，从用户方获取帐号密码，再访问授权服务器认证授权。
![图片 2](assets/image1.jpeg)

客户端从用户方获取帐号密码。2、客户端携带用户信息向认证服务器获取令牌。3、认证服务器确认无误后，向客户端提供访问令牌。4、客户端携带令牌访问资源端。
协议鉴权
![图片 4](assets/image2.png)

鉴权接口的access\_token有效期2h,权限与鉴权用户的组织、部门权限保持一致。
获取公钥：访问地址：https\://{{host}}/evo-apigw/evo-oauth/{{version}}/oauth/public-key。其中{{host}}为接口环境变量的host:端口。{{version}}为接口环境变量的version。

```http
GET /evo-apigw/evo-oauth/{{version}}/oauth/public-key HTTP/1.1
```

RSA加密密码。以下是java RSA加密示例：其中使用接口环境变量的username、password。

```java
import javax.crypto.Cipher;
import java.security.KeyFactory;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.X509EncodedKeySpec;
import java.util.Arrays;

public class RSAUtil {

/**
* 基于原生RSA公钥加密
* @param password 用户密码
* @param publicKey 公钥
* @return
* @throws Exception
*/
public static String encrypt(String password, String publicKey) throws Exception {
//base64编码的公钥
byte[] decoded = java.util.Base64.getDecoder().decode(publicKey);
RSAPublicKey pubKey = (RSAPublicKey) KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(decoded));
//RSA加密
Cipher cipher = Cipher.getInstance("RSA");
cipher.init(Cipher.ENCRYPT_MODE, pubKey);
String outStr;
byte[] inputArray = password.getBytes("UTF-8");
int inputLength = inputArray.length;
// 最大加密字节数，超出最大字节数需要分组加密
int MAX_ENCRYPT_BLOCK = 117;
// 标识
int offSet = 0;
byte[] resultBytes = {};
byte[] cache = {};
while (inputLength - offSet > 0) {
if (inputLength - offSet > MAX_ENCRYPT_BLOCK) {
cache = cipher.doFinal(inputArray, offSet, MAX_ENCRYPT_BLOCK);
offSet += MAX_ENCRYPT_BLOCK;
} else {
cache = cipher.doFinal(inputArray, offSet, inputLength - offSet);
offSet = inputLength;
}
resultBytes = Arrays.copyOf(resultBytes, resultBytes.length + cache.length);
System.arraycopy(cache, 0, resultBytes, resultBytes.length - cache.length, cache.length);
}
outStr = java.util.Base64.getEncoder().encodeToString(resultBytes);
return outStr;
}

}
```

认证：访问凭证client\_id与client\_secret，使用接口环境变量的clientId、clientSecret。access\_token有效期2h。访问地址：https\://{{host}}/evo-apigw/evo-oauth/{{version}}/oauth/extend/token其中使用接口环境变量的username、password、clientId、clientSecret。

```http
POST /evo-apigw/evo-oauth/1.0.0/oauth/extend/token HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: 222.243.55.92:1443

{
"username":"用户账号",
"password":"RSA加密后的密码",
"client_id":"申请的clientId",
"client_secret":"申请的clientSecret",
"public_key":"获取的公钥"
}
```

返回参数示例：

```json
{
"success": true,
"data": {
"access_token": "10000:5cb47cd80-35d9-406d-a8d3-d87dd672d5d3",
"token_type": "bearer",
"refresh_token": "b83403e1-5ea1-41fd-81fc-e86fe5252c93",
"expires_in": 7199,
"scope": "*",
"userId": "10000",
"magicId": "1868a7db-adeb-42de-8064-43b3706ae407"
},
"code": "0",
"errMsg": ""
}
```

请求头设置鉴权码：调用业务接口需在请求头中设置鉴权码：

| **头部参数**      | **解释**                                                                                                         |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| Authorization | 格式：token\_type + 空格 + access\_token, token\_type一般为固定值bearer  例如:bearer 1:bb951116-d963-4528-80e1-91c2e94c3e75 |

## 本次接口说明

### 一、组织全量数据同步接口

前置条件：请求头设置Authorization字段
接口URL：https\://{{host}}/evo-apigw/evo-brm/{{version}}/organization/page
请求Method：GET
数据提交格式：application/json
请求参数：

| **参数名**    | **必选** | **类型** | **说明**               |
| ---------- | ------ | ------ | -------------------- |
| pageNum    | false  | int    | 当前页, 默认1             |
| pageSize   | false  | int    | 每页记录数, 默认10，最大支持1000 |
| orgPreCode | false  | String | 组织父节点                |
| maxRangeId | true   | long   | 同步边界值                |

返回参数：

| **名称**  | **类型**  | **说明**               |
| ------- | ------- | -------------------- |
| success | boolean | 接口返回是否成功             |
| code    | string  | 错误码：0-为无错误，非0-为具体错误码 |
| errMsg  | string  | 错误消息                 |
| data    | PageVO  | 分页数据                 |

PageVO

| **名称**      | **类型**          | **说明** |
| ----------- | --------------- | ------ |
| currentPage | int             | 当前页码   |
| totalPage   | int             | 总页数    |
| pageSize    | int             | 每页记录数  |
| totalRows   | int             | 总数     |
| pageData    | List<OrgInfoVO> | 数据列表   |

OrgInfoVO

| **名称**            | **类型**  | **说明**                   |
| ----------------- | ------- | ------------------------ |
| orgCode           | string  | 组织编码                     |
| orgName           | string  | 组织名称                     |
| orgSn             | string  | 唯一标识码                    |
| orgType           | string  | 组织结构类型，具体参考组织类型          |
| province          | string  | 省                        |
| city              | string  | 市                        |
| county            | string  | 县                        |
| domainId          | Long    | 域ID                      |
| stat              | Integer | 状态                       |
| sort              | Integer | 排序码                      |
| allSort           | string  | 所有组织排序                   |
| service           | string  | 子系统服务编码,默认evo-thirdParty |
| forbidBindUser    | Integer | 禁止绑定用户 ：0-可绑定用户，1-不可绑定用户 |
| forbidBindService | String  | 禁止绑定用户服务                 |

组织类型

| **类型key**     | **类型value** | **备注** |
| ------------- | ----------- | ------ |
| org\_base     | 基础组织        | <br /> |
| org\_country  | 国家          | <br /> |
| org\_province | 省           | <br /> |
| org\_city     | 市           | <br /> |
| org\_county   | 区县          | <br /> |

接口数据字段与customer（客户信息表）对应关系：

| **接口字段名称** | **字段说明** | **客户信息表字段名称**  | **字段说明** |
| ---------- | -------- | -------------- | -------- |
| orgCode    | 组织编码     | iccCode        | ICC客户编码  |
| orgName    | 组织名称     | customer\_name | 客户名称     |
| province   | 省        | province       | 省        |
| city       | 市        | city           | 市        |
| county     | 县        | district       | 区/县      |

**二、消防物联设备分页查询接口**

前置条件：请求头设置Authorization字段
接口URL：https\://{{host}}/evo-apigw/evo-fdbu/{{version}}/device/subsystem/page
请求Method：POST 数据提交格式：application/json
请求参数：

| **参数名**      | **必选** | **类型** | **说明**           |
| :----------- | :----- | :----- | :--------------- |
| pageNum      | false  | int    | 当前页, 默认1         |
| pageSize     | false  | int    | 每页记录数, 默认10，最多50 |
| orgCodes     | false  | array  | 设备所属组织编码集合，最多10  |
| typeCode     | false  | string | 主机类型             |
| keyCondition | false  | string | 设备名称/设备编号/imei   |

**请求参数示例**

```JSON
{
	"pageNum": 1,
	"pageSize": 10,
	"orgCodes": ["001001", "002001"],
	"typeCode": 128,
	"keyCondition": "测试"
}
```

**返回参数**

| **名称**  | **类型**     | **说明**               |
| :------ | :--------- | :------------------- |
| success | boolean    | 接口返回是否成功             |
| code    | string     | 错误码：0-为无错误，非0-为具体错误码 |
| errMsg  | string     | 错误消息                 |
| data    | **PageVO** | 分页数据                 |

**PageVO**

| **名称**     | **类型**                 | **说明** |
| :--------- | :--------------------- | :----- |
| nextPage   | int                    | 当前页码   |
| totalCount | int                    | 总数     |
| pageData   | List<**DeviceInfoVO**> | 数据列表   |

**DeviceInfoVO**

| **名称**           | **类型** | **说明**           |
| :--------------- | :----- | :--------------- |
| id               | string | 唯一主键             |
| imei             | String | 设备唯一标识码,设备的imei号 |
| deviceCode       | String | 设备编码             |
| deviceName       | String | 设备名称             |
| companyId        | String | 公司编号             |
| companyName      | String | 公司名称             |
| manufacturerCode | String | 厂商编码             |
| manufacturerName | String | 厂商名称             |
| typeCode         | String | 主机类型             |
| typeName         | String | 主机类型名称           |
| orgCode          | String | 组织编码             |
| orgName          | String | 组织名称             |
| dcpsId           | string | 接入设备域            |
| softwareVersion  | string | 软件版本号            |
| systemAddress    | int    | 系统地址             |
| address          | string | 安装地址             |
| productModel     | String | 设备型号             |
| isOnline         | string | 在离线状态            |
| description      | string | 描述               |

接口数据字段与electric\_gateway（智能改造设备表）对应关系：

<br />

三、**消防探测器分页查询**

前置条件：请求头设置Authorization字段
接口URL：https\://{{host}}/evo-apigw/evo-fdbu/{{version}}/detector/subsystem/page
请求Method：POST 数据提交格式：application/json
请求参数：

| **参数名**      | **必选** | **类型** | **说明**           |
| :----------- | :----- | :----- | :--------------- |
| pageNum      | false  | int    | 当前页, 默认1         |
| pageSize     | false  | int    | 每页记录数, 默认10，最多50 |
| orgCodes     | false  | array  | 设备所属组织编码集合，最多10  |
| typeCode     | false  | string | 探测器类型            |
| keyCondition | false  | string | 设备名称/设备编号/imei   |

**请求参数示例**

```JSON
{
	"pageNum": 1,
	"pageSize": 10,
	"orgCodes": ["001001", "002001"],
	"typeCode": 128,
	"keyCondition": "测试"
}
```

**返回参数**

| **名称**  | **类型**     | **说明**               |
| :------ | :--------- | :------------------- |
| success | boolean    | 接口返回是否成功             |
| code    | string     | 错误码：0-为无错误，非0-为具体错误码 |
| errMsg  | string     | 错误消息                 |
| data    | **PageVO** | 分页数据                 |

**PageVO**

| **名称**     | **类型**               | **说明** |
| :--------- | :------------------- | :----- |
| nextPage   | int                  | 当前页码   |
| totalCount | int                  | 总数     |
| pageData   | List<**DetectorVO**> | 数据列表   |

**DetectorVO**

| **名称**           | **类型** | **说明**             |
| :--------------- | :----- | :----------------- |
| id               | string | 唯一主键               |
| detectorCode     | string | 探测器编码              |
| detectorName     | string | 探测器名称              |
| imei             | string | 设备唯一标识码,设备的imei号   |
| detectorStatus   | int    | 探测器状态，参考上报状态       |
| orgCode          | String | 组织编码               |
| orgName          | String | 组织名称               |
| companyId        | String | 探测器所属单位编码          |
| companyName      | String | 探测器所属单位名称          |
| parentCode       | string | 父设备编码              |
| parentName       | string | 父设备名称              |
| manufacturerCode | String | 厂商编码               |
| manufacturerName | String | 厂商名称               |
| typeCode         | String | 探测器类型              |
| typeName         | String | 探测器类型名称            |
| fireSystemCode   | String | 消防系统编码             |
| fireSystemName   | String | 消防系统名称             |
| partUnitLoopCode | string | 探测器回路号             |
| channelNo        | string | 探测器通道号             |
| systemAddress    | int    | 系统地址               |
| channelSn        | string | 通道唯一标识码            |
| mapType          | String | 地图类型               |
| produceDate      | string | 生产日期，格式：yyyy-MM-dd |

**上报状态**

| **状态编码** | **状态名称** | **备注** |
| :------- | :------- | :----- |
| 01       | 在线       | <br /> |
| 02       | 离线       | <br /> |

接口数据字段与electric\_**line**（智电改造线路表）对应关系：