EOP介绍

开发规范

调用说明

本开放平台基于 HTTP 协议开发，用户只需要按照开发规范拼装正确的 URL 以及参数，即可请求成功。

调用入口

调用环境	https服务地址
沙箱环境	http://sg-en-web-api-kdev0-api.ezbuy.me/api/open/router
正式环境	https://sg-en-web-api.ezbuy.sg/api/open/router

公共参数

名称	类型	是否必须	描述
method	string	y	api接口名称
app_key	string	y	ezbuy分配给应用的AppKey
sign_method	string	y	签名摘要算法，可选值：hmac,md5
sign	string	y	签名
timestamp	string	y	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8。ezbuy api服务端允许客户端请求的最大时间误差为10分钟
version	string	y	api协议版本，可选值：1.0 , 2.0

注：公共参数不区分请求方式，统一使用 query parameters 方式传递。

业务参数

API调用除必须包含公共参数外，如果API本身有业务级的参数也必须传入。

注：不同的请求方式，业务参数的传入方式也不一样。

GET 类型的接口，业务参数仅通过 query parameters 方式传递。
POST 类型的接口，需使用 JSON 协议传递业务级参数（即设置 Content-Type 为 application/json ）

签名算法

为了防止API调用过程中被恶意篡改，所有的API的调用都需要携带签名，服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。目前支持的签名算法有两种：

MD5 (sign_method=md5)
HMAC_MD5 (sign_method=hmac)

生成签名过程如下：

第一步

对除了 sign 以外的所有请求参数(包含公共参数和业务参数)根据参数名称的 ASCII 码表的顺序排序

例如： 将 sign_method,app_key,method,timestamp,version 排序为：app_key,method,sign_method,timestamp,version

注：对于POST类型的接口，增加参数ezbuy_json_param，并将 request body 的内容转换为 string 类型，去空格后赋值给该参数，作为签名的一部分

第二步

将排序好的参数名和参数值拼装在一起

例如： ${app_key}xxx${method}xxx${sign_method}xxx${timestamp}xxx${version}xxx

注：对于 POST 参数，转换为字符串类型，再去除空格后拼接在 ezbuy_json_param 参数后

第三步

对拼装后的字符进行urlencode后，使用签名算法进行摘要

（1）MD5算法，将分配的 ${appSecret} 拼接在字符串的前后两端，然后进行 MD5 加密，

例如：: ${appSecret}XXX${appSecret}

（2） HMAC_MD5算法，则需要用 ${appSecret} 初始化hmac算法后，再对编码后的内容进行 HMAC_MD5 加密

第四步

将摘要得到的字节流结果使用十六进制表示并转换为大写，如：99C2BC11CA8D8DC6DACA4B4072563EAB

注： MD5和HMAC_MD5都是128位长度的摘要算法，用16进制表示，一个十六进制的字符能表示4个位，所以签名后的字符串长度固定为32个十六进制字符。

调用示例

以 GET 方式的调用示例

ezbuy.product.get 接口

第一步

设置公共参数：

method=ezbuy.product.get
app_key=c4339c0730175faba1284b7acb24c9db
sign_method=md5
timestamp=2017-08-14 16:10:23
version=1.0

设置业务参数：

product_id=10096
fields=product_id,name,name_en,is_onsale

按ASCII排序参数

app_key=c4339c0730175faba1284b7acb24c9db
fields=product_id,name,name_en,is_onsale
method=ezbuy.product.get
product_id=10096
sign_method=md5
timestamp=2017-08-14 16:10:23
version=1.0

第二步

拼接参数名和参数值

app_keyc4339c0730175faba1284b7acb24c9dbfieldsproduct_id,name,name_en,is_onsalemethodezbuy.product.getproduct_id10096sign_methodmd5timestamp2017-08-14 16:10:23version1.0

第三步

对拼接后的字符串做urlencode

app_keyc4339c0730175faba1284b7acb24c9dbfieldsproduct_id%2Cname%2Cname_en%2Cis_onsalemethodezbuy.product.getproduct_id10096sign_methodmd5timestamp2017-08-14+16%3A10%3A23version1.0

第四步

生成签名

假设分配的 ${appSecret} 为 45CAC98AF0F736A3AB2087CE26970674 ，则签名结果为：

md5(45CAC98AF0F736A3AB2087CE26970674app_keyc4339c0730175faba1284b7acb24c9dbfieldsproduct_id%2Cname%2Cname_en%2Cis_onsalemethodezbuy.product.getproduct_id10096sign_methodmd5timestamp2017-08-14+16%3A10%3A23version1.045CAC98AF0F736A3AB2087CE26970674)

=> 4784FAD2943B0A13B8578594542AE00F

组装HTTP请求

将所有参数名和参数值进行urlencode，然后通过 GET 方式发起请求：

https://cn-ezseller-sandboxapi.ezbuy.sg:8088/api/open/router
?method=ezbuy.product.get&product_id=100968&app_key=c4339c0730175faba1284b7acb24c9db&sign_method=md5&timestamp=2017-08-14%2016%3A10%3A23&version=1.0&fields%3Dproduct_id%2Cname%2Cname_en%2Cis_onsale&sign=02E9A6C70789921055537102ED63C83B

代码示例

$api_url = "https://cn-ezseller-sandboxapi.ezbuy.sg:8088/api/open/router";
$app_key = "c4339c0730175faba1284b7acb24c9db";
$app_secret = "45CAC98AF0F736A3AB2087CE26970674";

// 组装请求参数
$args = array(
    "app_key" => $app_key,
    "method" => "ezbuy.product.get",
    "sign_method" => "md5",
    "timestamp" => date('Y-m-d H:i:s'),
    "version" => "1.0",
    "product_id" => 10096,
    "fields" => "product_id,name,name_en,is_onsale"
);

// key 按照字典序排序
ksort($args);

// 拼接 token
foreach ($args as $key => $value) {
    $token .= $key . $value;
}

// 生成签名
$token = urlencode($token);
$sign = md5($app_secret . $token . $app_secret, FALSE);

// sign 需转换为大写
$args["sign"] = strtoupper($sign);

$url = $api_url . "?" . http_build_query($args);

$client = curl_init($url);
curl_setopt($client, CURLOPT_SSL_VERIFYHOST, true);
curl_setopt($client, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

// 发起请求
curl_exec($client);

以 POST 方式的调用示例：

ezbuy.order.outofstock 接口

第一步

设置公共参数：

method=ezbuy.order.outofstock
app_key=c4339c0730175faba1284b7acb24c9db
sign_method=md5
timestamp=2017-08-14 16:10:23
version=1.0

设置业务参数：

POST 方式提交的接口，需要将 Content-Type 设为 application/json

{
　　"order_number":"25374807059770976-4",
　　"quantity":2,
   "reason":"五天后到货"
}

按ASCII排序参数：

增加 ezbuy_json_param 参数

app_key=c4339c0730175faba1284b7acb24c9db
ezbuy_json_param={"order_number":"25374807059770976-4","quantity":2,"reason":"五天后到货"}
method=ezbuy.order.outofstock
sign_method=md5
timestamp=2017-08-14 16:10:23
version=2.0

第二步

拼接参数和参数值

app_keyc4339c0730175faba1284b7acb24c9dbezbuy_json_param{"order_number":"25374807059770976-4","quantity":2,"reason":"五天后到货"}methodezbuy.product.getsign_methodmd5timestamp2017-08-14 16:10:23version2.0

第三步

对拼接后的字符串做urlencode

app_keyc4339c0730175faba1284b7acb24c9dbezbuy_json_param%7B%22order_number%22%3A%2225374807059070976-4%22%2C%22quantity%22%3A2%2C%22reason%22%3A%22%5Cu4e94%5Cu5929%5Cu540e%5Cu5230%5Cu8d27%22%7Dmethodezbuy.product.getsign_methodmd5timestamp2017-08-14+16%3A10%3A23version1.0

第四步

生成签名

组装HTTP请求，通过 POST 方式发起请求

注：url里不需要加上 ezbuy_json_param 参数，该参数只在签名时用到

代码示例

$api_url = "https://cn-ezseller-sandboxapi.ezbuy.sg:8088/api/open/router";
$app_key = "c4339c0730175faba1284b7acb24c9db";
$app_secret = "45CAC98AF0F736A3AB2087CE26970674";

$args = array(
    "app_key" => $app_key,
    "method" => "ezbuy.order.outofstock",
    "sign_method" => "md5",
    "timestamp" => date('Y-m-d H:i:s'),
    "version" => "2.0",
);

$business_args = array(
    "order_number" => "25374807059070976-4",
    "quantity" => 2,
    "reason" => "五天后到货",
);

str_replace(" ", "", $business_args); // 移除空格
$args["ezbuy_json_param"] = json_encode($business_args);

// key 按照字典序排序
ksort($args);

// 拼接 token
foreach ($args as $key => $value) {
    $token .= $key . $value;
};

// 生成签名
$token = urlencode($token);
$sign = md5($app_secret . $token . $app_secret, FALSE);

// sign 需转换为大写
$args["sign"] = strtoupper($sign);

unset($args["ezbuy_json_param"]); // OPTIONAL（请求时无需带上）
$url = $api_url . "?" . http_build_query($args);

$client = curl_init($url);
curl_setopt($client, CURLOPT_POST, true);
curl_setopt($client, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($client, CURLOPT_POSTFIELDS, json_encode($business_args));
curl_setopt($client, CURLOPT_SSL_VERIFYHOST, true);
curl_setopt($client, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

curl_exec($client);