商家接入白皮书-物流宝API

商家接入方案版本号1.0修订历史序号版本号修订内容作者1v1.0新增云士1引言1.1目的文档介绍了商家在使用菜鸟提供的仓配协同物流体系时，如何通过API接入的方式实现ERP与菜鸟仓的系统对接。1.2约定若对接业务方案上有所变更，此文档将同步更新，并将及时通知到各应用接入方接口人。1.3术语缩写、术语解释ISVISV（独立软件供应商/IndependentSoftwareVendor）APPISV开发的应用程序，应用需要先在TOP中注册，并申请API访问。appKeyISV或者ERP在TOP中注册APP时TOP分配的APP唯一编号。appSecretISV或者ERP在TOP中注册APP时TOP分配的访问API服务的密钥。TOP淘宝开放平台PACPartnerAccessCenter，即菜鸟合作伙伴“统一对接”中心。ERP商家的管理系统CP菜鸟合作伙伴（物流服务提供方），如仓、配、快递等服务商品特指物流相关的服务商品。如菜鸟发布的仓配一体的物流服务商品。TMSTransportationManagementSystem物流管理系统WMSWarehouseManagementSystem仓库管理系统TCTransactionCenter，交易中心，本文专指淘宝交易中心。LCLogisticsCenter，物流中心，本文专指淘宝物流中心。WLB物流宝2接入方案2.1业务描述本方案适用的业务范围2.2物流资源物流商提供的物流资源包括仓储与配送。2.3商家接入步骤因商家使用菜鸟提供的物流宝系统与物流商进行对接，所以商家需要接入菜鸟的物流宝系统。具体对接的步骤入下图所示：批注[霁清1]:接入商家ERP，以便采用ERP统一发货，而不用单独到卖家中心操作，提高发货效率，降低商家的操作成本。2.4系统的上下文2.5具体接入场景2.5.1整体场景图示概述2.5.2数据初始化配置货主编码商家要在ERP里面配置货主的编码，在菜鸟对接API需要货主参数时填写此编码；（举例：商家使用其中一个店铺账号user001订购了物流服务产品，此账号作为后续与菜鸟对接的货主账号，商家后续在API传入货主参数时，填写此账号user001作为识别货主的标示；）创建物流宝商品taobao.wlb.item.add添加单个物流宝商品在对接物流宝时，第一步就是调用该接口，返回一个item_id，该ID是商品在物流宝里的唯一ID。参数列表中的item_code，指商品编码，通常为EAN13，UPC，CODE39等商品条形码。若没有，则传入商家可以管理的编码。修改物流宝商品属性taobao.wlb.item.update删除物流宝商品taobao.wlb.item.delete查询物流宝商品信息taobao.wlb.item.get根据WLB商品ID获取商品信息taobao.wlb.item.query可以根据商品名称，标题，商品编码等多条件查询WLB商品详细信息。所有参数都是可选，但至少要有一个查询条件。建立商品组合关系组合商品创建分为两步1）通过商品添加接口，创建组合商品，子品（参考上述章节创建物流宝商品）2）创建商品组合关系taobao.wlb.item.combination.create创建商品组合关系taobao.wlb.item.combination.delete删除商品组合关系获取仓储编码批注[霁清2]:组合商品是指：淘系前台销售的宝贝与后台SKU存在1对多或多对1的组合关系。例如：1、前台A对应后台2B+2C2、前台A对应6B，前C对应12Ctaobao.wlb.subscription.query查询商家定购的所有服务根据状态查询商家订购的服务，通常用该接口查询商家订购的仓库编码，宅配编码等等。商家需要在ERP中配置仓储的资料，包括仓储的编码，常用联系人地址等信息。商家订购服务产品之后，小二会给商家划仓，这样就建立了商家与服务仓库的关系，其中涉及到仓库的编码，地址，联系方式等相关信息，由菜鸟提供给商家，商家也可通过接口获取仓储具体的信息。（参数WlbSellerSubscription.service_code代表仓储的编码）服务类型，STORE1-仓储、TMS2-TMS、PACKAGE3-包装服务SUPPLIER4-供货INSTALL5-安装COMPLEX_SERVICE100-综合服务获取配送公司编码商家订购服务产品之后，小二会给商家分配配送资源，包括可使用的快递或者落地配公司，这样就建立了商家与配送公司的关系，其中涉及到配送公司的编码等相关信息，商家也可以通过接口获取配送公司具体的信息。涉及的接口列表（与仓储使用同一个查询接口）taobao.wlb.subscription.query查询商家定购的所有服务2.5.3订单流转规则介绍&设置目前菜鸟两有种发货订单流转的规则，可参考图示；订单自动流转规则介绍如上图所示，以物流宝自动发货的淘宝交易逻辑为例：1)买家拍下商品并付款后，TC中心生成交易订单并向外广播。2)物流宝和LC后台收到广播后，记录交易信息。3)物流宝判断卖家是否是物流宝用户（是否入驻过物流宝），商品是否是物流宝商品（商品是否在物流宝仓，并创建映射，后文会提到），是否设置流转规则（ERP调用WLB3.0接口设置，参考XXXX）。4)确认订单满足3）中的判断条件，并且确定库存充足后，WLB生成WLB订单并自动下发给WMS。5)WMS返回仓内操作节点信息给WLB，商品出库后，TMS返回接单派送等节点信息给WLB，直到买家签收。6)WLB在收到WMS和TMS反馈后，主动推送订单状态给LC后台。7)LC后台推送订单状态给TC中心。买家在TC中心中可以看到当前订单状态。在此逻辑下，需要注意的是：首先，WLB任何时候都不会主动通知ERP，订单当前的状态。需要ERP调用WLB接口来获取。上图除WMS到TMS为实物流外，其他都是信息流。WLB相当于“信息调度中心”，在物流宝系统中，所有信息都是通过WLB来中转。一旦设置流转规则，并且符合WLB自动发货规则，WLB系统将自动完成下单发货等操作。在此处理逻辑中，ERP事先完成了添加物流宝商品，入库，创建映射关系，添加流转规则等操作，后文会具体提批注[云士3]:后续填充接口链接到这些操作。ERP控制物流宝发货规则介绍另一种更为常见的ERP控制物流宝发货的淘宝交易逻辑（ERP未设置流转规则）：1)买家拍下商品并付款后，TC中心生成交易订单并向外广播。2)物流宝和LC后台收到广播后，记录交易信息。在这里由于WLB中未设置流转规则，订单将不会自动流转到WMS。3)商家ERP系统通过调用TOP平台的交易接口，主动抓取交易订单信息。（具体接口可以参照open.taobao.com中的交易API）4)商家ERP系统判断订单是否需要由WLB发货（判断标准，ERP自己可以设置），并调用WLB创建订单接口(后文会提到)，创建并下发订单给WLB。5)WLB收到订单后的操作逻辑与前文的订单自动流转逻辑一致。这里不赘述了。订单自动流转设置设置订单自动流转，要分成两个步骤1.先创建WLB商品与IC前台商品映射taobao.wlb.item.synchronize商品映射同步，只有WLB仓内商品与淘宝IC前台商品建立映射关系后，商品销售出库，前台商品数量才会自动扣减。taobao.wlb.item.synchronize.delete删除商品映射同步taobao.wlb.item.map.get根据物流宝商品ID查询商品映射关系taobao.wlb.item.map.get.by.extentity根据外部实体查询映射的物流宝商品id2.可以选择通过页面或者接口设置订单流转的规则涉及到的接口列表taobao.wlb.order.schedule.rule.add可以根据地区，仓库或者配送特殊需求等，指定满足这些条件时，由WLB发货。设置该流转规则后ERP不需要再调用创建WLB订单接口，商品将自动由WLB发货，不经ERP，如图3-1的逻辑所示。taobao.wlb.order.schedule.rule.update修改订单调度规则taobao.wlb.orderschedulerule.delete删除订单调度规则taobao.wlb.orderschedulerule.query查询某个卖家的所有订单调度规则通过界面设置订单流转规则指导2.5.4仓储业务创建物流宝订单taobao.wlb.order.create所有出库，入库操作都通过该接口实现。其中store_code参数可以通过查询商家订购服务获取，参考2.5.2中关于仓储章节的介绍。接口调用成功后返回WLB订单号，该订单号是WLB系统唯一标识。receiver_info和sender_info分别是收发货地址，传入参数必需严格按照国家邮政地址标准填写。（即省市区规范，如果传入错误地址，如区信息不存在，则创建订单会报错。）虽然这两个参数都是可选参数，但不允许同时为空，建议都要传入。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盘亏时入库取消物流宝订单taobao.wlb.order.cancel商品一旦从WLB仓出库后，则不允许取消订单。该接口会返回失败。查询订单流转信息taobao.wlb.orderstatus.get根据WLB订单查看当前订单流转状态。包括仓和快递的信息。因为WLB不会主动通知ERP当前流转状态，所以需要ERP主动调用接口查询。查询订单商品信息taobao.wlb.orderitem.page.get根据物流宝订单，分页查询订单商品信息查询订单所有信息taobao.wlb.wlborder.get根据物流宝订单编号，查询物流宝订单概要信息taobao.wlb.order.page.get可以根据WLB订单，操作类型，时间，订单状态多条件查询WLB订单的所有信息。所有参数都是可选，但至少要有一个查询条件。taobao.wlb.tradeorder.get根据创建WLB订单时传入的交易号查询WLB订单的所有信息。用运单号查询订单物流信息taobao.wlb.tmsorder.query通过运单号分页查询物流信息查询库存信息taobao.wlb.inventory.detail.g