开普勒文档中心

文档列表

API调用方法详解

Kepler开放平台所有API是基于HTTP协议（同时支持HTTPS）来调用的。开发者需要自行封装HTTP请求进行调用。下面将对请求API调用的原理做详细说明。

1、调用地址

目前只提供正式环境:

调用环境	服务地址（HTTPS）
正式环境	https://router.jd.com/api
沙箱环境	即将提供

2、系统参数

调用任何API都必须传入系统参数，参数列表如下:

名称	类型	是否必选	描述
method	String	是	API接口名称
app_key	String	是	分配给应用的AppKey
access_token	String	是	Oauth2颁发的动态令牌,用户授权详细介绍
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。API服务端允许客户端请求最大时间误差为10分钟
format	String	是	响应格式。暂时只支持json
v	String	是	API协议版本，可选值：2.0
sign_method	String	是	签名的摘要算法，可选值为：hmac，md5
sign	String	是	API输入参数签名结果

3、业务参数

调用API时不仅必须传入系统参数，还需要根据API的具体参数传入业务参数，API的业务参数请参考API文档。

4、签名算法说明

签名sign是将请求串以及秘钥根据一定签名方法生成的签名值，用来防止传输过程中参数被篡改。具体签名方法如下：

Step 1：把所有请求参数根据参数名称的ASCII码表顺序进行排序
如: 将access_token,app_key,method,timestamp,v 排序为 access_token,app_key,method,timestamp,v

Step 2：把所有参数名和参数值进行拼接(拼接过程中param_json里面的参数顺序应该与请求时传入的顺序保持一致)

如：access_tokenxxxapp_keyxxxmethodxxxxxxtimestampxxxxxxvx

Step 3：把appSecret夹在字符串的两端
如：appSecret+ access_tokenxxxapp_keyxxxmethodxxxxxxtimestampxxxxxxvx +appSecret

Step 4：使用MD5进行加密，将摘要结果使用十六进制表示并转化成大写，如：

md5(appSecret+ access_tokenxxxapp_keyxxxmethodxxxxxxtimestampxxxxxxvx +appSecret)

JAVA签名示例代码

private String buildSign(String timestamp, String version, String signMethod ,String format ,

String method , String paramJson , String accessToken ,String appKey, String appSecret)

throws Exception {

//第一步，按照顺序填充参数

Map<String, String> map = new TreeMap();

map.put("timestamp", timestamp);

map.put("v", version);

map.put("sign_method", signMethod);

map.put("format", format);

map.put("method", method);

//param_json为空的时候需要写成 "{}"

map.put("param_json", paramJson);

map.put("access_token", accessToken);

map.put("app_key", appKey);

StringBuilder sb = new StringBuilder(appSecret);

//按照规则拼成字符串

for (Map.Entry entry : map.entrySet()) {

String name = (String) entry.getKey();

String value = (String) entry.getValue();

//检测参数是否为空

if (StringUtil.areNotEmpty(new String[]{name, value})) {

sb.append(name).append(value);

}

sb.append(appSecret);

//MD5

return CodecUtil.md5(sb.toString());

}

public static String md5(String source)

throws Exception

{

MessageDigest md = MessageDigest.getInstance("MD5");

byte[] bytes = md.digest(source.getBytes("utf-8"));

return byte2hex(bytes);

}

private static String byte2hex(byte[] bytes) {

StringBuilder sign = new StringBuilder();

for (int i = 0; i < bytes.length; i++) {

String hex = Integer.toHexString(bytes[i] & 0xFF);

if (hex.length() == 1) {

sign.append("0");

}

sign.append(hex.toUpperCase());

}

return sign.toString();

}

public static boolean areNotEmpty(String[] values) {

boolean result = true;

if ((values == null) || (values.length == 0))

result = false;

else {

for (String value : values) {

result &= !isEmpty(value);

}

return result;

}

public static boolean isEmpty(String value) {

int strLen;

if ((value == null) || ((strLen = value.length()) == 0))

return true;

for (int i = 0; i < strLen; i++) {

if (!Character.isWhitespace(value.charAt(i))) {

return false;

}

return true;

}

5、API调用示例

假设调用API jd.order.search

app_key： yourappkey

appSecret： yourappSecret

access_token： yourtoken

1) 设置参数

access_token=yourtoken

app_key=yourappkey

method=jd.order.search

timestamp=2011-07-20 11:10:04

v=2.0

param_json=

{
"end_date":"2012-05-16 17:03:56",
"optional_fields":"vender_id,
order_id,pay_type,order_total_price,freight_price,seller_discount,order_payment,
delivery_type,order_state,order_state_remark,invoice_info,order_remark,order_start_time,
order_end_time,consignee_info,item_info_list",
"order_state": "WAIT_SELLER_STOCK_OUT",
"page":"1",
"page_size":"20",
"start_date":"2012-05-14 17:03:56"
}

2) 按照ASCII 码表顺序排序

access_token=yourtoken
app_key=yourappkey

method=jd.order.search

param_json=

"start_date":"2012-05-14 17:03:56"

}

timestamp=2011-07-20 11:10:04

v=2.0

3) 拼接参数名与参数值

授权接口：（示例）

yourappSecretaccess_tokenyourtokenapp_keyyourappkeymethodjd.order.search param_json{"end_date":null,"optional_fields":null,"order_state":"WAIT_SELLER_STOCK_OUT","page":"1","page_size":"200","start_date":null}timestamp2012-06-21 16:28:02v2.0yourappSecret

非授权接口：（示例）

yourappSecretapp_keyyourappkeymethodjd.order.search param_json{"end_date":null,"optional_fields":null,"order_state":"WAIT_SELLER_STOCK_OUT","page":"1","page_size":"200","start_date":null}timestamp2012-06-21 16:28:02v2.0yourappSecret

注意事项：

以上字符串不允许有换行，除日期和时间中间的空格之外，不允许在其它位置出现空格。

4) 生成签名

假设app的appsecret为yourappSecret，则签名结果为：hex(md5(yourappSecret +按顺序拼接好的参数名与参数值+ yourappSecret)) = “91DEBBFBAA3245A88445F99E55FC214D”

5) 组装HTTP请求

将所有参数名和参数值采用utf-8进行URL编码（参数顺序可随意，但必须要包括签名参数），然后通过GET或POST发起请求，如：

https://router.jd.com/api?sign=91DEBBFBAA3245A88445F99E55FC214D&sign_method=md5&timestamp=2016-05-1920%3A15%3A07&v=1.0&

app_key= yourappkey &method=biz.stock.fivestockbyid.get&format=json&access_token= yourtoken &param_json={"end_date":"2012-05-16 17:03:56","optional_fields":"vender_id,order_id,pay_type,order_total_price,freight_price,seller_discount,order_payment,delivery_type,

order_state,order_state_remark,invoice_info,order_remark,order_start_time,order_end_time,consignee_info,item_info_list","order_state":"WAIT_SELLER_STOCK_OUT",

"page":"1","page_size":"20","start_date":"2012-05-14 17:03:56"}

注意事项：

1)所有的请求和响应数据编码皆为utf-8格式，URL里的所有参数名和参数值请做URL编码。

2)参数名与参数值拼装起来的URL长度小于1024个字符时，可以用GET发起请求；参数类型含byte[]类型或拼装好的请求URL过长时，必须用POST发起请求。所有API都可以用POST发起请求。