京东API接入流程文档 -商家版.doc

JOS接入流程文档（商家专用）
一、 应用申请流程

1. 注册成为开发者
请访问：
沙箱环境地址 ：
正式环境地址：
(1) 访问开发者中心，点击”申请成为开发者“，开始申请流程

(2) 用京东账户登录，没有京东账户则注册一个京东账户

（3） 登录成功后，完善注册信息

（4） 提交，申请成功！

(5) 然后进入我的开发中心

2. 创建应用
（1） 在开发者中心，点击“创建应用”

(2) 填写应用名称，选择应用类型

通用应用：此应用ISV和商家都可以使用（针对的ISV的应用需要商家进行授权，商家不需要提供用户名和密码给第三方开发者）
商家应用：此应用只有商家可以使用

（3）保存成功，可申请上线

1.通用应用：

2. 商家应用说明：(请选择您所需要的应用)

3. 管理应用
（1） 在开发者中心，点击“管理应用”

(2) 进入应用列表，点击“编辑”

(3) 进入应用详情，这里可以查询应用的相关密钥，及修改相关信息。

请保留appkey 和 appsecret 到oauth授权认证用到
appkey与appsecrect释义：appkey：JOS京东开放平台颁发的唯一标识一个应用的ID号，该appkey可在开发者中心创建应用后获取，appSecret:（应用密钥，不可对外公开，商家需注意保密，调用API的时候需要使用，可以通过该密钥获得的商家所有数据）。

(4)修改应用信息

二、 Oauth授权认证
访问地址：
沙箱环境地址 ：
正式环境地址：
注意事项：
请不要将地址直接贴于地址栏访问，否者提示您：“异常访问”
请不要沙箱环境和正式环境穿插调用。

前言:
如果您的应用和京东的JOS对接后，需要获取一些与用户紧密相关的信息（如订单、商品、促销等），为保证数据的安全性和隐私性，需要取得用户的同意，引导用户授权。JOS采用国际通用的OAuth2.0标准协议，支持网站、桌面客户端、ERP系统。如果要了解更多关于OAuth2.0的技术说明，请参考官方网站 目前，JOS的OAuth2.0支持以下方式获取Access Token ：
注意：所有授权流程都不需要商家提供用户名、密码给第三方开发者，商家请保护好自己的账号安全
1. Server-side flow(B/S)
此授权指对应用标签中的：“商家应用（京东商家应用）”里的“ WEB应用（B/S）”
Ø 通过用户授权获取授权码Code
获取授权码参数
参数名称
参数选项
描述
response_type
必须
此流程下，该值固定为code
client_id
必须
即创建应用时的Appkey (从开发者中心申请的应用中获取)
redirect_uri
必须
应用的回调地址，必须和应用的callback主域名匹配。
state
可选
状态参数，由应用自定义，颁发授权后会原封不动返回
scope
否（短授权为必须）
权限参数，API组名串，多个组名时，用“，”分隔，目前支持参数：read
（注意此地址需要拼参不能直接访问）（详细请参考oauth文档）示例：

² 用户登陆

输入用户名和密码点击登录按钮跳转到授权页面
² 授权

点击授权按钮跳转到回调页面

² 若用户选择“授权“，则页面跳转至应用的回调地址，同时返回授权码code以及state参数（code不能重复使用，下次使用需要重新获取）

Ø 用上一步获取的Code和应用密钥（AppSecret）通过Http Post方式换取Token

获取访问令牌参数
参数名称
参数选项
描述
grant_type
必须
授权类型，此流程下，该值固定为authorization_code
code
必须
授权请求中的授权码
redirect_uri
必须
应用的回调地址，必须和应用的callback主域名匹配。
client_id
必须
即Appkey(从开发者中心申请的应用中获取)
client_secret
必须
即Appsecret(从开发者中心申请的应用中获取)
scope
否（短授权为必须）
权限参数，API组名串，多个组名时，用“，”分隔，目前支持参数：read

（注意此地址需要拼参不能直接访问）（详细请参考oauth文档）
示例：

TOP返回的参数如下：
参数名称
参数选项
描述
access_token
用户授权令牌，等价于Sessionkey
access_token
code
返回0，为成功
code
token_type
授权令牌类型，暂做保留参数备用
token_type
expires_in
授权令牌有效期，以秒为单位
expires_in
refresh_token
刷新令牌，当授权令牌过期时，可以刷新access_token，如果有获取权限则返回
refresh_token
time
系统时间
time
结果如下：
{
· "access_token": "47565790-662f-4b32-8cb7-8b4f984be462",
· "code": 0,
· "expires_in": 31104000,
· "refresh_token": "71443717-d3ea-40df-9dc1-f7a77b448f91",
· "time": "1337674952269",
· "token_type": "bearer"
}
2. Password flow(C/S)
此授权指对应用标签中的：“商家应用（京东商家应用）”里的“客服端应用（C/S）”

请将您的商家店铺名和商家Id以及联系方式发送到邮箱获取C/S授权方式：jos@

三． 调用API接口
1. 准备调用接口所需要的数据
访问地址：
沙箱环境地址 ：
正式环境地址：
SERVER_URL地址：请写相对应的地址
示例：
access_token：从OAuth授权认证中获取
app_key：从开发者中心申请的应用的“京东证书”中获取
sign：请参考签名说明

调用示例：
接口名称360buy.order.search
Ø 功能说明
根据条件检索订单信息
Ø 系统级别输入参数
名称
类型
是否必须
描述
method
String
是
API接口名称
access_token
String
是
采用OAuth授权方式为必填参数
app_key
String
是
应用的app_key
sign
String
是
签名
timestamp
String
是
时间戳，格式为yyyy-MM-ddHH:mm:ss，例如：2011-06-16 13:23:30。京东API服务端允许客户端请求时间误差为6分钟
format
String
否
暂时只支持json
v
String
是
API协议版本，可选值:2.0.
Ø 应用级输入参数
名称
类型
是否必须
示例值
描述
start_date
String
否
2010-12-20 17:15:00
开始时间 和 结束时间 不得相差超过1个月
end_date
String
否
2010-12-20 17:15:00
开始时间 和 结束时间 不得相差超过1个月
order_state
String
是
WAIT_SELLER_STOCK_OUT
每个订单状态以逗号分隔,(该接口只提供三个状态， WAIT_SELLER_STOCK_OUT 等待出库， WAIT_SELLER_DELIVERY 等待发货(只适用于SOP商家)， TRADE_CANCELED 取消)
page
String
是
1
查询的页数
page_size
String
是
12
每页的条数（最大page_size 100条）
optional_fields
String
否

商家希望返回的订单的信息字段,每个字段以逗号分隔
2. SDK调用示例（java）
public JdClient client = new DefaultJdClient(SERVER_URL,
"c7b82199-f26d-459e-a4b3-d6f6cec4b869",”36AB8642CCEF66293AD391EE7E4E9515”,”0da953632d0a4741beb0bbd096214605”);
OrderSearchRequest request = new OrderSearchRequest();
request.setStartDate("2012-01-10 12:12:23");
request.setEndDate("2012-02-20 12:13:13");
request.setOrderState("WAIT_SELLER_STOCK_OUT");
request.setPage("1");
request.setPageSize("100");
request.setOptionalFields("vender_id,order_id,pay_type");
OrderSearchResponse response = client.execute(request);

3. url请求方式示例
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、系统级输入参数
名称
类型
是否必须
描述
示例值
默认值
method
String
是
API接口名称
method
String
access_token
String
是
采用OAuth授权方式为必填参数
access_token
String
app_key
String
是
应用的app_key
app_key
String
timestamp
String
是
时间戳，格式为yyyy-MM-dd HH:mm:ss，例如：2011-06-16 13:23:30。京东API服务端允许客户端请求时间误差为6分钟

无
v
String
是
API协议版本，可选值:2.0。

无

2、应用级输入参数
名称
类型
描述
示例
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"
}

3、加密规则：
a) 所有请求参数按照字母先后顺序排序
例如：将access_token,app_key,method,timestamp,v 排序为
access_token,app_key,method,timestamp,v)
b) 把所有参数名和参数值串在一起
例如：access_tokenxxxapp_keyxxxmethodxxxxxxtimestampxxxxxxvx
c) 把appSecret夹在字符串的两端
例如：appSecret+XXXX+appSecret
d) 使用MD5进行加密，再转化成大写

4、示例 ：
调用api方法：360buy.order.search，appSecret: 6d5524eb1c6c4f9caf8c7b430d1fdef9
（1）输入参数：

access_token=ad6c71c3-7fb3-4f7b-8258-9a6413a5bbbf
app_key=7843A398CCE3397EC50C495458F64B64
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=ad6c71c3-7fb3-4f7b-8258-9a6413a5bbbf
app_key=7843A398CCE3397EC50C495458F64B64
method=360buy.order.search
timestamp=2011-07-20 11:10:04
v=2.0

（3）连接参数名与参数值,并在首尾加上appSecret
6d5524eb1c6c4f9caf8c7b430d1fdef9360buy_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_tokenad6c71c3-7fb3-4f7b-8258-9a6413a5bbbf
app_key7843A398CCE3397EC50C495458F64B64
method360buy.order.search
timestamp2012-05-2213: 21: 44
v2.06d5524eb1c6c4f9caf8c7b430d1fdef9

（4） MD5加密后转成大写：
B7DC8C345645EE9C613283E2ECAD7F34

API调用注意事项
•所有的请求和响应数据编码皆为utf-8格式，url里的所有参数值请做urlencode编码。
•请求的应用级参数需要转换成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无需编码。