# TMS三方设备GPS接口文档

<!-- TOC -->

- [TMS三方设备GPS接口文档](#tms%E4%B8%89%E6%96%B9%E8%AE%BE%E5%A4%87gps%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3)
    - [接口简介](#%E6%8E%A5%E5%8F%A3%E7%AE%80%E4%BB%8B)
    - [轨迹数据对接流程](#%E8%BD%A8%E8%BF%B9%E6%95%B0%E6%8D%AE%E5%AF%B9%E6%8E%A5%E6%B5%81%E7%A8%8B)
    - [接口详细信息](#%E6%8E%A5%E5%8F%A3%E8%AF%A6%E7%BB%86%E4%BF%A1%E6%81%AF)
        - [添加设备接口](#%E6%B7%BB%E5%8A%A0%E8%AE%BE%E5%A4%87%E6%8E%A5%E5%8F%A3)
        - [上传设备状态位置数据接口](#%E4%B8%8A%E4%BC%A0%E8%AE%BE%E5%A4%87%E7%8A%B6%E6%80%81%E4%BD%8D%E7%BD%AE%E6%95%B0%E6%8D%AE%E6%8E%A5%E5%8F%A3)
        - [移除设备接口](#%E7%A7%BB%E9%99%A4%E8%AE%BE%E5%A4%87%E6%8E%A5%E5%8F%A3)
        - [通过车牌号获取绑定设备的轨迹数据](#%E9%80%9A%E8%BF%87%E8%BD%A6%E7%89%8C%E5%8F%B7%E8%8E%B7%E5%8F%96%E7%BB%91%E5%AE%9A%E8%AE%BE%E5%A4%87%E7%9A%84%E8%BD%A8%E8%BF%B9%E6%95%B0%E6%8D%AE)
        - [获取设备号的轨迹数据](#%E8%8E%B7%E5%8F%96%E8%AE%BE%E5%A4%87%E5%8F%B7%E7%9A%84%E8%BD%A8%E8%BF%B9%E6%95%B0%E6%8D%AE)
        - [获取受理单轨迹数据](#%e8%8e%b7%e5%8f%96%e5%8f%97%e7%90%86%e5%8d%95%e8%bd%a8%e8%bf%b9%e6%95%b0%e6%8d%ae)
    - [其他问题](#%E5%85%B6%E4%BB%96%E9%97%AE%E9%A2%98)

<!-- /TOC -->

## 接口简介

用于对接三方设备的GPS数据，也可以获取轨迹数据。传参方式如无特殊说明均为application/json格式。不支持将参数写进url中传递。小黑卡用户不需要使用此接口上传轨迹数据。

## 轨迹数据对接流程

**1.请求方式及获取token**

此部分请参考[3TMS/CTMS第三方接口文档](http://gogs.kuaihuoyun.com:3000/gongmingwei/ctms-sdk-demo)中的：[接口简介](http://gogs.kuaihuoyun.com:3000/gongmingwei/ctms-sdk-demo#接口简介请仔细阅读)、 [接口说明](http://gogs.kuaihuoyun.com:3000/gongmingwei/ctms-sdk-demo#接口说明) 以及 [获取登陆凭证接口](http://gogs.kuaihuoyun.com:3000/gongmingwei/ctms-sdk-demo#获取登陆凭证接口) 部分。**请务必仔细阅读此部分以后再做对接！**

**2.添加设备**

在上传设备信息之前，首先需要将设备添加进系统中，注意，此处的添加不是在TMS系统中添加，而是调用添加设备接口进行添加，这是两个不同的数据表，如果没有添加会提示设备不存在。设备只需添加一次即可。

**3.上传设备状态及位置**

添加完设备以后可以调用上传设备状态位置数据接口进行数据上传。

**4.删除设备**

三方设备的上限是500台，超过将无法添加新的设备，必须要删除部分设备才能继续添加。



## 接口详细信息

### 添加设备接口

**1.简要描述** ：用于添加设备，设备上限为每个账号最多500台。

**2.请求URL** ：`/gps/add_device`

**3.请求方式** ：POST

**4.调用频率限制** ：同一设备号一小时内只能添加一次

**5.请求参数** ：

| **参数名** | **必选** | **类型** | **说明** |
| :---: | :---: | :---: | --- |
| `deviceNumber` | `是` | `String` | `设备号` |

**6.返回示例** ：

- 调用成功示例：

```java
{
    "code": 200,
    "message": null,
    "data": true
}
```

- 调用失败示例：

```java
{
    "message": "操作太频繁",
    "status": 500
}

{
    "message": "设备浙A34421已存在",
    "status": 500
}
```

### 上传设备状态位置数据接口

**1.简要描述** ：上传设备状态位置数据。

**2.请求URL** ：`/gps/push_gps_data`

**3.请求方式** ：POST

**4.调用频率限制** ：5000次/小时

**5.请求参数** ：

| **参数名** | **必选** | **类型** | **说明** |
| :---: | :---: | :---: | --- |
| `deviceNumber` | `是` | `String` | `设备号` |
| `locateTime` | `是` | `Integer` | `轨迹上报时间，时间戳（单位：秒）` |
| `longitude` | `是` | `Double` | `经度` |
| `latitude` | `是` | `Double` | `纬度` |
| `locateType` | `是` | `Integer` | `轨迹上报类型必填：(0：未知，1：GPS，2：基站定位，4：北斗定位，5：GPS 和北斗定位)` |
| `runStatus` | `是` | `Integer` | `设备运行状态必填（1:行驶，2:停止，3:离线）` |
| `addr` | `是` | `String` | `设备具体定位地址` |
| `province` | `是` | `String` | `定位省份` |
| `city` | `是` | `String` | `定位城市` |
| `roadName` | `是` | `String` | `定位具体街道` |
| `powerRate` | `否` | `Integer` | `设备电量（单位：%）` |
| `humidity` | `否` | `Double` | `设备湿度（单位：度）` |
| `temperature` | `否` | `Double` | `设备温度（单位：度）` |
| `speed` | `否` | `Double` | `设备速度（单位：km／h）` |
| `direction` | `否` | `Double` | `设备运动方向（单位：角度）` |
| `abnormalProfile` | `否` | `String` | `异常点类型：简述` |
| `abnormalInfo` | `否` | `String` | `异常点内容：详细描述` |
| `note1-12` | `否` | `String` | `自定义备注，共12个，用于额外的参数` |

**6.返回示例** ：

- 调用成功示例：

```java
{
    "code": 200,
    "message": null,
    "data": {
        "message": "成功",
        "success": true
    }
}
```

- 调用失败示例：

```java
{
    "code": 200,
    "message": null,
    "data": {
        "message": "设备经纬度不能为空且必须大于0",
        "success": false
    }
}
```


### 移除设备接口

**1.简要描述** ：用于移除设备

**2.请求URL** ：`/gps/remove_device`

**3.请求方式** ：POST

**4.请求参数** ：

| **参数名** | **必选** | **类型** | **说明** |
| :---: | :---: | :---: | --- |
| `deviceNumber` | `是` | `String` | `设备号` |

**5.返回示例** ：

- 调用成功示例：

```java
{
    "code": 200,
    "message": null,
    "data": true
}
```

- 调用失败示例：

```java
{
    "code": 200,
    "message": null,
    "data": false
}
```

### 通过车牌号获取绑定设备的轨迹数据

**1.简要描述** ：通过车牌号获取绑定设备的轨迹数据

**2.请求URL** ：`/gps/get_gps_data`

**3.请求方式** ：POST

**4.调用频率限制** ：每秒最多5次，同时一小时最大请求量为10000次

**5.请求参数** ：

| **参数名** | **必选** | **类型** | **说明** |
| :---: | :---: | :---: | --- |
| `carNumber` | `是` | `String` | `车牌号，必填，多个车牌用英文','隔开，最多50个，查询多个设备时只返回最近的定位点` |
| `startTime` | `否` | `Integer` | `开始时间，如果不指定结束时间则查询开始时间到当前时间的数据` |
| `endTime` | `否` | `Integer` | `结束时间，如果传了结束时间必须传开始时间` |

**注：如果不传时间则只查询最近的一个轨迹点，查询时间范围不能超过1小时**

**6.返回示例** ：

- 调用成功示例：

```java
{
    "code": 200,
    "message": null,
    "data": {
        "苏B285942": //传参时的车牌号
        [
            {
                "device": "浙A34421", //车牌号绑定的设备号
                "gpsTime": 1547793092, //定位时间
                "lng": 120.114997, //精度
                "lat": 30.248416, //纬度
                "province": "浙江", //省份
                "city": "杭州", //城市名
                "location": "地址地址地址地址",  //定位地址
                "roadName": "地址地址地址地址", //街道名
                "locateType": 1, //轨迹上报类型必填：(0：未知，1：GPS，2：基站定位，4：北斗定位，5：GPS 和北斗定位)
                "speed": 0, //速度
                "direction": null, //方向
                "address": {
                    "province": "浙江", //省
                    "city": "杭州", //市
                    "district": "地址地址地址地址", //区
                    "detail": "地址地址地址地址" //详细地址
                }, 
                "runStatus": 1,  //设备运行状态必填（1:行驶，2:停止，3:离线，9:未激活）
                "created": 1547793212, //轨迹信息创建时间
            },
            {
                .........
            }
        ],
        "浙A98727": [.....]
    }
}
```

- 调用失败示例：

```java
{
    "message": "查询时间范围不得大于1小时",
    "status": 500
}

{
    "message": "车牌号XXXX未绑定设备",
    "status": 500
}
```

### 获取设备号的轨迹数据

**1.简要描述** ：获取设备号的轨迹数据

**2.请求URL** ：`/gps/get_gps_data_by_device`

**3.请求方式** ：POST

**4.调用频率限制** ：每秒最多5次，同时一小时最大请求量为10000次

**5.请求参数** ：

| **参数名** | **必选** | **类型** | **说明** |
| :---: | :---: | :---: | --- |
| `device` | `是` | `String` | `设备号，必填，多个设备用英文','隔开，最多100个` |
| `startTime` | `否` | `Integer` | `开始时间，如果不指定结束时间则查询开始时间到当前时间的数据` |
| `endTime` | `否` | `Integer` | `结束时间，如果传了结束时间必须传开始时间` |

**注：如果不传时间则只查询最近的一个轨迹点，查询时间范围不能超过1小时**

**6.返回示例** ：

- 调用成功示例：

```java
{
    "code": 200,
    "message": null,
    "data": {
        "867272034426851": //传参时的设备号
        [
            {
                "device": "867272034426851",//设备号
                "gpsTime": 1561081870, //定位时间
                "lng": 120.1242792, //精度
                "lat": 30.2776902, //纬度
                "province": "浙江省", //省份
                "city": "杭州市", //城市名
                "location": "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)", //定位地址
                "roadName": "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)", //街道名
                "powerRate": 72, //电量
                "humidity": null, //湿度
                "temperature": null, //温度
                "locateType": 2, //轨迹上报类型必填：(0：未知，1：GPS，2：基站定位，4：北斗定位，5：GPS 和北斗定位)
                "speed": 0, //速度
                "direction": 0, //方向
                "address": {
                    "province": "浙江省", //省
                    "city": "杭州市", //市
                    "district": "西湖区", //区
                    "detail": "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)" //详细地址
                },
                "runStatus": 1, //设备运行状态必填（1:行驶，2:停止，3:离线）
                "created": 1561081873 //轨迹信息创建时间
            },
            {
                ......
            }
        ],
        "867212233372371": [.......],
    }
}
```

- 调用失败示例：

```java
{
    "message": "查询时间范围不得大于1小时",
    "status": 500
}

{
    "message": "设备号不能为空",
    "status": 500
}
```

### 获取受理单轨迹数据

**1.简要描述** 获取受理单轨迹数据

**2.请求URL** ：`/gps/get_customer_order_track_points`

**3.请求方式** ：POST

**4.调用频率限制** ：每分钟最多调用100次

**5.请求参数** ：

| **参数名** | **必选** | **类型** | **说明** |
| :---: | :---: | :---: | --- |
| `customerOrderNumber` | `是` | `String` | `受理单号` |
| `fields` | `否` | `String` | `需要返回的数据的字段名，中间用','隔开，可选：consigner(发货人),consignee(收货人),cargo(货物),trackPoints(轨迹),currentGps(当前位置),mileage(总里程),leftMileage(剩余里程),progress(进度),estimatedArriveTime(预计到达时间)` |
| `devices` | `否` | `String` | `设备号，受理单可能绑定过多个设备，不传则返回所有` |


**6.返回示例** ：

- 调用成功示例：

```java
{
	"code": 200,
	"message": null,
	"data": {
		"consigner": {
			"name": "未填",
			"phone": "15268183002",
			"address": {
				"province": "广东省",
				"cityCode": null,
				"city": "江门",
				"district": "鹤山市",
				"name": "橡套成品仓库",
				"address": "橡套成品仓库",
				"streetNumber": null,
				"lng": 119.848037,
				"lat": 30.253302
			}
		},
		"consignee": {
			"name": "郝伟",
			"phone": "18601343360",
			"address": {
				"province": "北京市",
				"cityCode": null,
				"city": "北京",
				"district": "昌平区",
				"name": "北京市辖区昌平区(南口镇南雁路31号三一产业园重能1号厂房D1门)",
				"address": "北京市辖区昌平区(南口镇南雁路31号三一产业园重能1号厂房D1门)",
				"streetNumber": null,
				"lng": 116.085072,
				"lat": 40.208024
			}
		},
		"currentGps": {
			"device": "867282036402564",
			"gpsTime": 1744794151,
			"lng": 120.0632848,
			"lat": 30.3474954,
			"province": null,
			"city": null,
			"location": "浙江省 杭州市 西湖区 金庄路 靠近绿都·云和湖",
			"roadName": "浙江省 杭州市 西湖区 金庄路 靠近绿都·云和湖",
			"powerRate": 100,
			"chargerState": null,
			"humidity": null,
			"temperature": null,
			"locateType": 2,
			"speed": 0,
			"direction": 0,
			"address": {
				"province": "浙江省",
				"city": "杭州市",
				"district": "西湖区",
				"detail": "浙江省 杭州市 西湖区 金庄路 靠近绿都·云和湖"
			},
			"accStatus": null,
			"runStatus": 1,
			"created": 1744794154,
			"updated": 0
		},
		"progress": 0.02,
		"cargo": null,
		"trackPoints": [
			{
				"pointType": 2,
				"lng": 119.8582476,
				"lat": 30.2528982,
				"pointCreateTime": 1744792012,
				"pointEndTime": null,
				"detail": null
			},
			{
				"pointType": 4,
				"lng": 119.8582476,
				"lat": 30.2528982,
				"pointCreateTime": 1744792136,
				"pointEndTime": null,
				"detail": {
					"deltaTimeStr": "",
					"address": "浙江省 杭州市 临安区 鹤亭街 靠近浙江万马高分子材料集团有限公司"
				}
			},
			{
				"pointType": 13,
				"lng": 120.0632848,
				"lat": 30.3474954,
				"pointCreateTime": 1744794151,
				"pointEndTime": null,
				"detail": {
					"address": "浙江省 杭州市 西湖区 金庄路 靠近绿都·云和湖",
					"powerRateStr": "100%"
				}
			}
		],
		"mileage": 28
	}
}
```

- 调用失败示例：

```java
```

## 其他问题

**1.如何在系统中查看上传的轨迹**

进入`TMS系统-->车队管理-->智能管车`，点击列表，在底部进行添加设备
![智能管车](img/img_device.png)

其中，车牌号需要先添加进`车队管理-->车辆信息管理`中，否则添加的时候会提示车辆不存在，设备ID对应你调用接口时传递的设备号，添加完成之后就完成了车辆与设备的绑定关系。车牌号可以与设备ID相同。
![新增设备](img/img_add_device.png)

添加完成以后，在列表中点击车牌号则可以查看设备的最后一个定位点，点击设备号可以查看设备的轨迹信息。其余信息在操作的小齿轮中进行查看。