菜鸟电子面单对接技术方案（link）

一、背景

快递业务日新月异，收发快递是生活中不可缺少的一部分了，特别是做微商的商家，每天发送大量的快递。填写快递单已经成为过去式，快递小哥上门收件的时候，都使用手持的中端设备，再也不用客户填写快递单了。技术的更新带来的方便是有目共睹的。然而面对每天几十件的发送量，这种方式还是有点慢，且不说快递小哥有多少耐心，时间久了也没有那家快递单独为你服务，这是其一，其二是快递单和包裹是否及时准确的对应，这也是在发送大量快递时候经常搞错的事情，那么有没有一种方法，自己打印快递单，自己给包裹贴上快递单呢？答案是，有！这在以前是不可能实现的，这几年各快递公司都推出了自己的接口服务，供大客户的erp对接，从而实现面单打印。但是这种方式需要跟各家快递公司对接，每家快递公司的接口不一样，这造成了很大的工作量。有没有一种方式可以对接各大快递公司呢？答案是，有！那就是菜鸟物流云，这里不得不咱给马云点赞，老马确实改变了生活。菜鸟物流云提供了与各快递公司对接的接口。本文根据我们对接的经验总一下总结，由于菜鸟物流云也是刚刚推出，功能和文档上不是那么完善，我们把遇到的坑和注意事项写下来，供大家参考。

二、需求

我们再来梳理一下我们的需求，我们需要一种方式，能够打印快递单，然后把快递单贴在要发送的包裹上。这是最直接的需求，隐含的需求是商品从销售到配货发货都要管理起来，发送快递只是整个销售流程中的一部分，我们不仅要能自己打印快递单，更重要的是能查询那些已发货，那些未发货，发货的对应的快递单号是多少。这个销售过程的管理是统一不可分开的，使用一套系统来完成，如果销售系统与快递打印分开，那么会造成双倍的工作量，还容易出错。我们有三款进销存产品：商贸通、鞋服通、医药通，详情可以参加网站:www.hfbpm.com，快递面单打印需求也是上述产品的需求。

三、方案

需求明确了，我们来选择技术方案，前面提到了不使用与各快递公司的对接，而是采用与菜鸟物流云对接。这里说明一下，菜鸟物流云属于淘宝开放平台的一部分，淘宝开发平台提供了很多种对接接口，包括商品、销售单等等，几乎涉及到的业务都在该平台上开放了接口。这也是我们这次对接的时候才发现的，后续会继续与之对接，实现我们的禾丰进销存系统与淘宝卖家系统的对接。

淘宝开放平台提供了两种快递面单接口，一种是淘宝商家TOP接口，一种是菜鸟物流云Link接口。具体介绍请查看淘宝开发平台的文档：

https://open.taobao.com/doc.htm?docId=107052&docType=1，我们采用菜鸟Link接口对接。

四、设计

方案确定后，我们需要进行系统功能的设计，首先我们要做技术性的尝试，对菜鸟Link接口中的方法进行模拟测试。下面我们介绍具体的对接过程和遇到的坑。

对接流程：

对接流程如下图，需要介绍几个概念，ISV：Independent Software Vendors，独立软件开发商，我们做对接，我们就是ISV；CP：Cainiao Partner 菜鸟合作伙伴，官方介绍太简单，这里我们补充，CP就是快递物流公司，如韵达快递、顺丰快递等，目前各大快递物流公司都已接入；LINK：Logistics Integration Network，物流集成网络，这个也要补充一下，说白了就是菜鸟物流云接口的一个统称，淘宝那个接口叫TOP，这个叫Link（名字起的都挺有水平~）。

根据上图流程首先我们在菜鸟物流云系统注册成为ISV，然后发布API服务。这个过程参考官方文档，比较简单，文档写的比较详细，这里不赘述。
还要注册一个商家帐号，还是在这个系统上申请，这一点当初我也不理解，官方的解释如下图：

现在理解了，ISV是软件开发商，有权利发布接口服务，商户是真正的使用者，例如某服装店，淘宝上的某个卖家，商户可以使用多个ISV提供的服务，同样ISV也可以为多个商户服务，这样就实现了三方授权。商家帐号申请成功后，进行商家授权，获取到TOKEN，ISV对接的时候要使用，所以在ISV的ERP系统里，至少要设计可以存放多个商家的token，每个商家使用自己的token，这个不能乱了。

3. 使用商家帐号购买面单，前面是技术对接，这一步是业务对接，注意一定是使用商家帐号，而不是ISV帐号。这个需要跟快递公司谈判了，你要发哪家的快递就要像那家的快递申请，一般是向就近的网点申请，申请的审批工作也是由他们审核的，我们申请的时候就是进行了电话沟通，说明了用途，基本上他们经常跑你们那片都比较熟悉，没啥障碍，只要谈好面单价格和取货件方式都能通过。我申请了2次才通过，第一次没有打电话沟通，他们直接给拒绝了，一般申请3个工作日内必须答复，逾期会罚款（后来知道的）。

五、准备工作

前面的申请都做完后，就开始作技术对接了，总结一下前面的申请：ISV资质认证，ISV应用审核、商户订购关系购买，三个缺一不可。购买面单后，会给你面单纸，还需要一台打印机，网上购买或者网点的推荐都可以，型号一定要和面单纸对应。当然，测试的时候打印机可以暂时使用普通的打印机代替，也可以打印到pdf或者图片，等上线使用的时候再购买配套打印机。

1、 json、xml

Link接口的数据交互格式是xml或者是json，我们使用自己的Web开发平台，这些底层的处理方法都已经实现了，就不是技术难题了，没有实现的需要自己编写xml或者json相关的处理方法。

这里注意沙箱测试环境只支持xml方式，不支持json方式，这个不知道为啥，有点不理解，可能是待完善吧。

2、 http请求get、post

Link接口的通讯协议是http协议，我们使用自己的Web开发平台，这些底层的通讯协议都已经实现，没有实现的需要自己编写请求get、post的方法。

这个方法是调用link Api的通用方法，注意参数和注释，我们是使用C#语言来实现的，供参考。

3、 websocket

websocket是与浏览器相关的，是集成到浏览器中的，不需要引用第三方的js，目前流行的浏览器都支持这个技术。面单数据打印的时候通过该协议与菜鸟打印组件交互。

六、效果图

具体的对接公司文档都比较详细，下面是对接完成的效果图。

1、发货单的管理界面：

2、快递面单打印：

3、快递面单打印部分代码：

七、注意事项

1、沙箱测试使用固定的参数，支持xml格式，下图中的参数是固定。

2、收货地址必须包含省、市和详细地址，link接口市是允许为空的，但是如果为空，那么快递面单打印的时候没有三段码，没有三段码的快递面单是无效的。如下图：

正确的收货地址写法是北京北京市天通苑东三区XXX。最好是包含省、市、县、详细地址。

3、发货地址要与申请网点申请时发货地址一致，否则获取面单时会报错，可以调用

TMS_WAYBILL_SUBSCRIPTION_QUERY 接口查看，省、市、县、镇、详细地址一个字一个标点符号都不能错。

暂时总结这么多，欢迎技术交流！