菜鳥電子面單對接技術方案（link）

1、背景

        快遞業務突飛猛進，收發快遞是生活中不可缺乏的一部分了，特別是作微商的商家，天天發送大量的快遞。填寫快遞單已經成爲過去式，快遞小哥上門收件的時候，都使用手持的中端設備，不再用客戶填寫快遞單了。技術的更新帶來的方即是有目共睹的。然而面對天天幾十件的發送量，這種方式仍是有點慢，且不說快遞小哥有多少耐心，時間久了也沒有那家快遞單獨爲你服務，這是其一，其二是快遞單和包裹是否及時準確的對應，這也是在發送大量快遞 時候常常搞錯的事情，那麼有沒有一種方法，本身打印快遞單，本身給包裹貼上快遞單呢？答案是，有！這在之前是不可能實現的，這幾年各快遞公司都推出了本身的接口服務，供大客戶的erp對接，從而實現面單打印。可是這種方式須要跟各家快遞公司對接，每家快遞公司的接口不同，這形成了很大的工做量。有沒有一種方式能夠對接各大快遞公司呢？答案是，有！那就是菜鳥物流雲，這裏不得不咱給馬雲點贊，老馬確實改變了生活。菜鳥物流雲提供了與各快遞公司對接的接口。本文根據咱們對接的經驗總一下總結，因爲菜鳥物流雲也是剛剛推出，功能和文檔上不是那麼完善，咱們把遇到的坑和注意事項寫下來，供你們參考。

2、需求

       咱們再來梳理一下咱們的需求，咱們須要一種方式，可以打印快遞單，而後把快遞單貼在要發送的包裹上。這是最直接的需求，隱含的需求是商品從銷售到配貨發貨都要管理起來，發送快遞只是整個銷售流程中的一部分，咱們不只要能本身打印快遞單，更重要的是能查詢那些已發貨，那些未發貨，發貨的對應的快遞單號是多少。這個銷售過程的管理是統一不可分開的，使用一套系統來完成，若是銷售系統與快遞打印分開，那麼會形成雙倍的工做量，還容易出錯。咱們有三款進銷存產品：商貿通、鞋服通、醫藥通，詳情能夠參加網站:www.hfbpm.com，快遞面單打印需求也是上述產品的需求。

3、方案

        需求明確了，咱們來選擇技術方案，前面提到了不使用與各快遞公司的對接，而是採用與菜鳥物流雲對接。這裏說明一下，菜鳥物流雲屬於淘寶開放平臺的一部分，淘寶開發平臺提供了不少種對接接口，包括商品、銷售單等等，幾乎涉及到的業務都在該平臺上開放了接口。這也是咱們此次對接的時候才發現的，後續會繼續與之對接，實現咱們的禾豐進銷存系統與淘寶賣家系統的對接。

淘寶開放平臺提供了兩種快遞面單接口，一種是淘寶商家TOP接口，一種是菜鳥物流雲Link接口。具體介紹請查看淘寶開發平臺的文檔：

 

https://open.taobao.com/doc.htm?docId=107052&docType=1，咱們採用菜鳥Link接口對接。

4、設計

      方案肯定後，咱們須要進行系統功能的設計，首先咱們要作技術性的嘗試，對菜鳥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個工做日內必須答覆，逾期會罰款（後來知道的）。

5、準備工做

        前面的申請都作完後，就開始做技術對接了，總結一下前面的申請：ISV資質認證，ISV應用審覈、商戶訂購關係購買，三個缺一不可。購買面單後，會給你面單紙，還須要一臺打印機，網上購買或者網點的推薦均可以，型號必定要和麪單紙對應。固然，測試的時候打印機能夠暫時使用普通的打印機代替，也能夠打印到pdf或者圖片，等上線使用的時候再購買配套打印機。

一、  json、xml

Link接口的數據交互格式是xml或者是json，咱們使用本身的Web開發平臺，這些底層的處理方法都已經實現了，就不是技術難題了，沒有實現的須要本身編寫xml或者json相關的處理方法。

這裏注意沙箱測試環境只支持xml方式，不支持json方式，這個不知道爲啥，有點不理解，多是待完善吧。

二、  http請求get、post

Link接口的通信協議是http協議，咱們使用本身的Web開發平臺，這些底層的通信協議都已經實現，沒有實現的須要本身編寫請求get、post的方法。

這個方法是調用link Api的通用方法，注意參數和註釋，咱們是使用C#語言來實現的，供參考。

三、  websocket

websocket是與瀏覽器相關的，是集成到瀏覽器中的，不須要引用第三方的js，目前流行的瀏覽器都支持這個技術。面單數據打印的時候經過該協議與菜鳥打印組件交互。

6、效果圖

具體的對接公司文檔都比較詳細，下面是對接完成的效果圖。

一、發貨單的管理界面：

二、快遞面單打印：

三、快遞面單打印部分代碼：

 

7、注意事項

一、  沙箱測試使用固定的參數，支持xml格式，下圖中的參數是固定。

二、  收貨地址必須包含省、市和詳細地址，link接口市是容許爲空的，可是若是爲空，那麼快遞面單打印的時候沒有三段碼，沒有三段碼的快遞面單是無效的。以下圖：

 

正確的收貨地址寫法是 北京北京市天通苑東三區XXX。最好是包含省、市、縣、詳細地址。

三、  發貨地址要與申請網點申請時發貨地址一致，不然獲取面單時會報錯，能夠調用

TMS_WAYBILL_SUBSCRIPTION_QUERY 接口查看，省、市、縣、鎮、詳細地址一個字一個標點符號都不能錯。

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