淘宝商城ERP对接技术规范规范白皮书.docx

淘宝商城ERP对接技术规范白皮书淘宝商城ERP对接技术规范规范白皮书Revision HistoryDateVersionDescriptionAuthor20整体框架，系统逻辑，接口逻辑，测试用例，沙箱使用蒋启帅2011-12-50.5.1增加沙箱绑定时候的登陆截图3-11蒋启帅目录第一章 前言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技术人员 技术支持技术流程具体的时效以及接入流程请参照：TP接入具体流程.xlsx，本文仅涉及技术流程第三章 系统与接口1.系统逻辑此处为实物流，非信息流图3-1 物流宝自动发货系统逻辑如上图所示，以物流宝自动发货的淘宝交易逻辑为例：1) 买家拍下商品并付款后，TC中心生成交易订单并向外广播。2) 物流宝和LC后台收到广播后，记录交易信息。3) 物流宝判断卖家是否是物流宝用户（是否入驻过物流宝），商品是否是物流宝商品（商品是否在物流宝仓，并创建映射，后文会提到），是否设置流转规则（ERP调用WLB2.0接口设置，后文会提到）。4) 确认订单满足3）中的判断条件，并且确定库存充足后，WLB生成WLB订单并自动下发给WMS。5) WMS返回仓内操作节点信息给WLB，商品出库后，TMS返回接单派送等节点信息给WLB，直到买家签收。6) WLB在收到WMS和TMS反馈后，主动推送订单状态给LC后台。7) LC后台推送订单状态给TC中心。买家在TC中心中可以看到当前订单状态。在此逻辑下，需要注意的是：l 首先，WLB任何时候都不会主动通知ERP，订单当前的状态。需要ERP调用WLB接口来获取。l 上图除WMS到TMS为实物流外，其他都是信息流。WLB相当于“信息调度中心”，在物流宝系统中，所有信息都是通过WLB来中转。l 一旦设置流转规则，并且符合WLB自动发货规则，WLB系统将自动完成下单发货等操作。l 在此处理逻辑中，ERP事先完成了添加物流宝商品，入库，创建映射关系，添加流转规则等操作，后文会具体提到这些操作。另一种更为常见的ERP控制物流宝发货的淘宝交易逻辑，如下图所示：图3-2 ERP控制物流宝发货系统逻辑ERP控制WLB发货的逻辑（ERP未设置流转规则）：1) 买家拍下商品并付款后，TC中心生成交易订单并向外广播。2) 物流宝和LC后台收到广播后，记录交易信息。在这里由于WLB中未设置流转规则，订单将不会自动流转到WMS。 3) 商家ERP系统通过调用TOP平台的交易接口，主动抓取交易订单信息。（具体接口可以参照中的交易API）4) 商家ERP系统判断订单是否需要由WLB发货（判断标准，ERP自己可以设置），并调用WLB创建订单接口(后文会提到)，创建并下发订单给WLB。5) WLB收到订单后的操作逻辑与前文的自动发货逻辑一致。这里不累述了。2. 接口用例注意：1) 参数列表中，标注为必须的就是一定要传的参数。可选的根据具体应用场景决定是否传。如果接口所有参数都是可选，则通常为多条件的查询接口，不可以不传任何参数。2) 参数类型要保持一致，如“string”类型就一定要传入字符串。3) 具体接口请点击 按照常见的接口调用顺序，分别介绍以下接口（接口名称都做了超链接，可以直接按住ctrl+鼠标右键跳转到接口具体介绍页面）：(一) 创建物流宝商品（必测）taobao.wlb.item.addl 在对接物流宝时，第一步就是调用该接口，返回一个item_id，该ID是商品在物流宝仓里的唯一ID。l 参数列表中的item_code，指商品编码，通常为EAN13，UPC，CODE 39等商品条形码。若没有，则传入商家可以管理的编码。(二) 查询商家订购服务（必测）taobao.wlb.subscription.query根据状态查询商家订购的服务，通常用该接口查询商家订购的仓库编码，宅配编码等等。(三) 创建物流宝订单（必测）taobao.wlb.order.createl 所有出库，入库操作都通过该接口实现。l 其中store_code参数可以通过（二）中查询商家订购服务获取。l 接口调用成功后返回WLB订单号，该订单号是WLB系统唯一标识。l receiver_info和sender_info分别是收发货地址，传入参数必需严格按照国家邮政地址标准填写。（即省市区规范，如果传入错误地址，如区信息不存在，则创建订单会报错。）虽然这两个参数都是可选参数，但不允许同时为空，建议都要传入。l order_type和order_sub_type组合成所有支持的订单类型。当前支持的订单类型有：a) 淘宝交易出库单 需要特别注意，尤其是采用ERP控制物流宝发货逻辑的商家： order_item_list参数列表中的trade_code必须要传入正确的淘宝交易号。 order_item_list参数列表中的flag必须是0（即非赠品，否则在TC中心看不到发货信息）。 order_flag必须要传入CONSIGN（指定由WLB发货，如果不指定则需要商家再调用taobao.wlb.order.consign来通知TC物流宝商品已发货。）。只有满足上述三个条件，淘宝交易商品才能正常从WLB发货，并且买家可以在TC中心中看到商品发货信息。如果传入错误交易号或者未指定WLB发货则商家交易状态不会变成已发货（非常重要！）。b) 其他交易出库单 指非淘宝交易的交易出库单。如商家导入在其他电商平台交易的出库单由WLB仓发货。c) 调拨出库单指货主在WLB仓间调拨商品。调拨出库和入库单是分别生成的。建议商家通过out_biz_code参数来建立调拨出库单和调拨入库单的对应关系。如出库时out_biz_code传入“O*”盘点入时传入“I*”来达到一一对应。d) 调拨入库单 货主在WLB仓间调拨商品入库。e) 其他退货入库单 非淘宝交易的退货入库。需传入原运单。f) 换货出库单非淘宝交易的换货出库。需传入原运单。g) 淘宝换货出库单淘宝交易的换货出库。需传入原运单，原订单。h) 淘宝退货出库单 暂保留i) 淘宝退货入库单 淘宝交易的换货出库。需传入原运单，原订单。j) 采购入库单货主采购入库。k) 普通出库单 (如货主拉走一部分货) 货主拉走部分货l) 盘点出库单WMS盘盈时出库。m) 盘点入库单WMS盘亏时入库(四) 创建WLB商品与IC前台商品映射（必测）taobao.wlb.item.synchronize只有WLB仓内商品与淘宝IC前台商品建立映射关系后，商品销售出库，前台商品数量才会自动扣减。(五) 取消物流宝订单（必测）taobao.wlb.order.cancel商品一旦从WLB仓出库后，则不允许取消订单。该接口会返回失败。(六) 修改IC前台库存（必测）taobao.wlb.inventory.sync指定同步到IC前台的商品数量(七) 修改WLB商品属性（必测）taobao.wlb.item.update由WLB商品ID，修改商品属性。(八) 删除WLB商品（必测）taobao.wlb.item.delete仅在WLB商品在仓内库存为0时，才允许删除WLB商品，否则删除会报错。(九) 删除WLB商品与IC前台映射关系（必测）taobao.wlb.item.synchronize.delete(十) 查询WLB订单流转信息（必测）taobao.wlb.orderstatus.get根据WLB订单查看当前订单流转状态。包括仓和快递的信息。因为WLB不会主动通知ERP当前流转状态，所以需要ERP主动调用接口查询。(十一) 根据WLB订单分页查询订单商品信息（必测）taobao.wlb.orderitem.page.get(十二) 根据WLB订单查询订单所有信息（必测）taobao.wlb.wlborder.get(十三) 多条件分页查询WLB订单所有信息（必测）taobao.wlb.order.page.get可以根据WLB订单，操作类型，时间，订单状态多条件查询WLB订单的所有信息。所有参数都是可选，但至少要有一个查询条件。(十四) 根据交易号查询WLB订单所有信息（必测）taobao.wlb.tradeorder.get根据创建WLB订单时传入的交易号查询WLB订单的所有信息。(十五) 根据运单号查询订单物流信息（必测）taobao.wlb.tmsorder.query(十六) 根据WLB商品ID获取商品信息（必测）taobao.wlb.item.get(十七) 多条件分页查询WLB商品信息（必测）taobao.wlb.item.query可以根据商品名称，标题，商品编码等多条件查询WLB商品详细信息。所有参数都是可选，但至少要有一个查询条件。(十八) 根据WLB商品ID查询商品映射关系（必测）taobao.wlb.item.map.get(十九) 根据IC前台ID查询映射的WLB商品（必测）taobao.wlb.item.map.get.by.extentity(二十) 根据WLB商品ID查询库存信息（必测）taobao.wlb.inventory.detail.get 可以查询冻结，可销库存等，也可以查询不同仓内库存。(二十一) 多条件分页查询WLB商品库存信息记录（必测）taobao.wlb.inventorylog.query可以根据商品ID，时间，仓储，订单等多条件查询库存信息，同样至少需要指定一个查询条件。(二十二) 获取WLB通知消息（必测）taobao.wlb.notify.message.page.get这里的通知消息都与仓库有关，如入库不一致，盘点，拒签等信息时，WLB才会发送消息给ERP确认。其他状态不需要ERP确认。联调测试必须要测试的接口，就是上文这22个，只有这些接口都测试通过（接口返回true或者修改时间），才能认定为联调通过。另外还有非强制要求测试的接口如：商品授权，代销关系，组合商品等就不一一介绍了，可以查看具体接口请点击，这里再介绍下添加WLB商品流转规则和通知LC后台WLB已发货接口(二十三) 添加WLB商品流转规则（非必测）taobao.wlb.order.schedule.rule.add可以根据地区，仓库或者配送特殊需求等，指定满足这些条件时，由WLB发货。设置该流转规则后ERP不需要再调用创建WLB订单接口，商品将自动由WLB发货，不经ERP，如图3-1的逻辑所示。(二十四) 通知LC后台WLB已发货（非必测）taobao.wlb.order.consign调用该接口的情景： ERP获取淘宝交易单，创建WLB订单，并成功下发给WLB。 ERP创建订单时传入了正确淘宝交易单号，并且指定商品非赠品。 ERP创建订单时order_flag没有传入CONSIGN。 ERP获取到商品已成功发货，但商家无法点击发货。此时需要调用此接口来通知LC后台，商品已由WLB发货。以上条件任一不满足则不需要或者无法调用该接口通知LC后台商品已发货。3. 沙箱自测1) 获取联调账号在ERP开发完接口后，负责接入技术支持将提供联调账号。使用该账号登陆：/wlbfbi/partner_info.htm 如图所示：图3-3 获取联调账号和沙箱卖家账号2) 登陆mini淘宝使用1)中获取的普通卖家账号（非联调平台账号，建议使用与1)中登陆联调平台不同的浏览器）登陆mini淘宝： 。图3-4 登陆mini淘宝该账号是沙箱虚拟的普通卖家账号。可以在账号里进行商品管理。图3-5 出售的商品信息其中的宝贝ID即IC前台商品ID，在创建WLB商品映射时会使用到。也可以使用沙箱助手新增商品。图3-6 沙箱助手下载3) 绑定沙箱账号使用真实的淘宝开发者账号登陆TOP平台： 开发者中心(同样建议使用与1)中登陆联调平台不同的浏览器)：图3-4 登陆开发者中心创建应用：图3-7 创建应用配置沙箱：图3-8 配置沙箱环境获取沙箱Appkey和AppSercet并输入回调地址：图3-9 输入回调地址点击测试：图3-10 窗口拦截如果出现上图所示窗口拦截，请点击“总是允许弹出”。绑定虚拟卖家账号：使用1）中获取的虚拟卖家账号绑定。图3-11 使用虚拟卖家账号登陆（非联调平台账号）图3-