黑龙江快乐10分开奖查询
打印類接口
-云打印API(new)
物流跟蹤類接口
-訂閱推送API
-實時查詢API
增值服務接口
-短信接口API

訂閱推送API

  • 簡介:快遞100信息推送服務是快遞100 針對有超大運單查詢需求的企業推出的一項增值服務,服務整個過程是:貴公司將需要跟蹤的運單提交給快遞100指定的接口,快遞100接到后就對這些單號進行監控,如果監控到運單有了更新,就主動將這些物流跟蹤信息推送到貴公司指定的接口,直到這些單的生命周期結束(一般以“已簽收”為準),一個運單快遞100一般會多次推送多條跟蹤信息,貴方將之保存到數據庫。當用戶登錄貴方網站、系統或手機APP時,直接從貴司的數據庫讀取數據,并顯示于貴方的網站、系統或手機APP。
1、應用場景
(1)讓顧客登錄您的網站后,直接在“我的訂單”頁面內就能看到訂單的物流狀態。
(2)能開發自動的、批量查單功能,自動篩選出“已簽收”、“疑難件”等狀態的單號,減輕跟單人員的壓力。
(3)改變訂單的狀態與交易流程,例如只要運單號變為“已簽收”,就能讓訂單變為可以確認退換貨等。
(4)核銷售人員,評估與選擇快遞公司,根據“已簽收”的運單數,就能算出銷售人員的業績。
(5)助結算運費,用API找出“已簽收”的單及簽收時間,便能輕松應對貨到付款的結算與對帳。
2、是否需要授權
是,需要申請。
免費申請API
3、系統結構與流程

4、訂閱接口協議

4.1、訂閱請求地址
正式環境請求地址:https://poll.kuaidi100.com/poll
4.2、訂閱請求類型
post

4.3、訂閱輸入參數

名稱 類型 是否必需 示例值   描述
schema String JSON 返回的數據格式
param Object 由其他字段拼接
?└ company String ems 訂閱的快遞公司的編碼,一律用小寫字母
?└ number String em263999513jp 訂閱的快遞單號,單號的最大長度是32個字符
?└ from String 廣東省深圳市南山區 出發地城市,省-市-區,非必填,填了有助于提升簽收狀態的判斷的準確率,請盡量提供
?└ to String 北京市朝陽區 目的地城市,省-市-區,非必填,填了有助于提升簽收狀態的判斷的準確率,且到達目的地后會加大監控頻率,請盡量提供
?└ key String 授權碼,簽合同后發放,詳請聯系 快遞100 對接人 www.xedgb.tw/openapi, 請參考郵件《快遞100-企業版快遞查詢接口(API)——授權key及相關工具》
?└ parameters Object 附加參數信息
? └- callbackurl String http://www.您的域名.com/kuaidi?callbackid=... 回調接口的地址
? └- salt String XXXXXXXXXX 簽名用隨機字符串
? └- resultv2 String 1 添加此字段表示開通行政區域解析功能(僅對開通簽收狀態服務用戶有效)
? └- autoCom String 1 添加此字段且將此值設為1,則表示開始智能判斷單號所屬公司的功能,開啟后,company字段可為空,即只傳運單號(number字段),我方收到后會根據單號判斷出其所屬的快遞公司(即company字段)。建議只有在無法知道單號對應的快遞公司(即company的值)的情況下才開啟此功能
? └- interCom String 1 添加此字段表示開啟國際版,開啟后,若訂閱的單號(即number字段)屬于國際單號,會返回出發國與目的國兩個國家的跟蹤信息,本功能暫時只支持郵政體系(國際類的郵政小包、EMS)內的快遞公司,若單號我方識別為非國際單,即使添加本字段,也不會返回destResult元素組
? └- departureCountry String CN 出發國家編碼
? └- departureCom String ems 出發的快遞公司的編碼
? └- destinationCountry String JP 目的國家編碼
? └- destinationCom String japanposten 目的的快遞公司的編碼
? └- phone String 13488888888 收件人或寄件人的手機號(順豐單號必填)

4.4、訂閱請求參數示例

    schema= json
    param={
        "company":"ems",
        "number":"em263999513jp",
        "from":"廣東省深圳市南山區",
        "to":"北京市朝陽區",
        "key":"XXX ",
        "parameters":{
            "callbackurl":"您的回調接口的地址,如http://www.您的域名.com/kuaidi?callbackid=...",
            "salt":"XXXXXXXXXX",
            "resultv2":"1",
            "autoCom":"1",
            "interCom":"1",
            "departureCountry":"CN",
            "departureCom":"ems",
            "destinationCountry":"JP",
            "destinationCom":"japanposten"
        }
    }
         

4.5、訂閱返回結果

字段名稱   字段含義
result true表示成功,false表示失敗
returnCode 200: 提交成功
701: 拒絕訂閱的快遞公司
700: 訂閱方的訂閱數據存在錯誤(如不支持的快遞公司、單號為空、單號超長等)或錯誤的回調地址
702: POLL:識別不到該單號對應的快遞公司
600: 您不是合法的訂閱者(即授權Key出錯)
601: POLL:KEY已過期
500: 服務器錯誤(即快遞100的服務器出理間隙或臨時性異常,有時如果因為不按規范提交請求,比如快遞公司參數寫錯等,也會報此錯誤)
501:重復訂閱(請格外注意,501表示這張單已經訂閱成功且目前還在跟蹤過程中(即單號的status=polling),快遞100的服務器會因此忽略您最新的此次訂閱請求,從而返回501。一個運單號只要提交一次訂閱即可,若要提交多次訂閱,請在收到單號的status=abort或shutdown后隔半小時再提交訂閱
status 通訊狀態,請忽略
condition 快遞單明細狀態標記,暫未實現,請忽略
ischeck 是否簽收標記,請忽略,明細狀態請參考state字段
com 快遞公司編碼,一律用小寫字母
nu 單號
data 最新查詢結果,數組,包含多項,全量,倒序(即時間最新的在最前),每項都是對象,對象包含字段請展開
?└ context 內容
?└ time 時間,原始格式
?└ ftime 格式化后時間

4.6、訂閱返回示例(JSON格式)

    {
        "result":true,
        "returnCode":"200",
        "message":"提交成功"
    }
         

4.7、訂閱代碼示例

<?
    $post_data = array();
    $post_data["schema"] = 'json' ;

    //callbackurl請參考callback.php實現,key經常會變,請與快遞100聯系獲取最新key
    $post_data["param"]='{"company":"yuantong", "number":"12345678","from":"廣東深圳", "to":"北京朝陽",';
    $post_data["param"]=$post_data["param"].'"key":"testkuaidi1031",';
    $post_data["param"]=$post_data["param"].'"parameters":{"callbackurl":"http://www.yourdmain.com/kuaidi"}}';

    $url='http://www.xedgb.tw/poll';

    $o="";
    foreach ($post_data as $k=>$v)
    {
        $o.= "$k=".urlencode($v)."&";		//默認UTF-8編碼格式
    }

    $post_data=substr($o,0,-1);

    $ch = curl_init();
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_HEADER, 0);
        curl_setopt($ch, CURLOPT_URL,$url);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    $result = curl_exec($ch);		//返回提交結果,格式與指定的格式一致(result=true代表成功)

?>

5、推送接口協議

5.1、推送請求地址
由貴司在訂閱請求中通過callbackurl字段提供
5.2、推送請求類型
post

5.3、推送輸入參數

名稱 類型 示例值   描述
param Object 由其他字段拼接
?└ status String polling 監控狀態:polling:監控中,shutdown:結束,abort:中止,updateall:重新推送。其中當快遞單為已簽收時status=shutdown,當message為“3天查詢無記錄”或“60天無變化時”status= abort ,對于stuatus=abort的狀度,需要增加額外的處理邏輯
?└ billstatus String got 包括got、sending、check三個狀態,由于意義不大,已棄用,請忽略
?└ message String 監控狀態相關消息,如:3天查詢無記錄,60天無變化
?└ autoCheck String 1 快遞公司編碼是否出錯,0為本推送信息對應的是貴司提交的原始快遞公司編碼,1為本推送信息對應的是我方糾正后的新的快遞公司編碼。一個單如果我們連續3天都查不到結果,我方會(1)判斷一次貴司提交的快遞公司編碼是否正確,如果正確,給貴司的回調接口(callbackurl)推送帶有如下字段的信息:autoCheck=0、comOld與comNew都為空;(2)如果貴司提交的快遞公司編碼出錯,我們會幫忙用正確的快遞公司編碼+原來的運單號重新提交訂閱并開啟監控(后續如果監控到單號有更新就給貴司的回調接口(callbackurl)推送帶有如下字段的信息:autoCheck=1、comOld=原來的公司編碼、comNew=新的公司編碼);并且給貴方的回調接口(callbackurl)推送一條含有如下字段的信息:status=abort、autoCheck=0、comOld為空、comNew=糾正后的快遞公司編碼。
?└ comOld String yuantong 貴司提交的原始的快遞公司編碼。詳細見autoCheck后說明。若開啟了國際版(即在訂閱請求中增加字段interCom=1),則回調請求中暫無此字段
?└ comNew String ems 我司糾正后的新的快遞公司編碼。詳細見autoCheck后說明。若開啟了國際版(即在訂閱請求中增加字段interCom=1),則回調請求中暫無此字段
?└ lastResult Object 最新查詢結果,若在訂閱報文中通過interCom字段開通了國際版,則此lastResult表示出發國的查詢結果,全量,倒序(即時間最新的在最前)
? └- message String 消息體,請忽略
? └- state String 0 快遞單當前狀態,包括0在途,1攬收,2疑難,3簽收,4退簽,5派件,6退回等7個狀態
? └- status String 200 通訊狀態,請忽略
? └- condition String F00 快遞單明細狀態標記,暫未實現,請忽略
? └- ischeck String 0 是否簽收標記
? └- com String yuantong 快遞公司編碼,一律用小寫字母
? └- nu String V030344422 單號
? └- data Object 數組,包含多個對象,每個對象字段如展開所示
?  └-- context String 上海分撥中心/裝件入車掃描 內容
?  └-- time String 2012-08-28 16:33:19 時間,原始格式
?  └-- ftime String 2012-08-28 16:33:19 格式化后時間
?  └-- status String 在途 本數據元對應的簽收狀態。只有在開通簽收狀態服務(見上面"status"后的說明)且在訂閱接口中提交resultv2標記后才會出現
?  └-- areaCode String 310000000000 本數據元對應的行政區域的編碼,只有在開通簽收狀態服務(見上面"status"后的說明)且在訂閱接口中提交resultv2標記后才會出現
?  └-- areaName String 上海市 本數據元對應的行政區域的名稱,開通簽收狀態服務(見上面"status"后的說明)且在訂閱接口中提交resultv2標記后才會出現
?└ destResult Object 表示最新的目的國家的查詢結果,只有在訂閱報文中通過interCom=1字段開通了國際版才會顯示此數據元,全量,倒序(即時間最新的在最前)
? └- message String 消息體,請忽略
? └- state String 0 快遞單當前狀態,包括0在途,1攬收,2疑難,3簽收,4退簽,5派件,6退回等7個狀態
? └- status String 200 通訊狀態,請忽略
? └- condition String F00 快遞單明細狀態標記,暫未實現,請忽略
? └- ischeck String 0 是否簽收標記
? └- com String yuantong 快遞公司編碼,一律用小寫字母
? └- nu String V030344422 單號
? └- data Object 數組,包含多個對象,每個對象字段如展開所示
?  └-- context String 上海分撥中心/裝件入車掃描 內容
?  └-- time String 2012-08-28 16:33:19 時間,原始格式
?  └-- ftime String 2012-08-28 16:33:19 格式化后時間
?  └-- status String 在途 本數據元對應的簽收狀態。只有在開通簽收狀態服務(見上面"status"后的說明)且在訂閱接口中提交resultv2標記后才會出現
?  └-- areaCode String 310000000000 本數據元對應的行政區域的編碼,只有在開通簽收狀態服務(見上面"status"后的說明)且在訂閱接口中提交resultv2標記后才會出現
?  └-- areaName String 上海市 本數據元對應的行政區域的名稱,開通簽收狀態服務(見上面"status"后的說明)且在訂閱接口中提交resultv2標記后才會出現

5.4、推送輸入參數示例

    param={
        "status":"polling",
        "billstatus":"got",
        "message":"",
        "autoCheck":"1",
        "comOld":"yuantong",
        "comNew":"ems",
        "lastResult":{
            "message":"ok",
            "state":"0",
            "status":"200",
            "condition":"F00",
            "ischeck":"0",
            "com":"yuantong",
            "nu":"V030344422",
            "data":[{
                "context":"上海分撥中心/裝件入車掃描 ",
                "time":"2012-08-28 16:33:19",
                "ftime":"2012-08-28 16:33:19",
                "status":"在途",
                "areaCode":"310000000000",
                "areaName":"上海市"
            },
                "context":"上海分撥中心/下車掃描 ",
                "time":"2012-08-27 23:22:42",
                "ftime":"2012-08-27 23:22:42",
                "status":"在途",
                "areaCode":"310000000000",
                "areaName":"上海市"

             }]
	    },
        "destResult":{
            "message":"ok",
            "state":"0",
            "status":"200",
            "condition":"F00",
            "ischeck":"0"     ,
            "com":"speedpost",
            "nu":"EX015142583SG",
            "data":[{
                "context":"[01000]Final delivery Delivered to: SLOVESNOV",
                "time":"2016-05-24 14:00:00",
                "ftime":"2016-05-24 14:00:00",
                "status":"簽收",
                "areaCode":null,
                "areaName":null
            }]
        }
    }
         

5.5、推送返回結果

字段名稱   字段含義
result true表示成功,false表示失敗。如果提交回調接口的地址失敗,30分鐘后重新回調,3次仍舊失敗的,自動放棄
returnCode 200: 提交成功
500: 服務器錯誤
其他錯誤請自行定義
message 返回的提示

5.6、推送返回示例(JSON格式)

    {
        "result":true,
        "returnCode":"200",
        "message":"成功"
    }
         

5.7、推送代碼示例

<?php header("Content-Type:text/html;charset=utf-8"); ?>
<?
	//訂閱成功后,收到首次推送信息是在5~10分鐘之間,在能被5分鐘整除的時間點上,0分..5分..10分..15分....
	$param=$_POST['param'];

	try{
		//$param包含了文檔指定的信息,...這里保存您的快遞信息,$param的格式與訂閱時指定的格式一致

		echo  '{"result":"true",	"returnCode":"200","message":"成功"}';
		//要返回成功(格式與訂閱時指定的格式一致),不返回成功就代表失敗,沒有這個30分鐘以后會重推
	} catch(Exception $e)
		{
		echo  '{"result":"false",	"returnCode":"500","message":"失敗"}';
		//保存失敗,返回失敗信息,30分鐘以后會重推
	}


?>
黑龙江快乐10分开奖查询 11选5胆拖投注查询表 北京pk10直播网站 波音在线 欢乐生肖开奖记录 新时时五星直选 重庆时时五星彩走势图 秒速时时是哪开的 pc蛋蛋谁做出来的 捕鱼达人2 北京赛车2期6码计划