API

该教程面向基于IPS Tools软件的API接口做后台业务功能的软件集成商。通过API接口可获得Anchor、Tag设备的UID、坐标、电量、工作状态以及Tag的实时定位等信息，数据格式为JSON，接口协议包括MQTT、UDP、webhook、HTTP等，软件支持部署在Ubuntu、Windows、MacOs等平台。

1.数据格式：JSON

标签定位数据示例：

{
    "data": {
        "mapId": 2, // 定位所在楼层id
        "pos": [
            -3.2616942,
            4.3123593,
            1.1999172
        ], // 定位：x,y,z
        "noiseRadius": 0.085815825, // 定位噪声, 值越大置信度越低。
        "posVar": [
            0.71,
            0.62,
            0.03
        ],// x,y,z方向的定位噪声, 值越大置信度越低。
        "time": 1744625585087, // 定位unix毫秒时间戳.
        "vel": [
            -0.08,
            0.1,
            0
        ], //速度：x,y,z
        "velVar": [
            0.13,
            0.13,
            0.01
        ], //x,y,z方向的速度噪声, 值越大置信度越低。
        "properties": {
        	"tansmit": "xxxxxxxxxxxx"  // 透传数据，base64编码。
    	},
        "rxAnchorSn": "1e00400007503148", // 最强接收信号对应基站UID
        "rxRssi": -47.235565185546875, // 最强接收信号
        "fences": [
            {
                "id": 18,  // 标签所在的电子围栏id
                "name": "Fence-13", // 标签所在的电子围栏名称
                "userData": {} // 用户自定义数据
            }
        ],
        "optPoses": [
            [
                0.71,
                0.62,
                0.03
            ]
        ]  // 增加边界、墙约束后的输出位置
    },
    "deviceName": "T4", // 设备名，在软件内唯一
    "name": "Pos", // 消息类型
    "uid": "ea221ffdb4fbea42"  //设备UID
}

标签呼叫数据示例：

{
    "deviceName": "T4", // 设备名，在软件内唯一
    "name": "Call", // 消息类型
    "uid": "ea221ffdb4fbea42"  //设备UID
}

标签取消呼叫数据示例：

{
    "deviceName": "T4", // 设备名，在软件内唯一
    "name": "CancelCall", // 消息类型
    "uid": "ea221ffdb4fbea42"  //设备UID
}

标签响应用户呼叫数据示例：

{
    "deviceName": "T4", // 设备名，在软件内唯一
    "name": "Ack", // 消息类型
    "uid": "ea221ffdb4fbea42",  //设备UID
    "data": {
    	"reqId": "CallAck"  // 响应的请求id
	}
}

标签响应用户取消呼叫数据示例：

{
    "deviceName": "T4", // 设备名，在软件内唯一
    "name": "Ack", // 消息类型
    "uid": "ea221ffdb4fbea42",  //设备UID
    "data": {
    	"reqId": "CancelCallAck" // 响应的请求id
	}
}

2. 推送数据API配置入口

打开IPS Tool软件，按下图操作进入配置页面

3. 通过MQTT推送数据

address: 协议://用户名:密码@主机名:端口 或者 协议://主机名:端口

不加密协议支持：mqtt或者tcp、ws

加密协议支持：mqtts或者tcps、wss

示例：mqtt://admin:test@192.168.0.15:1883

clientId: 客户端标识，可为空

topic: 主题名

4. 通过UDP推送数据

address: {ip或域名}:{端口}

localAddress: 指定本地IP地址，主要存在多网卡时指定使用选择的网卡

5. 通过webhook推送数据

url格式: http://{ip或域名}:{端口}/{自定义uri}

http method: POST

6. HTTP获取设备状态

URL: GET http://localhost:8080/openapi/v1/devices?deviceType=&online=&query=&page=&pageSize=

Query参数：

参数名	参数类型	参数说明
deviceType	int	根据设备类型搜索，空表示查询所有类型设备，4表示查询Anchor设备，5表示查询Tag设备
online	bool	根据是否在线搜索，空表示查询所有状态，false表示查询离线设备，true表示查询在线设备
query	string	根据设备名前缀搜索或者设备UID后缀搜索
page	int	分页页码，默认为1，1表示第一页，依次类推
pageSize	int	分页每页大小，默认为20，最大100

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "records": [
          {
            "type": 4,  // 设备类型，4表示Anchor设备，5表示Tag设备
            "online": false, // 是否在线
            "onlineTime": 1727323909, //在线离线时间，online为true表示在线时间，online为false表示离线时间
            "uid": "1b00530007503148", // 设备UID
            "product": "A01", // 设备型号
            "coordinate": { // 设备坐标，目前仅Anchor设备有
                "coords": [
                  13.302,  // x坐标
                  12.9,    // y坐标
                  2.9      // z坐标
                ]
             },
             "name": "A1" // 设备名 
           },
           {
             "type": 5, // 设备类型，4表示Anchor设备，5表示Tag设备
             "online": false, // 是否在线
             "onlineTime": 1730860539, //在线离线时间，online为true表示在线时间，online为false表示离线时间
             "uid": "72bc78a7911d836f", // 设备UID
             "power": 50,  // 设备电量百分比，目前仅Tag设备有
             "product": "T02", // 设备型号
             "name": "T5" // 设备名 
           }
    	],
    	"total": 1 // 当前搜索条件下的总数
    }
}

7. HTTP下发透传数据

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/TransmitData

Query参数：

参数名	参数类型	参数说明
uid	string	设备uid

Body 参数：

参数名	参数类型	参数说明
data.data	string	透传数据，base64编码字符串数据
data.codec	string	数据编码格式，utf8表示utf8编码，hex表示hex编码，空或其他表示base64编码

{
    "data":{
        "data":"123",
        "codec":"utf8"
    }
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

8. HTTP下发格式化透传数据

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/FormatTransmitData

Query参数：

参数名	参数类型	参数说明
uid	string	设备uid

Body 参数：

参数名	参数类型	参数说明
data.data	string	透传数据，base64编码字符串数据
data.codec	string	数据编码格式，utf8表示utf8编码，hex表示hex编码，空或其他表示base64编码

{
    "data":{
        "data":"123",
        "codec":"utf8"
    }
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

9. HTTP下发呼叫标签

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/Call

Query参数：

参数名	参数类型	参数说明
uid	string	设备uid

Body 参数：

参数名	参数类型	参数说明
data.duration	int	呼叫持续时间，单位s，最大64s

{
    "data":{
        "duration": 1
    }
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

10. HTTP下发取消呼叫标签

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/CancelCall

Query参数：

参数名	参数类型	参数说明
uid	string	设备uid

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

11. HTTP下发响应标签呼叫

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/Ack

Query参数：

参数名	参数类型	参数说明
uid	string	设备uid

Body 参数：

参数名	参数类型	参数说明
data.reqId	string	值为CallAck

{
    "data":{
        "reqId": "CallAck"
    }
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

12. HTTP查询地图上电子围栏

URL: GET http://localhost:8080/openapi/v1/maps/{mapId}/fences

Path参数：

参数名	参数类型	参数说明
mapId	uint32	电子围栏所在地图id

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "records": [
            {
                "id": 11, // 电子围栏id
                "mapId": 2, // 电子围栏所在地图id
                "name": "测试围栏", // 电子围栏名称
                "enable": true, // 电子围栏是否使能
                "bounds": [
                    [
                        [
                            19.305483719334006,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            14.511200794018805
                        ]
                    ]
                ], // 电子围栏边界（当前不支持洞）
                "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
                "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
                "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效 
                "userData": {} // 用户自定义数据
            }
        ]
    }
}

13. HTTP搜索电子围栏

URL: GET http://localhost:8080/openapi/v1/fences

Query参数：

参数名	参数类型	参数说明
mapId	uint32	电子围栏所在地图id
query	string	根据电子围栏名前缀搜索
page	int	分页页码，默认为1，1表示第一页，依次类推
pageSize	int	分页每页大小，默认为20，最大100

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "records": [
            {
                "id": 11, // 电子围栏id
                "mapId": 2, // 电子围栏所在地图id
                "name": "测试围栏", // 电子围栏名称
                "enable": true, // 电子围栏是否使能
                "bounds": [
                    [
                        [
                            19.305483719334006,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            14.511200794018805
                        ]
                    ]
                ], // 电子围栏边界（当前不支持洞）
                "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
                "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
                "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
                "userData": {} // 用户自定义数据
            }
        ],
        "total": 1 // 当前搜索条件下的总数
    }
}

14. HTTP查询某个电子围栏

URL: GET http://localhost:8080/openapi/v1/fences/\{id\}

Path参数：

参数名	参数类型	参数说明
id	uint32	电子围栏id

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "mapId": 2, // 电子围栏所在地图id
        "name": "测试围栏", // 电子围栏名称
        "enable": true, // 电子围栏是否使能
        "bounds": [
            [
                [
                    19.305483719334006,
                    14.511200794018805
                ],
                [
                    21.019341055303812,
                    14.511200794018805
                ],
                [
                    21.019341055303812,
                    13.554935615509748
                ],
                [
                    19.305483719334006,
                    13.554935615509748
                ],
                [
                    19.305483719334006,
                    14.511200794018805
                ]
            ]
        ], // 电子围栏边界（当前不支持洞）
        "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
        "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
        "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
        "userData": {} // 用户自定义数据
    }
}

15. HTTP添加电子围栏

URL: POST http://localhost:8080/openapi/v1/fences

Body参数：

参数名	参数类型	参数说明
name	string	电子围栏名称
enable	bool	电子围栏是否使能
bounds	[][][][][][][]float64	电子围栏边界（当前不支持洞）
leaveBuffer	float64	当离开电子围栏边界>leaveBuffer时才判定为离开
includes	[]string	电子围栏生效的标签uid，为空表示所有都生效
excludes	[]string	电子围栏不生效的标签uid，为空表示所有都生效
userData	Object	用户自定义数据

{
    "mapId": 2, // 电子围栏所在地图id
    "name": "测试围栏", // 电子围栏名称
    "enable": true, // 电子围栏是否使能
    "bounds": [
        [
            [
                19.305483719334006,
                14.511200794018805
            ],
            [
                21.019341055303812,
                14.511200794018805
            ],
            [
                21.019341055303812,
                13.554935615509748
            ],
            [
                19.305483719334006,
                13.554935615509748
            ],
            [
                19.305483719334006,
                14.511200794018805
            ]
        ]
    ], // 电子围栏边界（当前不支持洞）
    "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
    "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
    "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
    "userData": {} // 用户自定义数据
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

16. HTTP更新电子围栏

URL: PUT http://localhost:8080/openapi/v1/fences/{id}

Path参数：

参数名	参数类型	参数说明
id	uint32	电子围栏id

Body参数：

参数名	参数类型	参数说明
name	string	电子围栏名称
enable	bool	电子围栏是否使能
bounds	[][][][][][][]float64	电子围栏边界（当前不支持洞）
leaveBuffer	float64	当离开电子围栏边界>leaveBuffer时才判定为离开
includes	[]string	电子围栏生效的标签uid，为空表示所有都生效
excludes	[]string	电子围栏不生效的标签uid，为空表示所有都生效
userData	Object	用户自定义数据

{
    "name": "测试围栏", // 电子围栏名称
    "enable": true, // 电子围栏是否使能
    "bounds": [
        [
            [
                19.305483719334006,
                14.511200794018805
            ],
            [
                21.019341055303812,
                14.511200794018805
            ],
            [
                21.019341055303812,
                13.554935615509748
            ],
            [
                19.305483719334006,
                13.554935615509748
            ],
            [
                19.305483719334006,
                14.511200794018805
            ]
        ]
    ], // 电子围栏边界（当前不支持洞）
    "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
    "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
    "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
    "userData": {} // 用户自定义数据
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

17. HTTP删除电子围栏

URL: DELETE http://localhost:8080/openapi/v1/fences/{id}

Path参数：

参数名	参数类型	参数说明
id	uint32	电子围栏id

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}