首页 > 开发文档 > 宙斯API调用方法详解

宙斯API调用方法详解

1.宙斯API调用

宙斯开放平台是基于HTTP协议调用的,开发者(ISV)可以使用宙斯提供的SDK (支持多种语言,需要对请求进行封装、签名加解密等)来调用、也可以根据协议规则进行封装为HTTP请求来进行调用。接下来会针对自行封装的HTTP请求进行API调用过程进行详细说明。

2.调用流程

   用户需要按照JOS的协议规范拼装一个正确的URL,通过Https请求到JOS既能够获取到所需数据。主要流程包含:填写参数、生成签名、拼装HTTP请求、发起请求、得到响应结果、解析结果。

4.调用参数

    系统参数:调用任何一个API都需要传入的参数,目前支持的系统参数是:

参数名称

参数类型

是否必传

参数描述

method

String

API接口名称

access_token

String

采用OAuth授权方式是必填参数

app_key

String

应用的app_key

sign

String

详见下文“5.签名算法”描述

timestamp

String

时间戳,格式为yyyy-MM-dd HH:mm:ss,例如:2019-05-01 00:00:00。京东API服务端允许客户端请求时间误差为10分钟

format

String

暂时只支持json

v

String

API协议版本,参考接口文档版本

应用级参数(更多API应用参数参考 接口文档)


5.签名算法

    为了防止API在调用过程中被恶意者拦截随意篡改,调用API是需要传入签名参数,宙斯服务端会根据请求参数对签名进行验证,判断请求参数是否合法。宙斯签名规则过程如下:

l 将所有请求参数按照字母先后顺序排列,例如将access_token,app_key,method,timestamp,v 排序为access_token,app_key,method,timestamp,v

l 把所有参数名和参数值进行拼接,例如:access_tokenxxxapp_keyxxxmethodxxxxxxtimestampxxxxxxvx

l appSecret夹在字符串的两端,例如:appSecret+XXXX+appSecret

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


6.调用示例

以调用jingdong.pop.order.search为调用示例,假设app_key=yourappkeyappSecret=yourappSecretaccess_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_keyyourappkeymethod
360buy.order.searchtimestamp2012-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

5). 组装HTTP请求,将所有的参数转化为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

  非授权调用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


7.API调用注意事项

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

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

l json格式应为标准的json

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

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

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

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