停车场边缘网关接入API

更新时间：2020-03-09 16:27:40

停车场边缘解决方案使用手册>>

1、名词

• 白名单车辆：无需缴费，可直接通行的车辆。

• 黑名单车辆：禁止进入停车场的车辆。

• 锁定车辆：如果车主需要将车停放在停车场一段时间，为了安全可以锁定自己在停车场中的车辆。车辆被锁定后，禁止出停车场。

• 普通车辆：有月卡或者购买了车位，没有收费过程。

• 临时车辆：进出车场受管控，肯定有订单。

2、规约信息

2.1 边缘和本地停车系统建立连接

• 通信协议基于HTTP，建立双向通道(即先由IoT边缘网关发起连接，成功后再由本地系统/设备发起连接到边缘服务器， 只有双向通道都建立成功后，才能进行业务通信)。

• 访问格式：http://:<相对url>，例如http://127.0.0.1:12345/connect。

• 时间字段类型：string-utc，单位：无明确说明则为毫秒， 如："1502175700000"。

• 文件传输时，路径、文件名一律为英文。

• edge 端的车行连接服务端口：10010

• 传输的图片的格式要求：png, jpg, jpeg, JPG

2.2 订单创建

• 不需要创建订单的情形：不需要收费的情况无需创建订单，具体例子如下：

  • 白名单车辆通行。
  • 普通车办理了月卡或者购买了车位，不需要进出车场时每次都缴费。
  • 车场免费期：有些车场中，比如停车时间不到30分钟可免费，对于这种情况，车辆进出不需要创建订单。

• 创建订单的两种方式

  • 调用云端创建订单接口，用户通过APP扫码缴费触发
    • 用户在出车场前在场内提前缴费
    • 用户到达闸机口扫码缴费
  • 本地停车系统创建订单，并上报云端。用户到达闸机口缴现金，车场中本地停车系统生成订单，停车系统通过停车区域上报订单事件，将订单信息同步到云端，无需调用云端创建订单接口。

2.3 停车场无停车区域的情况

部分厂商的停车场中，业务相关的操作绑定在停车场上而非停车区域，例如车辆黑白名单修改，停车场下并不做停车区域的进一步划分。

边缘网关由于要支持多种停车场场景，因此API设计上包含了停车区域相关的操作。不划分区域的停车场可以将停车场看做默认的停车区域。只需要在对应停车区域相关的API参数中使用lotId代替areaId即可。

3、接口说明

3.1 连接

• 相对url: /connect

• method: POST

• Content-Type：application/json

• 描述：由边缘网关主动发起， 等连接成功后，再由停车管理服务系统向边缘网关建立连接，只有双向连接建立成功后，边缘端和本地停车管理系统才算成功建立了连接。

• 调用发起方：

  • 边缘网关
  • 停车系统

• 参数：

• 返回值：

示例：
请求：

{
    "sn": "1234567890",
    "time": "123456789",
    "ip": "192.168.1.110",
    "mac": "11:22:33:44:55:66",
    "keepalive": 10,
    "signMethod": "md5",
    "sign": "sdfdgdsghgfdhfghgfhjdfj"
}

连接成功响应：

{
    "code": 0,
    "message": "success",
    "data": {
          "token": "234353455456"
    }
}

参数无效响应（如IP地址格式错误等情况，message根据具体错误有所不同）：

{
    "code": 2,
    "message": "......"
}

签名验证错误响应：

{
    "code": 3,
    "message": "Signature is invalid"
}

3.2 停车场-车位上报

• 相对url: /report/parkingLot/parkingSpaceNum

• method: POST

• Content-Type：application/json

• 描述：上报停车场车位总量，由停车管理服务系统发起。和边缘网关成功建立连接后，主动上报该事件给边缘网关。

• 调用发起方：停车系统

• 参数：

• 返回值：

示例
请求：

{
    "token": "123456789",
    "lotId": "车场Id",
    "totalNum": 100,
    "remainNum": 50
}

响应：

{
    "code": 0,
    "message": ""
}

3.3 查询停车区域列表

• 相对url: /query/parkingLot/areaList

• method: GET

• 描述：查询所有停车区域列表

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求：

token="123456789"
lotId="车场ID"
type=0

响应：

{
    "code": 0,
    "message": "",
    "data": {
        "areaList": [
            {"areaId": "area_id_1", "areaName": "xxx", "totalNum": 100, "remainNum": 50},
            {"areaId": "area_id_2", "areaName": "xxx", "totalNum": 100, "remainNum": 50}
            ...
        ]
    }
}

3.4 查询道闸列表

• 相对url: /query/parkingLot/barrierGateList

• method: GET

• 描述：查询所有道闸列表

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求：

token="123456789"
lotId="车场ID"

响应：

{
    "code": 0,
    "message": ""，
    "data": {
        "barrierGateList": [
            {"areaId": "mmm", "barrierGateId": "xxx", "barrierGateName": "yyy", "direction": 0/1}, // 0表示进库，1表示出库
            {"areaId": "mmm", "barrierGateId": "xxx", "barrierGateName": "yyy", "direction": 0/1},
            {"areaId": "mmm", "barrierGateId": "xxx", "barrierGateName": "yyy", "direction": 0/1},
            ...
        ]
    }
}

3.5 查询车辆信息

• 相对url: /query/vehicleInfo

• method: GET

• 描述：查询车辆信息

• 调用发起方：边缘网关

• 参数：

• 返回值

示例
请求：

token="1234567890"
lotId="车场ID"
numberPlate="车牌号"

响应：

{
    "code": 0,
    "message": "",
    "data": {
        "userId": "用户ID",
           "userName": "用户名",
        "phoneNumber": "手机号",
        "numberPlate": "浙A5566",
        "lockStartTime": "锁车起始时间",
        "lockEndTime": "锁车截止时间",
        "areaId": "停车区域ID",
        "spaceId": "停车位ID"，
        "permission":[
            {"barrierGateId": "barrierGateId_1", "effectiveDate": "起始时间", "expiryDate": "截止时间"},
            {"barrierGateId": "barrierGateId_2", "effectiveDate": "起始时间", "expiryDate": "截止时间"},
            {"barrierGateId": "barrierGateId_3", "effectiveDate": "起始时间", "expiryDate": "截止时间"}
        ]
       }
}

3.6 查询场内车辆列表

• 相对url: /query/vehicleList

• method: GET

• 描述： 获取车辆列表数据。

• 调用发起方：边缘网关

• 参数：

• 返回值

示例
请求：

token="123456789"
lotId="车场ID"

响应：

{
    "code": 0,
    "message": "success",
    "data": {
           "numberPlateList": [
             "浙A5566"，
             "浙A5567"，
             "浙A5568"，
             ...
         ]
    }
}

3.7 同步车辆信息

• 相对url: /sync/vehicleInfo

• method: POST

• Content-Type：application/json

• 描述：新增\修改\删除车辆信息。

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求:

{
   "token": "1234567890",
   "lotId": "停车场ID",
   "changeType": 0,
   "userId": "用户ID",
   "userName": "用户名",
   "numberPlate": "浙A5566",
   "phoneNumber": "手机号",
   "lockStartTime": "锁车起始时间",
   "lockEndTime": "锁车截止时间",
   "permission":[
      {"barrierGateId": "barrierGateId_1", "effectiveDate": "起始时间", "expiryDate": "截止时间"},
      {"barrierGateId": "barrierGateId_1", "effectiveDate": "起始时间", "expiryDate": "截止时间"},
      {"barrierGateId": "barrierGateId_1", "effectiveDate": "起始时间", "expiryDate": "截止时间"},
      ...
   ]
}

响应

{
    "code": 0,
    "message": ""
}

3.8 校正车牌

• 相对url: /correct/numberPlate

• method: POST

• Content-Type：application/json

• 描述： 校正车牌。

• 调用发起方：边缘网关

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "lotId": "asdfghjkl",
    "numberPlate": "浙A5566",
    "recordId": "xyz123"
}

响应：

{
    "code": 0,
    "message": ""
}

3.9 上报变更的车辆信息

• 相对url: /change/vehicleInfo

• method: POST

• Content-Type：application/json

• 描述： 本地停车系统上报车辆信息。与从云端同步车辆信息不同，本体上报车辆信息不需要提供手机号字段，手机号信息从云端获取。本地停车系统如果不提供用户信息变更功能，则无需实现该接口。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "lotId": "停车场ID"，
    "changeType": 0,
    "userId": "用户ID",
    "userName": "用户名",
    "numberPlate": "浙A5566",
    "phoneNumber": "手机号",
    "lockStartTime": "锁车起始时间",
    "lockEndTime": "锁车截止时间",
    "permission":[
        {"barrierGateId": "barrierGateId_1", "effectiveDate": "起始时间", "expiryDate": "截止时间"},
        {"barrierGateId": "barrierGateId_2", "effectiveDate": "起始时间", "expiryDate": "截止时间"},
        {"barrierGateId": "barrierGateId_3", "effectiveDate": "起始时间", "expiryDate": "截止时间"}
        ...
    ]
}

响应：

{
    "code": 0,
    "message": ""
}

3.10 上报停车场中停车区域的车位数量

• 相对url: /report/parkingLot/parkingAreaList/parkingSpaceNum

• method: POST

• Content-Type：application/json

• 描述：上报所有停车区中每个区域的车位总量和余量。

• 调用发起方：停车系统

• 参数：

• 返回值：

示例
请求：

{
    "token": "123456789",
    "lotId": "停车场id",
    "areaList": [
        {"areaId": "area_id_1", "totalNum": 100，"remainNum": 50},
        {"areaId": "area_id_2", "totalNum": 70，"remainNum": 20},
        ...
    ]
}

响应：

{
    "code": 0,
    "message": ""
}

3.11 上报停车场中停车区域的静态信息

• 相对url: /report/parkingLot/parkingAreaList/staticInfo

• method: POST

• Content-Type：application/json

• 描述：上报静态信息。

• 调用发起方：停车系统

• 参数：

• 返回值：

示例
请求：

{
    "token": "123456789",
    "lotId": "停车场Id"
    "areaList": [
        {"areaId": "area_id_1", "areaName": "name1"},
        {"areaId": "area_id_2", "areaName": "name2"},
        ...
    ]
}

响应：

{
    "code": 0,
    "message": ""
}

3.12 查询停车区域的车位列表

• 相对url: /query/parkingArea/parkingSpaceList

• method: GET

• 描述：查询指定区域中的所有车位。

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求：

token="123456789"
areaId="qwertyuiop"

响应：

{
    "code": 0,
    "message": "",
    "data": {
        "parkingSpaceList": [
            "parkingSpaceId_1",
            "parkingSpaceId_2",
            ...
        ]
    }
}

3.13 查询停车区域的上下级

• 相对url: /query/parkingArea/parentAndChildren

• method: GET

• 描述：查询指定停车区域的父区域和子区域列表。

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求：

token="123456789"
areaId="qwertyuiop"

响应：

{
    "code": 0,
    "message": "",
    "data": {
        "parentAreaId": "父级区域",
        "childrenList": [
            "areaid",
            "areaid",
            ...
        ]
    }
}

3.14 停车区域-车辆黑名单增\删

• 相对url: /adddel/parkingArea/VehicleBlacklist

• method: POST

• Content-Type：application/json

• 描述：在指定的停车区域中将给定车辆号牌增加到黑名单或从黑名单删除。

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求：

{
    "token": "123456789",
    "areaId": "qwertyuiop",
    "mode": 0,
    "numberPlate": "浙A5566"
}

响应：

{
    "code": 0,
    "message": ""
}

3.15 停车区域-查询车辆黑名单

• 相对url: /query/parkingArea/VehicleBlacklist

• method: GET

• 描述：查询指定停车区域中的黑名单车牌列表。

• 调用发起方：边缘网关

• 参数

• 返回值：

示例
请求：

token="123456789"
areaId="qwertyuiop"

响应：

{
    "code": 0,
    "message": "",
    "data": {
        "numberPlateList": [
            "浙A5566",
            "浙A5567",
            "浙A5568",
            ...
        ]
    }   
}

3.16 停车区域-车辆白名单增\删

• 相对url: /adddel/parkingArea/VehicleWhitelist

• method: POST

• Content-Type：application/json

• 描述：在指定的停车区域中将给定车辆号牌增加到白名单或从白名单删除。

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求：

{
    "token": "123456789",
    "areaId": "qwertyuiop",
    "mode": 0,
    "numberPlate": "浙A5566"
}

响应：

{
    "code": 0,
    "message": ""
}

3.17 停车区域-查询车辆白名单

• 相对url: /query/parkingArea/VehicleWhitelist

• method: GET

• 描述：查询指定区域中的白名单车牌列表。

• 调用发起方：边缘网关

• 参数：

• 返回值：

示例
请求：

token="123456789"
areaId="qwertyuiop"

响应：

{
    "code": 0,
    "message": "",
    "data": {
        "numberPlateList": [
            "浙A5566",
            "浙A5567",
            "浙A5568",
            ...
        ]
    }
}

3.18 停车区域-上报通行订单

• 相对url: /report/parkingArea/passOrder

• method: POST

• Content-Type：multipart/form-data

• 描述： 上报通行订单事件。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：(ps: 请求文本中省略了图片信息)

{
    "token": "1234567890",
    "areaId": "停车区域ID",
    "numberPlate": "浙A5566",
    "inBarrierGateId":"入场道闸ID",
    "inTime": "入场时间",
    "outBarrierGateId": "出场道闸ID",
    "outTime": "出场时间",
    "expenseAmount": "支付金额",
    "orderNumber": "订单号",
    "orderStatus": 0
}

响应：

{
   "code": 0,
   "message": ""
}

3.19 支付确认

• 相对url: /confirm/passOrder

• method: POST

• Content-Type：application/json

• 描述：“支付订单”的确认信息。

• 调用发起方：边缘网关

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "areaId": "asdfghjkl",
    "orderNumber": "asdfghjk",
    "payResult": 0
}

响应：

{
    "code": 0,
    "message": ""
}

3.20 创建订单

• 相对url: /new/passOrder

• method: POST

• Content-Type：application/json

• 描述: 边缘网关接收到云端的创建订单请求，下发到本地停车系统。

• 调用发起方：边缘网关

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "areaId": "停车区域ID",
    "numberPlate": "浙A5566",
    "inBarrierGateId":"入场道闸ID",
    "inTime": "入场时间",
    "outBarrierGateId": "出场道闸ID",
    "outTime": "出场时间",
    "orderStatus": 0
}

响应：

{
    "code": 0,
    "message": ""
}

3.21 停车区域-上报黑名单变更

• 相对url: /report/parkingArea/VehicleBlacklist

• method: POST

• Content-Type：application/json

• 描述： 停车区域的黑名单中有车牌增加或者删除时上报事件。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "areaId": "停车区域ID",
    "mode":0,
    "numberPlate": "浙A5566"
}

响应：

{
    "code": 0,
    "message": ""
}

3.22 停车区域-上报白名单变更

• 相对url: /report/parkingArea/VehicleWhitelist

• method: POST

• Content-Type：application/json

• 描述： 停车区域的白名单中有车牌增加或者删除时上报事件。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "areaId": "停车区域ID",
    "mode":0,
    "numberPlate": "浙A5566"
}

响应：

{
    "code": 0,
    "message": ""
}

3.23 道闸-上报运行状态

• 相对url: /report/barrierGate/runState

• method: POST

• Content-Type：application/json

• 描述： 上报道闸状态。Ps: http 连接成功后，Edge端默认所有道闸是运行正常。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "barrierGateId": "zxcvbnm",
    "state": 0
}

响应：

{
    "code": 0,
    "message": ""
}

3.24 道闸-上报开关状态

• 相对url: /report/barrierGate/switchState

• method: POST

• Content-Type：application/json

• 描述： 上报道闸状态。Ps: http 连接成功后，边缘网关默认所有道闸都是关闭的。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：

{
    "token": "1234567890",
    "barrierGateId": "zxcvbnm",
    "state": 0
}

响应：

{
    "code": 0,
    "message": ""
}

3.25 道闸-远程开关闸

• 相对url: /manager/barrierGate/remoteOnOff

• method: POST

• Content-Type：application/json

• 描述： 设置道闸状态。

• 调用发起方：边缘网关

• 参数

• 返回值

示例
请求：

{
    "token": "1234567890",
    "barrierGateId": "zxcvbnm",
    "onOff": 0
}

响应：

{
    "code": 0,
    "message": ""
}

3.26 道闸-上报通行事件

• 相对url: /report/barrierGate/passEvent

• method: POST

• Content-Type：multipart/form-data

• 描述： 车辆进出车场时上报车辆通行事件。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：(ps:请求文本中省略了图片信息)

{
   "token": "1234567890",
   "recordId": "xyz123",
   "barrierGateId": "",
   "inOut": 0,
   "numberPlate": "浙A5566",
   "orderNumber": "订单号",
   "openType": 0,
   "permissionType": 0  
}

响应：

{
    "code": 0,
    "message": ""
}

3.27 道闸-识别非法车辆

• 相对url: /report/barrierGate/illegalVehicle

• method: POST

• Content-Type：multipart/form-data

• 描述：在道闸识别到非法车辆时上报该事件。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：(ps: 请求文本中省略了图片信息)

{
    "token": "1234567890",
    "barrierGateId": "zxcvbnm",
    "type":0,
    "numberPlate": "浙A5566",
    "inOut": 0
}

响应：

{
    "code": 0,
    "message": ""
}

3.28 上报车位状态

• 相对url: /report/parkingSpaceState

• method: POST

• Content-Type：multipart/form-data

• 描述： 上报车位的占用状态。

• 调用发起方：停车系统

• 参数：

• 返回值

示例
请求：(ps: 请求文本中省略了图片信息)

{
   "token": "1234567890",
   "spaceId": "asdfghjkl",
   "sapceState": 1,
   "numberPlate": "浙A5566"
}

响应：

{
    "code": 0,
    "message": ""
}

3.29 查询车位状态

• 相对url: /query/parkingSpaceState

• method: GET

• Content-Type：application/json

• 描述： 查询车位的占用状态。

• 调用发起方：边缘网关

• 参数

• 返回值

示例
请求：(ps: 请求文本中省略了图片信息)

token="1234567890"
spaceId="asdfghjkl"

响应：

{
    "code": 0,
    "message": "",
    "data": {
           "spaceState": 1,   // 0表无车， 1表示有车
        "numberPlate": "浙A5566"  //spaceState 为1时有效
    }
}

3.30 心跳

• 相对url: /keepalive

• method: POST

• Content-Type：application/json

• 描述： http client 端发起。每个业务通信都可当作一次心跳，只有链路出现空闲的时候，则发送心跳，若对端长时间未收到心跳，则认为设备掉线，即当前链路通道失效，需要重新做connect操作。

• 调用发起方：边缘网关，停车系统

• 参数：

• 返回值

{
   "code": 0,
   "message": ""
}

4、错误码表

5、文档发布历史

v2.0.4 2020-03-09

• 【修改】修复文字拼写错误

v2.0.3 2020-01-30

• 【修改】在规则新约中详细说明utc时间戳的单位

v2.0.2 2019-11-30

• 【修改】上报车位状态接口中新增一个可选参数 “车位图片URL”，用于获取停车场系统中的车位照片。

v2.0.1 2019-10-30

• 【修改】统一同步添加车辆信息，上报变更车辆信息两个API中permission list中使用的生效时间和失效时间变量名为exffectiveTime和expiryTime。

• 【修复】解决文档转换格式错乱问题。

v2.0.0 2019-08-30

• 【新增】停车场无停车区域时API的使用方法。

• 【新增】增加API文档发布版本编号和修改历史描述。

• 【新增】增加连接错误返回值描述例子。

• 【修复】连接失败response中不需要data字段，修改data必选为可选，只有在连接成功的response时才需要该字段。

• 【修复】连接请求中版本号含义描述。

• 【优化】补充错误码含义描述。

• 【优化】增加边缘端连接本地系统时的默认保活时间30s。

• 【删除】去掉用不到的错误码4（查询信息不存在）。

v1.0.0 2019-08-16

• 停车场边缘网关接入API第一个版本。

• 支持停车场、停车区域、道闸和车位。