B2B电商开放平台API接口设计指南

笔者所负责的产品是一个医药电商平台，撮合采购商和供应商在平台上进行线上交易，其中采购商主要是药店、诊所、医院；供应商主要是各大医药公司经销商；本文主要先讲解电商与商家之间信息同步及API接口设计的规范及需要注意的问题。

B2B电商开放平台的设计需要从以下几面去思考：

1. 开放平台API接口的设计，主要是从功能需求的角度，设计满足业务需求的接口及对应的字段；
2. 平台与商家之间信息的对接，对接的方法有哪些？对接过程中需要可能会遇到什么问题；
3. 同步开关及权限的设计，处理信息自动同步和手动设置之间的矛盾。

一、开放平台API接口的设计

1. 商品

商品方面的同步，主要是考虑到：

1. 商品的上传；
2. 商品价格同步；
3. 商品批号同步；
4. 商品上下架同步。

1.1.1 商品的上传

商品上传同步的目的在于把商家需要出售的商品同步到平台，平台把商家上传的商品显示在前端页面，下单成功之后，商品明细信息跟着订单信息一起传给商家。

商品上传过程中需要处理的问题：

• 商品上传的信息需要包含“ERP商品ID”作为该商品的唯一标识；
• 很多平台都会存在基础商品，例如药品，食品，水果等；如果出售的标的是可以明确定义的，商家只是作为一个经销商存在的情况下，平台可以统一定义基础商品；
• 在存在基础商品的情况下，商家的上传的商品信息需要与平台的基础商品匹配生成出售的SKU。

匹配的方法可以分为两种：

1. 可以根据商品的条码，批准文号，规格，厂家等进行匹配，但是要求根据这些条件能完全确定这个商品和基础商品是同一个商品；
2. 对于一些商品来说，没有确定的规格供程序完成商品的匹配的时候，需要人工介入进行判断，然后在上传的时候直接附加上“基础商品ID”，通过“基础商品ID”直接进行关联。

正常情况下，商品上传之后不能马上上架并出售，而是先要同步库存之后通过调取批量上下架接口上架或手动点击上架。

如果商品上传之后如果需要直接可以上架出售，接口必须还包含商品销售信息如：价格和库存，所以商品上传的接口必须包含默认单价和库存，其中默认单价必填，库存可以为空并默认为0（同时可以设置规则：库存为0的商品不自动上架销售而库存不为0的商品自动上架销售）。

平台不存在基础商品的时候，不提倡商品直接上架，而是需要审核，因为可能商家上传的商品是平台不允许销售的。

1.1.2 修改商品价格

商家在平台出售的商品的价格并不是固定的，对于SKU比较多的商家而言，商品的价格往往是在ERP直接进行修改，然后同步到各个第三方平台，所以价格同步是不可或缺而且对于实时性，准确性的要求比较高。

另一方面，商品的销售价格往往由于成本的因素或市场的侧重点不同，往往需要针对不同的地区，客户类型设置不同的价格，而这些设置同样往往是在ERP中设定好的，同样需要同步到平台。

商品价格同步需要处理的问题：

1. 接口需要能满足商品需要同时修改多种类型的价格，包括默认单价，建议零售价，地区价/客户等级价的需求；
2. 对于地区价或客户等级价，需要在平台中定义好规范的地区组或客户组，同步价格的时候，接口中存在字段“地区组”或“客户组”的ID来与平台的商品价格进行匹配。

地区组的概念：由于行政区划的单位比较多，所以不可能为每一个行政区设置一个价格，通常由于不同商品对于地区价的定义都是一样的，如在A,B两个商品在广东，广西的定价一样而不同于其他地区，那么就可以将广东和广西设置为一个地区组；商品就可以针对每个地区定义价格了

1.1.3 商品批号同步

同一个商品可能由于生产批次不同会存在不同批号的货品，尤其是对于存在有效期的商品，商品的有效期是和批号是直接挂钩的；商品的批号上传至平台之后，可以直接展示在商品详情中，客户能知道其购买商品有效期的情况，在生成订单之后可以跟着订单信息一起传至商家ERP系统中，作为商家发货的依据。

商品批号同步需要处理的问题：

1. 接口需要传的字段主要包括批号，生产日期和有效期；
2. 每次通过接口同步批号的时候，应当只同步正在出售的批号（可以根据库存是否为0判断），且每次全量更新，数据库里面不能存在冗余批号数据；
3. 批号同步除了每次都全量更新之外，也可以选择每次只更新最新的或库存最大的批号。

1.1.4 商品上下架同步

商品上下架同步接口主要用来进行批量的商品下架或下架的操作，尤其是新商品刚刚上传的时候，商品处于待上架的状态，需要进行批量的上下架；此外，如需同时上下架多个商品，通过接口操作会比在界面上一个个点击的效率更高。

2. 库存

库存同步

库存同步是使用最频繁且实时性，准确性要求最高的接口；库存同步的不及时或不准确可能会造成商品负卖或客户无法下单购买。

库存同步需要处理的问题：

1. 同步时间间隔必须尽可能短且准确；
2. 有些ERP系统库存是和批号关联的，需要汇总求和该商品相关批号的库存。

3. 客户

商户ERP客户同步

正常来说，商户的ERP系统中保存的客户是不需要传给平台，只需要订单存在收货人，收货电话和送货地址及客户在下单时留的发票信息，即可完成发货的操作。

但对于一些特殊产品和特殊行业来说，由于商业原因或行业规则需要（如医药B2B采购要求采购商有相关资质证件），ERP系统中生成订单时需要先存在ERP客户信息，那么ERP客户编号必须先给到平台，然后与平台的客户进行匹配映射，在同步订单需要同时把ERP客户信息一起传输给ERP，商户ERP根据ERP客户信息生成新的ERP订单。

商户ERP客户同步需要处理的问题：

ERP客户同步至平台有多种方案：

1. 平台生成订单后，商户看到订单对应的客户资料之后，基于平台的客户资料补充ERP客户编号，平台将订单信息同步至商户ERP时顺便将ERP客户编号也一起传过去，商户ERP可根据这个ERP客户编号生成ERP订单；
2. 商户ERP预先直接将ERP中所有的客户全部同步至平台，并与平台客户做匹配，订单生成后若下单客户存在ERP客户编号，则该订单直接同步至ERP系统生成ERP订单，否则需要先在ERP系统中创建客户资料并同步至平台（ERP客户资料和平台客户可基于营业执照的统一信用代码进行匹配）。

方案1可以更好地保护商户的客户资料，保证不外泄；方案2会比较方便，需要手动操作的比较少。

4. 订单

订单方面的同步，包含以下几个方面：

1. 查询订单列表；
2. 同步物流信息；
3. 同步发货信息；
4. 同步ERP订单状态。

1.4.1 查询订单列表

该接口用于商家ERP系统请求同步平台已付款的订单，查询订单列表接口需要处理的问题：

1. 接口需要支持根据同步状态查询订单，查询订单成功后，平台方需要将对应的订单同步状态改为“已同步”，这样可以保证每次查询的时候至查询“未同步”的订单；另外，如需查询已同步的订单也可指定对应的状态进行查询。
2. 查询的方式需要支持按照条件查找，如：开始时间、结束时间、订单状态、同步状态等，同时也需要支持按照订单编号精确查询。
3. 响应的数据应分为四部分：订单基本信息；订单金额信息；送货信息；发票信息；订单商品项信息。其中送货信息和发票信息一般在商户的ERP系统中已存在，但可能与平台的信息不一致所以也需要一起返回给ERP系统。
4. 商品项信息可以包括发货的批号，客户将客户在下单时看到的批号信息传输给商户ERP，这样能很大程度减少客户退款率。

1.4.2 物流信息同步

订单在商户ERP系统发货后，需传递对应的物流信息给平台，用于展示给客户查看，物流信息同步接口需要处理的问题：

1. 商户ERP系统中的物流商与平台方的物流商必须一一对应，才能进行物流信息的传递和展示，所以平台可以提供一份物流商编码和物流商名称给商户ERP，ERP发货时将对应的物流商编码及订单号传给平台。
2. 物流信息同步也代表着订单肯定是已经发货了，如果不设计其他更改订单状态的接口的话，可以在ERP上传物流信息的时候，平台自动将订单将订单状态改为“已发货”。

1.4.3 发货信息同步

对于B2B电商来说，在平台产生的订单传到ERP系统的时候，可能产生以下问题：

1. 同一个商品可能购买多个，可能由于库存的原因导致部分商品缺货，所以在发货的时候，可能会少发某种商品或某种商品的一部分数量；
2. 商户ERP中商品由于不同批次的原因，生产日期和有效期可能会不一致，用户付款成功后，需要看到发货信息中商品批号对应的有效期的情况，所以商户ERP中需要在发货时传递相关信息到平台。

发货信息同步接口主要是在ERP系统订单出库之后，将出库的商品明细传至平台，需要传递的字段包括：ERP商品编号、发货数量、批号、生产日期、有效期。

1.4.4 同步ERP订单状态

ERP订单状态主要指订单在ERP中处理环节的各个状态，订单传至ERP系统之后，可能需要进行提单、分拣、出库、配送等环节，在客户收到货之后，物流公司也会反馈回签收信息。

ERP订单状态同步至平台后有以下两方面作用：

1. 平台可根据ERP订单状态单独生成物流信息，展示给客户，如：ERP订单状态变为“已提单”则物流信息新增一条：订单已处理，商家拣货中。
2.  特定的ERP订单状态可以与平台订单状态关联起来，如：ERP订单状态变为”已签收”，平台接收到该条ERP订单状态的信息之后，可以将订单状态改为“交易完成”。

二、商家信息同步至平台的渠道

按照商家的技术能力，可以为商家提供多种对接方案：

1. 通过平台提供的API接口对ERP系统进行开发，实现和平台的对接，适用于有专业技术开发能力的商家；
2. 平台统一开发服务系统，由平台人员实施商家ERP与平台的对接，适用于无专业的技术对接能力，有ERP系统且大批量信息不适合手工操作；
3. 手动在平台提供的商家操作后台，通过导入excel或直接手动操作的方式，直接在平台上创建或修改信息，适用于无专业的技术对接能力，商品SKU数和订单数比较少的商家，同时也可作为技术对接的替代办法。

2.1 API接口对接

商家存在技术开发能力的情况下，按照平台提供的接口调用说明文档，进行业务系统的设计与修改，通过直接请求调用API接口并获取返回数据，实现商家与平台之间的信息流通。

2.2 平台统一服务系统

主要的实现方式为：平台技术人员对商家ERP系统业务逻辑进行修改，并在商家的ERP系统上单独创建符合平台接口功能的视图，存储过程或中间表，调用平台的接口传递视图，存储过程中的信息给平台，并将平台接口的响应数据存储在中间表中。

由于不同的ERP系统的数据库结构，业务逻辑会有一定的差异，所以平台需要研究不同客户的ERP系统，进行统一的设计。

2.3 商家后台手动操作

商家后台手动操作不仅仅适用无法进行系统对接的客户，同时也是作为接口同步出故障时的临时替代办法，所以手动操作的功能需要满足系统对接的所有需求。

手动操作的功能包括：创建新商品（批量上传），商品的上下架，商品价格修改，商品库存修改，ERP客户编码上传，订单批量下载，订单状态更改等。

三、同步开关及权限的设计

由于商家的商品、客户、价格、库存、订单等信息都有手动同步和自动同步两种模式，当两种模式同时存在并进行的同时，可能会导致数据比较乱，而且不方便，如：由于库存不足，页面无法进行下单的操作。而此时商家需要进行负卖，那边这个时候需要手动修改库存，但是修改完之后，库存很快会被同步系统传过来的新库存数据给覆盖。

为了解决以上的问题，我们需要根据不同的功能模块分别做一个开关，即针对某个功能设置是否开启自动同步。如刚刚那个例子，如果此时该商品需要临时修改库存并维持一段时间（保证客户有足够的时间下单付款），可以暂时关闭库存同步服务。

此外，权限的设计可以设计得更细，即针对某个商品设置是否自动同步库存，这样的话，在关闭该商品库存同步功能的时候，不会影响其他商品库存的同步。