京东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用户授权令牌，等价于Sessionkeyaccess_tokencode返回0，为成功codetoken_type授权令牌类型，暂做保留参数备用token_typeexpires_in授权令牌有效期，以秒为单位expires_inrefresh_token刷新令牌，当授权令牌过期时，可以刷新access_token，如果有获取权限则返回refresh_tokentime系统时间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Ø 功能说明根据条件检索订单信息Ø 系统级别输入参数名称类型是否必须描述methodString是API接口名称access_tokenString是采用OAuth授权方式为必填参数app_keyString是应用的app_keysignString是签名timestampString是时间戳，格式为yyyy-MM-ddHH:mm:ss，例如：2011-06-16 13:23:30。京东API服务端允许客户端请求时间误差为6分钟formatString否暂时只支持jsonvString是API协议版本，可选值:2.0.Ø 应用级输入参数名称类型是否必须示例值描述start_dateString否 2010-12-20 17:15:00开始时间 和 结束时间 不得相差超过1个月end_dateString否2010-12-20 17:15:00开始时间 和 结束时间 不得相差超过1个月order_stateString是WAIT_SELLER_STOCK_OUT每个订单状态以逗号分隔,(该接口只提供三个状态， WAIT_SELLER_STOCK_OUT 等待出库， WAIT_SELLER_DELIVERY 等待发货(只适用于SOP商家)， TRADE_CANCELED 取消)pageString是1查询的页数page_sizeString是12每页的条数（最大page_size 100条）optional_fieldsString否商家希望返回的订单的信息字段,每个字段以逗号分隔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、系统级输入参数名称类型是否必须描述示例值默认值methodString是API接口名称methodStringaccess_tokenString是采用OAuth授权方式为必填参数access_tokenStringapp_keyString是应用的app_keyapp_keyStringtimestampString是时间戳，格式为yyyy-MM-dd HH:mm:ss，例如：2011-06-16 13:23:30。京东API服务端允许客户端请求时间误差为6分钟无vString是API协议版本，可选值:2.0。无2、应用级输入参数名称类型描述示例360buy_param_jsonString标准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_keyxxxmethodxxxxxxtimestampxxxxxxvxc) 把appSecret夹在字符串的两端例如：appSecret+XXXX+appSecretd) 使用MD5进行加密，再转化成大写4、示例 ： 调用api方法：360buy.order.search，appSecret: 6d5524eb1c6c4f9caf8c7b430d1fdef9 （1）输入参数：access_token=ad6c71c3-7fb3-4f7b-8258-9a6413a5bbbfapp_key=7843A398CCE3397EC50C495458F64B64method=360buy.order.searchtimestamp=2011-07-20 11:10:04v=2.0360buy_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.searchtimestamp=2011-07-20 11:10:04v=2.0（3）连接参数名与参数值,并在首尾加上appSecret6d5524eb1c6c4f9caf8c7b430d1fdef9360buy_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-9a6413a5bbbfapp_key7843A398CCE3397EC50C495458F64B64method360buy.order.searchtimestamp2012-05-2213: 21: 44v2.06d5524eb1c6c4f9caf8c7b430d1fdef9（4） MD5加密后转成大写：B7DC8C345645EE9C613283E2ECAD7F34API调用注意事项所有的请求和响应数据编码皆为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无需编码。