银行圈存、电控、网费前置接口文档整理
diff --git "a/source/_posts/\344\270\200\345\215\241\351\200\232v5\345\234\210\345\255\230\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md" "b/source/_posts/\344\270\200\345\215\241\351\200\232v5\345\234\210\345\255\230\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md"
index b90d185..e87bb55 100644
--- "a/source/_posts/\344\270\200\345\215\241\351\200\232v5\345\234\210\345\255\230\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md"
+++ "b/source/_posts/\344\270\200\345\215\241\351\200\232v5\345\234\210\345\255\230\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md"
@@ -8,10 +8,19 @@
|日期 |版本 |作者 |说明 |
|------------:|---------:|-----------:|------------------|
|2015-4-14 |V1.0 | 汤成 | 初稿 |
+|2017-2-13 |V1.1 | 夏凯祥 | V1.1 |
## 背景
-在项目中进行银行圈存对接开发时需要对悦校与一卡通同时支持，
+在项目中进行银行圈存对接开发时需要对悦校与一卡通同时支持。此文档为一卡通系统与银行圈存前置的对接规范，用户可根据实际情况实现前置与银行业务的对接。
+
+
+## 约定 ##
+
+1. 传输编码统一为utf-8
+2. 请求数据都用HAMC签名加密，收到请求参数后可验证数据正确性，秘钥共同约定。**`SIGN_ALGORITHMS ="HmacSHA1"`**;
+3. **retcode** 等于"0"（字符串）表示成功，其他表示失败，失败具体信息查看 **retmsg**
+
## 接口定义
@@ -19,34 +28,36 @@
* **URL: /bankservice/bankquery**
* **请求方式**
-`GET`, `POST`
+`POST`
-查询银行余额，根据银行实际情况不是所有银行都支持
+*查询银行余额，根据银行实际情况不是所有银行都支持*
-* **请求**
-`bankaccount` - 银行账号
-`custname` - 用户名，必须是该用户在银行的开户名（可选）
-`stuempno` - 学工号，可选
-`termid` - 发起终端号
-`tradetime` - 发起方时间，格式 yyyyMMddHHmmss
-`seqno` - 发起方流水号（可选）
-`timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+* **请求参数**
+- `bankcardno` - 银行账号（银行卡号）
+- `custname` - 用户姓名，必须是该用户在银行的开户名（可选）
+- `stuempno` - 系统唯一号，如学工号、客户号（可选）
+- `idno` - 身份证号（可选）
+- `termid` - 发起终端号（可选）
+- `tradetime` - 发起方时间，格式 yyyyMMddHHmmss
+- `seqno` - 发起方流水号（可选）
+- `timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `sign` - 签名。除sign的非空字段按上述顺序拼接进行签名加密，如（bankcardno+stuempno+termid+tradetime+timeout）。
* **返回**
-`ret` - "00"标识操作成功，其余为异常情况
-`retmsg` - 返回信息
-`money` - 银行卡余额，单位元
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `retmsg` - "msg" 返回信息
+- `money` - 银行卡余额，单位元
```json
{
- "ret":"00",
+ "retcode":"0",
"retmsg":"msg", // 异常原因
- "money":12.3 //单位（元）
+ "money":412.3 //单位（元）
}
```
### 2. 圈存请求
-* **URL: /bankservice/load**
+* **URL: /bankservice/charge**
* **请求方式**
`POST`
@@ -54,25 +65,27 @@
银行圈存请求，通过该请求完成银行卡转账业务
* **请求**
-`bankaccount` - 银行卡号
-`seqno` - 悦校/一卡通交易参考号
-`stuempno` - (可选）学工号
-`custname` - (可选）客户姓名
-`amount` - 圈存金额，单位元
-`termid` - （可选）终端编号
-`tradetime` - 请求时间， 格式yyyyMMddHHmmss
-`timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `bankcardno` - 银行卡号
+- `refno` - 系统交易参考号
+- `stuempno` - 系统唯一号，如学工号、客户号
+- `custname` - 客户姓名(可选）
+- `idno` - 客户姓名(可选）
+- `amount` - 圈存金额，单位分（整数）
+- `termid` - 终端编号（可选）
+- `tradetime` - 请求时间， 格式yyyyMMddHHmmss
+- `timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `sign` 签名。除sign的非空字段按上述顺序拼接进行签名加密，如（bankcardno+refno+stuempno+custname+idno+amount+termid+ tradetime+timeout）。
* **返回**
-`ret` - "00"标识操作成功，其余为异常情况
-`bankseqno` - （可选）返回银行端流水号，但不是所有银行都支持返回银行端流水号
-`retmsg` - 返回信息
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `retmsg` - "msg" 返回信息
+- `bankseqno` - （可选）返回银行端流水号，但不是所有银行都支持返回银行端流水号
```json
{
- "ret":"00",
+ "retcode":"0",
+ "retmsg":"msg", // 返回信息
"bankseqno": "1231", // 如果银行支持，返回银行端流水号
- "retmsg":"msg" // 返回信息
}
```
@@ -80,65 +93,118 @@
* **URL: /bankservice/transquery**
* **请求方式**
-`GET`, `POST`
+ `POST`
-查询圈存请求的结果，一般是圈存请求超时后通过这个接口判断银行交易是否成功，但不是所有银行都支持这个接口
+根据系统交易参考号查询圈存请求的结果，一般是圈存请求超时后通过这个接口判断银行交易是否成功，但不是所有银行都支持这个接口
* **请求**
-`bankaccount` - 银行卡号
-`seqno` - 悦校/一卡通交易参考号
-`loadseqno` - 前一笔圈存交易的参考号
-`stuempno` - (可选）学工号
-`custname` - (可选）客户姓名
-`amount` - 圈存金额，单位元
-`termid` - （可选）终端编号
-`tradetime` - 请求时间， 格式yyyyMMddHHmmss
-`timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `bankcardno` - 银行卡号
+- `refno` - 系统交易参考号
+- `stuempno` - (可选）学工号
+- `custname` - (可选）客户姓名
+- `idno` - (可选）身份证号码
+- `amount` - 圈存金额，单位分（整数）
+- `termid` - （可选）终端编号
+- `tradetime` - 请求时间， 格式yyyyMMddHHmmss
+- `timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `sign` - 签名。除sign的非空字段按上述顺序拼接进行签名加密。
* **返回**
-`ret` - "00" 标识查询到指定的圈存流水，"01" 标识无指定流水，其它表示错误
-`bankseqno` - （可选）如果查询到圈存流水则返回银行端流水号，但不是所有银行都支持返回银行端流水号
-`retmsg` - 返回信息
+- `retcode` - "0" 标识查询到指定的圈存流水,并交易成功；"01" 标识无指定流水，其它表示错误
+- `retmsg` -"msg" 返回信息
+- `bankseqno` - （可选）如果查询到圈存流水则返回银行端流水号，但不是所有银行都支持返回银行端流水号
```json
{
- "ret":"00",
- "bankseqno": 123, // 银行端流水号
+ "retcode":"0",
"retmsg":"msg" // 返回信息
+ "bankseqno": 123, // 银行端流水号
}
```
-### 4. 圈存冲正
-* **URL: /bankservice/loadcancel**
+### 4. 圈存冲正（退款）
+* **URL: /bankservice/chargereverse**
* **请求方式**
-`GET`, `POST`
+`POST`
圈存冲正接口，一般是圈存请求超时后通过这个接口冲正前面一笔圈存交易，但不是所有银行都支持这个接口
* **请求**
-`bankaccount` - 银行卡号
-`seqno` - 悦校/一卡通交易参考号
-`loadseqno` - 前一笔圈存交易的参考号
-`stuempno` - (可选）学工号
-`custname` - (可选）客户姓名
-`amount` - 圈存金额，单位元
-`termid` - （可选）终端编号
-`tradetime` - 请求时间， 格式yyyyMMddHHmmss
-`timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `bankcardno` - 银行卡号
+- `refno` - 系统交易参考号
+- `reverserefno` - 前一笔要冲正的圈存交易的参考号
+- `stuempno` - (可选）学工号
+- `custname` - (可选）客户姓名
+- `idno` - (可选）身份证号
+- `amount` - 金额，单位分（整数）
+- `termid` - （可选）终端编号
+- `tradetime` - 请求时间， 格式yyyyMMddHHmmss
+- `timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `sign` 签名。除sign的非空字段按上述顺序拼接进行签名加密
* **返回**
-`ret` - "00" 标识冲正成功，其它表示错误
-`bankseqno` - （可选）返回银行端流水号，但不是所有银行都支持返回银行端流水号
-`retmsg` - 返回信息
+- `retcode` - "0" 标识冲正成功，其它表示错误
+- `retmsg` - 返回信息
+- `bankseqno` - （可选）返回银行端流水号，但不是所有银行都支持返回银行端流水号
```json
{
- "ret":"00",
+ "retcode":"00",
"retmsg":"msg", // 返回信息
- "bankseqno" : 12
+ "bankseqno":"122121"
}
```
+### 5. 圈存对账
+* **URL: /bankservice/chargedtlchk**
+
+* **请求方式**
+`POST`
+
+圈存流水对账接口，一卡通系统每天定时的访问这个接口查询前一天或过去某一天的全部圈存流水(交易成功)，与系统记录的圈存流水进行比对，不一致时进行业务处理。
+
+* **请求**
+- `transdate` - 查询日期，yyyyMMdd
+- `bankid` - 银行标识
+- `billtype` - 查询类型,有的银行圈存转账和退款可能是分开的。"ALL"-查询圈存和冲正（退款）所有交易成功的流水;"SUCCESS"-查询圈存交易成功的流水;"REFUND"-查询冲正（退款）所有交易成功的流水。
+- `offset` - 偏移量，int型，初始为0
+- `tradetime` - 请求时间， 格式yyyyMMddHHmmss
+- `timeout` - (可选）前置机与银行通讯的超时时间，单位秒，范围 1 ~ 90 , 默认值为10
+- `sign` 签名。除sign的非空字段按上述顺序拼接进行签名加密
+
+* **返回**
+- `retcode` - "0" 标识冲正成功，其它表示错误
+- `retmsg` -"msg" 返回信息
+- `hasnext` - true或false。是否继续查询的标志。true继续查询，false结束查询
+- `offset` - 继续查询时的偏移量，int型。
+- `data` - 流水数据集合。
+ - `transdate` - 交易日期 yyyyMMdd
+ - `transtime` - 交易时间 HHmmss
+ - `stuempno` - 系统唯一号，如学工号、客户号
+ - `bankcardno` - 银行账号
+ - `refno` - 系统交易参考号，
+ - `bankseqno` - 银行端流水号
+ - `amount` - 交易金额，单位元
+
+
+```json
+{
+ "retcode":"0",
+ "retmsg":"msg", // 返回信息
+ "hasnext":true，
+ "offset":99,
+ "data":[
+ {
+ "transdate":"20160901",
+ "tramsdate":"142328",
+ "stuempno":"20170001",
+ "bankcardno":"6022111001004394733",
+ "refno":"20160901142328000023",
+ "bankseqno":"1020160901142328130713",
+ "amount":50.0
+ },...]
+}
+```
diff --git "a/source/_posts/\344\270\200\345\215\241\351\200\232v5\347\224\265\346\216\247\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md" "b/source/_posts/\344\270\200\345\215\241\351\200\232v5\347\224\265\346\216\247\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md"
new file mode 100644
index 0000000..60f66da
--- /dev/null
+++ "b/source/_posts/\344\270\200\345\215\241\351\200\232v5\347\224\265\346\216\247\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md"
@@ -0,0 +1,260 @@
+---
+title: 一卡通v5电控对接前置接口文档
+date: 2017-02-13 13:45:23
+tags:
+---
+
+
+|日期 |版本 |作者 |说明 |
+|------------:|---------:|-----------:|------------------|
+|2017-2-13 |V1.0 | 夏凯祥 | 初稿 |
+
+
+## 背景
+悦校/一卡通系统与电控系统的对接需要经过电控前置服务。此文档为一卡通系统与电控前置的对接规范，用户可根据实际情况实现前置与电控系统的业务对接。
+
+
+## 约定 ##
+
+1. 传输编码统一为utf-8
+2. **retcode** 等于"0"（字符串）表示成功，其他表示失败，失败具体信息查看 **msg**
+3. 宿舍房间在悦校/一卡通中规定了五级，校区（area）/区域（district）/楼栋（build）/楼层（floor）/房间（room）。级别不符合的请修改适应此规则。
+
+
+## 接口定义
+
+### 1. 查询所有校区
+* **URL: /elec/getareas**
+
+* **请求方式**
+`POST`
+
+*查询所有校区信息*
+
+* **请求参数**
+无
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `msg` - "msg" 返回信息
+- `data` - 校区数据集合
+ - areaId - 校区ID
+ - areaName - 校区名称
+
+```json
+{
+ "retcode":"0",
+ "msg":"成功", // 异常原因
+ "data":[{
+ "areaId":"1",
+ "areaName":"邯郸校区"
+ },{
+ "areaId":"2",
+ "areaName":"枫林校区"
+ }]
+}
+```
+
+### 2. 查询所有区域
+* **URL: /elec/getdistricts**
+
+* **请求方式**
+`POST`
+
+*查询某一校区下的所有区域*
+
+* **请求参数**
+- `area` - 查询校区返回的areaId
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `msg` - "msg" 返回信息
+- `data` - 区域数据集合
+ - districtId - 区域ID
+ - districtName - 区域名称
+
+```json
+{
+ "retcode":"0",
+ "msg":"成功", // 异常原因
+ "data":[{
+ "districtId":"01",
+ "districtName":"一期公寓"
+ }，{
+ "districtId":"02",
+ "districtName":"二期公寓"
+ }]
+}
+```
+
+### 3. 查询楼栋信息
+* **URL: /elec/getbuis**
+
+* **请求方式**
+ `POST`
+
+*根据校区、区域查询楼栋*
+
+* **请求**
+- `area` - 查询校区返回的areaId
+- `district` - 查询区域返回的districtId
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `msg` - "msg" 返回信息
+- `data` - 数据集合
+ - buiId - 楼栋ID
+ - buiName - 楼栋名称
+
+```json
+{
+ "retcode":"0",
+ "msg":"成功", // 异常原因
+ "data":[{
+ "buiId":"010",
+ "buiName":"男生公寓10栋"
+ }，{
+ "buiId":"020",
+ "buiName":"女生公寓20栋"
+ }]
+}
+```
+
+### 4. 查询楼层信息
+* **URL: /elec/getfloors**
+
+* **请求方式**
+ `POST`
+
+*根据校区、区域、楼栋查询楼层*
+
+* **请求**
+- `area` - 查询校区返回的areaId
+- `district` - 查询区域返回的districtId
+- `bui` - 查询楼栋返回的buiId
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `msg` - "msg" 返回信息
+- `data` - 数据集合
+ - floorId - 楼层ID
+ - floorName - 楼层名称
+
+```json
+{
+ "retcode":"0",
+ "msg":"成功", // 异常原因
+ "data":[{
+ "floorId":"1",
+ "floorName":"一楼"
+ }，{
+ "floorId":"2",
+ "floorName":"二楼"
+ }，...]
+}
+```
+
+### 5. 查询所有房间信息
+* **URL: /elec/getrooms**
+
+* **请求方式**
+ `POST`
+
+*查询房间信息*
+
+* **请求**
+- `area` - 查询校区返回的areaId
+- `district` - 查询区域返回的districtId
+- `bui` - 查询楼栋返回的buiId
+- `floor` - 查询楼层返回的floorId
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `msg` - "msg" 返回信息
+- `data` - 数据集合
+ - roomId - 房间ID
+ - roomName - 房间名称
+
+```json
+{
+ "retcode":"0",
+ "msg":"成功", // 异常原因
+ "data":[{
+ "roomId":"1010",
+ "roomName":"1010室"
+ }，{
+ "roomId":"2009",
+ "roomName":"2009室"
+ }，{
+ "roomId":"2",
+ "roomName":"2025室"
+ }，...]
+}
+```
+
+### 6. 查询房间电量信息
+* **URL: /elec/getroom**
+
+* **请求方式**
+ `POST`
+
+*查询房间信息*
+
+* **请求**
+- `area` - 查询校区返回的areaId
+- `bui` - 查询楼栋返回的buiId
+- `room` - 查询房间返回的roomId
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `msg` - "msg" 返回信息
+- `data` - 数据类
+ - areaId - 校区ID
+ - buiId - 楼栋ID
+ - roomId - 房间ID
+ - roomName - 房间名
+ - restElecDegree - 剩余电量
+
+```json
+{
+ "retcode":"0",
+ "msg":"成功", // 异常原因
+ "data":{
+ "areaId":"2",
+ "buiId":"20",
+ "roomId":"2010",
+ "roomName":"2010室",
+ "restElecDegree":12.0
+ }
+}
+```
+
+### 7. 电费转账（充值）
+* **URL: /elec/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" 返回信息
+
+
+```json
+{
+ "retcode":"0",
+ "msg":"成功", // 异常原因
+}
+```
diff --git "a/source/_posts/\344\270\200\345\215\241\351\200\232v5\347\275\221\350\264\271\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md" "b/source/_posts/\344\270\200\345\215\241\351\200\232v5\347\275\221\350\264\271\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md"
new file mode 100644
index 0000000..48e1952
--- /dev/null
+++ "b/source/_posts/\344\270\200\345\215\241\351\200\232v5\347\275\221\350\264\271\345\257\271\346\216\245\345\211\215\347\275\256\346\216\245\345\217\243\346\226\207\346\241\243.md"
@@ -0,0 +1,81 @@
+---
+title: 一卡通v5网费对接前置接口文档
+date: 2017-02-13 13:45:23
+tags:
+---
+
+
+|日期 |版本 |作者 |说明 |
+|------------:|---------:|-----------:|------------------|
+|2017-2-13 |V1.0 | 夏凯祥 | 初稿 |
+
+
+## 背景
+悦校/一卡通系统与网费系统的对接需要经过网费前置服务。此文档为一卡通系统与网费前置的对接规范，用户可根据实际情况实现前置与网费系统的业务对接。
+
+
+## 约定 ##
+
+1. 传输编码统一为utf-8
+2. 请求数据都用HAMC签名加密，收到请求参数后可验证数据正确性，秘钥共同约定。**`SIGN_ALGORITHMS ="HmacSHA1"`**;
+3. **retcode** 等于"0"（字符串）表示成功，其他表示失败，失败具体信息查看 **retmsg**
+
+
+## 接口定义
+
+### 1. 查询网费账号余额
+* **URL: /net/srun4k/query**
+
+* **请求方式**
+`POST`
+
+*查询剩余网费金额*
+
+* **请求参数**
+- `payacc` - 网费账号
+- `netpwd` - 密码（可选），现支持无密码查询
+- `timestamp` - 请求时间，yyyyMMddHHmmss
+- `sign` - 签名，按上面参数顺序拼接进行HAMC加密（payacc+ timestamp）。
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `retmsg` - "msg" 返回信息
+- `balance` - 剩余金额，字符串
+
+```json
+{
+ "retcode":"0",
+ "retmsg":"成功", // 异常原因
+ "balance": "6.5"
+}
+```
+
+### 2. 网费充值
+* **URL: /net/srun4k/query**
+
+* **请求方式**
+`POST`
+
+*查询剩余网费金额*
+
+* **请求参数**
+- `refno` - 系统交易参考号
+- `payacc` - 网费账号
+- `amount` - 充值金额，单位分
+- `timestamp` - 请求时间，yyyyMMddHHmmss
+- `sign` - 签名，按上面参数顺序拼接进行HAMC加密（refno+payacc+amount+timestamp）。
+
+* **返回**
+- `retcode` - "0" 标识操作成功，其余为异常情况
+- `retmsg` - "msg" 返回信息
+- `balance` - 剩余金额，字符串
+- `billno` - 网费系统的流水号
+
+```json
+{
+ "retcode":"0",
+ "retmsg":"成功", // 异常原因
+ "balance":"30.5",
+ "billno":"022017021412321100123"
+}
+```