準備參數


所有SDM API都需要用夥伴ID (Partner ID)與API金鑰 (API Key)方能進行串接, 在與SDM確立合作後,SDM會授權您一組夥伴ID與API金鑰。

由於夥伴ID與API金鑰在API溝通時,是用來驗證身份與檢驗資料完整性,因此夥伴ID與API金鑰具有私密性, 請妥善保管。以下為準備參數詳細資料:

  • 夥伴ID (Partner ID): 由SDM提供的ID,用以辨識使用者身份。格式為"channel-"開頭,其後接著32字元的字串。
  • API金鑰 (API Key): 由SDM提供的金鑰,用以驗證身份與驗證資料完整性,格式為32字元的字串。

發送請求 (API Request)


所有SDM API運作,皆透過使用者伺服器以POST方式發送SDM API請求 (request), 至SDM API伺服器,SDM API伺服器根據使用者之請求,計算使用者所需之資料,最後, 產生SDM API回應 (response)回傳給使用者。

SDM API請求又可細分為三個參數,包含資料格式 (dataType)、請求 (request)、簽章 (signature),詳細說明如下:

參數 名稱 型態 描述
dataType 資料格式 string 指定SDM API 請求與回應的資料格式。
  • JSON  -  請求與回應皆使用JSON資料型態。
request 請求 string 請求內容,產生步驟如下:
  1. 產生符合dataType結構的字串,其內容請參考各API文件
  2. 進行urlencode
signature 簽章 string 用來檢驗API使用者身份與request資料之完整性。 signature計算方式請參考 signature  -  身份與資料完整性驗證

解析回應 (API Response)


SDM API回應是一個用&符號分隔的字串,如下所示:
	response=responseValue&signature=signatureValue

解讀SDM API回應步驟如下:
  1. 分割字串,取得responseValue與signatureValue
  2. 驗證signature是否相同
  3. 讀取response
    • responseValue請先進行urldecode
    • 將字串解析成JSON物件 (PHP中,使用json_decode即可)

signature - 身份與資料完整性驗證


發送請求時signature計算
為了驗證身份與檢驗資料完整性,在發送請求時,將request變數用API金鑰,進行HMAC-SHA256計算,即可產生signature。 SDM在收到request後會比對signature是否一致,以確保安全性。
	$request='{
		"request":{
			"header":{
				"partner":"channel-0004ac09be84ebb292b14178b36581f2",
				"method":"hotels",
				"time":"2014-05-15 18:03:15",
				"token":"token-fffd89d7f9bbd7b0937d411327d30885"
			},
			"body":{
			}
		}
	}';

	$request=urlencode($request);
	$signature=hash_hmac("sha256",$request,$api_key);

收到回應時signature計算
收到response時,將response變數用API金鑰,進行HMAC-SHA256計算, 即可產生signature。 您在收到response後,應比對您收到與計算的signature是否一致,以確保安全性。
	if(hash_hmac("sha256",$response,$api_key)==$signature){
		//身份與資料完整性驗證通過
	}else{
		//身分或資料完整性驗證錯誤
	}

API範例


以下hotels API舉例,獲取旅館、房型基本資料:
  1. 填入夥伴ID與API金鑰
    	$partner="channel-0004ad29be84ebb292b14178bagh81f2";
    	$api_key="fQZoJw86vJmnHNGZGS53esd2DQg7BwD8";
  2. 填入請求內容
    	$request=array();
    	$request["request"]=array();
    	$request["request"]["header"]=array();
    	$request["request"]["header"]["partner"]=$partner;
    	$request["request"]["header"]["method"]="hotels";
    	$request["request"]["header"]["time"]="2014-06-02 12:00:02";
    	$request["request"]["header"]["token"]="token-ae04ad29be84ebb292b14178bagh92d3";
    	$request["request"]["body"]=array();
  3. 形成符合JSON格式之字串
    	$request=json_encode($request);
  4. 進行urlencode
    	$request=urlencode($request);
  5. 使用HMAC-SHA256計算出signature
    	$signature=hash_hmac("sha256",$request,$api_key);
  6. 發送request
    	$toURL="https://sdm_api_qazwsxedc.com/api/index.php";
    	$post=array(
    	    "dataType"=>"JSON",
    	    "request"=>$request,
    	    "signature"=>$signature
    	);
    	$ch=curl_init();
    	curl_setopt($ch,CURLOPT_URL,$toURL); 
    	curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
    	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,false);
    	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST,false);
    	curl_setopt($ch,CURLOPT_POST,true); 
    	curl_setopt($ch,CURLOPT_POSTFIELDS,http_build_query($post)); 
    	$result=curl_exec($ch); 
    	curl_close($ch);
  7. 收到回傳資料,解析出response跟signature
    	$temp=explode("&",$result);
    	$response=substr($temp[0],9);
    	$signature=substr($temp[1],10);
  8. 比對自行計算與收到的signature是否一致
    	if(hash_hmac("sha256",$response,$api_key)==$signature){
    		//身份與資料完整性驗證通過
    	}else{
    		//身分或資料完整性驗證錯誤
    	}
  9. 解析response
    	//將response進行urldecode,再進行json_decode
    	$data=json_decode(urldecode($response_str),true);
    
    	/*
    		$data["response"]
    		api回覆的response,格式請參考api文檔
    
    		$data["response"]["header"]["returnCode"]
    		回傳代碼,可用來判斷api執行是否成功
    
    		$data["response"]["header"]["returnMessage"] 
    		回傳的訊息
    	*/
    
    	//範例:列出所有旅館名稱
    	$hotels=$data["response"]["body"]["hotels"];
    	for($i=0;$i<count($hotels);$i++){
    		echo $hotels[$i]["name"].",";
    	}