易能时代SDK使用说明文档（H5接入传手机号）V1.2

一、对接流程#

1、合作方根据接口文档直接生成 H5 链接

2、合作方用户端，根据生成的 H5 链接跳转到易能时代平台，完成加油服务

二、对接须知#

参数信息#

· platformName，beforeKey，afterKey 等调取接口必要的信息由易能时代产品提供。

环境信息#

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

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

测试须知#

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

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

经纬度类型

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

三、 Java 项目使用说明#

说明#

此 JavaSDK 可供 springboot 项目与普通 spring 项目或非 spring 项目使用。
注意：请将包ejiayou-openapi-1.0.0-jar-with-dependencies.jar先上传至私有仓库

Extension : jar
groupId : com.ejiayou.platform
artifactId : ejiayou-openapi
version : 1.0.0

1、springboot 项目#

提示：具体请参考demo-springboot项目

1、引包#

1.maven :#

<dependency>
<groupId>com.ejiayou.platform</groupId>
<artifactId>ejiayou-openapi</artifactId>
<version>1.0.0</version>
</dependency>

2.gradle:#

dependencies {
    compile "com.ejiayou.platform:ejiayou-openapi:1.0.0"
}

3.直接使用 jar 包引入#

2.配置#

ejiayou:
  domain: https://dev.ejiayou.com
  platform-name: pdcszy
  before-key: cesJ5RccqdSRdciz
  after-key: uOeNqX7GVreYBzpv
  plat: XZe9X
  app_key: cesJ5RccqdSRdciz
  app_secret: uOeNqX7GVreYBzpv

Bean 配置

@Configuration
public class EjiayouOpenapiConfig {

    @Value("${ejiayou.domain}")
    private String domain;

    @Value("${ejiayou.platform-name}")
    private String platformName;

    @Value("${ejiayou.before-key}")
    private String beforeKey;

    @Value("${ejiayou.after-key}")
    private String afterKey;

    @Value("${ejiayou.app_key}")
    private String appKey;

    @Value("${ejiayou.app_secret}")
    private String appSecret;

    @Value("${ejiayou.plat}")
    private String plat;

    @Bean
    public EjiayouApiClient ejiayouApiClient() {
        EjiayouConfig config = new EjiayouConfig(domain, platformName, beforeKey, afterKey, plat, appKey, appSecret);
        return Ejiayou.create(config);
    }
}

参数说明

参数名	必选	类型	说明
domain	是	string	必须参数, 易能时代环境地址测试: https://dev.ejiayou.com 正式: https://api.ejiayou.com
platform-name	是	string	平台标识，调用 API 接口必须参数，由易能时代产品提供
before-key	是	string	调用 API 接口必须参数，由易能时代产品提供
after-key	是	string	调用 API 接口必须参数，由易能时代产品提供
plat	是	string	平台标识，生成 H5 链接必须参数，由易能时代产品提供
app-key	是	string	生成 H5 链接必须参数，由易能时代产品提供
app-secret	是	string	生成 H5 链接必须参数，由易能时代产品提供
longitude	是	string	经度，百度坐标
latitude	是	string	纬度，百度坐标
outState	是	string	该字段支持合作方自定义传参，传进来的参数会附加在订单数据上，实现合作方可对加油服务分渠道区分订单

3、使用#

API 调用 :#

    @Autowired
    private EjiayouApiClient ejiayouApiClient;
    ejiayouApiClient.stationList();

2、普通 spring 项目#

提示：具体请参考demo-spring项目

1、引包#

1.maven :#

<dependency>
    <groupId>com.ejiayou.platform</groupId>
    <artifactId>ejiayou-openapi</artifactId>
    <version>1.0.0</version>
</dependency>

2.gradle:#

dependencies {
    compile "com.ejiayou.platform:ejiayou-openapi:1.0.0"
}

3.直接使用 jar 包引入#

2、配置#

初始化 Bean
@Bean

public EjiayouApiClient ejiayouApiClient() {
   EjiayouConfig config = new EjiayouConfig(domain, platformName, beforeKey, afterKey, plat, appKey, appSecret);
    return Ejiayou.create(config);
}

参数说明

参数名	必选	类型	说明
domain	是	string	必须参数, 易能时代环境地址测试: https://dev.ejiayou.com 正式: https://api.ejiayou.com
platform-name	是	string	平台标识，调用 API 接口必须参数，由易能时代产品提供
before-key	是	string	调用 API 接口必须参数，由易能时代产品提供
after-key	是	string	调用 API 接口必须参数，由易能时代产品提供
plat	是	string	平台标识，生成 H5 链接必须参数，由易能时代产品提供
app-key	是	string	生成 H5 链接必须参数，由易能时代产品提供
app-secret	是	string	生成 H5 链接必须参数，由易能时代产品提供
longitude	是	string	经度，百度坐标
latitude	是	string	纬度，百度坐标
outState	是	string	该字段支持合作方自定义传参，传进来的参数会附加在订单数据上，实现合作方可对加油服务分渠道区分订单

3、使用#

API 调用 :#

@Autowired
private EjiayouApiClient ejiayouApiClient;
ejiayouApiClient.stationList();

3、普通 Java 项目#

提示：具体请参考demo-java项目

1、引包#

1.maven :#

<dependency>
    <groupId>com.ejiayou.platform</groupId>
    <artifactId>ejiayou-openapi</artifactId>
    <version>1.0.0</version>
</dependency>

2.gradle:#

dependencies {
    compile "com.ejiayou.platform:ejiayou-openapi:1.0.0"
}

3.直接使用 jar 包引入#

2、配置#

初始化 config

EjiayouConfig config = new EjiayouConfig(domain, platformName, beforeKey, afterKey, plat, appKey, appSecret);

参数说明

参数名	必选	类型	说明
domain	是	string	必须参数, 易能时代环境地址测试: https://dev.ejiayou.com 正式: https://api.ejiayou.com
platform-name	是	string	平台标识，调用 API 接口必须参数，由易能时代产品提供
before-key	是	string	调用 API 接口必须参数，由易能时代产品提供
after-key	是	string	调用 API 接口必须参数，由易能时代产品提供
plat	是	string	平台标识，生成 H5 链接必须参数，由易能时代产品提供
app-key	是	string	生成 H5 链接必须参数，由易能时代产品提供
app-secret	是	string	生成 H5 链接必须参数，由易能时代产品提供
longitude	是	string	经度，百度坐标
latitude	是	string	纬度，百度坐标
outState	是	string	该字段支持合作方自定义传参，传进来的参数会附加在订单数据上，实现合作方可对加油服务分渠道区分订单

3、使用#

API 调用 :#

@Autowired
private EjiayouApiClient ejiayouApiClient;
ejiayouApiClient.stationList();

四、PHP 项目使用说明#

说明#

供使用 PHP 开发合作方使用。

PHP 项目#

1、下载#

使用 composer 工具下载
打开命令行工具,进入项目目录下执行:

composer require ejiayou/p-openapi

2、配置#

安装完成后,打开新增的vendor文件夹，找到里边的EjyConfig.php，按对接文档给应的配置参数做修改即可(文件路径: vendor/ejiayou/p-openapi/src/EjyConfig.php)

const Domain = 'https://dev.ejiayou.com';
const PlatformName = 'test';
const BeforeKey = 'lvcXRvK1gT0ygNKy';
const AfterKey = '30bvIWj71oofv0Iv';
const Plat = 'SLnTK';
const AppKey = 'lvcXRvK1gT0ygNKy';
const AppSecret = '30bvIWj71oofv0Iv';
const Version = '1.0.0';

参数说明

参数名	必选	类型	说明
domain	是	string	必须参数, 易能时代环境地址测试: https://dev.ejiayou.com 正式: https://api.ejiayou.com
platform-name	是	string	平台标识，调用 API 接口必须参数，由易能时代产品提供
before-key	是	string	调用 API 接口必须参数，由易能时代产品提供
after-key	是	string	调用 API 接口必须参数，由易能时代产品提供
plat	是	string	平台标识，生成 H5 链接必须参数，由易能时代产品提供
app-key	是	string	生成 H5 链接必须参数，由易能时代产品提供
app-secret	是	string	生成 H5 链接必须参数，由易能时代产品提供
longitude	是	string	经度，百度坐标
latitude	是	string	纬度，百度坐标
outState	是	string	该字段支持合作方自定义传参，传进来的参数会附加在订单数据上，实现合作方可对加油服务分渠道区分订单
Version	是	string	SDK 版本号

3、使用#

生成 H5 链接：#

如果使用的是laravel、yii框架等，使用示例:

use Ejiayou\Platform\Openapi\EjyApi;
use Ejiayou\Platform\Openapi\Model\Api\H5UrlParam;
    $param = new H5UrlParam();
    $param->SetUserPhone(13316831108);
    $param->SetLongitude("113.251307");
    $param->SetLatitude("23.132411");

    print_r(EjyApi::h5Url($param)["data"]);

非 PHP 框架使用示例:

require_once __DIR__."/vendor/autoload.php";

use Ejiayou\Platform\Openapi\EjyApi;
use Ejiayou\Platform\Openapi\Model\Api\H5UrlParam;
    $param = new H5UrlParam();
    $param->SetUserPhone(13316831108);
    $param->SetLongitude("113.251307");
    $param->SetLatitude("23.132411");

    print_r(EjyApi::h5Url($param)["data"]);

API 调用：#

如果使用的是laravel、yii框架等，使用示例:

use Ejiayou\Platform\Openapi\EjyApi;
use Ejiayou\Platform\Openapi\Model\Api\OrderQueryParam;

$param = new OrderQueryParam();
$param->SetDate("20191031");

print_r(EjyApi::orderQuery($param)["data"]);

非 PHP 框架使用示例:

require_once __DIR__."/vendor/autoload.php";

use Ejiayou\Platform\Openapi\EjyApi;
use Ejiayou\Platform\Openapi\Model\Api\OrderQueryParam;

$param = new OrderQueryParam();
$param->SetDate("20191031");

print_r(EjyApi::orderQuery($param)["data"]);

五、API 参数说明#

1、财务对账 : finance(FinanceParam param)#

接口描述#

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

FinanceParam 参数：#

拼接参数	必选	类型	说明
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": "13312345678",
         "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	string	1-支付 2-退款

2、用户个人订单查询 :orderHistory(OrderHistoryParam param)#

接口描述：#

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

OrderHistoryParam 参数：#

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

返回示例：

{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "personalInfo": {
            "globalPicUrl": null,
            "nickName": null,
            "headUrl": null,
            "joinEjiayouDay": null,
            "centerPicUrl": null
        },
        "allPageNum": 11,
        "allPaySum": "422.30##元",
        "orderList": [
            {
                "hasStationPhone": 1,
                "oilMass": "0.16",
                "orderId": "9000000020063913",
                "payTime": "2020-01-20 19:09:09",
                "stationPic": "https://img.ejiayou.com/station_pic/SZ_fengze_240x192.jpg",
                "originalCost": "1.00",
                "stationName": "丰泽加油站",
                "stationPhone": "0755-27513266",
                "orderSum": "0.74元",
                "reduceSum": "0.26元",
                "oilCode": "92#",
                "orderState": 2
            }
        ],
        "currentPageNum": 1,
        "saveMoney": "0.70##元",
        "consumeTimes": "12##次",
        "orderQuantity": 12
    }
}

返回参数说明：#

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

data 参数说明：#

参数名	类型	说明
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	油站电话
oilCode	String	油号
originalCost	String	订单原价
oilMass	String	加油升数

3、发券接口 : sendMerchandise(SendMerchandiseParam param)#

接口描述#

合作平台可通过调取该接口给符合条件的指定用户发放易能时代优惠券,由易能时代配置并提供活动 id

SendMerchandiseParam 参数：#

参数名	必选	类型	说明
userPhone	是	string	用户手机号码
sourceId	是	string	优惠券活动 id

返回参数说明：#

参数名	类型	说明
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 直降券

六、接口接入说明#

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

接口描述#

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

特别提醒#

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

请求方式#

Method： GET

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);

七、特定接口签名规则#

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

第一步：设所有发送或者接收到的数据为集合 M，将集合 M 内非空参数值的参数按照参数名 ASCII 码从小到大排序（字典序），使用 URL 键值对的格式（即 key1=value1&key2=value2…）拼接成字符串 stringA。

特别注意以下重要规则：

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

· 如果参数的值为空不参与签名；

· 参数名区分大小写；

· 路径上的参数不参与签名（timestamp 除外）。

第二步：在 stringA 最后依次拼接上路径参数上的 timestamp 和提供给平台的 beforeKey 、afterKey 得到 stringSignTemp 字符串，并对 stringSignTemp 进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 sign 值 signValue。

签名示例#

假设请求接口为 oreo/ejiayou_open_api/orders/v2/{platformName}/{sign}/{timestamp}

假设传送的参数为：stationId 为 12，oilgunCode 为 5，totalAmount 为 1，phoneNumber 为 183xxxxxxxx

1、POST 请求 body 参数格式 json 格式

{
    "stationId": 12,

    "oilgunCode": 5,

    "totalAmount": "1", "phoneNumber": "183xxxxxxxx"
}

2、GET 请求参数格式#

stationId=12&oilgunCode=5&totalAmount=1&phoneNumber=183xxxxxxxx
假设当前 timestamp 为1556440144，beforeKey 为 jksdh，afterKey 为 sdhuub

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

stringA = "oilgunCode=5&phoneNumber=183xxxxxxxx&stationId=12&totalAmount=1"

第二步：拼接 timestamp 和平台的 beforeKey 、 afterKey

stringSignTemp = stringA + "&timestamp=1556440144&beforeKey=jksdh&afterKey=sdhuub"

sign = MD5(stringSignTemp).toUpperCase()

最后将得到的 sign 值以路径参数的形式发送即可。

一、 对接流程#

二、 对接须知#

参数信息#

环境信息#

测试须知#

三、 Java 项目使用说明#

说明#

1、springboot 项目#

1、引包#

1.maven :#

2.gradle:#

3.直接使用 jar 包引入#

2.配置#

3、使用#

API 调用 :#

2、普通 spring 项目#

1、引包#

1.maven :#

2.gradle:#

3.直接使用 jar 包引入#

2、配置#

3、使用#

API 调用 :#

3、普通 Java 项目#

1、引包#

1.maven :#

2.gradle:#

3.直接使用 jar 包引入#

2、配置#

3、使用#

API 调用 :#

四、PHP 项目使用说明#

说明#

PHP 项目#

1、下载#

2、配置#

3、使用#

生成 H5 链接：#

API 调用：#

五、API 参数说明#

1、财务对账 : finance(FinanceParam param)#

接口描述#

FinanceParam 参数：#

返回示例：#

返回参数说明：#

返回数据 data 详情：#

list:#

2、用户个人订单查询 :orderHistory(OrderHistoryParam param)#

接口描述：#

OrderHistoryParam 参数：#

返回参数说明：#

data 参数说明：#

3、发券接口 : sendMerchandise(SendMerchandiseParam param)#

接口描述#

SendMerchandiseParam 参数：#

返回参数说明：#

data 说明#

coupons 说明#

六、接口接入说明#

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

接口描述#

特别提醒#

请求方式#

请求示例#

路径参数：#

其他可选参数#

返回示例#

响应参数：#

签名验证方法:#

七、特定接口签名规则#

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

签名示例#

2、GET 请求参数格式#

一、对接流程#

二、对接须知#