测试环境全局变量（替换后面{{}}中的值）

socket类接口

总体描述

1、消息体的传输使用google的protobuf进行序列化
2、传送的内容格式为：
  消息体长度（int类型 4个字节）+消息体类型编码（int类型4个字节）+消息体
3、MsgId：每个消息体都会有一个msgId，接入方必须保证自己的msgId唯一
4、消息体proto文件，见附件
5、响应编码见附录

消息体

客服端发送到服务端的消息体

客服端响应消息体 （clientResp.proto 消息体编码：2000）

当客服端收到服务端主动推送的消息体时（如支付回调），
需要对服务端做出响应，否则服务端会重复发送4次请求，
如果一直没有收到响应，服务端会默认为客服端没有收到该消息。

消息体结构

message ClientResp {
    required string msgId = 1;       //消息ID（和服务端请求的msgId一样）
    required string code = 2;       //响应编码
    required string msg = 3;       //响应消息
}

clientResp.proto

客服端心跳请求消息体 （heartbeatReq.proto 消息体编码：2010）

  客服端登录以后，需要每隔一段时间（建议10-30秒）向服务端发送心跳检测包以检测连接是否正常，
  如果连续3次以上没有收到服务端的响应，请重新连接服务端，并重新登录。
  若服务端长时间没有收到客服端的心跳包，服务端会提示接入方的负责人。

消息体结构

message HeartbeatReq {
    required string msgId = 1;   //消息ID（客服端自己生成，并保证全局唯一）
}

heartbeatReq.proto

客服端登录请求消息体 （loginReq.proto 消息体编码：2020）

客服端连接成功以后，
需要发送登录请求，说明自己是哪个车场，哪个岗亭，哪个车道等信息。

消息体结构

message LoginReq {
  required string msgId = 1;  //消息ID（客服端自己生成，并保证全局唯一）
    required uint64 id = 2;     //车场ID（平台分配的车场ID）
    required string uuid = 3;    //车场UUID（平台分配的车场UUID）
    required string boxName = 4;  //岗亭名字（在平台注册的岗亭名字）
    required string gateName = 5;  //车道名字（在平台注册的车场名字）
    required uint64 type = 6;  //车道类型 ，进口（1），出口（2）
}

loginReq.proto

场内扫码提前支付查询响应 （queryNeedPayMoneyResp.proto 消息体编码：2030）

场内提前扫码预支付时，
返回该订单或者车牌需要支付的金额，以及需要提前离场的时间。

消息体结构

message QueryNeedPayMoneyResp {
    required string msgId = 1;       //消息ID
    required string code = 2;       //响应编码
    required string msg = 3;       //响应消息
    required string orderNo = 4;       //停车订单号
    required string carNo = 5;       //车牌号
    required uint64 totalAmount = 6;     // 需要支付的总金额（单位分）
    required string enterTime = 7;     // 进场时间
    required uint64 leaveTime = 8;     // 需要多少时间内离场（单位分）
}

queryNeedPayMoneyResp.proto

服务端发送到客服端的消息体

服务端响应消息体 （serverResp.proto 消息体编码：3000）

当服务端收到客服端主动推送的消息体时（如登录，心跳等），会对客服端做出响应。

消息体结构

message ServerResp{
  required string msgId = 1;       //消息ID（和客服端请求的msgId一样）
    required string code = 2;       //响应编码
    required string msg = 3;       //响应消息
}

serverResp.proto

支付完成消息体 （payFinishReq.proto 消息体编码：3010）

当用户完成支付以后，服务端会向客服端发送用户支付完成的消息体

消息体结构

message PayFinishReq {
  required string msgId = 1;    //消息ID（服务端生成，全局唯一）
  required string boxName = 2;   //岗亭名字
    required string gateName = 3;       //车道名字
    required string orderNo = 4;   //订单编号（该停车记录的订单号）
    required string payChannel = 5;       //支付渠道
    required string payType = 6;       //支付类型
    required uint64 payAmount = 7;       //实际支付金额（单位分）
    required string outTradeNo = 8;       //支付订单号
  required uint64 totalAmount = 9;       //应该需要支付总金额（单位分）
     required uint64 discountAmount = 10;       //优惠券减免的金额（如果使用了优惠券）
}

payFinishReq.proto

场内扫码提前支付查询请求 （queryNeedPayMoneyReq.proto 消息体编码：3020）

场内提前扫码预支付时，
查询订单（或者车牌）需要支付的金额等信息。

消息体结构

message QueryNeedPayMoneyReq {
    required string msgId = 1;       //消息ID
    required string orderNo = 2;     //停车订单号
    required string carNo = 3;       //车牌号
}

queryNeedPayMoneyReq.proto

无牌车进场，同步虚拟车牌 （virtualCarNoSynReq.proto 消息体编码：3030）

无牌车进场的时候，用户扫码车道码，
生成虚拟车牌，并同步到停车场软件

消息体结构

message VirtualCarNoSynReq {
    required string msgId = 1;       //消息ID
    required string carNo = 2;     //虚拟车牌号
    required string boxName = 3;       //岗亭名
    required string gateName = 4;       //车道名
}

virtualCarNoSynReq.proto

无牌车支付完成，请求出场消息体（virtualCarNoOutReq.proto 消息体编码：3050）

无牌车支付完成，请求出场

消息体结构

message VirtualCarNoOutReq {
  required string msgId = 1;       //消息ID
  required string carNo = 2;       //虚拟车牌号
  required string boxName = 3;       //岗亭名字
     required string gateName = 4;       //车道名字
     required string orderNo = 5;       //订单编号
     required string payChannel = 6;       //支付渠道
     required string payType = 7;       //支付类型
     required uint64 payAmount = 8;       //实际需要支付金额（单位分）
     required string outTradeNo = 9;       //支付订单号
     required uint64 totalAmount = 10;       //应该需要支付总金额（单位分）
     required uint64 discountAmount = 11;       //优惠券减免的金额（如果使用了优惠券）
 }

virtualCarNoOutReq.proto

月卡信息同步消息体（monthCardSynReq.proto 消息体编码：3040）

月卡信息同步

消息体结构

message MonthCardSynReq {
    required string msgId = 1;           //消息ID
    required string userCode = 2;        //用户唯一编号
    required string userName = 3;       //用户名
    required string linkPhone = 4;      //用户联系电话
    required string address = 5;           //住址
    required uint64 parkingCount = 6;    //用户拥有车位数
    required string parkingNo = 7;      //车位编号
    required string cardName = 8;        //月卡名称
    required string carNo = 9;           //车牌号码
    required string startTime = 10;     //月卡起始时间
    required string endTime = 11;       //月卡结束时间
    required uint64 status = 12;        //月卡状态【0：禁用；1：启用】
 }

monthCardSynReq.proto

车道闸门开启消息体（openGateReq.proto 消息体编码：3060）

服务端主动向车场车道闸门发送开启命令的消息体

消息体结构

message OpenGateReq {
    required string msgId = 1;         // 消息ID
     required uint64 parkingLotId = 2;  // 停车场ID
    required string boxName = 3;       // 岗亭名字
     required string gateName = 4;      // 车道名字
     required uint64 type = 5;      // 车道类型（1-进口  2-出口）
    required uint64 command = 6;  // 开闸关闸（1-开闸 2-关闸）
 }

openGateReq.proto

月租车续费金额同步消息体（monthCardAmountSynReq.proto 消息体编码：3090）

服务端主动向车场发送月租车的续费金额的消息体

消息体结构

required string msgId = 1;          //消息ID
    required string carNo = 2;          //车牌号码
    required string cardName = 3;       //月卡名称
    required string orderNo = 4;        // 充值订单号
    required uint64 payCount = 5;       // 购买数量
    required uint64 payAmount = 6;      // 支付金额
    required string rechargeDate = 7;     // 充值日期
    required string extr = 8;             // 其他（json字符串，做扩展用。例：{"operate":"续费"}）

monthCardAmountSynReq.proto

附录

响应编码

回调类接口

扫码支付回调

当用户扫码完成支付，并且设置了支付回调地址的时候，云停车平台会将支付完成的结果回调给对接方。对接方接到回到以后回复"SUCCESS"即可。

POST 由对接方提供回调地址

请求参数

返回示例

"SUCCESS"

主动调用类接口

时序图

调用接口规则

  智享云停车平台接口采用http协议，如果没有特殊说明，使用post方式。

  调用接口时，参数包括 uuid,random,以及params。

  uuid为停车场的uuid(智享云平台分配),
  random为随机数（建议时间戳+随机字符串）,
  params为AES加密(详情见附录-AES加密)的请求参数，加密的秘钥由智享云平台分配。

  例如：某停车场的uuid为A, 调用某个接口需要的参数为B,C,D 那么参数加密的过程为：
  step1:将请求参数拼接为json字符串{"B":"xx","C":"xx","D":"xx"},得到json字符串str
  step2:将str进行AES加密,得到机密后的字符串str2=AES(str)
  step3:请求接口的最终参数就为：uuid=A&params=str2&random=xxx

返回结果说明

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
    }
}

返回参数

上传车辆进场数据（#1）

车辆进入车场时，将车辆入场信息上传到智享云平台

POST https://{{host}}/record/api/record/park/enter/upload

请求参数

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "orderNo": "154986668615537eca8a02532"
    }
}

返回参数

上传车辆离场数据（#2）

车辆行驶到车道口还未离场时，将车辆离场信息上传到智享云

POST https://{{host}}/record/api/record/park/out/upload

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "orderNo": "154986668615537eca8a02532",
        "errorCode":"",
        "errorMsg":"",
        "isAllow":true,
        "payChannel":"WECHAT",
        "payType":"WECHAT_PARKING",
        "totalAomunt":1500,
        "discountAmount":1000,
        "outTradeNo":"1106011109397102593",
        "payAmount":500
    }
}

返回参数

确认车辆离场订单 （#3）

主动确认车辆离场订单的收费方式

POST https://{{host}}/record/api/record/park/confirm

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "orderNo": "154986668615537eca8a02532",
        "errorCode":"",
        "errorMsg":"",
        "payChannel":"WECHAT",
        "payType":"WECHAT_PARKING",
        "totalAmount":1500,
        "discountAmount":1000,
        "payAmount":500
    }
}

返回参数

查询车辆离场订单信息（#4）

查询车辆离场的订单信息（用来确定订单支付状态）

POST https://{{host}}/record/api/record/park/query

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "orderNo": "154986668615537eca8a02532",
        "errorCode":"",
        "errorMsg":"",
        "isAllow":true,
        "payChannel":"WECHAT",
        "payType":"WECHAT_PARKING",
        "totalAmount":1500,
        "discountAmount":1000,
        "outTradeNo":"1106011109397102593",
        "payAmount":500
    }
}

返回参数

上传车辆进出场的离线数据 （#5）

<p>当网络出现问题时，先将数据离线保存到本地，等到有网络时再将离线数据上传到智享云</p>

POST https://{{host}}/record/api/record/park/offline

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "orderNo": "15615398737497d959d161845"
    }
}

获取上传车辆进出场图片token (#6)

智享云使用的七牛云上传服务（客服端直传七牛云模式）。
通过本接口获取上传七牛云的token，然后根据自己的语言在七牛云的官网选择
上传的SDK进行文件上传。
上传文件的格式为：/【车场ID】/【岗亭名字】/【yyyy-MM-dd】/【in(out)】/【车牌】【HHmmss】.jpg
上传成功后会获取到文件的全路径。
七牛云SDK地址：https://developer.qiniu.com/kodo/sdk/1255/cpp

POST https://{{host}}/record/api/upload-file/getUploadToken

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "expireTime": 3700,
        "token": "epx-FQR0_yjtM_Cp9nYJhop2u9qOh9cDS7UuMxKJ:ViAzpy_gOIgFRt_fhriAfEKMGjg=:eyJzY29wZSI6InhmdC1wYXJraW5nLWNsb3VkIiwicmV0dXJuQm9keSI6IntcImtleVwiOlwiaHR0cDovL3BvNmtzZXFqaS5ia3QuY2xvdWRkbi5jb20vJChrZXkpXCIsXCJoYXNoXCI6XCIkKGV0YWcpXCJ9IiwiZGVhZGxpbmUiOjE1NTM4NDgzMjZ9"
    }
}

返回参数

上传车辆进出场图片 (#7)

当图片上传完七牛云以后，需要将图片补到相关的停车记录上面（详情流程请见附录图片上传）

POST https://{{host}}/record/api/record/park/imgUrl/upload

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "orderNo": "154986668615537eca8a02532",
        "errorCode":"",
        "errorMsg":""
    }
}

返回参数

被扫支付授权码支付 (#8)

当用户在车道需要付款时，使用机器人扫用户出示的付款码完成支付放行

POST https://{{host}}/pay/api/pay/barCode

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "orderNo": "154986668615537eca8a02532",
        "state":"00",
        "payChannel":"WECHAT",
        "payType":"WECHAT_BAR_CODE_PAY",
        "outTradeNo":"1549866683qc537eca8a02532",
        "totalAmount":"2000",
        "payAmount":"1000",
        "discountAmount":"1000"
    }
}

返回参数

撤销支付 (#9)

当用户撤销支付时，调用该接口

POST https://{{host}}/pay/api/pay/cancel

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "errorCode": "0000",
        "errorMsg":"成功",
        "orderNo": "停车记录订单号",
        "outTradeNo":"支付订单号"
    }
}

返回参数

同步月租车 (#10)

同步月租车

POST https://{{host}}/bms/api/month/card/car/sync

返回示例

{
    "code": "0000",
    "msg": "操作成功",
    "result": true,
    "data": {
        "errorCode": "0000",
        "errorMsg":"成功"
    }
}

返回参数

附录

AES加密

  AES加密：
  加密模式：ECB
  填充模式：pkcs5padding
  数据块：128位
  输出字符串转码方式：HEX ，并且全部大写
  字符集:UTF-8
  验证地址：http://tool.chacuo.net/cryptaes

返回结果code

支付渠道payChannel

支付类型payType

订单状态

上传车辆进出场图片

准备工作：
1、进入七牛云官网（https://www.qiniu.com/）
2、选择服务与支持-开发者中心（https://developer.qiniu.com/?ref=www.qiniu.com）
3、选择SDK & 工具-官方 SDK（https://developer.qiniu.com/sdk#official-sdk），在对象存储中选择相应的开发语言。

实现流程：
1、调用获取上传车辆进出场图片token接口（4.9）获取上传的token
2、参见七牛云的SDK文档中的简单上传方法，上传图片，并获取返回的图片地址
3、调用上传车辆进出场图片接口（4.10），将相应的数据上传至平台

C++进出场图片上传客服端DEMO

时序图

车道静态码时序图

无感时序图

场内码时序图

无牌车进出场时序图

查询车辆离场订单信息时序图

离线数据上传时序图

现金收费时序图

被扫（付款码支付）时序图

月租车同步时序图