调用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应用级参数参见接口帮助文档)
名称 | 类型 | 是否必须 | 示例值 | 描述 |
fields | String | 否 | 设置需要返回的字段列表,字段之间用","分隔。 |
如下为JOS应用级参数拼装示例
名称 | 类型 | 描述 | 示例 |
360buy_param_json | String | 标准json 类型,而且是按照字母先后顺序排序的 | { |
调用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=
{
}
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
调用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×tamp=2013-05-30 00:00:00&v=2.0&sign=E981702AF260F37FCCD7D60FD19AAEA7
• 所有的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无需编码。