【开发规范】导航


一、调用介绍

二、调用环境入口

三、调用参数

四、API签名

五、拼装HTTP请求

六、API调用注意事项

一、调用介绍


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

二、调用环境入口


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

    

     正式环境入口地址:http://gw.api.360buy.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.search

timestamp2012-06-21 16:28:02v2.0yourappSecret

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


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

五、拼装HTTP请求


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


调用URL示例(仅为示例):

http://gw.api.360buy.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&timestamp=2013-05-30 00:00:00&v=2.0&sign=E981702AF260F37FCCD7D60FD19AAEA7

六、API调用注意事项


• 所有的API请求和响应数据编码皆为UTF-8格式,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无需编码。