JD-API对接帮助文档 2018-11-客户版

产品帮助文档 大客户开放平台VOP【实物】帮助文档文档版本号：1.8.7文档编号：文档密级：保密归属部门/项目：大客户部产品名：大客户开放平台VOP子系统名：编写人：顾科、杨猛、武文编写日期：2015/03/30京东商城 版权所有内部资料 注意保密修订记录：版本号修订人修订日期修订描述1.0武文2014/03/241.1武文2014/05/041.2武文2014/05/151.3武文2014/05/281.4武文2014/06/281.5武文2014/07/251.6武文2014/07/291.6.1武文2014/08/051.6.2武文2014/08/281.6.3武文2014/09/281.6.4武文2015/01/041.6.5武文2015/03/041.加入了区域购买限制，2.增加了图书商品返回结果武文2015/03/301.6.7陶韬2015/07/06添加赠品附件查询以及下单接口，金彩、网银钱包余额查询接口，以及推送消息新增内容1.6.7王子健2015/07/16增加实物礼品卡说明1.6.8陶韬2015/09/16Token提供新接口，增加错误码周德东2016/01/12添加统一的价格查询接口。【5.3 批量查询商品售卖价】周德东2016/01/127.10公司装帐下单接口添加doOrderPriceMode,orderPriceSnap入参，详细描述bNeedAnnex和bNeedGift的给值说明;1.6.9陶韬2016/1/26添加运费相关参数1.7.0谢乐2016/1/26添加商品搜索接口1.7.1顾科2016/3/9新增：统一下单接口添加商品价格透传参数（其他下单接口也可以使用）1.7.2顾科2016/3/17新增3.12.商品可售验证接口1.7.3周德东2016/3/21新增7.25 获取京东预约日历1.7.4周德东2016/5/26添加 3.13 查询商品延保接口1.7.5陶韬2016/05/30调整3.12（返回是否支持7天无理由退货）、7.23（去京豆话语）周德东2016/05/30下单接口添加延保入参字段说明;1.7.6顾科2016/07/04新增 7.26余额明细查询接口顾科2016/08/11修改9.1消息推送接口，新增类别:25(新订单)王勇2016/08/23修改9.1消息推送接口，type=5修改备注买断模式为外单妥投或外单拒收消息王勇2016/09/01新增分类信息查询接口；新增分类列表信息查询接口；修改商品详情查询接口（增加商品移动介绍信息和售后信息查询）顾科2016/11/30新增 4.5验证四级地址是否正确 1.7.7杨猛2016/12/30新增 同类商品查询和重定向1.7.8顾科2016/12/30新增 3.3 获取池内商品编号接口-品类商品池（兼容老接口）杨猛2017/01/04删除同类商品重定向接口修改同类商品查询接口返回数据格式顾科2017/01/17更新 3.3 获取池内商品编号接口-品类商品池（兼容老接口） 接口描述信息顾科2017/02/23更新 5.2批量查询协议价价格，加入税率更新 5.3批量查询商品售卖价，加入税率1.7.9顾科2017/04/01新增 7.27确认收货（厂家直送）1.8.0顾科2017/05/11更新5.3 批量查询商品售卖价.v1,加入市场价更新6.2 批量获取库存接口.v1,加入无货开预定更新7.20 查询京东订单信息接口.v1，加入无货开预定，订单状态，订单类别1.8.1杨猛2017/05/15更新 获取京东预约日历 接口，增加返回值更新 统一下单接口 增加履约日历相关信息1.8.2李超2017/06/08新增电子签单下载地址查询接口顾科2017/07/18新增 获取电子发票信息.v1，查询发票列表信息更新 确认预占库存订单接口.v1，增加企业付款金额（移动）1.8.3顾科2017/08/11新增 查询商品详情装吧样式.v1新增 保存更新采购单号.v1更新 获取商品详细信息接口.v1，优化扩展参数更新 统一下单接口.v2，新增poNo字段更新 查询京东订单信息接口.v1，扩展参数添加返回地址、姓名、联系电话、采购单号更新 申请开票接口.v1，新增poNo字段唐子力2017/8/22更新 查询京东订单信息接口.v1，商品扩展参数添加 运费拆分价格 字段1.8.4顾科2017/10/09新增 根据地址查询京东地址编码.v1新增 根据经纬度查询京东地址编码.v1更新 去掉URL链接中的空格顾科2017/11/20新增 根据订单号查询和服务单号查询支付信息.v1更新 消息接口-查询，增加type=26，28更新 消息接口-删除，文案描述支持批量1.8.5顾科2018/01/15更新 新建订单查询接口更新 获取妥投订单接口更新 获取拒收消息接口更新 下单接口，删除统一下单外的下单接口顾科2018/04/12新增 订单号查询第三方申请单号新增 订单号查询发票物流信息更新 消息接口-查询，增加type=48，491.8.6顾科2018/05/07新增 创建合单号接口新增 订单号查询合单号新增 合单号查询订单号新增 取消合单号新增 获取汇款识别码1.8.7王丽娟2018/10/31新增 商品序列号查询接口目录大客户开放平台VOP1【实物】帮助文档1更新 获取京东预约日历 接口，增加返回值4一、名词解释12二、系统对接帮助文档（实物）121、授权服务121.1 采用HTTPS的方式调用服务121.2 接口返回值说明131.3 获取Access Token131.4 使用Refresh Token 刷新 Access Token162、API调用流程图183、商品API接口193.1 获取商品池编号接口193.2 获取池内商品编号接口193.3 获取池内商品编号接口-品类商品池（兼容老接口）203.4 获取商品详细信息接口.v1213.5 获取商品上下架状态接口283.6 获取所有图片信息293.7 商品好评度查询303.8 商品区域购买限制查询303.9 商品区域是否支持货到付款333.10 查询赠品信息接口363.11 运费查询接口383.12 商品搜索接口393.13 商品可售验证接口433.14 查询商品延保接口443.15 查询分类信息接口473.16 查询分类列表信息接口493.17 同类商品查询523.18 查询商品详情装吧样式.v1553.19 商品序列号查询接口564、地址api接口574.1 获取一级地址574.2 获取二级地址584.3 获取三级地址594.4 获取四级地址594.5 验证四级地址是否正确604.6 根据地址查询京东地址编码.v1614.7 根据经纬度查询京东地址编码.v1625、价格API接口635.1 批量查询商品售卖价.v1（推荐）636、库存API接口656.1 调用流程图656.2 批量获取库存接口.v1（推荐）656.3 批量获取库存接口(建议商品列表页使用，待下线)676.4 批量获取库存接口（买卖宝使用，以5为阈值，待下线）687、订单API接口707.1 统一下单接口.v3717.2 统一余额查询接口797.3 查询用户余额接口（仅供预存款客户使用）807.4 查询用户金彩余额接口（仅供金彩支付客户使用）807.5 查询用户网银钱包余额接口（仅供网银钱包客户使用）817.6 查询用户金彩余额接口（仅供金彩支付客户使用）817.7 确认预占库存订单接口.v1827.8 取消未确认订单接口827.9 查询京东订单信息接口.v1837.10 订单反查接口907.11 发起支付接口917.12 查询配送信息接口917.13 根据订单号查询运单配送信息接口（买断模式使用）937.14 获取京东预约日历947.15 余额明细查询接口1007.16 确认收货（厂家直送）1027.17 获取电子签单下载地址1037.18 保存更新采购单号.v11048、企销API对账接口1058.1 新建订单查询接口1058.2 获取妥投订单接口1078.3 获取拒收消息接口1099、信息推送api接口1109.1 信息推送接口1109.2 根据推送id，删除推送信息接口11410、售后相关接口11510.1 服务单保存申请11510.2 填写客户发运信息11710.3 校验某订单中某商品是否可以提交售后服务11910.4 根据订单号、商品编号查询支持的服务类型11910.5 根据订单号、商品编号查询支持的商品返回京东方式12010.6 根据客户账号和订单号分页查询服务单概要信息12110.7 根据服务单号查询服务单明细信息12310.8 取消服务单/客户放弃12810.9 根据订单号查询和服务单号查询支付信息.v112911、发票相关接口13011.1 申请开票接口.v113011.2 查询发票信息接口13411.3 查询发票运单号13611.4 取消发票申请13711.5 获取电子发票信息.v113711.6 订单号查询第三方申请单号.v114011.7 订单号查询发票物流信息.v114112、合单支付相关接口14312.1 生成合单号接口14312.2 订单号查询合单号14412.3 合单号查询订单号14612.4 撤销合单号14812.5 获取汇款识别码14913、错误码（除售后外）151一、 名词解释 【拆单】：如果一个订单中有两个商品在京东分别存放在两个库房，比如说客户购买了一台苹果笔记本和一把尺子。下单后订单就会被拆分为两个子订单下到库房生产。【妥投】：快递员把货送到客户手中并且客户已经签收。【拒收】：快递员把货送到客户家时，客户由于某种原因拒绝签收该货物，视为拒收。【商品池】：由于京东商品数量太多，对于企业客户而言，获取京东所有商品不现实也没有必要。销售会把每个品类销售排名靠前的sku加到商品池中，也就是说商品池的放的商品就是客户所能购买的商品范围。二、 系统对接帮助文档（实物）1、 授权服务1.1 采用HTTPS的方式调用服务为保障传输过程中的信息安全，建议采用https方式调用服务。如果你已经熟悉https的访问，可以忽略下面的内容。因为是经过正规机构授权认证的证书，所以，客户端程序代码无需做手工校验或把证书加入受信任的证书列表。变更方法1、如果你原来基于HttpURLConnection方式调用，则需要更改为HttpsURLConnection。2、如果你原来是基于HttpClient方式调用，则直接把原访问地址改成https即可。比如：原访问地址为/xxx，改为/xxx。Java代码片段以下代码仅做示例使用。为了减少建立连接所消耗的时间和资源，建议采用连接池的方式。基于HttpsURLConnection的调用URL url = new URL(/xxx);HttpsURLConnection conn = (HttpsURLConnection) url.openConnection();conn.setRequestMethod(POST);.其它配置和参数传递略过基于HttpClient的调用HttpClient httpclient = new HttpClient();GetMethod httpget = new GetMethod(/xxx); try httpclient.executeMethod(httpget); System.out.println(httpget.getStatusLine(); finally httpget.releaseConnection();1.2 接口返回值说明注意：后续所有接口，均按照以下格式返回：result: /具体结果：说明，每个接口都会单独进行说明；resultCode:null, /错误码，详见“点击这里”；success:true, / 执行结果成功，还是失败；resultMessage: / 错误描述1.3 获取Access Token URL: /oauth2/accessToken HTTPS请求方式：POST 请求参数参数参数选项意义grant_type必须该值固定为access_tokenclient_id必须即对接账号(由京东人员提供)client_secret必须即对接账号的密码 (由京东人员提供)timestamp必须当前调用时间，格式为“2014-01-01 01:01:01”与京东服务器时差不能相差半小时以上，京东服务器时间为北京时间（年月日和时分秒中间有空格）username必须京东的用户名（注意：在调用我们接口时，如果username是中文，在url参数里面，需要将username使用urf-8格式进行UrlEncode编码，在生成sign签名串时，不需要进行编码，使用原文！）password必须京东的用户密码，必须是md5加密后的字符串，不要使用原文！scope非必须申请权限。（目前推荐为空。为以后扩展用）sign必须签名,生成规则如下：1. 按照以下顺序将字符串拼接起来client_secret+timestamp+client_id+username+password+grant_type+scope+client_secret其中client_secret的值是京东分配的username使用原文，password需要md5加密后的2. 将上述拼接的字符串使用MD5加密，加密后的值再转为大写 返回结果：类型JSON参数意义UIDAccess_token调接口使用长度varchar(25) 注：获取token之后token有效期24小时，有效期内都使用该token，设置定时任务，token即将过期时获取新的token替换旧的tokenRefresh_tokentime当前时间expires_inAccess_token的过期时间，秒级别,有效期24小时refresh_token_expiresrefresh_token的过期时间，毫秒级别 示例代码：输入参数：1. grant_type = access_token2. client_id = yourclientid3. username = yourpin4. password = yourpassword5. timestamp = 2014-01-01 01:01:016. scope=京东分配的 client_secret = yourclientsecret把所有参数按照顺序拼接起来，结果如下：yourclientsecret2014-01-0101:01:01yourclientidyourpinyourpasswordaccess_tokenyourclientsecretsign值为上述字符串进行MD5加密后转为大写，结果如下：sign=00C29BAAB23BBCE20C9BBD9C180E8330具体生成的访问url为：/oauth2/access_token?grant_type=access_token&client_id=yourclientid&scope=&username=yourpin&password=yourpassword×tamp=2014-01-01 01:01:01&sign=00C29BAAB23BBCE20C9BBD9C180E8330如果username是中文的话，在url中，需要进行UrlEncode.encode(“中文”,”utf-8”); 返回示例如下（包括AccessToken和RefreshToken等信息）：result:uid:111111,access_token : access_token,refresh_token : refresh_token,time : 1381480688147,expires_in : 86400,refresh_token_expires : 1397205488147其中time为当前时间expire_in 为access_token的过期时间，秒级别，代表86400秒后过期，即24小时有效期refresh_token_expires 为refresh_token的过期时间注意：如果token获取失败，返回的消息体 result: resultCode:null,success:false,resultMessage:失败原因1.4 使用Refresh Token 刷新 Access Token URL: /oauth2/refreshToken HTTPS请求方式：POST 请求参数参数名称参数选项意义refresh_token必须授权时获取的refresh_token client_id必须京东提供的client_id client_secret必须京东提供的 client_secret 返回结果：类型JSON参数意义UIDAccess_tokenRefresh_tokentime当前时间expires_inAccess_token的过期时间，秒级别,有效期24小时refresh_token_expiresrefresh_token的过期时间，秒级别 返回示例result: uid:111111,access_token : access_token,refresh_token : refresh_token,time : 1381480688147,expires_in : 86400,refresh_token_expires : 1397205488147time为当前时间expire_in 为access_token的过期时间，秒级别，代表86400秒后过期，即24小时有效期refresh_token_expires 为refresh_token的过期时间 注意事项：请将access_token和refresh_token进行数据库保存，access_token的有效期为24小时，如果access_token过期，请使用refresh_token进行刷新。推荐的方式是，利用定时器，每天凌晨调用刷新接口，使用refresh_token刷新一个新的access_token。如果token刷新失败，返回的消息体 result: resultCode:null,success:false,resultMessage:失败原因2、 API调用流程图3、 商品API接口3.1 获取商品池编号接口 URL: /api/product/getPageNum HTTPS请求方式：POST 请求参数参数名称参数选项意义token必须授权时获取的access token 返回结果result: name:池子名称, page_num:1, name:池子名称2, page_num:2 3.2 获取池内商品编号接口 URL: /api/product/getSku HTTPS请求方式：POST 请求参数参数名称参数选项意义token必须授权时获取的access tokenpageNum必须池子编号 返回结果result: 123123,1523523.3 获取池内商品编号接口-品类商品池（兼容老接口） URL: /api/product/getSkuByPage HTTPS请求方式：POST 请求参数参数名称参数选项意义token必须授权时获取的access tokenpageNum必须池子编号pageNo必须页码，默认取第一页；每页最多10000条数据（因每页数据动态过滤，可能存在当前页无数据的情况，请继续查询下一页），品类商品池可能存在多页数据，具体根据返回的页总数判断是否有下一页数据 返回结果 success: true, resultMessage: 操作成功, resultCode: 0000, result: pageCount: 1, skuIds: 916606, 853073 3.4 获取商品详细信息接口.v1 URL: /api/product/getDetail HTTPS请求方式：POST 请求参数参数名称参数选项意义tokenString必须授权时获取的access tokenskuString必须商品编号，只支持单个查询isShowboolean非必须false:查询商品基本信息；true:商品基本信息 + 商品售后信息 + 移动商品详情介绍信息该值废弃，老用用户默认=appintroduce,shouhouqueryExtsString非必需可选扩展参数，支持单个/多个查询逗号间隔： appintroduce：移动商品详情介绍信息(如果接口的appintroduce是null，就用introduction) shouhou：商品售后信息 isFactoryShip 是否厂商直送(仅针对自营商品查询。出参中 1是厂商直送，0非厂商直送) isEnergySaving 是否政府节能 contractSkuExt 定制商品池开关 ChinaCatalog 中图法分类号 taxCode 税收分类编码LowestBuy 最小购买数量capacity 成品油容量spuId 主商品idpName主商品名称isJDLogistics是否京东配送：1是 ，0 不是isSelf是否京东自营：1是 ，0 不是返回结果返回结果会根据skuid位数而不同。sku小于8位会返回其他sku的格式，sku为8位时，返回图书或者是音像的详情结果。具体字段如下：为图书： (图书商品详细的样例数据)result: sku : 商品编号,name: 商品名称， skuType : book, / 可以使用这个字段区分是图书还是音像 Author : 著者, Editer : 编者, Transfer : 译者, Drawer : 绘者, Proofreader : 校对, ISBN : ISBN, Publishers : 出版社, Sheet : 开本, Pages : 页数, Package：包装, PublishTime：出版时间, BatchNo：版次, PrintTime：印刷时间, PrintNo：印次, PackNum：套装数量, Language：正文语言, Papers：用纸, Brand：品牌, comments：媒体评论, image：插图, contentDesc：内容摘要, relatedProducts：产品描述, editerDesc：编辑推荐, catalogue：目录, bookAbstract：精彩摘要, authorDesc：作者简介, introduction：前言为音像：（音像商品详细样例数据）result: sku : 商品编号,brandName : 品牌, name : 商品名称，音像名称, productArea : 产地, upc：条形码, saleUnit : 销售单位, category: 类别, skuType : vedio,/ 可以使用这个字段区分是图书还是音像 Actor : 演员, Director : 导演, Singer : 演奏者, Performer : 演唱者, Authors : 作词, Compose : 作曲, Screenwriter : 编剧, Language_Pronunciation : 主讲人, Voiceover : 解说, Foreignname：外文名, Aka：又名, Publishing_Company：发行公司, Soundtrack：碟数, Media：介质, Dregion：地区, Episode：集数, Brand：厂牌, Length：片长, Region：区码, Press：出版社, Production_Company：出品公司, ReleaseDate：上映日期, Copyright：版权提供, Mvd_Wxjz：文像进字, Audio_Encoding_Chinese：音频格式, Language_Dubbed：配音语言, Language_Subtitled：字幕语言, Screen_Ratio：屏幕比例, Format：画面色彩, ISRC：ISRC, comments：评论, image：商品主图, contentDesc：内容摘要, editerDesc：编辑推荐, catalogue：目录, box_Contents：包装清单, material_Description：特殊说明, manual：说明书为其他实物：result: sku : 商品编号, weight : 重量, imagePath : 主图地址, state : 上下架状态, brandName : 品牌, name : 商品名称, productArea : 产地, upc：条形码, saleUnit : 销售单位, category: 类别, eleGift: 4, / 京东自营礼品卡， 只有当sku为京东自营实物礼品卡的时候才有该字段 introduction:产品信息Product Information产品特色Selling Point, param： 主体品牌雷蛇 Razer类型有线鼠标型号地狱狂蛇镜面特别版颜色黑色规格传输方式线缆人体工学否鼠标工作方式光电鼠标分辨率3500dpi接口USB鼠标尺寸115(L) x 63(W) x 40(H) mm重量0.09kg, wareQD : 笔记本主机 x1 电池 x1 电源适配器 x1 注意事项其中：param 返回的是 规格参数 Introduction 详细介绍 提供了demo页面 分别是 规格参数.html,详细介绍.html,样式在demo页面中imagePath 为商品的主图片地址。需要在前面添加/n0/ 其中n0(最大图)、n1(350*350px)、n2(160*160px)、n3(130*130px)、n4(100*100px) 为图片大小。例如接口返回imagePath为g8/M03/0E/06/rBEHaFCg5wQIAAAAAAGhG73oiLUAACxswH4MBwAAaEz619.jpg拼接后的url为：/n0/g8/M03/0E/06/rBEHaFCg5wQIAAAAAAGhG73oiLUAACxswH4MBwAAaEz619.jpg移动商品详情查询举例请求：/api/product/getDetail?token=yourToken&sku=569200&isShow=true返回请见文件：3.5 获取商品上下架状态接口 URL: /api/product/skuState HTTPS请求方式：POST 请求参数参数名称参数选项意义token必须授权时获取的access tokensku必须商品编号，支持批量，以，分隔 (最高支持100个商品)1为上架，0为下架 返回结果result”:sku”:111111,”state”:1,sku”:111111,”state”:03.6 获取所有图片信息 URL: /api/product/skuImage HTTPS请求方式：POST 请求参数参数名称参数选项意义token必须授权时获取的access tokensku必须商品编号，支持批量，以，分隔 (最高支持100个商品) 返回结果result:100012”:path:” 7393/ca49c783-e1bb-418f-8063-47a6d20158ca.jpg”,”isPrimary”:1,”orderSort”:0,path:” 7393/ca49c783-e1bb-418f-8063-47a6d20158ca.jpg”,” isPrimary”,0,”orderSort”:1其中path是地址，isPrimary为是否是主图，1为主图，0为附图。orderSort为排序图片路径，如上面商品详情页面返回的图片地址一致。3.7 商品好评度查询 URL: /api/product/getCommentSummarys HTTPS请求方式：POST 请求参数参数名称参数选项意义token必须授权时获取的access tokensku必须商品编号，支持批量，以，分隔 (最高支持50个商品) 返回结果参数名称意义averageScore商品评分 (5颗星，4颗星)goodRate好评度generalRate中评度poorRate差评度result:averageScore:5,generalRate:0.0,goodRate:1.0,skuId:800020,poorRate:0.0,averageScore:5,generalRate:0.0,goodRate:1.0,skuId:800035,poorRate:0.03.8 商品区域购买限制查询 URL: /api/product/checkAreaLimit HTTPS请求方式：POST 请求参数参数名称参数选项意义token必须授权时获取的access tokenskuIds必须商品编号，支持批量，以,分隔 (最高支持100个商品)province必须京东一级地址编号city必须京东二级地址编号county必须京东三级地址编号town必须京东四级地址编号 返回结果参数名称意义success检查是否成功，true:成功；false:失败resultMessage若检查失败，则该字段会显示失败原因resultCode错误码，暂未使用，默认为nullresult若检查成功，则该字段显示商品区域限制检测结果，检验结果格式如下：result:skuId:12345,isAreaRestrict:true,skuId:12344,isAreaRestrict:false,skuId:12345,isAreaRestrict:false说明skuId 商品编号isAreaRestrict true 代表区域受限 false 区域不受限 检测成功返回示例：success:true,resultMessage:,resultCode:null,result:skuId:102194,isAreaRestrict:truesuccess:true,resultMessage:,resultCode:null,result:skuId:102194, isAreaRestrict :true,skuId:107164, isAreaRestrict :false用户不具备该商品购买权限：success:true,resultMessage:您不具有如下商品购买权限skuIds:102194,resultCode:null,result:nullsuccess:true,resultMessage:您不具有如下商品购买权限skuIds:1,2,3,resultCode:null,result:skuId:107164,isAreaRestrict:false 检测失败返回示例：参数有误：success:false,resultMessage:待检查的skuIds输入为空! 省份信息输入不能为空! 市级信息输入不能为空! 县级信息输入不能为空!,res