API
一、对接须知#
参数信息#
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 分钟之内申请退款，需要告知易能时代工作人员进行退款操作，正式环境退款最终是需要油站点击同意退款。
推荐参考平台#
货拉拉、高德地图
二、 对接流程#
核心业务流程说明
A、合作方服务端向易能时代调取“油站列表”接口，该接口每天限制最多只能调取 24 次。易能时代根据合作方的请求，向合作方返回油站列表信息，合作方用户端向合作方服务端请求油站信息列表，合作方服务端根据以获取的油站列表返回对应油站列表信息给到合作方用户端；
B、合作方用户端向合作方服务端请求进入油站详情页，合作方服务端向易能时代“油站详细信息”接口发起请求，获取油站详情信息，易能时代向合作方服务端返回对应油站详情信息，合作方用户端获取油站详情信息，进入油站详情信息界面；
C、合作方用户选定油枪、油品及购买金额后，向合作方服务端提交订单，合作方服务端向易能时代“创建订单”接口发起请求；
a、如果合作方服务端向易能时代请求校验未通过，则返回创建失败的结果，合作方服务端收到易能时代订单创 建失败的结果，返回给合作方用户端，此时合作方用户端需要重新走订单支付流程；
b、如果合作方服务端向易能时代请求校验通过，则返回创建成功的结果，合作方服务端收到易能时代订单创建 成功的结果，返回给合作方用户端，订单创建成功；
D、合作方用户端向合作方服务端发起支付请求，合作方服务端向合作方用户端返回支付结果；
E、如果用户支付成功，合作方服务端向易能时代“支付接口”接口发起请求，告知易能时代订单支付结果，易能时代返回回告请求结果给到合作方服务端。用户支付完成，油站放行。
三、 接口列表（易能时代实现）#
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/14D431A6AAEA2BED9237C 5F0E5211EDD/1531364788
路径参数：
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的 platformName |
| sign | 是 | string | 签名见《特定接口签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒 |
返回示例：
返回参数说明：
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | string | 200 表示成功，其他失败 |
| msg | string | 提示消息，成功为 SUCCESS |
| data | string | 返回 油站集合 数据 |
油站集合数据返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| 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 | 图标后文案 |
温馨提示：adverts 返回参数建议在油站列表中进行展示，方便后期做活动运营，如不展示后续运营活动可能存在客诉情况，展示示例如下（仅供参考）：#
2、油站列表分页（必接）- 新增#
接口描述：#
合作平台可通过该接口查询获取到易能时代开放给合作方的油站列表数据。需每天分阶段同步数据，每天默认访问次数限制为 24 次。
请求方式：#
Path:getStationPages/{currentPage}/{pageSize}/{platformName}/{sign}/{timestamp}
Method：GET
路径参数
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的platformName |
| sign | 是 | string | 签名 |
| timestamp | 是 | long | 时间戳，单位秒 |
| currentPage | 是 | int | 当前页 |
| pageSize | 否 | int | 分页大小 |
返回示例
返回参数说明：
| 参数名 | 类型 | 说明 |
|---|---|---|
| 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:/gateway/ensd-service/openApi/stations/detail/v1/{platformName}/{stationId}/{userPhone}/{sign}/{timestamp}
Method：GET
路径参数：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的platformName |
| userPhone | 是 | string | 手机号码 |
| stationId | 否 | Integer | 易能时代油站 ID |
| sign | 是 | string | 签名 |
| timestamp | 是 | long | 时间戳，单位秒 |
返回示例：#
返回参数说明：#
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | string | 200 表示成功，其他失败 |
| msg | string | 提示消息，成功为 SUCCESS |
| data | data | 接口响应参数 |
| 参数名 | 必选 | 类型 |
|---|---|---|
| limitCount | 是 | string |
| orderCount | 是 | string |
feeRules返回参数说明#
| 参数名 | 必选 | 类型 |
|---|---|---|
| feeValue | 是 | double |
| threshold | 是 | double |
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/order/compute/v1/{platformName}/{sign}/{timestamp}
Method： POST
请求示例：#
路径参数:#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的 platformName |
| sign | 是 | string | 签名见 《特定接口签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒 |
请求参数：#
| 拼接参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
| stationId | 是 | string | 易能时代油站 ID |
| oilgunCode | 是 | string | 易能时代油枪编号 |
| totalAmount | 是 | string | 订单总金额，即用户输入金额，保留两位小数 |
| phoneNumber | 是 | string | 创建订单的手机号码 |
| userCouponId | 是 | int | 用户优惠券编号 |
返回示例：
返回参数说明#
| 参数名 | 类型 | 说明 |
|---|---|---|
| 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（优惠券优惠金额）
5、创建订单#
接口描述#
为第三方平台提供统一的创建订单接口。
请求方式#
Path：/oreo/ejiayou_open_api/orders/v2/{platformName}/{sign}/{timestamp}
Method：POST
路径参数：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的 platformName |
| sign | 是 | string | 签名见《特定接口签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒 |
请求示例：#
请求参数说明：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| stationId | 是 | Integer | 易能时代油站 ID |
| oilgunCode | 是 | Integer | 易能时代油枪编号 |
| totalAmount | 是 | string | 订单总金额，即用户输入金额，保留两位小数 |
| phoneNumber | 是 | string | 创建订单的手机号码 |
| userCouponId | 否 | String | 用户优惠券编号 |
| outOrderSign | 否 | String | 第三方订单号 |
响应示例：#
返回公共参数说明：#
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | Integer | 200 表示成功，其他失败 |
| msg | string | 提示消息，成功为 SUCCESS |
| data | Object | 接口响应参数 |
返回接口参数说明：#
| 参数名 | 类型 | 说明 |
|---|---|---|
| orderSign | String | 易能时代订单标识 |
| oilMass | BigDecimal | 油量，单位升，保留两位小数 |
| payAmount | BigDecimal | 用户支付金额，保留两位小数 |
| discountPrice | string | 用户最终享受单价 |
| couponAmount | BigDecimal | 优惠券（若有使用优惠券）优惠金额，保留两位小数 |
6、支付接口#
接口描述#
为第三方平台提供统一的支付订单接口。
请求方式#
Path：/oreo/ejiayou_open_api/orders/v1/payments/{orderSign}/{platformName}/{sign}/{timestamp}
Method： POST
路径参数说明：#
| 路径参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
| orderSign | 是 | String | 易能时代订单标识 |
| sign | 是 | String | 签名见《特定接口签名规则》 |
| platformName | 是 | String | 平台名称，由易能时代产品提供正式/测试的 platformName |
| timestamp | 是 | Long | 时间戳，单位秒 |
请求示例
请求参数说明：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| outOrderSign | 是 | string | 第三方平台订单标识 |
| payAmount | 是 | string | 用户支付金额 |
返回示例
返回参数说明：#
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | string | 200 表示成功，其他失败 |
| msg | string | 提示消息，成功为 SUCCESS |
| data | data | 接口响应参数 |
7、申请退款#
接口描述#
用户在第三方平台上发起退款申请，可通过该接口通知易能时代申请是否给予处理退款（30分钟内可用直接用该接口发起退款申请，30分钟后，需要联系易能时代客服发起退款）。申请退款流程参考【常见问题-4.退款申请流程】
请求方式#
Path：/oreo/ejiayou_open_api/platform/refund/v1/{platformName}/{userPhone}/{orderId}/{sign}/{timestamp}
Method：GET
路径参数:#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的 platformName |
| userPhone | 是 | string | 用户手机号码 |
| orderId | 是 | string | 易能时代订单号 |
| sign | 是 | string | 签名见《特定接口签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒 |
返回示例：#
返回参数说明：#
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | string | 200 表示成功，其他失败 |
| msg | string | 提示消息，成功为 SUCCESS |
Data 说明：#
| 参数名 | 类型 | 说明 |
|---|---|---|
| orderId | double | 易能时代订单 id |
| refundTime | double | 退款时间 |
| status | string | 1.订单审核中 2.订单已退款 3.审核不通过 |
| msg | string | 退款申请状态信息 |
| userPhone | string | 用户手机号 |
8、取消订单#
接口描述#
取消订单接口，第三方可通过该接口取消待支付的订单。
请求方式#
Path：/oreo/ejiayou_open_api/platform/orders/cancel/v1/{platformName}/{sign}/{timestamp}
Method：POST
示例：
路径参数：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的 platformName |
| sign | 是 | string | 签名见《特定接口签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒 |
body 参数说明：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| outOrderSign | 是 | string | 第三方订单号 |
返回示例：#
9、用户个人订单查询#
接口描述#
用户个人订单查询接口，由易能时代返回用户的历史订单数据
请求方式#
Path： /oreo/ejiayou_open_api/orders/histroy/(userPhone}/(platformName}/(sign}/(timestamp}
Method：GET
Headers:Content-Type:application/json
路径参数：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| 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 | 整图模块地址 |
10、财务对账#
接口描述#
第三方平台可通过该接口查询历史订单，查询时间段最大为 31 天。
请求方式#
Path：/oreo/ejiayou_open_api/platform/orders/v2/{platformName}/{sign}/{timestamp}
Method： GET
路径参数:#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| 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 | 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-退款 |
11、用户个人优惠券查询#
接口描述#
合作平台用户可通过该接口查询在仅限合作方平台使用或者全平台使用的优惠券信息。
请求方式#
Path：/oreo/ejiayou_open_api/merchandi se/query/(userPhone}/(platformName}/(sign}/(timestamp}
Method：GET
路径参数：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| userPhone | 是 | string | 手机号码 |
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的platformName |
| sign | 是 | string | 签名 |
| timestamp | 是 | long | 时间戳，单位秒 |
POST参数说明：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| stationId | 是 | Integer | 油站id，为空默认查询所有油站订单记录，如指定12号油站输入:12；可传传多个值，用 ‘ ，’ 英文逗号隔开 |
| page | 是 | int | 分页，表示当前页数，每页固定10条数据 |
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 | 油站地址 |
12、发券接口#
接口描述#
合作平台可通过调取该接口给符合条件的指定用户发放易能时代优惠券,由易能时代配置并提供活动 id。兑换优惠券流程参考【常见问题-5.用户获取优惠券流程】
请求方式#
Path：/oreo/ejiayou_open_api/platform/merchandise/v1/{platformName}/{userPhone}/{sourceId}/{s ign}/{timestamp}
Method：GET
请求参数:#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| 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 直降券 |
13、兑换优惠券#
接口描述#
第三方平台可通过该接口对易能时代发放的优惠券兑换码进行兑换。兑换优惠券流程参考【常见问题-5.用户获取优惠券流程】
请求方式#
Path：/oreo/ejiayou_open_api/platform/merchandise/exchange/v1/{platformName}/{sign}/{timestamp}
Method： POST
示例:#
路径参数：#
| 路径参数 | 必选 | 类型 | 说明 |
|---|---|---|---|
| platformName | 是 | string | 平台名称，由易能时代产品提供正式/测试的 platformName |
| sign | 是 | string | 签名见《特定接口签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒 |
Body 参数：#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| exchangeCode | 是 | string | 兑换码 |
| userPhone | 是 | string | 用户手机号或用户标识 |
返回示例：#
返回参数说明：#
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | Integer | 200 表示成功，其他失败 |
| msg | String | 提示消息，成功为 SUCCESS |
| data | Object | 接口响应参数 |
| status | int | 1-成功 2-活动已结束 3-该优惠码已经被领取或您已经参与此活动了 4-优惠码输入错误 |
四、接口列表（合作平台实现）#
1、支付状态/退款状态回调通知#
接口描述#
需由易能时代调用第三方平台接口，调用地址由易能时代工作人员在后台进行配置。
特别提醒#
提供 URL 时请按以下格式告知易能时代工作人员，如：测试环境/正式环境+支付/退款回调 URL
用户完成支付/申请退款，合作方将订单订单状态同步至易能时代，易能时代会把支付/退款结果发送给合作方服务端，合作方服务端接 s 收到结果后无需返回应答。
支付/退款回调通知务必要做签名验证，保证请求参数与易能时代平台参数的一致性
请求方式#
Method： POST
Header application/json
请求示例#
路径参数：#
| 参数名 | 类型 | 说明 | 是否参与签名 |
|---|---|---|---|
| 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 | 是 | String 返回码 SUCCESS 为成功，即订单支付成功或订单退款成功，否则为失败，会重复回调 8 次，每次间隔 15 秒（注意：支付成功/退款成功通知为油站方与用户核实确认的订单） |
签名验证方法:#
1.按字段的 key 进行排序，拼接 key=value 字符，使用&符号连接，最后加上 sk(由我方提供)(注意:sk 前也 用 & 连接)Charset 为 UTF8
示例
2.对整体字符串进行 MD5 加密,Charset 为 UTF8
五、特定接口签名规则#
签名生成的通用步骤如下：#
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+H5对接中，有两套签名规则，均在相应接口中有说明。
4. 退款申请流程#
30分钟内可用申请退款接口发起退款申请，30 分钟后需要联系易能时代客服发起退款，30 分钟后用户电话联系易能时代客服退款成功通知仅能通过【退款回调接口】返回退款成功通知，油站不同意退款的订单不会返回任何通知。以下是 30 分钟内退款申请流程：
5. 用户获取优惠券流程#
6. 用户个人优惠券查询接口返回的优惠券具体是哪种状态的优惠券：#
优惠券分为三种状态可用、不可用、已使用，目前仅返回可用和不可用这两种状态的优惠券，不只是当前有效的优惠券，也有可能是不在使用时间范围内的优惠券或者不满足使用条件的优惠券。
可用：该优惠全部返回,且在 unavailableCause 中返回 NULL，标明优惠券在当前时间范围内可用
不可用：该状态优惠券页全部返回，且在 unavailableCause 中会标明不可用原因，如：未到使用时间、限首单使用等
已使用：已使用优惠券信息是不返回的，除非用户在支付完成后又申请退款且退款成功，该优惠券就会信息就会返回，优惠券状态会按照可用和不可用两种状态展示。
7.用户待支付订单会在一定时间范围内系统自动取消订单吗#
目前系统不支持自动取消订单，需要平台调取取消订单进行订单取消操作。如果用户一直未支付订单且为才做，订单状态会一直处在【待支付】状态。