API收银台

一、对接流程#

核心业务流程说明

A、合作方服务端向易能时代调取“油站列表”接口，该接口每天限制最多只能调取 24 次。易能时代根据合作方的请求，向合作方返回油站列表信息，合作方用户端向合作方服务端请求油站信息列表，合作方服务端根据以获取的油站列表返回对应油站列表信息给到合作方用户端；

B、合作方用户端向合作方服务端请求进入油站详情页，合作方服务端向易能时代“油站详细信息”接口发起请求，获取油站详情信息，易能时代向合作方服务端返回对应油站详情信息，合作方用户端获取油站详情信息，进入油站详情信息界面；

C、合作方用户选定油枪、油品及购买金额后，向合作方服务端提交订单，合作方服务端向易能时代“创建订单”接口发起请求；

a、如果合作方服务端向易能时代请求校验未通过，则返回创建失败的结果，合作方服务端收到易能时代订单创建失败的结果，返回给合作方用户端，此时合作方用户端需要重新走订单支付流程；

b、如果合作方服务端向易能时代请求校验通过，则返回创建成功的结果，合作方服务端收到易能时代订单创建成功的结果，返回给合作方用户端，订单创建成功；

D、合作方用户端向合作方服务端发起支付请求，合作方服务端向易能时代“P端收银台”接口发起支付请求

a、易能时代平台针对该请求发起校验，校验不通过（如合作方预存款不足或其他原因），则直接返回支付失败及相关失败原因给合作方服务端，合作方服务端收到易能时代订单支付失败的结果，返回给合作方用户端，此时当前支付流程结束。

b、如果合作方服务端向易能时代支付请求校验通过，则返回创建成功的结果，合作方服务端向合作方用户端返回支付成功结果，流程结束，支付完成，油站放行。

二、对接须知#

参数信息#

platformName，beforeKey、afterKey 、app_key、app_secret、ak、sk 等调取接口必要的信息由易加油产品提供。

环境信息#

· 测试域名: https://pre.ejiayou.com

· 正式域名: https://api.ejiayou.com

测试须知#

· 请谨慎使用正式环境的油站测试支付！若需测试请提前告知易能时代，由易能时代运营与油站提前沟通后方可进行测试。已确认测试油站后有以下要求：单笔支付金额**≤**10 元，单个油站可测试订单数**≤**5 笔，当天支付订单必须当天反馈易能时代工作人员申请退款，隔天订单不予退款申请操作。如需测试 10 元 ≤ 订单支付金额 ≤1000 元），请使用易能时代正式环境测试油站 id:21413。

· 测试环境获取的油站均可进行测试操作。

接口参数类型#

分为路径参数，请求参数，body 参数

· 路径参数：接口路径中对应的{}中

· 请求参数：在接口路径之后，与接口路径使用 ? 分隔，且请求参数与请求参数使用&分隔

· body 参数：POST 方法放在 json 请求体中的参数

接口返回类型#

· 统一 Content-Type : application/json 格式

经纬度类型#

· 易能时代经纬度为百度坐标系

测试环境退款说明#

· 在测试环境，30 分钟之内申请退款，需要告知易能时代工作人员进行退款操作，正式环境退款最终是需要油站点击同意退款。

三、接口列表（易能时代实现）#

1、油站列表#

接口描述#

合作平台可通过该接口查询获取到易能时代开放给合作方的油站列表数据。需每天分阶段同步数据，每天默认访问次数限制为 24 次。

特别提醒#

少数油站油价信息会在当天某个时刻因客观原因进行调整，为避免客诉，建议合作方每一小时获取一次油站列表数据；同时为了避免各平台在同一时刻请求接口导致无法获取油站列表数据，建议可错峰拉取，例如在一小时中的15分/30分/45分拉取。

请求方式#

Path：#

/oreo/ejiayou_open_api/stations/v2/{platformName}/{sign}/{timestamp}

Method： GET#

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/stations/v2/xxxx/14D431A6AAEA2BED9237C5F0E5211EDD/1531364788

请求参数说明#

参数名	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
sign	是	string	签名见《特定接口签名规则》
timestamp	是	long	时间戳，单位秒

返回参数说明：#

参数名	类型	说明
code	string	200 表示成功，其他失败
msg	string	提示消息，成功为 SUCCESS
data	string	返回 stationList 数据

staionList 说明#

参数名	类型	说明
stationId	int	油站 id
stationName	string	油站名称
provinceName	String	省份
cityName	String	城市
latitude	string	纬度，百度坐标系
longitude	string	经度，百度坐标系
location	string	地址
starNum	string	评分
phone	string	电话
stationPic	string	油站小图
stationBannerPic	string	油站大图
district	string	地区
provinceId	int	省份编号
cityId	int	城市编号
stationType	int	1 中石油，2 中石化，3 壳牌，4 其他

prices 返回参数说明#

参数名	类型	说明
oilId	string	油号 id
oilCode	string	油号
oilType	int	1.汽油 2.柴油
countryPrice	string	国家价
stationPrice	string	油站挂牌价
discountPrice	string	优惠后单价
oilgunCodes	array	油枪号列表

adverts 返回参数说明#

参数名	类型	说明
id	string	id，活动标签的唯一标识
weight	string	权重，999 为最高权重
oilType	int	单字图标文案
singleWordIcon	string	图标内文案
titleWithinIcon	string	图标后文案

2、油站列表分页（必接）- 新增#

接口描述：#

合作平台可通过该接口查询获取到易能时代开放给合作方的油站列表数据。需每天分阶段同步数据，每天默认访问次数限制为 24 次。

请求方式：#

Path:getStationPages/{currentPage}/{pageSize}/{platformName}/{sign}/{timestamp}

Method：GET

路径参数

参数名	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的platformName
sign	是	string	签名
timestamp	是	long	时间戳，单位秒
currentPage	是	int	当前页
pageSize	否	int	分页大小

返回示例

{
    "code": 0,
    "data": [
        {
            "adverts": [
                {}
            ],
            "cityId": 0,
            "cityName": "",
            "invoiceType": 0,
            "latitude": "",
            "location": "",
            "longitude": "",
            "phone": "",
            "prices": [
                {
                    "countryPrice": 0,
                    "discountPrice": 0,
                    "isXyActivity": 0,
                    "oilCode": "",
                    "oilId": 0,
                    "oilType": "",
                    "oilgunCodes": [],
                    "stationPrice": 0
                }
            ],
            "provinceId": 0,
            "provinceName": "",
            "starNum": "",
            "stationBannerPic": "",
            "stationId": 0,
            "stationName": "",
            "stationOrgnization": 0,
            "stationPic": "",
            "stationType": 0
        }
    ],
    "message": "",
    "success": true,
    "totalCount": 0
}

返回参数说明：

参数名	类型	说明
code	string	200 表示成功，其他失败
msg	string	提示消息，成功为 SUCCESS
data	string	返回油站集合数据
success	boolean	是否操作成功
totalCount	Int	总条数

油站集合数据返回参数说明

参数名	类型	说明
stationId	int	油站 id
stationName	string	油站名称
provinceName	String	省份
cityName	String	城市
latitude	string	纬度，百度坐标系
longitude	string	经度，百度坐标系
location	string	地址
starNum	string	评分
phone	string	电话
stationPic	string	油站小图
stationBannerPic	string	油站大图
district	string	地区
provinceId	int	省份编号
cityId	int	城市编号
stationType	int	油站类型 : 1 中石油，2 中石化，3 壳牌，4 其他
defaultpay	int	是否支持微信支付：2：不支持 0：支持

prices 返回参数说明#

参数名	类型	说明
oilId	string	油号 id
oilCode	string	油号
oilType	int	1.汽油 2.柴油
countryPrice	string	国家价
stationPrice	string	油站挂牌价
discountPrice	string	优惠后单价
oilgunCodes	array	油枪号列表

adverts 返回参数说明#

参数名	类型	说明
id	string	id，活动标签的唯一标识
weight	string	权重，999 为最高权重
oilType	int	单字图标文案
singleWordIcon	string	图标内文案
titleWithinIcon	string	图标后文案

3、油站详情信息（必接）#

接口描述#

合作平台通过请油站详细信息接口，获取易能时代油站的详细数据。

请求方式#

Path：#

/oreo/ejiayou_open_api/platform/station/prices/v1/{platformName}/{userPhone}/{stationId}/{sign}/{timestamp}

Method： GET#

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/platform/station/prices/v1/xxxx/13000000000/12/14D431A6AAEA2BED9237C5F0E5211EDD/1531364788

路径参数:#

参数名	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
userPhone	是	string	用户手机号码
stationId	是	string	油站 ID
sign	是	string	签名见《特定接口签名规则》
timestamp	是	long	时间戳，单位秒

返回参数说明：#

参数名	类型	说明
code	string	200 表示成功，其他失败
msg	string	提示消息，成功为 SUCCESS
data	string	业务参数

参数名	类型	说明
feeValue	double	服务费
threshold	double	临界阈值，优惠大于等于这个值收取手续费
limitCount	string	油站每天单个用户优惠次数
orderCount	string	用户当天已加油次数

返回示例：#

{
        "code":  200,
        "msg":  "SUCCESS",
        "data":  {
                "feeRules":  [

        ],
                "adverts":  [

        ],
                "serviceFeeType":  0,
                "limitCount":  2,
                "orderCount":  0,
                "prices":  [
                        {
                                "oilId":  "1",
                                "stationPrice":  "8.00",
                                "oilType":  "1",
                                "discountPrice":  "6.64",
                                "countryPrice":  "8.30",
                                "iconInnerContent":  "满20升前5升享￥6.64/L",
                                "oilgunCodes":  [
                                        "10"               
                ],
                                "isXyActivity":  0,
                                "oilCode":  "92#",
                                "iconOutererContent":  "加油满20升，总价满160元，前5升优惠价为￥6.64/L，超出5升部分优惠价为￥7.92/L；总价不满160元，优惠价为￥7.45/L"            
            },
                        {
                                "oilId":  "2",
                                "stationPrice":  "8.53",
                                "oilType":  "1",
                                "discountPrice":  "7.24",
                                "countryPrice":  "8.83",
                                "iconInnerContent":  "满20升前5升享￥7.24/L",
                                "oilgunCodes":  [
                                        "1"               
                ],
                                "isXyActivity":  1          
            }        
        ]    
    }
}

prices 返回参数说明：#

参数名	类型	说明
oilId	string	油号 id
oilCode	string	油号
oilType	int	1.汽油 2.柴油
countryPrice	string	国家价
stationPrice	string	油站挂牌价
discountPrice	string	优惠后单价
oilgunCodes	array	油枪号列表
isXyActivity	int	0-参与，1-不参与
iconInnerContent	string	图标内文案
iconOutererContent	string	图标外文案，为避免客诉该字段为必接字段

Xy活动规则前端展示参考：#

4、取消订单（必接）#

接口描述#

取消订单接口，第三方可通过该接口取消待支付的订单。

请求方式#

Path：#

/oreo/ejiayou_open_api/platform/orders/cancel/v1/{platformName}/{sign}/{timestamp}

Method：POST#

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/platform/orders/cancel/v1/xxxx/14D431A6AAEA2BE
{
   "outOrderSign": "1000000020059318"
}

路径参数：#

参数名	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
sign	是	string	签名见《特定接口签名规则》
timestamp	是	long	时间戳，单位秒

body 参数说明：#

参数名	必选	类型	说明
outOrderSign	是	string	第三方订单号

返回示例：#

{
    "code": 200,
    "msg": "SUCCESS",
    "data": "取消订单成功"
}

5、用户个人优惠券查询（必接）#

接口描述#

合作平台用户可通过该接口查询在仅限合作方平台使用或者全平台使用的优惠券信息。

请求方式#

Path：#

/oreo/ejiayou_open_api/merchandise/query/(userPhone}/(platformName}/(sign}/(timestamp}

Method：GET#

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/merchandise/query/13000000000/xxxx/14D431A6AAEA2BED9237C5F0E5211EDD/1531364788

路径参数：#

参数名	必选	类型	说明
userPhone	是	string	手机号码
platformName	是	string	平台名称，由易能时代产品提供正式/测试的platformName
sign	是	string	签名见《sign签名规则》
timestamp	是	long	时间戳，单位秒
stationId	否	Integer	易能时代油站 ID
oilgunCode	否	String	易能时代油枪编号
totalAmount	否	String	订单总金额，即用户输入金额，保留两位小数

sign 签名规则：#

名称	说明	示例
beforeKey	我们方提供的固定值(我方产品以邮件告知)	echoejy
timestamp	时间戳, 单位秒, 对应{timestamp}	1531364788
afterKey	我们方提供的固定值(我方产品以邮件告知)	ko0s1dSqwo1XZ

对(beforeKey + timestamp + afterKey)采用 MD5 加密，结果取 32 位大写。

返回参数说明：#

参数名	类型	说明
name	String	优惠券名字
nameExt	String	名字扩展如加油券·元岗开业钜惠
limitTime	String	优惠券有效期
limitTimeExplain	String	有效期扩展说明如全天可用 12 点到 14 点可用等
merchandiseType	int	优惠券类型 1 直减券（现金券） 2 折扣券， 6 直降券
value	String	优惠券值
valueExplain	String	优惠券限制金额解释,满多少可用
enabled	int	1 为可用，2 为不可用
unavailableCause	String	不可用原因如可用本字段为 null
moreRules	String	更多规则
stationNum	int	可用油站数,-1 为全部可用
type	int	优惠券类型 1 为油品 2 为商品 3 为洗车
userCouponId	String	优惠券 id,优惠券唯一表示
limitStations	list	限制油站集合

limitStations 参数说明#

参数名	类型	说明
stationName	String	油站名称
url	String	油站图标 url
stationId	int	油站 id
longitude	String	经度，百度坐标系
latitude	String	纬度，百度坐标系
address	String	油站地址

6、用户个人订单查询（必接）#

接口描述#

用户个人订单查询接口，由易能时代返回用户的历史订单数据

请求方式#

Path：#

/oreo/ejiayou_open_api/orders/histroy/(userPhone}/(platformName}/(sign}/(timestamp}

Method：GET#

Headers:Content-Type:application/json#

示例:

https://pre.ejiayou.com/oreo/ejiayou_open_api/orders/histroy/13000000000/xxxx/(sign}/(timestamp}

路径参数：#

参数名	必选	类型	说明
userPhone	是	string	手机号码
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
sign	是	string	签名见《sign签名规则》
timestamp	是	long	时间戳，单位秒

POST 参数说明：#

参数名	必选	类型	说明
stationIds	是	string	油站id，为空默认查询所有油站订单记录，如指定12号油站输入:12；可传传多个值，用 ‘ ，’ 英文逗号隔开
page	是	int	分页，表示当前页数，每页固定 10 条数据

sign 签名规则：#

名称	说明	示例
beforeKey	我们方提供的固定值(我方产品以邮件告知)	echoejy
timestamp	时间戳, 单位秒, 对应{timestamp}	1531364788
afterKey	我们方提供的固定值(我方产品以邮件告知)	ko0s1dSqwo1XZ

对(beforeKey + timestamp + afterKey)采用 MD5 加密，结果取 32 位大写。

返回参数说明：#

参数名	类型	说明
consumeTimes	String	消费次数
allPaySum	String	共支付
saveMoney	String	共节省
orderList	List	历史订单列表
orderQuantity	int	订单数，只有 stationsIds 不为 0 时才会给出
currentPageNum	int	当前页数
allPageNum	int	所有数量
personalInfo	PersonalInfo 类	个人信息类

历史订单列表参数名	类型	说明
orderId	String	订单号
stationName	String	油站名称
stationPic	String	油站图片
payTime	String	支付时间
orderSum	String	订单金额
reduceSum	String	优惠金额
orderState	int	订单状态 2 为正常订单，3 为退款中订单，4 为已退款订单
hasStationPhone	int	1 为有油站电话 0 为没有油站电话
stationPhone	String	油站电话

personalInfo 参数说明

个人信息类参数名	类型	说明
joinEjiayouDay	String	加入易能时代天数
headUrl	String	微信头像
nickName	String	微信昵称
centerPicUrl	String	中心图片地址
globalPicUrl	String	整图模块地址

7、申请退款（必接）#

接口描述#

用户在第三方平台上发起退款申请，可通过该接口通知易能时代申请是否给予处理退款（30分钟内可用直接用该接口发起退款申请，30分钟后，需要联系易能时代客服发起退款）。申请退款流程参考【常见问题-4.退款申请流程】

请求方式#

Path：#

/oreo/ejiayou_open_api/platform/refund/v1/{platformName}/{userPhone}/{orderId}/{sign}/{timestamp}

Method：GET

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/platform/refund/v1/xxxx/13000000000/14D431A6AAEA2BED9237C5F0E5211EDD/1531364788?reason=付错油站了

路径参数:#

参数名	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
userPhone	是	string	用户手机号码
orderId	是	string	易能时代订单号
sign	是	string	签名见《特定接口签名规则》
timestamp	是	long	时间戳，单位秒

请求参数：#

参数名	必选	类型	说明
reason	是	string	退款原因

返回示例：#

{
    "code": 200, "msg": "SUCCESS",
    "data": {
        "orderId": "9000000020023544",
        "status": "2",
        "refundTime": "2018-11-29 15:19:26",
        "msg": "此订单已经退款", "userPhone":"13111111111"
    }
}

返回参数说明：#

参数名	类型	说明
code	string	200 表示成功，其他失败
msg	string	提示消息，成功为 SUCCESS

Data 说明：#

参数名	类型	说明
orderId	double	易能时代订单 id
refundTime	double	退款时间
status	string	1.订单审核中 2.订单已退款 3.审核不通过
msg	string	退款申请状态信息
userPhon	string	用户手机号

8、发券接口#

接口描述#

合作平台可通过调取该接口给符合条件的指定用户发放易能时代优惠券,由易能时代配置并提供活动id。兑换优惠券流程参考【常见问题-5.用户获取优惠券流程】

请求方式#

Path：#

/oreo/ejiayou_open_api/platform/merchandise/v1/{platformName}/{userPhone}/{sourceId}/{s ign}/{timestamp}

Method：GET

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/platform/merchandise/v1/xxxx/13000000000/183780111/14E3584DBCED5C2CD5DFC27B340E3EC5/1582526116956

请求参数:#

参数名	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
userPhone	是	string	用户手机号码
sourceId	是	string	优惠券活动 id
sign	是	string	签名见《sign 签名规则》
timestamp	是	long	时间戳单位秒对应 url 中{timestamp}

sign 签名规则：#

名称	说明	示例
beforeKey	我们方提供的固定值(我方产品以邮件告知)	echoejy
timestamp	时间戳, 单位秒, 对应{timestamp}	1531364788
afterKey	我们方提供的固定值(我方产品以邮件告知)	ko0s1dSqwo1XZ

对(beforeKey + timestamp + afterKey)采用 MD5 加密，结果取 32 位大写。

返回参数说明：#

参数名	类型	说明
code	string	200 表示成功，其他失败
msg	string	提示消息，成功为 SUCCESS

data 说明#

参数名	类型	说明
status	int	1.成功 0.失败
userPhone	string	用户手机号
sendTime	String	送券时间
msg	String	提示信息，优惠券发放状态信息
sourceId	List	活动 id

coupons 说明#

参数名	类型	说明
couponId	int	优惠券 id
userMerchandiseId	string	用户优惠券编号，即优惠券唯一码
merchandiseType	int	券类型 1 直减券（现金券），2 折扣券， 6 直降券

9、兑换优惠券#

接口描述#

第三方平台可通过该接口对易能时代发放的优惠券兑换码进行兑换。兑换优惠券流程参考【常见问题-5.用户获取优惠券流程】

请求方式#

Path：#

/oreo/ejiayou_open_api/platform/merchandise/exchange/v1/{platformName}/{sign}/{timestamp}

Method： POST

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/platform/merchandise/exchange/v1/test/14E3584DBCED5C2CD5DFC27B340E3EC5/1582526116956

{
   "exchangeCode":"68979920",
   "userPhone":"15813737176"
}

路径参数：#

路径参数	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
sign	是	string	签名见《特定接口签名规则》
timestamp	是	long	时间戳，单位秒

Body 参数：#

参数名	必选	类型	说明
exchangeCode	是	string	兑换码
userPhone	是	string	用户手机号或用户标识

返回示例：#

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "status": 2
    }
}

返回参数说明：#

参数名	类型	说明
code	Integer	200 表示成功，其他失败
msg	String	提示消息，成功为 SUCCESS
data	Object	接口响应参数
status	int	1-成功 2-活动已结束 3-该优惠码已经被领取或您已经参与此活动了 4-优惠码输入错误

10、P端收银台（必接）#

接口描述#

第三方平台可通过该接口创建订单并拉起易能时代支付页面。

请求方式#

Path：#

/pages/ejiayoupay/index_platform_new.html

Method： GET#

示例:签名见《特定接口签名规则》#

https://pre.ejiayou.com/pages/ejiayoupay/index_platform_new.html?totalAmount=2&phoneNumber=13888888888&oilgunCode=1&stationId=12&platformName=test&payType=1&sign=AAE62C51CE5419F92863B8E5AF124CED&timestamp=1591002874194

路径参数说明：#

参数名	必选	类型	说明	是否参与签名
platformName	是	string	平台标识，由易能时代提供	否
stationId	是	int	油站编号	是
sign	是	string	签名见《特定接口签名规则》	否
timestamp	是	long	时间戳单位秒对用url中{timestamp}	否
phoneNumber	是	string	手机号	是
payType	是	int	支付方式 1：微信 2：支付宝	是
oilgunCode	是	int	油枪号	是
totalAmount	是	string	订单金额	是
thirdPartyCouponAmount	否	string	第三方优惠金额（在有优惠的情况下必填）	否
thirdPartyCouponType	否	int	第三方优惠类型（在有优惠的情况下必填）0:不可叠加券；1:可叠加券；3：会员积分抵扣；	否
thirdPartyCouponDes	否	string	第三方优惠描述（在有优惠的情况下必填）	否
thirdPartyCouponUserId	否	string	第三方用户优惠券唯一标识（在有优惠券的情况下必填）	否

返回示例

无

11、财务对账（必接）#

接口描述#

第三方平台可通过该接口查询历史订单，查询时间段最大为 31 天。

请求方式#

Path：#

/oreo/ejiayou_open_api/platform/orders/v2/{platformName}/{sign}/{timestamp}

Method： GET

示例:#

https://pre.ejiayou.com/oreo/ejiayou_open_api/platform/orders/v2/xxxx/14D431A6AAEA2BED9237C5F0E5211EDD/1531364788?startTime=20190612235959&endTime=20190620235959&pageNum=1&pageSize=100

路径参数说明:#

路径参数	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
sign	是	string	签名见《特定接口签名规则》
timestamp	是	long	时间戳，单位秒

请求参数说明：#

拼接参数	必选	类型	说明
orderId	否	string	易能时代订单号
outOrderSign	否	string	合作平台订单号
startTime	是	string	订单支付开始日期时间格式 yyyyMMddHHmmss 例 20190612235959 startTime 与 endTime 需同时传，如果有 orderId 可不传
endTime	是	string	订单支付结束日期时间格式 yyyyMMddHHmmss 例 20190612235959 startTime 与 endTime 需同时传，如果有 orderId 可不传
pageNum	否	int	页码不传默认 1
pageSize	否	int	每页数不传默认 100 最大 500

返回示例

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "total": 1,
        "list": [
            {
                "payOrderTime": "2019-05-14 17:06:24",
                "orderId": "9000000020026004",
                "city": "深圳市",
                "refundTime": "2019-06-14 18:13:39",
                "orderSum": "76.42",
                "oilCode": "92#",
                "oilMass": "11.94",
                "payType": "52",
                "province": "广东省",
                "phone": "F0A69914398DC6CE15E9A9D136665471",
                "couponMoney": "0.00",
                "originalCost": "80.00",
                "stationName": "源政创业大厦加油站",
                "status": 2
            }
        ],
        "pageNum": 1,
        "pageSize": 100
    }
}

返回参数说明：#

参数名	类型	说明
code	string	200 表示成功，其他失败
msg	string	提示消息，成功为 SUCCESS
data	string	订单数据

Data 说明：#

参数名	类型	说明
total	int	查询总条数
pageNum	int	页码
pageSize	int	每页数
list	list	订单列表

list:#

参数名	类型	说明
orderId	string	易能时代内部订单流水号
phone	string	手机号码
province	string	省份名称
city	string	城市名字
stationName	string	油站名称
oilCode	string	油号名称
originalCost	string	机显金额（元）
couponMoney	string	优惠券金额（元）
orderSum	string	用户实际支付金额（元）
oilMass	string	加油升数（升）
payType	string	1-微信 2-支付宝 52-第三方支付
payOrderTime	string	支付时间
refundTime	string	退款时间， status 为 2 时有值
status	int	0 待支付 1-支付 2-退款

12、计算订单（必接）#

接口描述#

在创建订单前，合作平台可通过该接口查询用户该笔订单的应付金额。

请求方式#

Path：#

/oreo/ejiayou_open_api/platform/order/compute/v1/{platformName}/{sign}/{timestamp}

Method：POST

示例:#

https://de.ejiayou.com/oreo/ejiayou_open_api/platform/order/compute/v1/xxxx/14D431A6AAEA2BED9237C5F0E5211EDD/1531364788

路径参数:#

路径参数	必选	类型	说明
platformName	是	string	平台名称，由易能时代产品提供正式/测试的 platformName
sign	是	string	签名见《特定接口签名规则》
timestamp	是	long	时间戳，单位秒

请求示例：

{
   "stationId": 12,
   "oilgunCode": "5",
   "totalAmount": "1",
   "phoneNumber": "183xxxxxxxx"
}

请求参数：#

拼接参数	必选	类型	说明
stationId	是	string	易能时代油站 ID
oilgunCode	是	string	易能时代油枪编号
totalAmount	是	string	订单总金额，即用户输入金额，保留两位小数
phoneNumber	是	string	创建订单的手机号码
userCouponId	是	int	用户优惠券编号

返回示例：

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "oilMass": 37.5940,
        "payAmount": 108.93,
        "serviceFee": 0.00,
        "discountAmount": 91.07,
        "couponAmount": 0,
        "discountPrice": "2.90",
        "countryPrice": 7.13,
        "stationPrice": 5.32,
        "payUnitPrice": 2.8976
    }
}

返回参数说明#

参数名	类型	说明
code	string	200 表示成功，其他失败
msg	string	提示消息，成功为 SUCCESS
data	Object	接口响应参数
oilMass	BigDecimal	油量，单位升，保留两位小数
payAmount	BigDecimal	用户本单应支付的金额，保留两位小数
serviceFee	BigDecimal	服务费，保留两位小数（服务费规则具体咨询易能时代工作人员）
discountAmount	BigDecimal	直降优惠金额（含服务费计算），保留两位小数
couponAmount	BigDecimal	优惠券（若有使用优惠券）优惠金额，保留两位小数
discountPrice	string	最终享受单价
countryPrice	BigDecimal	国家价
stationPrice	BigDecimal	挂牌价
payUnitPrice	BigDecimal	用户享受单价

说明：#

payAmount（应付金额）=totalAmount（订单总金额）-discountAmount（直降优惠金额，含服务费）-couponAmount（优惠券优惠金额）

四、接口列表（合作平台实现）#

1、支付状态/退款状态回调通知#

接口描述#

需由易能时代调用第三方平台接口，调用地址由易能时代工作人员在后台进行配置。

特别提醒#

提供 URL 时请按以下格式告知易能时代工作人员，如：测试环境/正式环境+支付/退款回调 URL
用户完成支付/申请退款，合作方将订单订单状态同步至易能时代，易能时代会把支付/退款结果发送给合作方服务端，合作方服务端接 s 收到结果后无需返回应答。
支付/退款回调通知务必要做签名验证，保证请求参数与易能时代平台参数的一致性

请求方式#

Method： POST

Header application/json

请求示例#

{
    "orderld": "8888889",
    "phone": "15812341234",
    "province":"广东省”，
    "city":"深圳市”，
    "stationName":"丽资加油站”，
    "oilcode”: "92#”,
    "originalcost": "100.00",
    "couponMoney": "0",
    "ordersum": "80.00",
    "oilMass": "12.67",
    "payType": "1",
    "dateTime": "2018-05-07 10:40:12",
    "status": 1,
    "ak": "axmduwq1",
    "nonce": "A03F033911D12BD330171346A0192E5B”,
    "timestamp": "1536146925000",
    "sign": "8cb2862f95aa6949c19b0c8561217588"
}

路径参数：#

参数名	类型	说明	是否参与签名
orderId	string	易能时代内部订单流水号	是
phone	string	手机号码	是
province	string	省份名称	是
city	string	城市名字	是
stationName	string	油站名称	是
oilCode	string	油号名称	是
originalCost	string	机显金额（元）	是
couponMoney	string	优惠券金额（元）	是
orderSum	string	用户实际支付金额（元）	是
oilMass	string	加油升数（升）	是
payType	string	1.微信 2.支付宝	是
dateTime	string	支付/退款时间	是
status	int	1-支付 2-退款	是
ak	string	appkey 加密使用	是
nonce	string	32 位随机字母数字组合	是
timestamp	string	时间戳	是
sign	string	签名	否

其他可选参数#

参数名	类型	说明	是否参与签名
stationId	string	油站 id	是
couponId	string	优惠券 id	是
userMerchandiseId	string	用户优惠券号码，唯一号码	是
stationPrice	string	油站挂牌价	是
discountPrice	string	最终享受单价	是
countryPrice	string	国家价	是
outState	string	从 H5 传入的 P 端自定义参数重新传回给 P 端，跳转前把数据放进 seesionStorage 里	是

返回示例#

{
    "returnCode":"SUCCESS"
}

响应参数：#

参数名	必填	类型	说明
returnCode	是	String 返回码 SUCCESS 为成功，即订单支付成功或订单退款成功，否则为失败，会重复回调 8 次，每次间隔 15 秒（注意：支付成功/退款成功通知为油站方与用户核实确认的订单）

签名验证方法:#

1.按字段的 key 进行排序，拼接 key=value 字符，使用&符号连接，最后加上 sk(由我方提供)(注意:sk 前也用 & 连接)Charset 为 UTF8

示例

 ak=axmduwq1&city=深圳市&couponMoney=0&dateTime=2019-01-1508:47:18&nonce=5eb667eff4a0462ba358cbf0f64be20e&oilCode=92#&oilMass=20.00&orderId=1000000050312339&orderSum=120.00&originalCost=131.00&payType=1&phone=13509605015& province=广东省&stationName=中石油南海湾加油站&status=1&timestamp=1547706551446&0ba224ca335bf18xa12aasd1

2.对整体字符串进行 MD5 加密,Charset 为 UTF8

 apache:
 //依赖
 <dependency
 <groupldcommons-codec</groupld
 <artifactldcommons-codec</artifactld
 <version1.9</version
 </dependency
 //代码
 DigestUtils.md5Hex(str);
 spring:
 //依赖
 <dependency
 <groupIdorg.springframework</groupId
 <artifactIdspri ng-core</artifactId
 <version4.3.6.RELEASE</version
 </dependency
 //代码
 DigestUtils.md5DigestAsHex(str);

五、特定接口签名规则#

签名生成的通用步骤如下：#

API对接对(beforeKey + timestamp + afterKey)采用 MD5 加密，结果取 32 位大写

H5对接：使用#号连接sign=MD5(app_key+#+timestamp+#+app_secret)

六、错误码#

在对接过程中出现的异常中带有错误码 Code 和错误提示 msg，常见 code 和 msg 值及对应解决方案如下所示：

code	msg	解决方案
400	签名错误	1、首先，核实签名是否按照文档的签名规则进行生成。 2、其次，看app_key、app_secret等是否于易能时代提供的一致
19112	找不到对应平台	/
19113	系统异常，无法识别当前用户	/
19117	获取用户唯一标识失败	/
19121	油站功能未开放，请联系易能时代运营	/
19125	该油枪数据不存在	/
19126	金额最高不能超过:xxx	/
19127	金额最低不能小于:xxx	/

注意：在联系易能时代解决问题时需要告知环境信息，如：正式环境/测试环境

七、常见问题#

1. 易能时代目面向平台端优惠券类型有哪些#

现金券：订单金额需满足一定的最低额度才可使用，例如满 200 减 20 元。（特殊情况：A 油站满 200 直降 10 元，用户领取满 200 减 20 元优惠券，那么用户的最终支付金额为 200-20-10=170 元）；

折扣券：使用折扣券购买油品时可打折；

以上优惠券均可配置可叠加和不可叠加两种形式，同时也可配置仅部分平台使用或全平台使用，具体的运营配置规则需和易能时代运营进行沟通确认。

2. 为什么易能时代 app 的油站数和获取油站列表数不一致，或是易能时代 app 中展示的参数接口文档中未看到。#

因客观原因少量油站不支持在第三方平台透出。与易能时代 app 为两种不同的展现方式，最终参数以接口文档中的返回参数为准，具体可以参考推荐的平台.

3. 已经按照签名规则进行生成，为什么还是提示签名错误#

API+收银台对接中，有两套签名规则，均在相应接口中有说明。

4. 退款申请流程#

30 分钟内可用申请退款接口发起退款申请，30 分钟后需要联系易能时代客服发起退款，30 分钟后用户电话联系易能时代客服退款成功通知仅能通过【退款回调接口】返回退款成功通知，油站不同意退款的订单不会返回任何通知。以下是 30 分钟内退款申请流程：

5. 用户获取优惠券流程#

6. 用户个人优惠券查询接口返回的优惠券具体是哪种状态的优惠券：#

优惠券分为三种状态可用、不可用、已使用，目前仅返回可用和不可用这两种状态的优惠券，不只是当前有效的优惠券，也有可能是不在使用时间范围内的优惠券或者不满足使用条件的优惠券。

可用：该优惠全部返回,且在 unavailableCause 中返回 NULL，标明优惠券在当前时间范围内可用

不可用：该状态优惠券页全部返回，且在 unavailableCause 中会标明不可用原因，如：未到使用时间、限首单使用等

已使用：已使用优惠券信息是不返回的，除非用户在支付完成后又申请退款且退款成功，该优惠券就会信息就会返回，优惠券状态会按照可用和不可用两种状态展示。

7. 用户待支付订单会在一定时间范围内系统自动取消订单吗#

目前系统不支持自动取消订单，需要平台调取取消订单进行订单取消操作。如果用户一直未支付订单且为取消，订单状态会一直处在【待支付】状态。

一、 对接流程#

二、 对接须知#

参数信息#

环境信息#

测试须知#

接口参数类型#

接口返回类型#

经纬度类型#

测试环境退款说明#

三、 接口列表（易能时代实现）#

1、油站列表#

接口描述#

特别提醒#

请求方式#

Path：#

Method： GET#

示例:#

请求参数说明#

返回参数说明：#

staionList 说明#

prices 返回参数说明#

adverts 返回参数说明#

温馨提示：adverts 返回参数建议在油站列表中进行展示，方便后期做活动运营，如不展示后续运营活动可能存在客诉情况，展示示例如下（仅供参考）：#

2、油站列表分页（必接）- 新增#

接口描述：#

请求方式：#

prices 返回参数说明#

adverts 返回参数说明#

3、油站详情信息（必接）#

接口描述#

请求方式#

Path：#

Method： GET#

示例:#

路径参数:#

返回参数说明：#

返回示例：#

prices 返回参数说明：#

Xy活动规则前端展示参考：#

4、取消订单（必接）#

接口描述#

请求方式#

Path：#

Method：POST#

示例:#

路径参数：#

body 参数说明：#

返回示例：#

5、用户个人优惠券查询（必接）#

接口描述#

请求方式#

Path：#

Method：GET#

示例:#

路径参数：#

sign 签名规则：#

返回参数说明：#

limitStations 参数说明#

6、用户个人订单查询（必接）#

接口描述#

请求方式#

Path：#

Method：GET#

Headers:Content-Type:application/json#

路径参数：#

POST 参数说明：#

sign 签名规则：#

返回参数说明：#

7、申请退款（必接）#

接口描述#

请求方式#

Path：#

示例:#

路径参数:#

请求参数：#

返回示例：#

返回参数说明：#

Data 说明：#

8、发券接口#

接口描述#

一、对接流程#

二、对接须知#

三、接口列表（易能时代实现）#