介紹自架購物網站如何配合美安的串接要求,一步一步完成網站與美安系統的程式串接,讓來自美安的推薦訂單,能正確的回報給美安。
在今年(2024)4月的時候,與美安有串接合作的商家,都陸續收到了美安的串接變更通知,主要是將過去以提供月報表的形式,改成線上即時串送的方式,此次的串接規格變更,不只要新增即時傳送交易資料的功能,修改程式後,美安需要再從頭測試一次系統的串接功能,程序與第一次串接大致相同,因為目前正在幫幾個商家進行串接修改工程,所以順便紀錄過程來分享給有興趣與美安串接的自架購物網站,不管你是美安現有的合作商家,或是未來計畫與美安進行串接合作,這些作業程序都是相同的。
如果尚未架設網站,但想要有一個串接美安的購物網站,我認為 OpenCart 開源架站系統是一個很好的選擇,雖然 OpenCart 系統並無內建美安串接的功能,但是 OpenCart 系統的功能擴充或修改都相當的容易,稍微具有程式能力的人就能幫 OpenCart 加上美安串接的功能,稍後的文章內容,我也會提供 OpenCart 串接美安的細節介紹。
![](https://blog.ntcart.com/wp-content/uploads/2024/05/image-7.png)
串接美安步驟一
即使你是現有的美安串接商家,仍需要重新填寫下貴公司基本資料,美安會在 5 個工作日內審查資料,若資料沒問題,則會在 5 日內回覆並提供一組新的 Offer_ID 與 Advertiser_ID,雖然舊的串接規格也有 Offer_ID 與 Advertiser_ID,但美安會發給一組全新的,記得修改現有串接程式中的值。
這些基本資料由商家自行填寫即可,不過其中的佣金比例,美安強調上線後就不能再調整,所以建議花點時間精算一下。
串接美安步驟二
當步驟一完成並收到美安提供的回覆之後,美安就會要求提供步驟二的 2 的項目:
- 屆時會送出交易紀錄的主機IP,請提供所有會用來回傳訂單紀錄的IP。
- 產品資料XML,格式請參考附件1文件中的第3點敘述。
其中的主機 IP,工程師查一下就可以立即知道,無需特別提前準備,美安會把這個主機 IP,加入他們伺服器的白名單中,當網站向美安傳送訂單成立或取消的資料時,如果主機的 IP 不在白名單中,就會被美安的伺服器踢回,所以在設計這段傳送程式的時候,請記錄下美安回傳的訊息,以便在發生問題時,能檢查美安回傳的訊息內容來排除問題。
第 2 項的產品資料XML,這是需要一點時間進行開發的,而且也不會用到 Offer_ID 與 Advertiser_ID,所以建議在步驟一提供資料之後,在等待美安審查資料的期間,就可以請工程師先進行產品資料XML的產生程式,這個產品資料XML是要讓美安來撈取你網站上的商品,以便顯示在美安商城上用的,這個 XML 有一些格式上的要求,可能需要來回測試及修正,所以建議盡早開始進行,以便縮短整個串接工程的時程,至於這個產品資料XML檔的詳細格式,請自行參考美安提供的串接規格文件的附件資料。
![](https://blog.ntcart.com/wp-content/uploads/2024/06/image.png)
如果是採用 OpenCart 系統來做,可以參考內建的 Google SiteMap 這個 Feed 模組,檔案位置在 catalog\controller\extension\feed\google_sitemap.php,複製這個檔案,改成給美安要的產品資料表XML檔案使用,包含 class Name (假設將 GoogleSitemap 改為 ShopCom),以及要輸出的 $output 變數內容,改成美安文件上要求的格式,完成後,就可以從前台 https://yourdomain/index.php?route=extension/feed/shopcom 看到產品資料的輸出結果,這個網址就可以提供給美安了,讓美安每次來呼叫時,模組就即時整理出最新的商品資訊來提供,讓美安每次都可以得到網站最新的商品資料內容。
![](https://blog.ntcart.com/wp-content/uploads/2024/06/image-2.png)
產品資料表XML檔案最常見的問題是,美安要求圖檔不得含有中文,所以請檢查商品的圖檔檔名,以及存放商品圖檔的目錄,都不要含有中文字。
![](https://blog.ntcart.com/wp-content/uploads/2024/06/image-3.png)
串接美安步驟三
當您的工程師依照技術文件的說明,為您準備完成您的網站後請通知我們,我們會請夥伴商店部門為您測試網站。夥伴商店部門同仁會於您的網站中以「美安測試」的名義下測試訂單,並以email通知您。屆時請您依照信件上的指示,回覆測試訂定單的內容以及之後於TW.SHOP.COM網站上線後您網站的介紹。
請注意:此訂單為測試使用,我們不會實際付款,您亦不須實際出貨。
步驟三是工程的重點,必須依據文件將交易資料傳送給美安,由於美安會檢查傳送資料的來源 IP,所以這個傳送動作應該設計成由主機端的程式發送,而不能從用戶端的網頁傳送。
![](https://blog.ntcart.com/wp-content/uploads/2024/05/image-8.png)
由於美安對於推薦參數的要求,是直到使用者關閉瀏覽器為主,這部分在設計時可以考慮直接將 RID 和 Click_ID 存在 session 變數中,因為 session 變數的生命週期就是到使用者關閉瀏覽器為止,正好可以符合美安的需求。
以 OpenCart 系統為例,OpenCart 本身就有提供推薦機制,在程式的某處就有判斷是否連結有帶入推薦參數,並將參數存在 cookie 的功能,所以只要找到這一段程式所在的位置,在它的後方增加判斷美安參數,並存入 session 變數的一小段程式即可。
![](https://blog.ntcart.com/wp-content/uploads/2024/06/image-1.png)
上面這個位置是在 OpenCart 系統的 catalog\controller\startup\startup.php 這支檔案中,在 136 行這邊,在這段後面增加判斷是否有 RID 和 Click_ID 參數,若有就將它們存在 session 變數中,以便之後結帳時將它們寫入訂單資料中。
根據我們的經驗,美安在進行下單測試時,通常會測試 3 張訂單,在下第一張訂單之前,會先以帶有 RID 和 Click_ID 參數的網址進到網站,在進行結帳,這是一筆合格的美安推薦訂單,網站應該要能為這筆訂單,正確記錄下 RID 和 Click_ID 參數。
接著,美安會關閉瀏覽器,重新開啟新的瀏覽分頁,再以沒有帶 RID 和 Click_ID 參數的網址進到網站,進行下單,因為沒有帶 RID 和 Click_ID 參數,所以這應該不是一張合格的美安推薦訂單,訂單不應該紀錄 RID 和 Click_ID 參數,過去我曾經接手其他人開發的美安串接程式,發現他使用 cookie 來記錄 RID 和 Click_ID 參數,並且沒有控制好 cookie 的 expire 時間,造成美安在下第 2 張測試訂單時,仍會把第一張訂單進來時的 RID 和 Click_ID 參數,也記錄到第 2 張訂單去了,所以建議開發者在測試的時候,使用與美安相同的做法,關閉瀏覽器,再重新開啟瀏覽器,輸入或貼上沒有帶 RID 和 Click_ID 參數的網址進入網站下單,再檢查這張訂單是不是能濾掉前一張訂單的 RID 和 Click_ID 參數。
第 3 張訂單則是會再使用帶有 RID 和 Click_ID 參數的網址進到網站進行結帳,這應該也是一張合格的美安推薦訂單,所以美安進行完下單測試之後,應該會在網站後台看到 3 張美安下的訂單,會員或買家姓名通常是 “美安測試”,第 1 張和第 3 張是合格的美安推薦訂單,第 2 張不是,美安下完測試訂單之後,會通知商家依據 API 串接規格進行 “傳送訂單成立” 的資料到美安,透過後台訂單管理所開發的美安訂單傳送功能傳送,再將 2 張合格訂單整理訂單資料到美安提供的 Excel 檔,回覆給美安進行核對。
![](https://blog.ntcart.com/wp-content/uploads/2024/06/image-8.png)
串接美安步驟四
步驟三的測試主要為新增訂單,美安除了要測試傳送新增訂單的交易資訊以外,也會測試傳送取消訂單的交易,畢竟訂單總會有異動的時候,如果已傳送給美安的訂單,後來因故取消了,是需要將取消的資訊傳送給美安,才不會讓這筆已取消的訂單被計算了分潤。
美安下單測試之後,必須在後台將交易資料傳送給美安,同時要將美安的測試訂單資訊,包含 RID 和 Click_ID 參數,填入美安所提供的銷售月報表檔案中,並回傳給美安,讓美安檢查核對。
![](https://blog.ntcart.com/wp-content/uploads/2024/06/image-6.png)
下單是由美安人員操作的,而取消訂單是需要從商店端操作的,美安會告通過測試取消訂單,這時就需要將美安下單的測試訂單,傳送取消的交易資訊給美安,工程是可以設計成與訂單的變更連動,也可以額外設計一個傳送取消交易給美安的獨立功能。
串接美安步驟五
若訂單取消紀錄也正確回傳,則我們的所有測試即是完成。我們會將您的案件交至夥伴商店部門,由夥伴商店部門為您安排後續上線的時程。
如果步驟四也通過美安的測試,就等於完成了串接的測試,只要靜待美安後續的作業即可。
總結說明
主要的工程是第三、第四步驟,不過只要依據美安提供的文件規格製作,就算無法一次就通過測試,通常也能在來回修正幾次之後完成串接,只不過可能是美安的人員人力較為吃緊,所以有時候等待回信的時間會比較長,建議可以適時撥打電話追一下進度,對加速時程就會有一些幫助。
不同的架站系統,串接的步驟都是一樣的,我們主要是協助 OpenCart 商家進行串接,如果您是採用 WordPress + WooCommerce 的系統,建議尋找 WordPress 的專家,但如果您的網站不是使用開源(Open Source)的架站系統,而是找軟體廠商專案建置開發,這可能就只能回透找原廠商,所以自架購物網站,建議還是選擇 OpenCart 或是 WordPress + WooCommerce 的開源系統比較省事。