title: 一卡通v5电控对接前置接口文档 date: 2017-02-13 13:45:23 tags:

日期版本作者说明
2017-2-13V1.0夏凯祥初稿

背景

一卡通系统与电控系统的对接需要经过电控前置服务。此文档为一卡通系统与电控前置的对接规范，用户可根据实际情况实现前置与电控系统的业务对接。

约定

  1. 传输编码统一为utf-8
  2. retcode 等于"0"（字符串）表示成功，其他表示失败，失败具体信息查看 msg
  3. 宿舍房间在一卡通中规定了五级，校区（area）/区域（district）/楼栋（build）/楼层（floor）/房间（room）。级别不符合的请修改适应此规则。
  4. {elecsystem} 电控系统代码，区分多套电控

接口定义

1. 查询所有校区

  • URL: .../elec/{elecsystem}/getareas

  • 请求方式 POST

查询所有校区信息

  • 请求参数 无

  • 返回

  • retcode - "0" 标识操作成功，其余为异常情况
  • msg - "msg" 返回信息
  • data - 校区数据集合
    • areaId - 校区ID
    • areaName - 校区名称
{
    "retcode":"0",
    "msg":"成功", // 异常原因
    "data":[{
    			"areaId":"1",
    			"areaName":"邯郸校区"
    		  },{
    			"areaId":"2",
    			"areaName":"枫林校区"
    		}]
}

2. 查询所有区域

  • URL: /elec/{elecsystem}/getdistricts

  • 请求方式 POST

查询某一校区下的所有区域

  • 请求参数
  • area - 查询校区返回的areaId
  • 返回
  • retcode - "0" 标识操作成功，其余为异常情况
  • msg - "msg" 返回信息
  • data - 区域数据集合
    • districtId - 区域ID
    • districtName - 区域名称
{
    "retcode":"0",
    "msg":"成功", // 异常原因
    "data":[{
    			"districtId":"01",
    			"districtName":"一期公寓"
    		  }，{
    			"districtId":"02",
    			"districtName":"二期公寓"
    		  }]
}

3. 查询楼栋信息

  • URL: /elec/{elecsystem}/getbuis

  • 请求方式 POST

根据校区、区域查询楼栋

  • 请求
  • area - 查询校区返回的areaId
  • district - 查询区域返回的districtId
  • 返回
  • retcode - "0" 标识操作成功，其余为异常情况
  • msg - "msg" 返回信息
  • data - 数据集合
    • buiId - 楼栋ID
    • buiName - 楼栋名称
{
    "retcode":"0",
    "msg":"成功", // 异常原因
    "data":[{
    			"buiId":"010",
    			"buiName":"男生公寓10栋"
    		  }，{
    			"buiId":"020",
    			"buiName":"女生公寓20栋"
    		  }]
}

4. 查询楼层信息

  • URL: /elec/{elecsystem}/getfloors

  • 请求方式 POST

根据校区、区域、楼栋查询楼层

  • 请求
  • area - 查询校区返回的areaId
  • district - 查询区域返回的districtId
  • bui - 查询楼栋返回的buiId
  • 返回
  • retcode - "0" 标识操作成功，其余为异常情况
  • msg - "msg" 返回信息
  • data - 数据集合
    • floorId - 楼层ID
    • floorName - 楼层名称
{
    "retcode":"0",
    "msg":"成功", // 异常原因
    "data":[{
    			"floorId":"1",
    			"floorName":"一楼"
    		  }，{
    			"floorId":"2",
    			"floorName":"二楼"
    		  }，...]
}

5. 查询所有房间信息

  • URL: /elec/{elecsystem}/getrooms

  • 请求方式 POST

查询房间信息

  • 请求
  • area - 查询校区返回的areaId
  • district - 查询区域返回的districtId
  • bui - 查询楼栋返回的buiId
  • floor - 查询楼层返回的floorId
  • 返回
  • retcode - "0" 标识操作成功，其余为异常情况
  • msg - "msg" 返回信息
  • data - 数据集合
    • roomId - 房间ID
    • roomName - 房间名称
{
    "retcode":"0",
    "msg":"成功", // 异常原因
    "data":[{
    			"roomId":"1010",
    			"roomName":"1010室"
    		  }，{
    			"roomId":"2009",
    			"roomName":"2009室"
    		  }，{
    			"roomId":"2",
    			"roomName":"2025室"
    		  }，...]
}

6. 查询房间电量信息

  • URL: /elec/{elecsystem}/getroom

  • 请求方式 POST

查询房间信息

  • 请求
  • area - 查询校区返回的areaId
  • bui - 查询楼栋返回的buiId
  • room - 查询房间返回的roomId
  • 返回
  • retcode - "0" 标识操作成功，其余为异常情况
  • msg - "msg" 返回信息
  • data - 数据类
    • areaId - 校区ID
    • buiId - 楼栋ID
    • roomId - 房间ID
    • roomName - 房间名
    • restElecDegree - 剩余电量
{
    "retcode":"0",
    "msg":"成功", // 异常原因
    "data":{
    			"areaId":"2",
    			"buiId":"20",
    			"roomId":"2010",
    			"roomName":"2010室",
    			"restElecDegree":12.0
    		 }
}

7. 电费转账（充值）

  • URL: /elec/{elecsystem}/buyelec

  • 请求方式 POST

查询房间信息

  • 请求
  • area - 查询校区返回的areaId
  • bui - 查询楼栋返回的buiId
  • room - 查询房间返回的roomId
  • cust - 系统唯一号，学工号或客户号
  • amount - 转账金额，单位分
  • transtime - 交易时间
  • transno - 系统的交易参考号
  • sign - 按上面参数顺序拼接最后加上秘钥进行MD5加密。（area + bui + room + cust + amount + transtime + transno + elec_key）
  • 返回
  • retcode - "0" 标识操作成功，其余为异常情况
  • msg - "msg" 返回信息
{
    "retcode":"0",
    "msg":"成功", // 异常原因
}