H5传手机号
一、 对接流程#
1、合作方根据接口文档直接生成H5链接
2、合作方用户端，根据生成的H5链接跳转到易能时代平台，完成加油服务
二、 对接须知#
参数信息#
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、H5油站列表页（必接）#
接口描述#
用户通过拼接相关参数进入油站首页。
请求方式#
Path： /pages/platform/soulList/detail.html
Method： GET
示例:
请求参数:#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| plat | 是 | string | 平台标识 |
| userPhone | 是 | string | 手机号码 |
| sign | 是 | string | 签名见《sign签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒，超时5分钟 |
| stationId | 是 | long | 油站id |
| longitude | 否 | long | 经度，用户坐标 |
| latitude | 否 | long | 纬度，用户坐标 |
sign 签名规则：#
| 名称 | 说明 | 示例 |
|---|---|---|
| app_key | 我们方提供的固定值 | kkkkkkkk |
| timestamp | 和请求所传｛timestamp｝相等 | 1531364788 |
| app_secret | 我们方提供的固定值 | ssssssss |
示例 ：使用#号连接sign = MD5(kkkkkkkk + # + timestamp + # + ssssssss)。特别提醒：该签名区分大小写
2、H5 油站详情页#
接口描述#
合作方平台通过此接口生成H5链接，用户通过点击H5链接进入到属于易能时代的油站详情页。
请求方式#
Path： /pages/platform/soulList/detail.html
Method： GET
示例:
请求参数:#
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| plat | 是 | string | 平台标识 |
| userPhone | 是 | string | 手机号码 |
| sign | 是 | string | 签名见《sign签名规则》 |
| timestamp | 是 | long | 时间戳，单位秒，超时5分钟 |
| stationId | 是 | long | 油站id |
| longitude | 否 | long | 经度，用户坐标 |
| latitude | 否 | long | 纬度，用户坐标 |
| oil | 是 | 油品 | 如 92# |
| oilId | 是 | Int | 油品id，如 1 |
sign 签名规则：#
| 名称 | 说明 | 示例 |
|---|---|---|
| app_key | 我们方提供的固定值 | kkkkkkkk |
| timestamp | 和请求所传｛timestamp｝相等 | 1531364788 |
| app_secret | 我们方提供的固定值 | ssssssss |
示例 ：使用#号连接sign = MD5(kkkkkkkk + # + timestamp + # + ssssssss)。特别提醒：该签名区分大小写
3、用户个人订单查询（必接）#
接口描述#
请求方式#
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 | 整图模块地址 |
4、发券接口#
接口描述#
合作平台可通过调取该接口给符合条件的指定用户发放易能时代优惠券,由易能时代配置并提供活动 id。兑换优惠券流程参考【常见问题-4.用户获取优惠券流程】
请求方式#
Path：#
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 直降券 |
5、财务对账#
接口描述#
第三方平台可通过该接口查询历史订单，查询时间段最大为 31 天。
请求方式#
Path：#
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-退款 |
四、接口列表（合作平台实现）#
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)
签名示例#
假设请求接口为 oreo/ejiayou_open_api/orders/v2/{platformName}/{sign}/{timestamp}
假设传送的参数为：stationId 为 12，oilgunCode 为 5，totalAmount 为 1，phoneNumber 为 183xxxxxxxx
1、POST 请求 body 参数格式 json 格式
2、GET 请求参数格式#
第一步：对参数按照 key=value 的格式，并按照参数名 ASCII 字典序排序如下：
第二步：拼接 timestamp 和平台的 beforeKey 、 afterKey
最后将得到的 sign 值以路径参数的形式发送即可。
六、错误码#
在对接过程中出现的异常中带有 错误码 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. 已经按照签名规则进行生成，为什么还是提示签名错误#
H5对接中，有三套签名规则，均在相应接口中有说明。
4. 用户获取优惠券流程#
