京东POP-Open-API文档.doc

POP Open API京东商城 Open API （WebService版）1使用说明11.1在线文档11.2接入说明11.3技术说明12订单API22.1获取订单信息列表API22.2获取单个订单信息API62.3商家出库操作API72.4面单打印API（发货到京东）82.5SOP发货操作API113商品API123.1SKU信息查询API123.2SKU信息修改API133.3通过条件查询商品ID列表 API（初版）143.4通过商品ID查询商品信息API（初版）153.5商品上下架API164库存API174.1更新SKU库存API175售后API185.1退货收货查询API185.2退货收货确认API206其他API216.1获取商家发货地址API216.2获取商家物流公司API217商家合作类型说明238签名说明23京东POP Open API （WebService版） 2011-05-201 使用说明1.1 在线文档主页：/正式版：/doc/doc.html测试版：0/doc/doc.html文档会进行定期更新，请以最新在线文档为准！正式版文档里面包含正式发布的API；测试版文档一般要比正式版更新，里面包含了还没发布的新API或者更新。1.2 接入说明使用API需要提供商家编号(venderId) ，商家密钥(venderKey、secretcode)，如何使用，请参考签名说明。测试时，向API产品经理提供商家基本信息（尤其是合作类型），API产品经理会根据情况给予测试环境的商家编号和密钥。商家的开发人员可以在测试环境的地址使用测试账号信息进行测试。正式对接时，商家编号可以在京东商家后台(/)中看到（首页“用户ID：10XXX”或者 我的店铺“商家编号：10XXX”，注意不是“店铺ID”）；正式环境的商家密钥，在向API产品经理确认测试完成并且给予基本信息、IP后，由API产品经理开通并将密钥以邮件附件的形式发送给商家的京东负责人。1.3 技术说明京东开放平台API，目前以SOAP WebService的方式提供。目前主流语言平台，比如：.Net、Java、PHP、vb6、C/C+等，都可以接入。由于要使用IP本API文档由 杨宇帆 整理2 订单API2.1 获取订单信息列表API功能说明：根据检索条件，进行订单的查询，获取订单列表（支持分页）。适用商家：所有类型商家注意事项：开始时间和结束时间不得超过1个月！此查询类接口不能过于频繁的调用！字段列表，如果为空，则返回默认字段；不为空，返回选择的字段，订单ID不选也会返回查询的时候，时间是下单的时间，考虑到等待付款的问题，请把开始时间调整到当前时间24个小时以上（一般26-48个小时应该没问题），就不会漏单了。请不要把间隔调太大，否则很容易查询超时！方法名：searchOrderInfo正式WSDL：/services/services/orderSearchService?wsdl测试WSDL：0/services/services/orderSearchService?wsdl 输入参数名称类型必填描述venderSignlong商家签名，详见签名说明tradeNostring流水号，用于生产变化的签名，详见签名说明venderIdstring商家ID，商家唯一标识，例如：10111，详见签名说明startDatestring用于查询时间段的开始时间（目前推荐为当前时间26个小时之前）（时间格式 yyyy-MM-dd hh:mm:ss，下同）endDatestring用于查询时间段的结束时间（相差不能超过一个月）orderStatestring用于基于订单状态的查询（商家只需要录入等待出库的订单）optionalFieldsstring字段列表，选择需要哪些内容返回pagestring查询的页数（不限页数）（默认是第一页）pageSizestring每页的条数（一次最多20条，默认10条） 查询的订单的状态状态码名称备注ALL全部正式环境不要查询全部订单WAIT_BUYER_PAY等待付款SOP商家专用（最多24小时）WAIT_SELLER_STOCK_OUT等待出库对于商家而言是新订单，需要对这些订单进行“出库”操作（LBP、SOPL操作结束）TO_JD_DISTRIBUTION_CENTER发往京东配送中心LBP、SOPL商家专用JD_DISTRIBUTION_CENTER_RECEIVED京东配送中心已收货LBP、SOPL商家专用WAIT_SELLER_DELIVERY等待发货SOP商家需要对这个状态的订单进行“发货”操作（SOP操作结束）WAIT_BUYER_CONFIRM_GOODS已发货等待买家确认（SOP订单会在一定时间后自动妥投）TRADE_FINISHED买家已收货妥投的订单TRADE_CLOSED已取消此项将删除，使用新API代替TRADE_BUYER_REFUSED拒收LBP商家专用 可选字段选择需要的字段，并且用逗号分开，比如：payType,totalDiscountFee,payment,skuOutId字段名称名称备注orderId订单编号不用选择，必然返回venderId商家编号payType支付方式对于货到付款和自提，都是后款freightPrice订单运费京东目前免运费，所以此项为0factFreightPrice实际运费totalDiscountFee优惠总金额商家承担的优惠+京东券礼券+用户余额payment用户实付金额用户付款之前为0sellerOrderRemark商家订单备注卖家自己在订单上的备注，买家看不见orderEndTime结单时间在结单之前，此项为空deliveryDateRemark送货日期wareTotalPrice商品总金额京东不收取运费，目前两者相等orderTotalPrice订单总金额orderState订单状态返回的是中文状态invoiceInfo发票信息对于非SOP商家，京东开发票，意义不大buyerOrderRemark买家订单备注orderStartTime下单时间wareId商品idskuOutIdSKU外部idwareOutId商品外部id预留字段，目前为空，请不要选择skuIdSKU京东idproductNo商品货号giftPoint赠送积分在赠送积分促销是会有wareName商品名称规格jdPriceSKU京东价单件的京东价，不包括数量和优惠wareDiscountFee优惠金额商家承担的优惠，已经包括数量wareTotal商品数量每个wareInfo的数量，不是wareInfo总数consigneeInfo用户信息包括了姓名、地址等信息 输出参数名称类型必须描述apiOrderQueryDetailApiOrderQueryDetail是 数据类型 API返回结果（ApiResult）名称类型非空描述isSuccess*boolean是否成功（成功返回true，失败返回false）englishErrCodeString英文错误原因，如果成功，此字段为空chineseErrCodeString中文错误原因，如果成功，此字段为空numberCodeint错误号码*由于我们使用的Java服务框架会自动将isSuccess解析为success，所以非Java用户，此项为success！ 订单查询返回结果（ApiOrderQueryDetail）名称类型描述隐私示例值ordersList 所有订单数据否apiResultApiResult返回的处理信息否orderTotalint查询订单的数量否 订单信息（Order）名称类型默认描述orderIdstringpop的订单编号venderIdstring商家唯一标识wareInfosList参见“商品信息类型Ware”payTypestring支付方式：货到付款/上门自提/在线支付等freightPricestring运费金额factfreightPricestring实际的运费，订单完成之前为0deliveryDateRemarkstring送货日期：只工作日/工作日等类型wareTotalPricestring商品总金额（各个商品的京东价累计和，不包括优惠）orderTotalPricestring订单总金额（商家后台的订单金额，不包括优惠）totalDiscountFeestring优惠的总金额（包括京东券和余额）paymentstring用户实际支付金额，支付前为0consigneeInfoConsignee参见“收货人基本信息类型”orderStatestring订单的状态，返回的是中文状态invoiceInfostring发票信息，比如：发票类型:普通发票;发票抬头:个人;发票内容:明细buyerOrderRemarkstring买家下单时的备注sellerOrderRemarkstring商家自己的订单备注（买家看不到）orderStartTimestring订单创建时间orderEndTimestring订单结束时间（妥投或者取消），之前为空 订单中商品（Ware）名称类型默认描述wareIdstring商品的京东idwareOutIdstring对应商家的商品idproductNostring商品的货号wareNamestring商品的名称和规格（比如：XXX 红 M）skuOutIdstring对应商家的SKU的idskuIdstring京东内部SKU idjdPricestringSKU的京东价（没有乘以数量），不包括优惠wareDiscountFeestring此SKU的优惠金额（目前只包含单品促销）（已经乘以数量）giftPointstring赠送积分，购买此商品赠送的积分wareTotalstring商品的数量 订单中收货人信息（Consignee）名称类型描述userNamestring姓名userAddressstring地址userPoststring邮编（一直为空）userTelephonestring固定电话userMobilephonestring手机userEmailstringEmail2.2 获取单个订单信息API功能说明：根据京东订单ID获取单笔交易订单的详细信息。适用商家：所有类型商家注意事项：此API必须通过批量查询API获取京东订单ID后才能使用方法名：searchOrderInfoByOrderId正式WSDL：/services/services/orderSearchService?wsdl测试WSDL：0/services/services/orderSearchService?wsdl 输入参数名称类型必须描述venderSignstring是签名tradeNostring是流水号venderIdlong是商家idorderIdstring否订单idoptionalFieldsstring否字段列表，选择需要哪些内容返回 输出参数名称类型必须描述apiOrderQueryDetailApiOrderQueryDetail是订单列表，但本API只返回单个2.3 商家出库操作API功能说明：通知京东订单已经出库，京东会按照订单信息，自动减去相应库存。LBP和SOPL，由于发往京东配送中心，还需输入一些额外信息。适用商家：非FBP（LBP、SOPL、SOP）注意事项：一次只能出库一个订单。各个类型商家输入的参数有所不同。LBP、SOPL商家必须设置默认发货地址！方法名：outStorage正式WSDL：/services/services/orderSearchService?wsdl测试WSDL：0/services/services/orderOutStorageService?wsdl 输入参数名称类型必须描述venderSignstring签名tradeNostring流水号venderIdlong商家的idorderOutDataOrderOutDataLBP出库数据最大长度为20 输出参数名称类型非空描述apiResultApiResult请求是否正确接收 数据类型 出库信息（OrderOutData）（请注意不同类型商家可以输入的值）名称类型LBPSOPLSOP描述orderIdlong必填必填必填京东订单ID（SOP只需填写此项）packageNumint1-1001-100空包裹数sendTypeint11空发货类型（1发往配送中心；2 通知京东取货）addressIdlong空可选空发货地址ID（可通过获取商家发货地址接口获得）0表示默认发货地址（在后台设置）logisticsIdint可选空空物流公司ID（可通过获取商家物流公司接口获得）0为“自送”，SOP不用waybillstring见说明*空空这次发往配送中心的运单号（20个字符）“自送”时，必须为空，否则不能为空*logisticsId=0则waybill必须为空；logisticsId0则waybill必填！为“空”的字段，系统会忽略里面的内容，请不要填写！2.4 面单打印API（发货到京东）功能说明：LBP、SOPL出库时，需要把打印的面单贴在包装上适用商家：仅LBP、SOPL（SOP不适用此API）注意事项：必须先获取订单id。最好先出库后打印订单，否则打印结果的出库时间是错误的。打印必须使用京东的彩色面单纸进行套打！方法名：print正式WSDL：/services/services/orderPrintService?wsdl测试WSDL：0/services/services/orderPrintService?wsdl 输入参数名称类型必须描述venderSignstring签名tradeNostring流水号venderIdlong商家的idorderIdstring订单号selectFieldsstring返回字段选择（htmlContent，imageData，默认都返回）如果不需要图片，请设置为“htmlContent”如果只需要图片，请设置为“imageData”（按需选择可以提高效率） 输出参数名称类型必须描述printResultPrintResult打印结果对象 数据类型 打印结果（PrintResult）名称类型非空描述apiResultApiResult返回的处理信息htmlContentstringhtml的内容，条形码src=barcode_urlimageDatastring订单条形码图片二进制base64编码条形码内容为订单号，使用Code128编码l htmlContent：返回面单页面的HTML代码，使用时把barcode_url替换成图片的地址即可。l imageData：是条形码图片二进制内容进行base64编码的结果，内容为图片文件根据data uri协议编码的结果。比如data:image/jpeg;base64,/9j/4AAQ.(图片内容base64编码)image/jpeg表示是jpg文件，image/gif、image/png分别表示gif、png文件。l 如果打印的系统安装的浏览器是IE6、IE7，由于不支持data uri，必须将图片的base64编码（不含前面data:image/jpeg;base64,）进行base64解码形成二进制内容，然后根据定义的图片格式保存成图片，然后将图片地址替换掉html中的barcode_url既可。l 如果不考虑IE6、7，浏览器是IE8或以上版本，或者使用Firefox、Chrome浏览器，可以直接把imageData中的内容替换掉html中的barcode_url既可。（打印结果、彩色面单纸参见下两页） 京东面单示例图1面单打印结果示意（纵向A4，内容可能会有略微不同）图2京东面单纸示意图（纵向A4，从京东购买）2.5 SOP发货操作API功能说明：SOP对订单进行发货操作，先出库后发货；发货操作意味着货物上路适用商家：仅SOP注意事项：一次只能发货一个订单。物流公司为0自送时，运单号必须为空，否则必填！方法名：delivery正式WSDL：/services/services/orderDeliveryService?wsdl测试WSDL：0/services/services/orderDeliveryService?wsdl 输入参数名称类型描述必须venderSignstring签名是tradeNostring流水号是venderIdlong商家的id是sopDeliverySopDeliveryDataSOP商家的发货的订单信息是 输出参数名称类型描述必须apiResultApiResultAPI 返回的处理信息是 数据类型 SOP发货信息（SopDeliveryData）名称类型必填描述orderIdlong京东订单IDlogisticsIdint物流公司ID（可通过获取商家物流公司接口获得）。0表示“自送”waybillstring这次发往物流的运单号（20个字符）“自送”时，必须为空，否则必填3 商品API3.1 SKU信息查询API功能说明：通过输入商品ID列表、京东SKUID或者商家SKUID，来查询SKU信息。京东商品ID列表：返回所有选定商品的所有SKU信息列表京东SKUID列表：返回对应SKU的信息列表（顺序一一对应），如果某个ID查询失败，对应的SKU信息为空商家SKUID列表：返回对应SKU信息列表，规则同上适用商家：所有类型商家注意事项：根据“ID类型Type”选择输入哪种ID的列表方法名：searchSkuInfo正式WSDL：/services/services/skuInfoSearchService?wsdl测试WSDL：0/services/services/skuInfoSearchService?wsdl 输入参数名称类型必填描述venderSignstring签名tradeNostring流水号venderIdlong商家唯一标识，例如：10001idTypestring查询id列表类型当是京东商品ID列表，类型是JD_WARE 当是京东SKUID列表，类型是JD_SKU 当是商家SKUID列表，类型是VENDER_SKUidListList京东商品ID列表，最多10个京东/商家SKU列表，最多30个optionalFieldsstring选择需要返回的字段（见默认返回列）可选：skuId,outerSkuId,wareId,skuStocks,jdSkuPrice,createdTime,modifiedTime,skuName 输出参数名称类型非空描述apiResultApiResult成功与否venderIdstring商家唯一标识，例如：10001skuTotalint获取SKU信息的总数量skuInfosListSKU信息列表 数据类型 SKU信息（SkuInfo）名称类型默认返回描述skuIdstring京东的SKU IDouterIdstring商家外部SKU IDvenderIdstringSKU所属商品的京东IDstockNumint此SKU的库存量jdPricestring次SKU的京东价skuNamestringSKU的商品名称+规格（比如 XXX 红 L）createdTimestringSKU创建的时间modifiedTimestringSKU最后修改时间3.2 SKU信息修改API功能说明：根据商家ID和京东SKUID修改SKU的信息，包括SKU的京东价、库存和外部ID。适用商家：所有类型商家，但FBP不能修改库存注意：SKU的属性信息，暂不提供！如果商家SKUID、京东价、库存都不填，即没有修改任何信息，报错一次只能修改一个字段，不可以同时修改多个字段目前暂不支持修改京东价！方法名：updateSkuInfo正式WSDL：/services/services/skuInfoUpdateService?wsdl测试WSDL：0/services/services/skuInfoUpdateService?wsdl 输入参数名称类型必须描述venderSignstring签名tradeNostring流水号venderIdlong商家唯一标识，例如：10001skuIdstring京东的SKU IDfieldNamestring要修改字段名称，只能选择一个stocks：库存(FBP不可选)outerSkuId：sku外部IDfieldValuestring要修改字段值（外部ID可为空，为空时就是将此属性置空） 输出参数名称类型非空描述apiResultApiResult请求是否正确接收3.3 通过条件查询商品ID列表 API（初版）功能说明：通过各种商品的字段进行搜索，返回商品ID列表，并支持分页适用商家：所有类型商家注意：目前只能分别查询在售和待售的商品列表；开始时间和结束时间不能相差超过3个月此API目前还未定型，可能在未来进行改进方法名：searchWareIdInfo正式WSDL：/services/services/wareIdSearchService?wsdl测试WSDL：0/services/services/wareIdSearchService?wsdl 输入参数名称类型必填描述venderSignString签名tradeNoString流水号venderIdlong商家的idfieldNameString查询字段名称（目前只支持货号 productNo）可选fieldValueString查询字段值，货号最多支持50个字符。wareStateString商品状态(在售：selling，待售：waiting)startTimeString时间开始endTimeString时间结束pageString分页号(1-100)pageSizeString每页数量(1-100) 输出参数名称类型非空描述apiResultApiResult成功与否venderIdstring商家唯一标识，例如：10001wareTotalint（目前是当前页数量，分页请进行试探）wareIdListList符合条件的商品ID列表3.4 通过商品ID查询商品信息API（初版）功能说明：通过京东的水平ID查询商品，可以比较精确的查询适用商家：所有类型商家注意：此API目前还未定型，可能在未来进行改进方法名：searchWareInfo正式WSDL：/services/services/wareInfoSearchService?wsdl测试WSDL：0/services/services/wareInfoSearchService?wsdl 输入参数名称类型必填描述venderSignstring签名tradeNostring流水号venderIdlong商家唯一标识，例如：10001wareIdListList京东商品ID的列表optionalFieldsstring选择需要返回的字段（见默认返回列） 输出参数名称类型非空描述apiResultApiResult成功与否venderIdstring商家唯一标识，例如：10001wareTotalint获取商品的数量wareInfoListList商品信息列表 数据类型 商品信息（WareInfo）名称类型默认返回描述wareIdstring商品idwareOuterIdstring商家自己的商品idvenderIdstring商家唯一标识wareNamestring商品的名称productNostring商品的货号wareStatestring上下架状态jdPricestring商品的京东价wareStocksTotalstring各个SKU库存之和delistingOrListingTimestring在售商品上架时间 或 待售商品下架时间3.5 商品上下架API功能说明：通过京东商品ID，上架或下架对应商品。适用商家：所有类型商家注意：每次只能操作一个商品，不支持批量；操作后，系统会有较长的延迟，展示页面才会变化方法名：updateSaleSate正式WSDL：/services/services/saleStateUpdateService?wsdl测试WSDL：0/services/services/saleStateUpdateService?wsdl 输入参数名称类型必填描述venderSignstring签名tradeNostring流水号venderIdlong商家的idwareIdstring京东的商品ID（只支持一个）wareStatestring上架(ON_SHELF)、下架(OFF_SHELF) 输出参数名称类型非空描述apiResultApiResult请求是否正确接收4 库存API4.1 更新SKU库存API功能说明：根据京东SKU的id更新SKU库存量。适用商家：仅LBP、SOP前提条件：通过京东SKU ID获取接口或其他接口已经获取了京东SKU的ID。由于skuId是Java的Long类，所以如果是.Net对接，则必须把一个叫做skuIdSpecial的属性设置为true！注意：此API功能以被SKU信息修改API包含，但是可能没有这个API效率高。方法名：stockUpdate正式WSDL：/services/services/stockService?wsdl测试WSDL：0/services/services/stockService?wsdl 输入参数名称类型必须描述venderSignstring签名tradeNostring流水号venderIDlong商家的idskuStockUpdataSkuStockUpdata更新的库存的数据 输出参数名称类型非空描述返回结果ApiResult请求是否正确接收 数据类型 库存更新信息（SkuStockUpdata）名称类型必填描述skuIdLongsku的idsubtractNumint要更新的库存数（大于等于0的整数）5 售后API5.1 退货收货查询API功能说明：查询退货单及其SKU信息。用户退货、拒收后，商品被退回京东备件库，在备件库积累一段时间或一定数量后，将商品寄回商家，并产生退货单，此API提供退货单信息查询的功能。适用商家：所有类型商家注意：商家收货地址是包括邮编的字符串，比如：“邮编：321061。地址：浙江省金华市婺城区白龙桥镇山回铺村”。拒收商品一定不会有退货原因，退货商品的退货原因不一定会录入。发货地址、发货人联系方式，目前没有内容，字段预留。方法名：searchReturnInfo正式WSDL：/services/services/returnGoodsSearchService?wsdl测试WSDL：0/services/services/returnGoodsSearchService?wsdl 输入参数名称类型必填描述venderSignstring签名：商家ID、流水号、商家Key生成的签名tradeNostring流水号：商家自行生成的字符串，相同流水号表示同一个请求venderIdlong商家ID：商家唯一标识，例如：10001queryFieldsList查询字段键值对，详见“查询字段”selectFieldsstring选择需要返回的字段，为空返回默认字段，否则按照指定字段返回。可选包括ReturnInfo全部非预留字段，详情只需选returnItemList即可。pagestring分页号：1-100pageSizestring每页数量：1-10 查询字段（queryFields中Field类型的name）名称类型描述returnIdstring退货单号，只支持查询一个，默认不限制consignorstring发货人，只支持查询一个，默认不限制receiveStatestring退货状态：待收获WAITING、已收货RECEIVED，默认不限制orderIdstring订单号：退货物品所属订单号，返回所属的整个退货单attachmentCodestring备件条码：退货物品的备件条码，返回结果与上面类似timeTypestring时间类型：可以按选择的时间查询（修改时间 MODIFIED_TIME发货时间SEND_TIME、收货时间RECEIVE_TIME）startTimestring开始时间：所选类型时间的开始(yyyy-MM-dd hh:mm:ss) endTimestring结束时间：所选类型时间的结束（格式同上） 输出参数名称类型非空描述apiResultApiResult结果：成功与否totalNumint总数量：匹配查询结果的数量returnInfoList退货单信息列表 数据类型 字段键值对（Field）名称类型描述keystring键名valuestring键值 退货单信息（ReturnInfo）名称类型默认描述returnIdstring退货单号：退货单ID，此次退货的发货单venderIdstring商家编号sendTypestring发货类型：目前只有出商家TO_VENDERreceiveStatestring收货状态：待收获WAITING、已收货RECEIVEDlinkmanstring商家联系人姓名mobilestring商家联系人手机（预留）phonestring商家联系人电话returnAddressstring商家收货地址（包括了邮编）returnRemarkstring退货备注（预留）consigneestring实际收货人（商家收货前为空）consignorstring京东的发货人姓名sendAddressstring京东发货地址（预留）sendMobilestring发货人手机（预留）sendPhonestring发货人电话（预留）sendTimestring京东给商家发货的时间receiveTimestring商家确认收货的时间modifidTimestring记录更新时间returnItemListList货物信息列表 退货物品信息（ReturnItem）名称类型描述returnItemIdstring退货物品信息记录ID，每个SKU都会有一条记录attachmentCodestring备件条码：贴在退货商品上的退货条码，如：FX-POP2115627skuIdstring京东的SKU ID，可以通过SKU接口查询到具体信息skuNamestringSKU名称：商品名称+规格（如果商品多个规格）orderIdstring订单号：退货商品所属订单，0表示没有记录订单号pricestring购买时的最终价格，商品的单价returnTypestring售后RETURNED、拒收REJECTED、大库入FROM_WAREHOUSEreturnReasonstring客户申请退货时填写的原因，目前大都为空modifidTimestring记录更新时间5.2 退货收货确认API功能说明：商家收到退货后，对退货单进行收货确认操作适用商家：所有类型商家注意：不支持批量确认和部分确认方法名：searchReturnInfo正式WSDL：/services/services/returnGoodsConfirmService?wsdl测试WSDL：0/services/services/returnGoodsConfirmService?wsdl 输入参数名称类型必填描述venderSignstring签名：商家ID、流水号、商家Key生成的签名tradeNostring流水号：商家自行生成的字符串，相同流水号表示同一个请求venderIdlong商家ID：商家唯一标识，例如：10001returnIdstring退货单ID：查询得到的退货单ID（不支持多个） 输出参数名称类型非空描述apiResultApiResult结果：成功与否6 其他API6.1 获取商家发货地址API功能说明：用于SOPL订单出库时，获取发货地址列表，LBP无需调用此接口适用商家：仅LBP、SOPL（SOP无此功能）前提条件：商家通过商家客户端设置了我的发货地址信息，并且设置了默认地址注意：SOPL如果有多个发货地址可以使用本接口，SOP、LBP无需调用此接口LBP、SOPL商家，出库使可以使用0表示默认地址方法名：getStockAddress正式WSDL：/services/services/venderOutAddressService?wsdl测试WSDL：0/services/services/venderOutAddressService?wsdl 输入参数名称类型必须描述vender