开发规范 - 京东O2O

商家接口开发规范 (该规范适用于服务类中的商家接口)

一、调用介绍

到家通过HTTP协议POST方式调用商家接口。性能要求： TP99 <200ms，TPS>1000, 最长响应时间超时阀值为3s。
注:本文档中定义的接口，仅限于京东秒送APP 1.4(含) 以后版本终端应用。
对于京东秒送APP 1.4以前版本的终端用户，商家需要通过开放平台订单查询接口获取订单，不需要回执订单服务状态(接单、开始服务、结束服务)操作。

二、调用环境入口

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

http调用入口地址:http://xxx.xxx.xxx/xxx/接口名，（其中红色部分商家自定义）。

三、调用参数

商家侧开发消息接收接口，须严格按照开放平台签名规则开发，以下签名示例，仅供参考。
调用API时，必须传入系统级参数和对应的应用级参数。各个API的输入参数和返回结果详见API文档。

①系统级参数

字段	类型	是否必须	描述
token	String	是	采用OAuth授权方式为必填参数。
app_key	String	是	应用的app_key
sign	String	是	签名
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，例如：2011-06-16 13:23:30。京东API服务端允许客户端请求时间误差为6分钟
format	String	是	暂时只支持json
v	String	是	API协议版本，可选值:1.0.

②如下为应用级参数拼装(拼装示例，仅供参考)

字段

描述

示例值

jd_param_json

String

标准json 类型

{
"itemCode ": "10023351",
"cityCode " : "10”,
"longitude"：116.46，
"latitude": 39.92

}

调用API时需要对请求参数进行签名，服务器端会验证请求参数是否合法。

加密规则

① 所有请求参数按照字母先后顺序排列

例如：将token,app_key,timestamp,format,v 排序为app_key,format,timestamp,token,v

② 把所有参数名和参数值进行拼装

例如：app_keyxxxformatxxxxtimestampxxxxxxtokenxxxvx

③ 把appSecret夹在字符串的两端

例如：appSecret+XXXX+appSecret

④ 使用MD5进行加密，再转化成大写

示例（以下示例只体现逻辑）

调用http://xxxx.xxx.xxx/xxx/接口名，假设app_key=yourappkey、appSecret=yourappSecret、token=yourtoken

1) 输入参数

token=yourtoken
app_key=yourappkey
timestamp=2011-07-20 11:10:04
format=json
v=1.0
jd_param_json=
{
"itemCode":"10023351",
"cityCode ":"10,
"longitude": "116.46",
"latitude":"39.92",
}

2) 把参数按照字母顺序排列

app_key=yourappkey
format=json
jd_param_json=
{
"cityCode":"10",
"itemCode":"10023351",
"latitude": "39.92",
"longitude":"116.46",

}
timestamp=2011-07-20 11:10:04
token=yourtoken
v=1.0

3) 连接参数名与参数值，并在首尾加上appSecret

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

注：

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

②时间戳 timestamp最好就填写当前时间的前几分钟（必须在6分钟之内）

③反向签名验证时，在接收到的jd_param_json值，当成普通字符串，不要解析成array，然后直接参与签名运算

五、API调用注意事项

• 所有的API请求和响应数据编码皆为UTF-8格式（切勿转成unicode编码），如采用Get方式请求，URL里的所有参数值在发送请求时请做UrlEncoder处理。

• API请求的应用级参数需要转换成json格式，例如：jd_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

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

六、错误码