首页 > 开发指南 > 开发规范

开发规范

一、调用介绍

JOS作为京东的数据出口,用户只需要按照JOS的规范拼装一个正确的URL,通过https请求到JOS,即能获取到所需的数据。

二、调用环境入口

环境入口释义:调用API时,需要传入如下地址,获取相应环境下的数据。

https调用入口地址(即server_url):https://api.jd.com/routerjson(查看详情

三、调用参数

调用API时,必须传入系统级参数和对应的应用级参数。各个API的输入参数和返回结果详见API文档。

①系统级参数

名称

类型

是否必须

描述

method

String

API接口名称

access_token

String

JOS分配给用户的令牌,通过授权获取,方法详见授权说明。如API文档上标识为“是”,则调用时均需要传入。

app_key

String

应用的app_key

sign

String

签名

timestamp

String

时间戳,格式为yyyy-MM-ddHH:mm:ss,例如:2011-06-16 13:23:30。京东API服务端允许客户端请求时间误差为6分钟

v

String

API协议版本,可选值:2.0.


②应用级参数(更多API应用级参数参见接口帮助文档

名称类型是否必须示例值描述
fieldsString
设置需要返回的字段列表,字段之间用","分隔


如下为JOS应用级参数拼装示例

名称

描述

示例

360buy_param_json

String

标准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"
}


四、API签名

调用API时需要对请求参数进行签名,JOS服务器端会验证请求参数是否合法。

加密规则

① 所有请求参数按照字母先后顺序排列

例如:将access_token,app_key,method,timestamp,v 排序为access_token,app_key,method,timestamp,v

② 把所有参数名和参数值进行拼装

例如:access_tokenxxxapp_keyxxxmethodxxxxxxtimestampxxxxxxvx

③ 把appSecret夹在字符串的两端

例如:appSecret+XXXX+appSecret

使用MD5进行加密,再转化成大写

示例(以下示例只体现逻辑)

调用360buy.order.search,假设app_key=yourappkey、appSecret=yourappSecret、access_token=yourtoken

1) 输入参数

access_token=yourtoken
app_key=yourappkey
method=360buy.order.search
timestamp=2011-07-20 11:10:04
v=2.0
360buy_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) 把参数按照字母顺序排列

360buy_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"

}
access_token=yourtoken
app_key=yourappkey
method=360buy.order.search
timestamp=2011-07-20 11:10:04
v=2.0

3) 连接参数名与参数值,并在首尾加上appSecret

授权接口:(示例)

yourappSecret360buy_param_json{"end_date":null,"optional_fields":null,"order_state":"WAIT_SELLER_STOCK_OUT","page":"1",

"page_size":"200","start_date":null}access_tokenyourtokenapp_keyyourappkeymethod360buy.order.searchtimestamp

2012-06-2116:28:02v2.0yourappSecret

非授权接口:(示例)

yourappSecret360buy_param_json{"end_date":null,"optional_fields":null,"order_state":"WAIT_SELLER_STOCK_OUT",

"page":"1","page_size":"200","start_date":null}app_keyyourappkeymethod360buy.order.searchtimestamp2012-06-21 16:28:02v2.0yourappSecret

注:

①以上字符串不允许有跨行,粘贴时请特别注意,除日期和时间中间的空格之外,不允许在其它位置出现空格。

②时间戳 timestamp 最好就填写当前时间的前几分钟(必须在6分钟之内)
③相应的,获得签名后进行拼装URL的时候,调用的接口是非授权的话,把access_token那一块也去掉,无需填写,具体参见非授权接口拼接示例。



4) MD5加密后转成大写:EDBE87FB9640EDD681FEBC79D858AAC0

五、拼装https请求

调用API时,将所有的参数转换成UTF-8编码,然后进行拼装,通过浏览器访问该地址即可成功调取一次接口。

授权API调用URL示例(仅为示例):

https://api.jd.com/routerjson?360buy_param_json={"end_date":"2013-12-01 00:00:00","order_state":"WAIT_SELLER_STOCK_OUT,WAIT_GOODS_RECEIVE_CONFIRM","page":"1","page_size":"20","start_date":"2013-05-01 00:00:00"}&access_token=12345678-b0e1-4d0c-9d10-a998d9597d75&app_key=123456780233FA31AD94AA59CFA65305&method=360buy.order.search×tamp=2013-05-30 00:00:00&v=2.0&sign=E981702AF260F37FCCD7D60FD19AAEA7

非授权API调用URL示例(仅为示例):

https://api.jd.com/routerjson?360buy_param_json={"end_date":"2013-12-01 00:00:00","order_state":"WAIT_SELLER_STOCK_OUT,WAIT_GOODS_RECEIVE_CONFIRM","page":"1","page_size":"20","start_date":"2013-05-01 00:00:00"}&app_key=123456780233FA31AD94AA59CFA65305&method=360buy.order.search×tamp=2013-05-30 00:00:00&v=2.0&sign=E981702AF260F37FCCD7D60FD19AAEA7

六、API调用注意事项

• 所有的API请求和响应数据编码皆为GBK格式,URL里的所有参数值请做urlencode编码

API请求的应用级参数需要转换成json格式,例如:360buy_param_json={"return_id":"20032","trade_no":"20032"}

• json格式应为标准的json

• 目前只支持返回结果是json格式

• 所有API请求和响应内的日期格式都为yyyy-MM-dd HH:mm:ss,注意小时格式是24小时制,例如:2011-07-21 20:23:30

• API接口的错误信息在http response body内

• 签名方式为 md5(appsecret + key+ value .... key + value+appsecret)然后转大写字母,其中key、value对是除签名所有请求参数按key做的升序排列,value无需编码。