系统平台API接口-慢充接口

文档历史记录

日期	版本	作者	描述
2018-05-21	1.0	陈微战	撰写
2018-05-28	1.0	陈微战	修改
2018-05-31	1.0	陈微战	增加psd_entry参数示例说明
2018-07-27	1.0	陈微战	1、增加异步通知接口及相关说明 2、修正测试环境接口地址
2018-07-30	1.0	陈微战	1、启用设备充电接口增加端口号跟充电时间参数
2018-07-31	1.0	陈微战	1、远程控制响应码增加：2003错误响应； 2、升级慢充充电桩同步接口。
2018-08-01	1.0	陈微战	1、增加设备在离线查询； 2、增加异步通知请求头说明； 3、增加异步通知数据格式说明。
2019-03-10	1.0	陈文杰	1、增加设备信息查询接口； 2、增加设备入驻接口； 3、增加设备故障告警信息查询。
2019-06-19	1.0	陈文杰	1、下发启动命令，下发单位统一； 2、端口查询，查询单位统一。
2019-12-04	1.0	陈文杰	1、增加设备启动充电接口2.0版本。
2020-04-13	1.10	陈文杰	1、增加设备列表查询接口。 2、增加设备联网数量统计接口
2020-05-28	1.11	陈文杰	1、增加新版完成充电异步通知。

引言

编写目的

   波塞冬物联平台为第三方平台提供充电桩API业务接口，适用人群：开发人员、运维人员。

背景

   项目名称：：波塞冬充电桩项目

   任务提出者：杭州东骏科技有限公司

   开发者：杭州东骏科技有限公司

   用户：第三方平台

定义

术语/缩写	含义
-/--	-/--

基本需求

   说明：API基础URL

   测试环境: https://qa-api.supeeder.com/api/gateway

   生产环境: https://api.supeeder.com/api/gateway

HTTP标准包头字段（必填）

字段	类型	约束	说明
app_id	string	必填	平台给API接口商的系统appid
psd_entry	long	必填	当前调用日期的毫秒数，13位长度整型数值，例如：1527751383732, 误差在10分钟之内

HTTP公共请求体参数（必填）

字段	类型	约束	说明
api	string	必填	接口api，具体值参见每章节接口地址，例如3.1.1接口地址中api项值
nonce	string(16)	必填	随机串, 由16个ASCII可见字符(除空格)组成, 即ASCII码范围从0x21 至 0x7E, 每次调用需重新生成nonce
version	string	选填	接口版本号，默认为1.0
sign	string	必填	签名，加密方式为MD5加密，详见签名方式

   说明：下述所有接口的请求包体中不再重复累述，务必在发起调用时带上。

异步通知

请求头

   说明：服务方将在客户端提供的回调地址请求头中增加如下头信息。

属性	类型	约束	说明
app_id	string	必填	调用方的app_id原路传回给客户端
api	string	必填	参见异步通知接口API
version	string	必填	固定值为1.0，供客户端调用方判断标识，无实际意义。

数据格式

   说明：服务方发起异步数据数据格式为：Json字符串，Content-Type：Application/json，Charset：UTF-8。

重试机制

 目前接口平台针对失败或超时的异步请求响应制定如下重试机制：
 a)频率：第一次：1s，第二次：10s，第三次：30s，第四次：3m，第五次：1h，最后一
   次：1d；
 b)请第三方根据实际情况制定重试通知的幂等处理。

安全规则

签名方式

   1)必须带有nonce随机串, 由16个ASCII可见字符(除空格)组成, 即ASCII码范围从0x21 至 0x7E, 每次调用需重新生成nonce；

   2)参数名ASCII码从小到大排序（字典序）；

   3)参数名区分大小写；

   4)排序后的参数串需要加上&key=商户的密钥, 再生成签名，

     * key为每个已开通商户自己(或默认)设置的密钥, 请妥善保管切勿泄漏, 可定时修改*

   5)使用MD5加密并全部转大写得到sign签名串, 发送时带上此sign字段；

   举例：假设传送的参数如下：

        nonce : 1234abcd1234abcd

        api： net.charge.test

        version :  1.0

        data1 :  aaa

        data2 :  bbb

   第一步：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：

       stringA="api=net.charge.test&data1=aaa&data2=bbb&nonce=1234abcd1234abcd&version=1.0";

   第二步：拼接API密钥：

       stringSignTemp="stringA&key=123123123123123"

       sign=MD5(stringSignTemp).toUpperCase()="154ADAB370EF191E882E548BE71568EE"

   得到最终发送的数据 (真正发送时参数无需排序, 不允许发送key)：

   示例

    {
        "nonce"="1234abcd1234abcd",
        "api"="net.charge.test",
        "version"="1.0",
        "data1"="aaa",
        "data2"="bbb",
        "sign"="154ADAB370EF191E882E548BE71568EE"
    }

响应解析

设备基础接口

同步接口：设备在离线查询

业务说明

   提供设备在离线查询。

请求地址

URL	详见基本需求说明
API	net.equip.online.query
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填	示例	设备号

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
data		Object	必填		内容
	online	boolean	必填	true\|false	在离线状态，true：在线，false：离线

示例

{
    "code":1,
    "data":
    {
         "online":false
    }
}

慢充设备模块通信

同步接口：查询设备端口

业务说明

   慢充设备端口查询。

请求地址

URL	详见基本需求说明
API	net.equip.charge.slow.port.query
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：查询失败公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
ports		array	必填		端口数组
	port	int(2)	必填		端口数组
	status	string(10)	必填	1\|2\|3\|4	端口状态； 1-端口空闲； 2-端口正在使用； 3-端口禁用； 4-端口故障。

示例

{
    "code":1,
    "ports":[
        {"port":"1","status":"2"},
        {"port":"2","status":"1"},
        {"port":"3","status":"1"},
        {"port":"4","status":"1"},
        {"port":"5","status":"1"},
        {"port":"6","status":"1"},
        {"port":"7","status":"1"},
        {"port":"8","status":"1"},
        {"port":"9","status":"1"},
        {"port":"10","status":"1"}
    ]
}

同步接口：启动设备充电

业务说明

   下发慢充设备开始充电。

请求地址

URL	详见基本需求说明
API	net.equip.charge.slow.run
Method	GET

请求包体

属性	类型	约束	说明
equipCd	string(20)	必填	设备号
port	int(2)	必填	端口
time	int	必填	充电量；时间主板：下发单位为分钟；电量主板：下发单位为0.01度（千瓦时）

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：启动失败； 10002：端口非法； 10003：充电时长非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息

示例

{
    "code":1
}

同步接口：启动设备充电 v2.0

业务说明

   下发慢充设备开始充电。

请求地址

URL	详见基本需求说明
API	net.equip.charge.slow.run
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
version	string	必填	2.0	必须填写2.0
equipCd	string(20)	必填		设备号
port	int(2)	必填		端口
time	int	必填		充电时间,与充电电量二选一，都存在的情况取时间计费; 单位为分钟
electric	int	必填		充电充电电量,与充电时间二选一，都存在的情况取时间计费; 单位为0.01度（千瓦时）,请确认主板支持电量计费

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：启动失败； 10002：端口非法； 10003：充电时长非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息

示例

{
    "code":1
}

同步接口：查询设备充电状态

业务说明

   根据设备端口号查询设备充电状态。

请求地址

URL	详见基本需求说明
API	net.equip.charge.slow.port.status
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
port	int(2)	必填		设备端口，1-99

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：查询失败； 10002：端口非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
ports		Object	必填		内容
	port	int(2)	必填		设备端口号，1-99
	value	int(4)	选填		当前端口的充电剩余时间或者剩余电量；如果是充电时间则以分钟为单位；如果是充电电量则以0.01度（千瓦时）为单位。
	instantPower	int(5)	选填		当前充电瞬时功率，单位：瓦

示例

{
    "code":1,
    "data":{
        "port":"1",
        "value":"52",
        "instantPower":"368"
    }
}

同步接口：停止设备充电

业务说明

   下发慢充设备停止充电。

请求地址

URL	详见基本需求说明
API	net.equip.charge.slow.run.stop
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
port	int(2)	必填		设备端口，1-99

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：停止失败； 10002：端口非法。公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
ports		Object	必填		内容
	port	int(2)	必填		设备端口号，1-99
	time	int(4)	选填		用户充电剩余时长，单位：分钟

示例

{
    "code":1,
    "data":{
        "port":"1",
        "time":23
    }
}

异步通知：完成充电

业务说明

   服务端异步通知第三方平台慢充设备完成充电通知。

   说明：因慢充业务决定并非所有的设备都能及时进行充电完成上报（例如：充电桩断电、网络等原因），考虑到类似异常情况，请客户端自行处理异常业务情况，保证业务闭环。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.charge.slow.async.notice.finish
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
port	int(2)	必填		设备端口，1-99
value	int(4)	必填		充电结束剩余量；如果是充电时间则以分钟为单位，如果是充电电量则1个单位为0.01度（千瓦时）。
reason	int(1)	必填	0\|1\|2\|3\|4	上报充电结束原因； 0：充电时间用完； 1：用户手动停止； 2：充满自停； 3：设备或端口出现故障； 4：因充电器功率超过充电站的单路最大输出功率，切断输出。

响应包体

响应	类型	约束	说明
SUCCESS	string	必填	通知接收并处理成功
FAIL	string	必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制
无响应或超时		必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制

示例

   SUCCESS

异步通知：上报故障

业务说明

   服务端异步通知第三方平台慢充设备上报故障通知。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.charge.slow.async.notice.fault
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
port	int(2)	必填		设备端口，1-99
errorCode	int(1)	必填	1\|2\|3	故障编号，1：端口输出故障，2：机器整体充电功率过大，3：电源故障

响应包体

响应	类型	约束	说明
SUCCESS	string	必填	通知接收并处理成功
FAIL	string	必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制
无响应或超时		必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制

示例

   SUCCESS

异步通知：投币上报

业务说明

   服务端异步通知第三方平台慢充设备投币上报事件。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.charge.slow.async.notice.coin.order
Method	POST

请求包体

属性	类型	约束	说明
equipCd	string(20)	必填	设备号
port	int(2)	必填	设备端口，1-99
num	int(2)	必填	投币数

响应包体

响应	类型	约束	说明
SUCCESS	string	必填	通知接收并处理成功
FAIL	string	必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制
无响应或超时		必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制

示例

   SUCCESS

异步通知：刷卡上报（老版本）

业务说明

   服务端异步通知第三方平台慢充设备刷卡上报事件。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.charge.slow.async.notice.card.order
Method	POST

请求包体

属性	类型	约束	说明
equipCd	string(20)	必填	设备号
cardNo	string(20)	选填	卡号
amount	double(6,2)	必填	刷卡金额，单位：元，保留两位小数

响应包体

响应	类型	约束	说明
SUCCESS	string	必填	通知接收并处理成功
FAIL	string	必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制
无响应或超时		必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制

示例

   SUCCESS

异步通知：完成充电（新版）

业务说明

   服务端异步通知第三方平台慢充设备完成充电通知。

说明：请根据模块支持的完成上报接口开发对应的业务；因慢充业务决定并非所有的设备都能及时进行充电完成上报（例如：充电桩断电、网络等原因），考虑到类似异常情况，请客户端自行处理异常业务情况，保证业务闭环。

请求地址

URL	第三方平台提供的notifyUrl地址
API	net.equip.charge.slow.async.notice.finish.new
Method	POST

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	必填		设备号
port	int(2)	选填		设备端口，1-99
amount	int	选填		退费金额（正常结束为0, 表示无需退款）, 单位角
time	String	必填		充电剩余时间（FFFF表示全部退款）, 单位分钟
electricity	int	必填		充电电量, 单位0.01度
reason	String(1)	必填	0\|1\|2\|3\|4\|B	上报充电结束原因，0：购买的时间或电量已经用完了；1：用户手动停止；2：充满自停；3：超功率自停；4：远程断电；B：设备或端口出现问题，被迫停止

响应包体

响应	类型	约束	说明
SUCCESS	string	必填	通知接收并处理成功
FAIL	string	必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制
无响应或超时		必填	通知已接收但是处理失败，将触发通知重发，详见异步通知重试机制

示例

   SUCCESS

慢充设备业务接口

设备信息查询

业务说明

   查询单台设备信息。

请求地址

URL	详见基本需求说明
API	charge.equip.info.query
Method	GET

请求包体

属性	类型	约束	格式枚举	说明
equipCd	string(20)	二选一		设备编号
terminalNo	string(20)	二选一		设备入驻后生成的终端号

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
data		Object	必填		设备信息
	cd	string(20)	必填		设备编号
	terminalNo	string(20)	必填		设备终端号
	name	string(32)	必填		设备名称
	expireDate	date	选填		设备到期时间，格式为：YYYY-MM-DD
	province	string(32)	选填		设备所在省份
	city	string(32)	选填		设备所在城市
	area	string(32)	选填		设备所在区域
	address	string(32)	选填		设备详细地址
	contact	string(32)	选填		售后联系人名称
	contactMobilePhone	string(11)	选填		售后联系人电话
	longitude	string(22)	选填		经度
	latitude	string(22)	选填		纬度

示例

{
	"code": 1,
	"data": {
		"cd": "12345654321",
		"name": "充电桩",
		"address": "浙江省",
		"contactMobilePhone": "18368404465",
		"terminalNo": "DJ54321TORU",
		"longitude": 120.220763,
		"latitude": 30.178396
	}
}

设备入驻

业务说明

   将设备IMEI入驻到平台。

请求地址

URL	详见基本需求说明
API	charge.slow.equip.create
Method	POST

请求包体

属性	类型	约束	说明
cd	string(20)	必填	设备IMEI
name	string(32)	必填	设备名称
afterSalesContact	string(32)	选填	售后联系人
afterSalesCall	string(11)	选填	售后电话

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	私有返回码： 10001：设备IMEI已入驻公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
data		Object	必填		设备信息
	cd	string(20)	必填		设备编号
	name	string(32)	必填		设备名称
	terminalNo	string(20)	必填		设备终端号

示例

{
	"code": 1,
	"data": {
		"cd": "12345654321",
		"name": "充电桩",
		"terminalNo": "DJ54321TORU"
	}
}

设备故障告警信息查询

业务说明

   查询设备告警信息。

请求地址

URL	详见基本需求说明
API	charge.equip.alarm.query
Method	GET

请求包体

属性	类型	约束	说明
equipCd	string(20)	必填	设备编号
startTime	date	选填	起始时间默认为当天0:00，格式为：YYYY-MM-DD HH:mm:ss
endTime	date	选填	结束时间默认为当前时间，格式为：YYYY-MM-DD HH:mm:ss
offset	int	选填	偏移量，默认为0，即从第一条开始查询
limit	int	选填	查询总数，默认为30，从偏移量offset开始，取limit条，最大为1000条

响应包体

属性			类型	约束	格式枚举	说明
code			int	必填	参见返回码	公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg			string	选填		若请求失败，此处会包含失败信息
data			Object	必填		告警信息
	total		int	必填		告警的条数
	alarmList		array	必填		告警列表
		errorCode	int	必填	1\|2\|3\|999	故障代码 1：端口故障 2：整机功率过大 3：电源故障 999：其他故障
		message	string(32)	必填		告警详情
		time	date	必填		故障发生时间，格式为：YYYY-MM-DD HH:mm:ss

示例

{
	"code": 1,
	"data": {
		"total": 1,
		"alarmList": [{
			"errorCode": 1,
			"message": "12345654321设备6号端口功率超载"
		}]
	}
}

设备联网数量统计

业务说明

   查询在离线设备数量。

请求地址

URL	详见基本需求说明
API	net.equip.signal.statistics.query
Method	GET

请求包体

属性	类型	约束	格式枚举	说明

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
data		Object	必填		统计信息
	total	int	必填		设备总数
	online	int	必填		在线设备数量
	offline	int	必填		离线设备数量
	sigHigh	int	必填		信号优设备量
	sigMeidum	int	必填		信号中等设备量
	sigLow	int	必填		信号低设备量
	sigZero	int	必填		无信号设备量
	sigUnknown	int	必填		信号未知设备量

示例

{"code":1,"data":{"total":131,"online":6,"offline":125,"sigHigh":5,"sigMedium":1,"sigLow":0,"sigZero":0,"sigUnknown":125}}

设备列表查询

业务说明

   查询设备列表信息。

请求地址

URL	详见基本需求说明
API	charge.equip.list.query
Method	GET

请求包体

属性	类型	约束	说明
equipCd	string(20)	选填	设备编号
terminalNo	string(20)	选填	终端号
name	string(20)	选填	设备名称
offset	int	选填	偏移量，默认为0，即从第一条开始查询
limit	int	选填	查询总数，默认为30，从偏移量offset开始，取limit条，最大为1000条

响应包体

属性		类型	约束	格式枚举	说明
code		int	必填	参见返回码	公共响应码： 0：请求失败 1：请求成功，更多参见返回码示例。
msg		string	选填		若请求失败，此处会包含失败信息
total		int	必填		设备总条数
data		array	必填		设备列表信息
	cd	string(20)	必填		设备编号
	terminalNo	string(20)	必填		设备终端号
	name	string(32)	必填		设备名称
	expireDate	date	选填		设备到期时间，格式为：YYYY-MM-DD
	province	string(32)	选填		设备所在省份
	city	string(32)	选填		设备所在城市
	area	string(32)	选填		设备所在区域
	address	string(32)	选填		设备详细地址
	contact	string(32)	选填		售后联系人名称
	contactMobilePhone	string(11)	选填		售后联系人电话
	longitude	string(22)	选填		经度
	latitude	string(22)	选填		纬度

示例

{"code":1,"total":1,"data":[{"cd":"123456","terminalNo":"DJ01995KPM5","name":"测试设备","contact":"陈","contactMobilePhone":"12345678901"}]}

返回码

基础返回码

返回码	说明
0	失败
1	成功
9999	系统异常, 出现后需联系平台方
1000	请求参数为空
1001	http method非法
1002	appid为空
1003	API接口名为空
1004	签名非法
1005	商户非法, appid对应的商户不存在或者已停用
1006	商户无此API权限
1007	商户API已停用
1008	API调用次数已达上限
1009	IP非法, 即调用方IP不在白名单访问规则内
1010	API不存在
1011	nonce非法随机串为空或不正确或已使用
1012	调用时段非法调用时的时间串为空或者误差超过10分钟
1013	API密钥非法, 平台中的密钥未设置或设置错误

远程控制基础返回码

返回码	说明
2000	设备非法设备号错误、对应的设备未在平台入驻、设备停用等
2001	设备离线设备由于通讯板故障、网络闪断、断电等物理原因导致网络不通
2002	响应超时平台发送指令后，设备在指定时间内未返回响应
2003	设备过期针对续费模式设备需要在服务提供方平台进行设备续费

分页基础返回码

返回码	说明
3000	参数缺失没有传入足够的必要参数
3001	参数类型错误传入错误类型参数
3002	查询页数错误传入的查询页数小于等于0
3003	查询单页条数错误传入的单页查询条数小于等于0
3004	单页查询条数超过最大值传入的单页查询条数大于30

系统平台API接口-慢充接口

目录

文档历史记录

引言

编写目的

背景

定义

基本需求

HTTP标准包头字段（必填）

HTTP公共请求体参数（必填）

异步通知

请求头

数据格式

重试机制

安全规则

签名方式

响应解析

设备基础接口

同步接口：设备在离线查询

业务说明

请求地址

请求包体

响应包体

示例

慢充设备模块通信

同步接口：查询设备端口

业务说明

请求地址

请求包体

响应包体

示例

同步接口：启动设备充电

业务说明

请求地址

请求包体

响应包体

示例

同步接口：启动设备充电 v2.0

业务说明

请求地址

请求包体

响应包体

示例

同步接口：查询设备充电状态

业务说明

请求地址

请求包体

响应包体

示例

同步接口：停止设备充电

业务说明

请求地址

请求包体

响应包体

示例

异步通知：完成充电

业务说明

请求地址

请求包体

响应包体

示例

异步通知：上报故障

业务说明

请求地址

请求包体

响应包体

示例

异步通知：投币上报

业务说明

请求地址

请求包体

响应包体

示例

异步通知：刷卡上报（老版本）

业务说明

请求地址

请求包体

响应包体

示例

异步通知：完成充电（新版）