WordPress: 與美安系統的串接

由

啟民林

2019-12-30

2451

美安- 串接技術文件

安裝外掛程式碼片段 Code Snippets

新增程式碼片段

1：擷取參數
當我們雙方正式合作之後，美安的優惠顧客會透過TW.SHOP.COM網站上您的店家簡介頁面或是商品搜尋結果頁或是相關APP之功能進入到您的網站。當優惠顧客進入您網站的時候，我們會於您的網址後方帶入兩組分別為RID與Click_ID參數值。
之後美安公司會用此資訊判斷是哪一位美安的優惠顧客在您的網站上消費。因此請您須確保您的首頁，以及您的商品頁面，都要可以接收得到我們送過去的兩組參數，並優惠顧客完成訂單時寫入您的資料庫保存，並於訂單成立或取消時回拋相對應資訊。
例如：http://www.yourdomain.com.tw/?RID=&Click_ID=

新增程式碼美安-接收參數存入cookie

add_action('init', 'get_shop_com_para');
 function get_shop_com_para( $shop_com ) {
     if (!isset($shop_com)) { $shop_com=''; }
     $shop_com_RID=$_GET['RID'];
     $shop_com_Click_ID=$_GET['Click_ID'];
     //setcookie('shop_com', '', time()-3600, "/", $_SERVER['SERVER_NAME']);    return; //clear cookie
     if (isset($_COOKIE['shop_com']) || $shop_com != '1') { //若不是從美安首頁進入或已經設cookie就不強迫設cookie
         if (empty($shop_com_RID)) { return; }
         if (empty($shop_com_Click_ID)) { return; }     
     }
     $shop_com_str='shopcom '.$shop_com_RID.' '.$shop_com_Click_ID;
     setcookie('shop_com', $shop_com_str, time()+(3600247), "/", $_SERVER['SERVER_NAME']); //24 x 7小時有效
 }

2-1：訂單成立紀錄向美安回報成交資訊

當訂單成立時，您的網站需要回傳訂單成立資料給我們。由於傳送訂單紀錄功能有安全性設定，因此您必須提供至少一組屆時會用來傳送取消紀錄的主機IP Address給我們。

交易紀錄回拋API網址如下：https://api.hasoffers.com/Api?Format=json&Target=Conversion&Method=create&Service=HasOffers&Version=2&NetworkId=marktamerica&NetworkToken=NETPYKNAYOswzsboApxaL6GPQRiY2s&data[offer_id]=&data[advertiser_id]=&data[sale_amount]=&data[affiliate_id]=12&data[payout]=&data[revenue]=&data[advertiser_info]=&data[affiliate_info1]=&data[ad_id]=&data[session_datetime]=

序號	欄位名稱	形式	說明
1	Offer_ID	文字	帶入專屬Offer ID值
2	Advertiser_ID	文字	帶入專屬Advertiser_ID值
3	Order_Amount	數字	帶入消費者使用您網站上的折扣之後，實際支付「商品本身」的金額。請勿加上運費、手續費。例如：消費者購買了1,000元的商品，並使用了您網站的100元折價券，並支付了80元的運費。此時您需要傳900給我們。
4	Commission_Amount	數字	帶入佣金金額並計算至小數點第二位計算方式為訂單金額乘上佣金百分比
5	ORDER_ID	文字	帶入此訂單的訂單編號
6	RID	文字	帶入此訂單原始記錄到的RID
7	Click_ID	文字	帶入此訂單原始記錄到的Clicik_ID
8	DateTime	日期	訂單日期，格式為YYYY-MM-DD HH:mm:ss (24小時制，使用GMT-4 美國東岸時間) *請注意，日期與時間之間有一個空格，若您的程式語言無法處理空格時，建議您可用URL Encoding取代空格。

新增程式碼美安-設定聯合行銷屬性:專屬Offer ID值,專屬Advertiser_ID值,廣告佣金比率

function shop_com_shipping_attr() {
     return (
         array(
           'url'=>'https://api.hasoffers.com/Api',
           //'url'=>'https://www.origthatone.com/shop_com.php', //測試
           'Offer_ID'=>'12xxx',  //Offer_ID
           'Advertiser_ID'=>'12xxx',  //Advertiser_ID
           'revenue_rate'=>0.25 //廣告佣金比率 25%
         )
    );
 }

新增程式碼美安-向美安回報成交資訊

add_action( 'woocommerce_thankyou', 'report_shop_com_shipping_order', 20 );
 function report_shop_com_shipping_order( $order_id ){
     $shipping_attr=shop_com_shipping_attr();
     if(!isset($_COOKIE['shop_com'])) { return; }
     $shop_com_str=$_COOKIE['shop_com'];
     $shop_com=explode(' ',$shop_com_str);
     if (!is_array($shop_com)) { return; }
     if (empty($shop_com[1])) { return; }
     if (empty($shop_com[2])) { return; }
     update_post_meta($order_id, 'shop_com', $shop_com_str); //儲存退貨用   
     //$order_id :訂單編號
     $Order_Amount=0;
     $order = wc_get_order($order_id); 
     // Iterating through each WC_Order_Item_Product objects 
     foreach ($order->get_items() as $item_key => $item_values):     
         //## Access Order Items data properties (in an array of values) ## 
         $item_data = $item_values->get_data(); 
         $Order_Amount=$Order_Amount+(int)$item_data['total'];
     endforeach;     
     $Commission_Amount=round($Order_Amount * $shipping_attr['revenue_rate'],2); //廣告佣金比率 
     $time=strtotime(get_the_date("Y-m-d H:i:s",$order_id)); // -3600*12; //GMT-4(標準時間-4小時)(台灣時間-12小時)美國東岸時間
     $session_datetime=gmdate("Y/m/d",$time).'%C2%A0'.gmdate("H:i:s",$time); 
     $http_str=$shipping_attr['url'];
     $http_str=$http_str.'?Format=json';
     $http_str=$http_str.'&Target=Conversion';
     $http_str=$http_str.'&Method=create';
     $http_str=$http_str.'&Service=HasOffers';
     $http_str=$http_str.'&Version=2';
     $http_str=$http_str.'&NetworkId=marktamerica';
     $http_str=$http_str.'&NetworkToken=NETPYKNAYOswzsboApxaL6GPQRiY2s';
     $http_str=$http_str.'&data[offer_id]='.$shipping_attr['Offer_ID'];
     $http_str=$http_str.'&data[advertiser_id]='.$shipping_attr['Advertiser_ID'];
     $http_str=$http_str.'&data[sale_amount]='.$Order_Amount;
     $http_str=$http_str.'&data[affiliate_id]=12';
     $http_str=$http_str.'&data[payout]='.$Commission_Amount;
     $http_str=$http_str.'&data[revenue]='.$Commission_Amount;
     $http_str=$http_str.'&data[advertiser_info]='.$order_id;
     $http_str=$http_str.'&data[affiliate_info1]='.$shop_com[1]; //RID
     $http_str=$http_str.'&data[ad_id]='.$shop_com[2]; //Click_ID
     $http_str=$http_str.'&data[session_datetime]='.$session_datetime;
     $contents = file_get_contents($http_str);
 }

2-2：失效訂單及訂單取消紀錄回傳向美安回報取消訂單資訊
由於在前一步驟訂單成立時您已將訂單紀錄回傳，但若有以下狀況發生時，則您需透過API，將訂單取消紀錄回傳給我們。由於取消訂單功能有安全性設定，因此您必須提供至少一組屆時會用來傳送取消紀錄的主機IP Address給我們。
1.此張訂單因使用者未付款造成訂單失效
2.消費者自行取消訂單
3.網站管理者取消訂單
4.日後消費者退訂訂單。
5.其他造成訂單失效的各種原因。

交易取消API網址如下：
https://api.hasoffers.com/Api?Format=json&Target=Conversion&Method=create&Service=HasOffers&Version=2&NetworkId=marktamerica&NetworkToken=NETPYKNAYOswzsboApxaL6GPQRiY2s&data[offer_id]=&data[advertiser_id]=&data[sale_amount]=&data[affiliate_id]=12&data[payout]=&data[revenue]=&data[advertiser_info]=&data[affiliate_info1]=&data[ad_id]=&data[is_adjustment]=1&data[session_datetime]=

序號	欄位名稱	形式	說明
1	Offer_ID	文字	帶入專屬Offer ID值
2	Advertiser_ID	文字	帶入專屬Advertiser_ID值
3	Refund_Amount	數字	帶入退款金額，負值
4	Commission_Amount	數字	帶入佣金金額，負值，並計算至小數點第二位計算方式為退款金額乘上佣金百分比
5	ORDER_ID	文字	帶入此訂單原始的訂單編號
6	RID	文字	帶入此訂單原始記錄到的RID
7	Click_ID	文字	帶入此訂單原始記錄到的Clicik_ID
8	Date	日期	訂單日期，格式為YYYY-MM-DD HH:mm:ss (24小時制，使用GMT-4 美國東岸時間) *請注意，日期與時間之間有一個空格，若您的程式語言無法處理空格時，建議您可用URL Encoding取代空格。

新增程式碼美安-回報取消訂單資訊

add_action( 'woocommerce_order_status_cancelled', 'report_shop_com_shipping_order_cancelled', 21, 1 );
function report_shop_com_shipping_order_cancelled( $order_id ) {
  $shop_com_str=get_post_meta( $order_id, 'shop_com', true );
  if (empty($shop_com_str)) { return; } //若非美安連結進來不處理
  $shipping_attr=shop_com_shipping_attr();
  $shop_com=explode(' ',$shop_com_str);
  if (!is_array($shop_com)) { return; }
  if (empty($shop_com[1])) { return; }
  if (empty($shop_com[2])) { return; }
  //$order_id :訂單編號
  $Order_Amount=0;
  $order = wc_get_order($order_id); 
    // Iterating through each WC_Order_Item_Product objects 
    foreach ($order->get_items() as $item_key => $item_values):     
        //## Access Order Items data properties (in an array of values) ## 
        $item_data = $item_values->get_data(); 
        $Order_Amount=$Order_Amount+(int)$item_data['total'];
    endforeach;   
  
  //$Order_Amount=(int)get_post_meta($order_id, '_order_total', true);
  $Order_Amount=(-1)*$Order_Amount; //退貨x-1
  $Commission_Amount=round($Order_Amount * $shipping_attr['revenue_rate'],2); //廣告佣金比率 
  $time=strtotime(get_the_date("Y-m-d H:i:s",$order_id)); //-3600*12; //GMT-4(標準時間-4小時)(台灣時間-12小時)美國東岸時間
  $session_datetime=gmdate("Y/m/d",$time).'%C2%A0'.gmdate("H:i:s",$time); 
  $http_str=$shipping_attr['url'];
  $http_str=$http_str.'?Format=json';
  $http_str=$http_str.'&Target=Conversion';
  $http_str=$http_str.'&Method=create';
  $http_str=$http_str.'&Service=HasOffers';
  $http_str=$http_str.'&Version=2';
  $http_str=$http_str.'&NetworkId=marktamerica';
  $http_str=$http_str.'&NetworkToken=NETPYKNAYOswzsboApxaL6GPQRiY2s';
  $http_str=$http_str.'&data[offer_id]='.$shipping_attr['Offer_ID'];
  $http_str=$http_str.'&data[advertiser_id]='.$shipping_attr['Advertiser_ID'];
  $http_str=$http_str.'&data[sale_amount]='.$Order_Amount;
  $http_str=$http_str.'&data[affiliate_id]=12';
  $http_str=$http_str.'&data[payout]='.$Commission_Amount;
  $http_str=$http_str.'&data[revenue]='.$Commission_Amount;
  $http_str=$http_str.'&data[advertiser_info]='.$order_id;
  $http_str=$http_str.'&data[affiliate_info1]='.$shop_com[1]; //RID
  $http_str=$http_str.'&data[ad_id]='.$shop_com[2]; //Click_ID
  $http_str=$http_str.'&data[session_datetime]='.$session_datetime;
  $http_str=$http_str.'&data[is_adjustment]=1';
  $contents = file_get_contents($http_str);
}

3：產品銷售資料表XML檔案- 這個部分沒有有效工具要自行產生
為了提高您的產品的曝光度以及讓使用者方便搜尋，請您務必提供以下的產品銷售資料表XML檔案，我們會將您的商品資料匯入到TW.SHOP.COM中呈現。
請您依照以下格式製作XML檔案，並儲存於您的伺服器上，提供我們這個檔案的網址。若您的網址為HTTPS，請確認您的網站使用的是預設的443 PORT。
我們會將您提供的網址設定至我們的主機。當您的網站上的商品資訊有任何異動，請您再次產生一份產品資料檔，並放置於同一路徑，我們的主機會於每天自動檢查您的資料內容是否更新，並於您更新後的約24小時同步到TW.SHOP.COM。
產品銷售資料表XML檔案的格式說明說明如下。請確保每一個必填欄位的資料都須填寫，若遺漏了任一必填欄位，則該筆資料將會被略過不被匯入。當您準備檔案時，請遵循XML的格式原則，若您的欄位中需要使用特殊字元，建議使用CDATA形式呈現。也請特別留意每一個標籤的英文字母大小寫必須與文件上的說明一致。

<?xml version="1.0" encoding="utf-8"?> 
<Products> 
<Product> 
<SKU>產品編號</SKU> 
<Name>商品名稱</Name> 
<Description>產品敘述</Description> 
<URL>產品網址</URL> 
<Price>售價</Price> 
<LargeImage>圖片網址</LargeImage> 
<SalePrice>優惠價</SalePrice> 
<UPC>UPC商品條碼</UPC> 
<ISBN>ISBN書碼</ISBN> 
<MPN>零件號碼</MPN> 
<Manufacturer>製造商名稱</Manufacturer> 
<Brand>品牌名稱</Brand> 
<Category>分類</Category> 
<EAN>EAN商品條碼</EAN> 
<Condition>New</Condition> 
</Product> 
</Products>

序號	欄位名稱	形式	說明
1	SKU	C	必填，最大50字元，帶入商品編號
2	Name	C	必填，最大255字元，帶入商品名稱
3	Description	C	必填，最大4000字元，帶入商品敘述
4	URL	C	必填，最大2000字元，帶入商品頁面網址
5	Price	N	必填，最大10字元，帶入商品價格
6	LargeImage	C	必填，最大2000字元，帶入商品圖片網址請使用RGB模式的jpg或gif檔案，英文檔名
7	SalePrice	N	非必填，最大10字元，促銷價格
8	UPC	C	非必填，最大20字元，UPC商品條碼
9	ISBN	C	非必填，最大13個字元，ISBN書碼
10	MPN	C	非必填，最大50個字元，MPN零件號碼
11	Manufacturer	C	非必填，最大255個字元，製造商名稱
12	Brand	C	非必填，最大255個字元，品牌名稱
13	Category	C	必填，最大255個字元，分類名稱。您可使用貴網站的分類，亦可至TW.SHOP.COM網站選擇合適的分類。請填寫最下層分類名稱。
14	EAN	C	非必填，最大13個字元，EAN商品條碼

您所輸入的各項資料將會呈現於TW.SHOP.COM商品詳細頁面，例如：

4：加入防詐騙宣導資訊
近年網路詐騙案件頻傳，除民眾本身要提高警覺之外，內政部警政署也呼籲購物網站業者應主動於網站中加入防詐騙宣導相關資訊提醒消費者。
當美安的優惠顧客會透過TW.SHOP.COM連結至貴網站時*1，請於您網站中顯示防詐騙宣導訊息。您可以依照貴網站的美術、排版設計呈現相關資訊，但請務必確保相關文字必須清晰可閱讀。
1.訂單完成頁面：[此為雙方合作之必要功能] 當美安的優惠顧客會透過TW.SHOP.COM連結進入貴網站並完成訂單時，請於訂單完成頁面中顯示防詐騙資訊。您可參考以下內容：
「提醒您，以下都是詐騙：訂單設錯、訂單金額有誤、設成分期每月扣款、重覆訂購多筆、宅配或超商出錯、簽收單簽成簽帳單、條碼刷錯、重覆扣款。歹徒會以更改訂單要求退費給您為由，要求您操作ATM，這些都是詐騙手法。若遇可疑來電，隨時可撥打165反詐騙諮詢專線。」
2.防詐騙宣導專頁：[此為雙方合作之必要功能] 請於網站中加入宣導防詐騙相關資訊之專屬頁面。
3.網站進入頁：[此為建議選項] 當美安的優惠顧客會透過TW.SHOP.COM連結進入貴網站時，請使用新視窗顯示防詐騙資訊。並請於該視窗中增加一個關閉按鈕，將畫面顯示至消費者點下關閉按鈕為止。您可參考以下內容：
「防詐騙！我們不會要求並指示您至ATM操作。ATM只有匯款及轉帳功能，無法解除分期付款或訂單錯誤問題。隨時可撥打165反詐騙諮詢專線。」
4.發送電子郵件提醒：[此為建議選項] 定期寄送防詐騙宣導資訊給消費者。
註: *1: 當美安的優惠顧客會透過TW.SHOP.COM連結至貴網站時，我們會帶入兩個參數到貴網站，您可使用此兩個參數來判斷消費者是由TW.SHOP.COM而來。相關說明，請參考本文件第1項「擷取參數」之敘述。
更多的防詐騙相關資訊，您也可以參考內政部警政署165全民防騙網或其臉書專頁查詢
https://165.npa.gov.tw/
https://www.facebook.com/165bear/

新增程式碼美安-在客戶下訂完成顯示反詐騙資訊

add_action( 'woocommerce_thankyou', 'show_myopia_glasses_shipping_order_and_thankyou_page', 20 );
add_action( 'woocommerce_view_order', 'show_myopia_glasses_shipping_order_and_thankyou_page', 20 );
function show_myopia_glasses_shipping_order_and_thankyou_page( $order_id ){
	if(isset($_COOKIE['shop_com'])) { //美安要求顯示
		echo '<p>「提醒您，以下都是詐騙：訂單設錯、訂單金額有誤、設成分期每月扣款、重覆訂購多筆、宅配或超商出錯、簽收單簽成簽帳單、條碼刷錯、重覆扣款。歹徒會以更改訂單要求退費給您為由，要求您操作ATM，這些都是詐騙手法。若遇可疑來電，隨時可撥打165反詐騙諮詢專線。」</p>';
	}
}

新增程式碼美安-在後台訂單明細顯示美安RID,Click_ID欄位內容

/**
在後台訂單明細顯示
*/
add_action('woocommerce_admin_order_data_after_billing_address', 'show_myopia_glasses_shipping_order_after_billing', 10, 1 );
function show_myopia_glasses_shipping_order_after_billing($order){
	$shop_com_str=get_post_meta( $order->id, 'shop_com', true ); //若由美安連結進來顯示屬性
	if (!empty($shop_com_str)) {
		$shop_com=explode(' ',$shop_com_str);
		if (is_array($shop_com)) {
			echo '<p><strong>美安RID:</strong>'.$shop_com[1].'<br/><strong>Click_ID:</strong>'.$shop_com[2].'</p>';		
		}
	}
}

WordPress: 與美安系統的串接

＜文章提供＞

亞巨多媒體有限公司

亞巨多媒WordPress的架站實例

jean@aibab.tv