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

1 接口規(guī)范說(shuō)明

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

1.1.1 報(bào)文及報(bào)文編碼

報(bào)文格式：Json格式

請(qǐng)求方法的編碼格式(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)級(jí){數(shù)據(jù)})

1.1.3 JSON示例

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

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

1.1.5 流程示意圖

1.1.6 名詞定義

1.2 簽名說(shuō)明

1.2.1 關(guān)于簽名

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

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

2.注：

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

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

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

舉例：

1.假設(shè)

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

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

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

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

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

OWFhM2I5N2ViM2U2MGRkMjc4YzU2NmVlZWI3ZDk0MmE=

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

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

1.3 接入步驟

1.快遞鳥(niǎo)官網(wǎng)注冊(cè)賬號(hào)成為快遞鳥(niǎo)用戶;

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

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

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

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

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

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

2 下單類接口

2.1 上門(mén)取件-下單

2.1.1 功能說(shuō)明

1. 此接口用于通知快遞公司快遞員上門(mén)攬件。

2.1.2 基本信息

2.1.3 接口規(guī)則

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

2.1.4 應(yīng)用場(chǎng)景

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

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

請(qǐng)求示例：

2.1.6 返回參數(shù)

2.2 上門(mén)取件-訂單取消

2.2.1 功能說(shuō)明

此接口用于取消“上門(mén)取件接口”下單成功的訂單。

2.2.2 基本信息

2.2.3 接口規(guī)則

1. 只支持取消通過(guò)上門(mén)取件接口下單成功的訂單；

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

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

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

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

請(qǐng)求示例:

2.2.5 返回參數(shù)

返回示例:

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

2.3.1 功能說(shuō)明

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