天猫商城WMS接入规范白皮书.docx

天猫商城WMS接入规范白皮书天猫商城WMS接入规范白皮书Revision HistoryDateVersionDescriptionAuthor2011.12.050.5整体框架，系统逻辑，接口逻辑，测试用例，沙箱使用，联调上线蒋启帅2011-12-270.6添加XML示例，去掉表3-12中的“item-code”蒋启帅2012-1-50.6.1增加沙箱环境里的gateway地址蒋启帅2012-2-220.6.2修改日常测试环境gateway地址，订单确认中的item list.蒋启帅2012-02-290.6.3增加订单操作的注意事项蒋启帅2012-10-240.7.0订单确认接口修改蒋启帅目录目录第一章 前言41.前言42.名词解释4第二章 对接流程5第三章 系统与接口7包装整理费-包裹处理费34包装整理费-打包费34包装整理费-包装物料费35运费-配送费35装卸搬运费-装卸费35服饰仓储费35电器仓储费（TP）36电器仓储费（商家）36包装整理费-开箱全检费36包装整理费-熨烫整形费37包装整理费-紧急收货费37包装整理费-更换包装费37包装整理费-挂吊牌费37包装整理费-代贴条码费37包装整理费-退货入仓费38包装整理费-批量退仓费38包装整理费-鞋类清洁费38包装整理费-鞋类清洁费38包装整理费-订单取消返回货架费38第四章 联调与上线51第一章 前言1. 前言淘宝商城，亚洲最大网上购物网站淘宝网打造的在线B2C购物平台。自2008年4月10日建立淘宝商城以来，众多品牌包括联想、惠普、优衣库、迪士尼、Kappa、乐扣乐扣、JackJones、罗莱家纺在淘宝商城开设的官方旗舰店，受到了消费者的热烈欢迎。迄今为止，淘宝商城已经拥有超过1.8亿买家，15000个商户，20000个品牌。目前的淘宝商城处在飞速发展阶段，多种新型网络营销模式正在不断被开创。在淘宝商城业务飞速发展的过程中，商城商家产生了巨大的整体电子商务解决方案需求。物流宝通过整合各方资源为淘宝商城商家提供了包括物流服务、ERP服务在内的整体电子商务解决方案。为了方便ERP合作伙伴能快速了解淘宝商城的业务、物流宝业务、商城商家的作业流程，对接物流宝，加入物流宝体系，从而为商城商家提供更好的服务，我们推出了ERP接入物流宝白皮书。本文档的目标读者为有意向接入物流宝为淘宝商城商家服务的TMS合作伙伴。2. 名词解释WLB: 物流宝B2C：Business to Customer TMS：Transportation Management System 物流管理系统 WMS: Warehouse Management System 仓库管理系统TP：淘拍档（Taobao Partner），即淘宝合作伙伴，是指加入淘宝合作伙伴计划的各类外包服务提供商，简称TP。TC: Transaction Center，交易中心，本文专指淘宝交易中心。LC: Logistics Center，物流中心，本文专指淘宝物流中心。第二章 对接流程TP淘宝商城1. 业务接洽运营业务流程2. 垂直市场PD确认垂直市场PD3. 横向PD提供申请表横向PD4. 提交申请表 横向PD5. 提供白皮书，组织业务技术讲解TP技术人员技术支持，横向PD 6. 待TP开发完成接口后，提供沙箱账号TP技术人员技术支持7. 调用接口联调自测TP技术人员 技术支持8. 反馈联调结果TP技术人员技术支持9. 日常环境测试TP技术人员 淘宝测试人员10. 日常测试通过后，发布服务TP技术人员 运营11. 线上线下联调测试TP技术人员 淘宝测试人员技术流程具体的时效以及接入流程请参照：TP接入具体流程.xlsx，本文仅涉及技术流程第三章 系统与接口3.1. 系统逻辑WLB与WMS使用HTTP POST方式进行通讯。WLB提供gateway服务。l 主动模式WLBWMS 1.WLB下发消息 2.WMS返回T or F图3-1WLB主动模式主动模式由WLB下发消息，WMS在收到消息后，解析消息操作类型和业务参数，指导生产和实操。此处WMS返回的“T”，通常只表示通讯正常和消息必选参数正常。主动模式有： 出入库订单下发（除盘点单外） 用户订购仓储服务消息 取消订单消息l 被动模式WMSWLB 1.WMS回传WLB消息 2.WLB返回T or F 图3-2WLB被动模式依据约定，WMS需要将订单实操状态回传WLB，或者WMS需要获取WLB商品信息等等，需要WMS主动调用WLB提供的gateway方法来完成。WLB 会校验WMS回传的必选参数，并做出响应。此处的“T”通常也只表示通讯正常和必选参数正常。被动模式有： WMS回传库内实操订单状态 WMS确认出入库消息 WMS上传盘点出入库单 WMS上传对账单 WMS查询商品信息 WMS回传费用信息无论是主动或者被动模式，都是调用WLB的gateway中的方法，来完成通讯。区别仅是主动模式由WLB主动下发消息，而被动模式则是WMS主动回传消息给WLB。3.2. 接口概述3.2.1 基本约定（重要！）1) 通讯约定：使用HTTP POST方式进行通讯，参数不做encode(URL转码)。2) 参数大小写约定：没有强制要求的地方，统一使用小写。3) 编码约定：如GBK或UTF-8等，TP指定（input_charset），默认入驻时提交的设置。4) 参数约定：支持JSON或XML，TP指定，默认入驻时提交的设置。5) 签名约定：对通讯的业务参数（content，下文会提到）进行校验，签名生成公式：base64(MD5(content+keyValue)，keyValue由TP在发布WMS服务时指定。6) 消息数量约定：默认一个消息一个WLB订单，订单生成和下发并行，生成多少下发多少。当涉及批量处理时，默认最多处理50个。如查询多个商品item（50），一个消息一次查询50个。7) 消息去重约定：在主动模式下，WLB通过下发字段中的notify_id（下文会提到）去重，WMS若收到重复的notify_id，可以认为该消息是重复下发。（TP对于WLB重复下发的消息，若已处理，则直接回传“T”）同样，被动模式下WMS通过回传唯一的out_biz_code(下文会提到)去重。8) 时间约定：时间格式使用 YYYY-MM-DD HH:mm:ss 的格式，精确到秒。9) Content-Type约定：普通接口：application/x-www-form-urlencoded，上传文件接口：multipart/form-data（application/x-www-form-urlencoded： 窗体数据被编码为名称/值对。multipart/form-data： 窗体数据被编码为一条消息，页上的每个控件对应消息中的一个部分。 text/plain： 窗体数据以纯文本形式进行编码，其中不含任何控件或格式字符。）10) 字段类型约定：需要严格依据字段表格中给出的参数格式和大小进行开发，避免类型不匹配或参数大小预留不够导致溢出。11) 字段解析约定：参数字段中的必选字段是每次调用接口时都要求必须传入的。而可选字段会根据业务场景需求有差别（在某些特殊业务场景下，可选也有可能是必选）。所以仓库需根据实际业务场景，支持解析可选字段。在开发时，不应该认为可选字段，就不预留或不处理。3.2.2 主动模式基本字段WLB下发消息给WMS，其基本字段定义如下表所示：接口类名消息请求格式名称类型可选/必选备注PartnerString(32)必选合作伙伴在淘宝用户的唯一标识，由淘宝指定。（向淘宝索取）如:2088002464631181notify_timeDate必选消息通知时间YYYY-MM-DD hh:mm:ssnotify_typeString(32)必选通知类型，接口方法名如:wlb_order_notifynotify_idString(32)必选通知ID，每个消息唯一，用于去重。input_charsetString(16)必选编码格式GBK UTF-8 默认GBKSignString(64)必选签名ContentString必选消息内容或者消息参数，接口的消息参数，格式为 表3-1主动模式基本字段3.2.3 被动模式基本字段WMS调用gateway中的接口反馈或者向WLB查询消息。接口类名消息请求格式名称类型可选/必选备注serviceString(64)必选服务名称，接口名称，如wlb_order_notifypartnerString(32)必选合作伙伴在淘宝用户的唯一标识，由淘宝指定（向淘宝索取）如:2088002464631181input_charsetString(16)必选编码格式GBK UTF-8 默认GBKout_biz_codeString(64)可选WMS传入的消息ID，每个消息唯一，用于消息去重signString(64)必选签名contentString必选消息内容或者消息参数，接口的消息参数，格式为 content_typeString可选请求参数数据格式值类型：XML/JSON表3-2被动模式基本字段3.2.3 被动模式消息响应字段WLB在收到WMS的消息后，会立即返回响应，其字段定义如下所示：接口类名消息响应格式名称类型可选/必选备注is_successString必选T 成功 F 失败业务参数responseString可选文档中下发接口定义的响应格式，格式为 errorString可选错误信息，如果is_success是T，则不需要填写该参数，如果is_success是F,则必须填写该参数，便于查找问题原因表3-3被动模式响应字段3.2.4 主动模式消息响应字段同样WMS在收到WLB消息后，同样需要立即返回响应，其字段定义如下：基本参数名称类型可选/必选备注is_successString必选是否成功 T 成功 F 失败业务参数名称类型可选/必选备注errorString可选错误信息，如果is_success是T，则不需要填写该参数，如果is_success是F,则必须填写该参数，便于查找问题原因表3-4主动模式响应字段3.3.接口详述3.3.1 用户订购仓储服务通知（主动模式，sub_params_notify）WLB在收到货主订购仓储服务后，会立即调用此接口，下发货主信息给WMS。其字段定义如下表所示：接口名称用户订购仓储服务状态信息功能描述订单信息同步接口服务名称sub_params_notify名称类型可选/必选备注partnerString(32)必选合作伙伴ID，由淘宝指定，（向淘宝索取）sign typeString(16)必选签名方式 DAS MD5signString(64)必选签名内容notify_idString(32)必选消息通知ID，用于去重notify_typeString(11)必选消息通知类型，此处固定是sub_params_notifynotify_timeDate必选消息通知时间YYYY-MM-DD hh:mm:sscontentString必选请求内容01000111ANNTO-0001刘刘商家测试113569875203ADDSTO,EMS,HAIBAO备注业务参数 content具体内容名称类型可选/必选备注user_idLong(20)必选货主idservice_codeString(64)必选服务编码，淘宝指定subscriber_nameString(32)必选订购用户名字添加新字段，卖家注册时填写的真实姓名subscriber_nickString(32)必选订购用户昵称subscriber_mobileString(32)可选订购用户手机subscriber_phoneString(32)可选订购用户电话subscriber_contact_emailString(64)可选订购用户邮箱subscriber_addressString(128)可选订购用户地址action_typeString(16)必选操作类型： ADD-新增MODIFY-修改CANCEL-取消contentString必选仓储参数内容：默认物流公司，第二默认物流，包装材料格式如下：STO,EMS,HAIBAO如果其中为空，格式保持不变remarkString(4000)可选备注信息表3-5 货主订购仓储服务字段WMS返回：WMS在收到货主订购仓储服务信息后，必须立刻依照表3-4格式返回“T”or“F”。此处返回“T”表示：1.接受用户订购仓储服务2.通讯正常 3.约定必选参数解析正常。l XML样例WLB下发：仓储用户id服务编码，淘宝指定订购用户名字 卖家注册时填写的真实姓名订购用户昵称订购用户手机订购用户电话订购用户邮箱订购用户地址操作类型： ADD-新增,MODIFY-修改,CANCEL-取消仓储参数内容：默认物流公司，第二默认物流，包装材料格式如下：STO,EMS,HAIBAO如果其中为空，格式保持不变备注信息WMS返回：成功：T失败：F失败原因3.3.2 WLB出入库订单下发（主动模式，wlb_order_notify）WLB生成订单并主动下发订单给对应的WMS。其字段定义如下表所示：接口类名订单信息通知接口功能描述订单信息通知接口(销售出库单 销售入库单 调拨出库单 调拨入库单 采购入库单)服务名称wlb_order_notify基础参数名称类型可选/必选备注partnerString(32)必选合作伙伴ID，由淘宝指定。（向淘宝索取）sign_typeString(16)必选签名方式 DAS MD5signString(64)必选签名内容notify_idString(32)必选消息通知ID，用于去重notify_typeString(11)必选消息通知类型，此处固定为： wlb_order_notifynotify_timeString必选消息通知时间 YYYY-MM-DD hh:mm:sscontentString必选内容，见业务参数定义业务参数项目名称类型可选/必选备注订单基本信息store_codeString(64)必选仓储编码，淘宝指定。order_codeString(64)必选WLB订单编码order_typeInteger(11)必选操作子类型201 交易出库单301 调拨出库单302 调拨入库单501退货入库单502 换货出库单601 采购入库单901 普通出库单 (如货主拉走一部分货)order_sourceInteger(11)必选201 淘宝 301 其他订单来源，WMS可以选择使用order_create_timeString必选订单创建时间 order_flagString可选订单标记以逗号分隔：1: cod 货到付款2: limit-限时配送3: presell-预售4:invoiceinfo-需要发票8:退换货9:上门服务10: 是否可改配送方式 默认可更改，即没1012: 是否卖家承担运费 默认是，即没12 13: 退货时是否收取发票 默认不收取,即没13为多选项，如1,2,8,9虽然是可选字段，但仓库必须能够处理此字段。（重要！）对于订单类型的特殊业务要求，如货到付款，限时配送，要求带发票等等。alipay_noString 可选支付宝交易号COD订单必选total_amountLong可选总金额订单总额，非必要字段修改备注信息payable_amountLong可选对COD必选，应收总金额COD订单必选service_feeLong可选COD服务费COD订单必选订单商品很多时有用（商品item50），来判断是否还有更多的订单商品order_item_countint(11)可选本消息的order_item数量当distribute_type为1时为必选订单多次下发必选如订单中订单商品明细数为500本次下发50，order_item_count值为50total_order_item_count为500 ，即WMS需要接收到500个时，再开始处理订单，而不是接收到50处理50total_order_item_countint(11)可选总共ITEM数量当distribute_type为1时为必选订单多次下发必选说明同上distribute_typeint(11)必选是否有更多商品 0 一次发送 1 多次发送标识订单多次下发实际配送信息tms_service_codeString(64)可选物流公司编码销退单会使用买家发货到仓库物流上门取货的情形则不用tms_order_codeString(64)可选运单号,退货单有可能有运单号同上prev_order_codeString(64)可选原物流宝订单编码，在退换货时会用到退货入库单 时可能会有销退单必选调拨出库单必选，对于调拨出库单，这个值是调拨入库单的编码，需要作强校验收货方信息receiver_infoString(512)可选收货方 发货方信息必选其一 手机和电话必选其一收货方信息邮编省市区具体地址收件方名称手机电话交易出库单必选换货出库单必选调拨出库单必选调拨入库单必选采购单入库单可选销退单可选全部字段都为空值则该字段为空某个字段为空用NA来代替如310012浙江省杭州市西湖区塘苗路18号淘A发货方信息sender_infoString(512)可选发货方 收货方信息必选其一 手机和电话必选其一邮编省市区具体地址发件方名称手机电话调拨出库单必选调拨入库单必选全部字段都为空值则该字段为空某个字段为空用NA来代替如310012浙江省杭州市西湖区塘苗路18号淘A配送要求（order_flag字段中有时效要求时，有效）schedule_typeInteger(11)可选投递时延要求: 1-工作日 2-节假日 101,当日达102次晨达103次日达 如果订单打上了限时配送标记（order_flag为2），该字段才会有效如果没有限时配送标记则为非限时配送各个值是互拆的关系，虽然字面意义上有交集schedule_startString可选送达开始时间 COD订单一定会有同上 格式为 hh:mm:ssschedule_endString可选送达结束时间 COD订单一定会有同上 hh:mm:ss订单商品信息order_item_listList必选订单商品信息,wlb_order_item见下表3-7订单商品明细信息，这里有可能会存在一个订单里包含两个相同的item_id,在解析些数据时请注意package_countInteger(11)包裹数量入库单可能会关心这个字段expect_start_timeString可选预期送达开始时间 入库单常用YYYY-MM-DD hh:mm:ss入库单关心该字段expect_end_timeString可选预期送达结束时间 入库单常用YYYY-MM-DD hh:mm:ss入库单关心该字段EXPECT_TIMEstirng可选预计开始入库时间入库单关键字段（行舟）invoice_info_listinvoice_info-invoice_info_listList可选发票信息，见下表3-8一个物流宝订单可能会带多张发票信息下来tms_infoString(512)可选运办公司相关信息出库单中可能会用到运输公司名称运输公司联系人运输公司运单号运输公司电话运输公司联系人身份证号申通物流张三 EG12312313945234321330621589478541244特殊字段，在调拨出库时可能会用到，如涉及到大宗货物出库时，仓储公司可能会要求运输公司的人带上身份证等上门取货，以降低操作风险全部字段都为空值则该字段为空某个字段为空用NA来代替distributor_user_nickString可选带下来的信息，一般不用关心分销附带信息订单其他属性attributes(2000)String可选扩展字段备注remark(4000)String(4000)可选备注表3-6 订单信息下发字段注意：order_flag可选字段指定订单的特殊需求。如order_flag中有“2”时，表示订单有时效要求。WMS在指定快递时，需注意选择可以满足时效要求的快递。同时时效要求记录在schedule_type，schedule_start，schedule_end三个字段中。order_flag中有“10”时，表示商家指定了快递公司。指定的快递公司编码在tms_service_code中。如果商家指定的快递公司与仓实际指定的有差异，仓储可以与商家协调一致。最后使用的快递以仓储指定的为准。order_flag中有“4”时，表示订单需要货票同行服务，需要WMS解析发票信息字段(invoice_info_list)。order_flag中有“8”时，表示该订单是退换货订单，需要WMS关注“实际配送信息”的相关字段。order_flag中有“12”时，表示该订单包邮订单。有“9”表示该订单需要上门退换货。有“13”时表示需要同时退回发票。这些主要与TMS有关。l 下发订单商品信息字段表3-6中商品信息字段如下表所示：不同于商品的item-id,需要TP记录，在出库确认时会用到。订单商品对象 wlb_order_item名称类型可选/必选备注order_item_idLong(20)必选订单IDorder_source_codeString(64)可选交易编码sub_source_codeString(64)可选子交易编码user_idLong(20)必选卖家ID 一般情况下，货主ID和卖家ID相同owner_user_id货主Long(20)必选货主ID 代销情况下货主ID和卖家ID不同item_idLong(20)必选商品IDitem_nameString(64)必选商品名称item_codeString(64)必选商家编码（商品统一条码，如UCC，EAN）inventory_typeInt(11)必选库存类型1可销售库存101残次102机损103箱损201冻结库存301在途库存item_quantityLong(11)必选商品数量item_priceLong(20)可选销售价格item _versionitem_public_versionitem_versionInt(11)必选商品版本，WLB允许货主修改商品属性描述，每修改一次就对应一个商品版本信息batch_remarkString(64)可选批次备注（商超需关注）attributesString(2000)可选属性数据 KEY VALUE格式，允许货主新增或修改商品属性（KEY），如颜色，尺寸等等表3-7 订单商品信息字段l 下发订单发票字段（invoice_info_list）表3-6中发票字段如下表所示：名称类型可选/必选备注typeString(64)必选发票类型 1 增值税普通发票 2 普通发票titleString(64)必选发票抬头amountString(64)必选发票金额contentString(512)可选发票内容表3-8 订单发票信息字段上表中的发票内容（content），为扩展字段，具体商品信息会随该字段下发。其格式为：商品名称商品型号商品数量商品计量单位单价!商品名称商品型号商品数量商品计量单位单价WMS返回：WMS在收到订单信息后，必须立刻依照表3-4格式返回“T”or“F”。此处返回“T”仅表示：1.通讯正常 2.约定必选参数解析正常。并不代表WMS正式接单。若返回“F”需要附加错误描述信息。l XML样例WLB下发： 仓储编码，淘宝指定 WLB订单编码 操作子类型: 201 交易出库单,301 调拨出库单,302 调拨入库单,501退货入库单,502 换货出库单,601 采购入库单,901 普通出库单 (如货主拉走一部分货) 201 淘宝 301 其他 -订单来源，WMS可以选择使用 订单创建时间订单标记以逗号分隔：1: cod 货到付款2: limit-限时配送3: presell-预售4:invoiceinfo-需要发票8:退换货9:上门服务10: 是否可改配送方式 默认可更改，即没1012: 是否卖家承担运费 默认是，即没12 13: 退货时是否收取发票 默认不收取,即没13为多选项，如1,2,8,9支付宝交易号 COD订单必选 19560对COD必选，应收总金额COD服务费 订单多次下发必选如订单中订单商品明细数为500本次下发50，order_item_count值为50total_order_item_count为500 ，即WMS需要接收到500个时，再开始处理订单，而不是接收到50处理50 订单多次下发必选说明同上 是否有更多商品: 0 一次发送 1 多次发送 收货方 发货方信息必选其一 手机和电话必选其一收货方信息邮编省市区具体地址收件方名称手机电话交易出库单必选换货出库单必选调拨出库单必选调拨入库单必选采购单入库单可选销退单可选全部字段都为空值则该字段为空某个字段为空用NA来代替如310012浙江省杭州市西湖区塘苗路18号淘A 发货方 收货方信息必选其一 手机和电话必选其一邮编省市区具体地址发件方名称手机电话调拨出库单必选调拨入库单必选全部字段都为空值则该字段为空某个字段为空用NA来代替如310012浙江省杭州市西湖区塘苗路18号淘A 发票类型 : 1普通发票 ,2增值税发票发票抬头发票金额商品名称商品型号商品数量商品计量单位单价!商品名称商品型号商品数量商品计量单位单价22223333 订单商品ID交易编码子交易编码 卖家ID 一般情况下，货主ID和卖家ID相同 货主ID 代销情况下货主ID和卖家ID不同 商品ID 可能会存在一个订单里包含两个相同的item_id 商品名称 商家编码（商品统一条码，如UCC，EAN） 库存类型:1 可销售库存101 残次102 机损103 箱损201 冻结库存301 在途库存 商品数量 销售价格 商品版本，WLB允许货主修改商品属性描述，每修改一次就对应一个商品版本信息 批次备注属性数据 KEY VALUE格式，允许货主新增或修改商品属性（KEY），如颜色，尺寸等等:例如 分号 key:value;key:value;key:value;key:value; 105177768交易编码子交易编码 628491299 628491299 100068102 奔腾电饭煲PFFN3009T TB_00018 1 2 32600 5批次备注 105177769交易编码子交易编码 628