菜鳥電子面單對接技術方案（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（名字起的都挺有水平~）。

   

1. 根據上圖流程首先我們在菜鳥物流雲系統注冊成為ISV，然后發布API服務。這個過程參考官方文檔，比較簡單，文檔寫的比較詳細，這里不贅述。
2. 還要注冊一個商家帳號，還是在這個系統上申請，這一點當初我也不理解，官方的解釋如下圖：        

        現在理解了，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 接口查看，省、市、縣、鎮、詳細地址一個字一個標點符號都不能錯。

暫時總結這么多，歡迎技術交流！