天猫商城WMS接入规范白皮书
天猫商城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-24 0.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提供申请表 横向PD 4. 提交申请表 横向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必选消息内容或者消息参数，接口的消息参数，格式为
其字段定义如下表所示：接口名称用户订购仓储服务状态信息功能描述订单信息同步接口服务名称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必选请求内容
此处返回“T”表示：1.接受用户订购仓储服务2.通讯正常 3.约定必选参数解析正常l XML样例WLB下发：
其字段定义如下表所示：接口类名订单信息通知接口功能描述订单信息通知接口(销售出库单 销售入库单 调拨出库单 调拨入库单 采购入库单)服务名称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订单必选订单商品很多时有用（商品item>50），来判断是否还有更多的订单商品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号^^^淘宝^^^13688993333^^^NA发货方信息sender_infoString(512)可选发货方 收货方信息必选其一 手机和电话必选其一邮编^^^省^^^市^^^区^^^具体地址^^^发件方名称^^^手机^^^电话调拨出库单必选调拨入库单必选全部字段都为空值则该字段为空某个字段为空用NA来代替如310012^^^浙江省^^^杭州市^^^西湖区^^^塘苗路18号^^^淘宝^^^13688993333^^^NA配送要求（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 >必选订单商品信息,wlb_order_item见下表3-7
如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_versionàitem_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），为扩展字段，具体商品信息会随该字段下发。
其格式为：
WLB将依据回传消息在TC前台显示l 状态约定ü WMS_ACCEPT出库入库，共有状态WMS确认订单可以处理，并正式接单需要特别强调：1. WMS未回传接单，若产生撤单（订单取消），WLB不会调用取消订单接口（下文会提到）通知WMS因为WLB认为此时WMS未接单，订单将被直接取消而不会有通知2. 若WMS已回传接单，若产生撤单，WLB会询问WMS是否允许撤单若WMS拒绝撤单，订单将无法取消3. 回传状态的起点必须是WMS_ACCECPT或WMS_REJECT4. 目前接单后不允许回传拒单ü WMS_REJECT出库入库，共有状态WMS确认订单无法处理，返回拒单ü WMS_PRINT出库实操WMS打印拣货单ü WMS_PICK出库实操，WMS开始拣货ü WMS_CHECK出库实操，WMS复核订单商品ü WMS_PACKAGE出库实操，WMS打包订单商品ü WMS_FAILED出库实操，订单发货失败（买家拒签） l 订单状态回传字段如下表所示：接口类名订单信息同步接口功能描述订单信息同步接口 本接口和TMS共用服务名称wlb_order_info_sync基本参数名称类型可选/必选备注serviceString(64)必选服务名称 ，此处固定为：wlb_order_info_syncpartnerString(32)必选合作伙伴在淘宝注册的用户ID，由淘宝指定（向淘宝索取）sign_typeString(16)必选签名类型 MD5 DSAsignString(64)必选签名内容contentString必选详细见 业务参数业务参数 content名称类型可选/必选备注out_biz_codeString(64)必选消息ID，用来去重。
service_codeString(64)必选仓库编码，淘宝指定order_codeString(64)必选WLB订单编码tms_order_cod。
