電商售后退貨快遞寄件下單預(yù)約快遞員上門取件接口對接，調(diào)用快遞鳥提供的上門取件API標(biāo)準(zhǔn)接口，成功調(diào)用后，快遞員會準(zhǔn)時上門取件，同時支持快遞單號物流軌跡查詢，快遞鳥物流單號查詢api接口不區(qū)分開發(fā)語言，支持Java，C#，PHP，Python，ObjectC等開發(fā)語言的程序調(diào)用。

1 接口規(guī)范說明

1.1 接口規(guī)范及說明

1.1.1 報文及報文編碼

報文格式：Json格式

請求方法的編碼格式(utf-8)：交互協(xié)議上統(tǒng)一用UTF-8，避免傳遞中文數(shù)據(jù)出現(xiàn)亂碼。

1.1.2 接口數(shù)據(jù)包結(jié)構(gòu)

圖例- 數(shù)據(jù)包結(jié)構(gòu)(系統(tǒng)級{數(shù)據(jù)})

1.1.3 JSON示例

1.1.4 系統(tǒng)級參數(shù)

*快遞下單類接口統(tǒng)一使用此系統(tǒng)級參數(shù)，根據(jù)不同的請求接口指令接入不同的接口。

1.1.5 流程示意圖

1.1.6 名詞定義

1.2 簽名說明

1.2.1 關(guān)于簽名

快遞鳥和第三方電子商務(wù)公司系統(tǒng)進(jìn)行對接，有一定的安全機(jī)制。采用IP認(rèn)證加簽名的方式對接，具體方案如下：

1.防止數(shù)據(jù)被篡改

2.注：

DataSign生成后，對方接收到數(shù)據(jù)后，以同樣的算法進(jìn)行簽名(推送接口RequestType為101/102不需要進(jìn)行URL編碼)，生成摘要，對比兩者的摘要是否相同，如果不同，說明傳遞過程中發(fā)生數(shù)據(jù)篡改。

2.調(diào)用接口的身份認(rèn)證

注冊成為快遞鳥用戶后，會生成對應(yīng)的用戶ID和APIKey，用戶ID相當(dāng)于用戶名，APIKey相當(dāng)于密碼。

舉例：

1.假設(shè)

2.那么DataSign簽名的內(nèi)容為

3.接收方收到數(shù)據(jù)后，獲得

EBusinessID 和RequestData和DataSign等這幾個數(shù)據(jù)。

4.接收方對EBusinessID得到APIKey，RequestData+APIKey的數(shù)據(jù)進(jìn)行

md5和base64后的內(nèi)容就為

OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=

5.接收方判斷簽名后的數(shù)據(jù)跟傳遞過來的DataSign是否一致，如果一致進(jìn)行業(yè)務(wù)操作，如果不一致返回錯誤。

1.2.2 (C#)DataSign簽名加密代碼

1.3 接入步驟

1.快遞鳥官網(wǎng)注冊賬號成為快遞鳥用戶;

快遞鳥提供的用戶ID是調(diào)用接口服務(wù)的身份證明，不可更改、不可轉(zhuǎn)用，API Key是應(yīng)用訪問API的簽名附加密鑰，必須妥善保存。兩者關(guān)系類似于用戶名和密碼，兩者都會在簽名和業(yè)務(wù)參數(shù)中使用。

2.登陸用戶后臺，進(jìn)行實名認(rèn)證，并開通會員服務(wù);

3.根據(jù)技術(shù)文檔進(jìn)行開發(fā)并在調(diào)試平臺測試聯(lián)調(diào)；

快遞鳥提供各個API接口的DEMO(包括：.Net版本、Java版本、PHP版本)供開發(fā)參考。

4.系統(tǒng)發(fā)布上線。

注意：測試環(huán)境中獲取的測試快遞單號不可用于實際發(fā)貨。

2 下單類接口

2.1 上門取件-下單

2.1.1 功能說明

1. 此接口用于通知快遞公司快遞員上門攬件。

2.1.2 基本信息

2.1.3 接口規(guī)則

1. 請求報文中不允許出現(xiàn)以下特殊字符：’ ” # & + < > % \2. 預(yù)約時提供的收寄方信息必須真實準(zhǔn)確。3. 用戶提供的寄件地址若超出快遞公司服務(wù)范圍，則無快遞員上門攬件。4. 因用戶原因(如：惡意下單、批量下單長時間不發(fā)貨等)導(dǎo)致快遞公司投訴超過3次，快遞鳥將停用此用戶接口權(quán)限。5. 預(yù)約時間段：9點-17點可預(yù)約當(dāng)天上門，17點-次日9點前，預(yù)約次日上門全國（除特殊區(qū)域）：當(dāng)前時間：9點前 可預(yù)約時間段：預(yù)約當(dāng)天任意時間段上門當(dāng)前時間：11點前 可預(yù)約時間段：11點后預(yù)約當(dāng)天任意時間段上門當(dāng)前時間：13點前 可預(yù)約時間段：13點后任意時間段上門當(dāng)前時間：15點前 可預(yù)約時間段：15點后任意時間段上門當(dāng)前時間：17點前 可預(yù)約時間段：17點-19點當(dāng)前時間：17-次日9點前，預(yù)約次日任意時間段上門特殊區(qū)域：（西北6?。ǜ拭C、青海、寧夏、陜西、新疆、西藏），東北三?。ㄟ|寧省、吉林省、黑龍江省），海南?。┊?dāng)前時間：11點前 可預(yù)約時間段：19點前當(dāng)前時間：11-17點前 可預(yù)約時間段：19點前當(dāng)前時間：17-次日9點前，預(yù)約次日19點前

2.1.4 應(yīng)用場景

電商平臺、打單工具、ERP系統(tǒng)、WEB端、APP移動端、小程序、集團(tuán)統(tǒng)一結(jié)算運(yùn)費(fèi)

2.1.5 應(yīng)用級參數(shù)

請求示例：

2.1.6 返回參數(shù)

2.2 上門取件-訂單取消

2.2.1 功能說明

此接口用于取消“上門取件接口”下單成功的訂單。

2.2.2 基本信息

2.2.3 接口規(guī)則

1. 只支持取消通過上門取件接口下單成功的訂單；

2. 已攬件狀態(tài)后不允許取消；提示“您的訂單已攬件，不可取消訂單”；

3. 距離預(yù)約開始剩余5分鐘至預(yù)約結(jié)束時間加2小時不能取消訂單，提示“您的訂單在正常服務(wù)時間內(nèi)，不可取消訂單”；

4. 其它時間均可取消訂單提示“您的訂單已取消成功”。

2.2.4 應(yīng)用級參數(shù)

請求示例:

2.2.5 返回參數(shù)

返回示例:

2.3 上門取件-訂單狀態(tài)推送

2.3.1 功能說明

接口邏輯說明：向快遞公司預(yù)約后，由快遞公司推送訂單狀態(tài)（包含成功和失敗的狀態(tài)及原因）給快遞鳥，快遞鳥字段轉(zhuǎn)換后，再通過RequestType ：103實時推送給客戶；（注：訂單狀態(tài)數(shù)據(jù)在快遞鳥后臺保存7天，推送失敗時的重推機(jī)制：同軌跡推送接口）；商家端：支持客戶通過上門取件接口1801接口的預(yù)約指令；