source/_posts/一卡通v5电控对接前置接口文档.md

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

日期	版本	作者	说明
2017-02-13	V1.0	夏凯祥	初稿
2017-07-05	V1.1	夏凯祥	多套电控、转账接口修改、增加对账单

背景

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

约定

传输编码统一为utf-8
retcode 等于"0"（字符串）表示成功，其他表示失败，失败具体信息查看 msg
宿舍房间在一卡通中规定了五级，校区（area）/区域（district）/楼栋（build）/楼层（floor）/房间（room）。级别不符合的请修改适应此规则。
{elecsystem} 电控系统代码，区分多套电控。如新开普电控，标识为newcapec,则前置对应校区查询url为：.../elec/newcapec/getareas;区域为：.../elec/newcapec/getdistricts 等等。

接口定义

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 - 客户唯一号（兼容以前版本）,空时填0
custid - 系统唯一号，客户号（与stuempno，可选）,空时填0
stuempno - 系统唯一号，学工号（与custid，可选）,空时填0
custname - 姓名（可选）,空时填0
cardno - 卡号（可选）,空时填0
amount - 转账金额，单位分
accdate -记账日期。对账时用accdate获取电控对账单
transtime - 交易时间
refno - 系统的交易参考号 (原 transno)
sign - 按上面参数顺序拼接最后加上秘钥进行MD5加密。（area + bui + room + cust + amount + transtime + refno + elec_key）

retcode - "0" 标识操作成功，其余为异常情况
msg - "msg" 返回信息

{
    "retcode":"0",
    "msg":"成功", // 异常原因
}

8、获取电费转账流水（对账单）

URL: .../epayapi/services/elecfee/thirdparty/queryelecdtl
请求方式 POST

API提供按记账日期（转账时的accdate字段）查询当天所有交易成功的电控转账流水。供第三方查询对账用

请求

accdate - 记账日期
elecsystem - 电控系统的标识
offset - 偏移量，int型，初始为0
timestamp - 请求时间，格式yyyyMMddHHmmss
sign - 按上面参数顺序拼接最后加上秘钥进行MD5加密(accdate + [elecsystem] + offset + timestamp + elec_key)

retcode - "0" 标识操作成功，其余为异常情况
retmsg - "OK" 返回信息
hasnext - true或false。是否继续查询的标志。true继续查询，false结束查询
offset - 继续查询时的偏移量，int型。
data - 流水数据集合。
- transdate - 交易日期 yyyyMMdd
- transtime - 交易时间 HHmmss
- refno - 系统交易参考号，
- accdate - 记账日期，
- amount - 交易金额，单位元
- stuempno - 学工号
- custid - 客户号
- custname - 姓名
- cardno - 卡号。APP、网页等支付时cardno=0
- revflag - 冲正标志。1-被冲正；0-未被冲正
- area - 校区 areaId
- bui - 楼栋 buiId
- room - 房间 roomId

{
    "retcode":"0",
    "retmsg":"msg", // 返回信息
    "hasnext":true，
    "offset":100,
    "data":[
    			{
    				"transdate":"20160901",
    				"transtime":"142328",
    				"refno":"20160901142328000023",
    				"accdate":"20160901",
    				"amount":20.0,
    				"stuempno":"20170001",
    				"custid":1000234,
    				"custname":"测试人员",
    				"cardno":0,
    				"revflag":0,
    				"area":"1",
    				"bui":"102",
    				"room":"1101"
    			},...]
}