WooCommerce Store API 實戰(二)- 用 API 買東西

前情提要:由於想要復仇鐵人賽沒有得獎的遺憾但又很懶得連續三十天寫文,於是我決定按著自己的步調每週寫一篇,主題是使用 WooCommerce Store API 來打造類似 Snipcart 的結帳流程,希望可以讓自己實際走過一次用 API 設計購物網站,並且開發出符合市場所需的購物外掛。

瀏覽商品 > 選擇規格 > 加入購物車 > 套用折價券 > 選擇運送方式 > 輸入訂購資料 > 前往第三方金流頁付款…,這個流程對有用過購物網站買過東西的你絕對不陌生,如果是使用 WooCommerce 的網站更是再熟悉也不過,但假設不靠滑鼠或觸碰點擊畫面上的按鈕有可能走完這個流程嗎?

常被朋友問到到底什麼是 API,它是一種「應用程式操作介面」,跟畫面上能看到的按鈕也就是「使用者操作介面」類似,只是一個是給程式用的一個是給使用者用的,後者的操作方法就是透過瀏覽網址 > 點擊頁面中的介面來完成任務,而程式的操作方式跟使用者一樣也是要先瀏覽網址,但差別在於根據請求的方法與傳送的參數不同,就能達成特定的行為。

聽起來很抽象?沒關係,我會以實際的購物流程來示範 Store API 要怎麼用,如果你也想跟我一起感受一下 API 的魔力可以下載 API 專用瀏覽器 Postman,用它看網頁非常酷,因為你看不到任何按鈕或圖片XD,只有一大堆文字以及符號而已,而這些就是程式需要的內容。

前置作業

我在本機準備了一個安裝 WooCommerce 6.4 以上版本的 WordPress 網站,網址是 https://wc.test ,裡面有兩個商品,一個是定價 800 元的小小兵公仔,另一個是有三種顏色的樂高金龜車,不同顏色有不同的價格,提供的付款方式為綠界信用卡與 100 元的運送費用,並且還有一組可以打九折的折價券。

一、Store API 瀏覽商品

完成前置作業後,打開 Postman,可以看到它就跟一般瀏覽器一樣有個起始畫面,點選左上角的加號就能新增一個頁籤,頁籤裡面可以看到輸入網址的文字框以及其他一堆沒看過的設定項,假設我們現在查看商品列表頁,在網址列輸入「https://wc.test/wp-json/wc/store/v1/products」就能看到所有商品,記得 https://wc.test 要換成你自己本機的網址喔:

如果要查看 ID 為 62 的小小兵公仔的商品資訊,輸入「https://wc.test/wp-json/wc/store/v1/products/62」 就能看到瀏覽結果:

可變商品也沒問題,假設我要查看紅色樂高金龜車的資訊,先在後台找到可變商品的 ID,一樣放在請求網址的最後即可:

可以看到下面的 Body 回傳了一種叫做 JSON 的格式,裡面包含了商品名稱、圖片、定價、是否在特價中、商品描述等等的所有資訊,有了這些資訊就能拿來設計使用者介面,接下來我們試著用 API 把商品加入購物車。

二、API 基礎觀念

在測試前我們先講解三個等等會遇到的概念:

HTTP 請求方法

首先你可能有注意到 Postman 瀏覽器的網址輸入列旁邊有一個 GET 的按鈕,點下去之後會出現一些不知道幹嘛用的英文單字:

這些叫做 HTTP 請求方法,也就是你告訴瀏覽器要用什麼方式來操作輸入的網址,像是 GET 就是取得,因此當我們要取得商品資訊的時候就是使用 GET 方法,如果要加入購物車就是用 POST、修改購物車的商品資料就是用 PUT、刪除購物車裡面的品項就是用 DELETE。

同一個請求網址透過不同的請求方法就會有不同的功能,而設計 API 的工程師就會根據你的請求方法來執行相對應的動作,也有 API 會設計成用不同的請求網址來表達不同的功能,像是加入購物車叫做 「https://example-store.com/api/cart/add-cart」、刪除購物車內的品項叫做 「https://example-store.com/api/cart/delete-item/」,用 add-cart、delete-cart-item 來表達功能,實際該如何用都要參考 API 的使用說明書。

而 Store API 這兩種方式都有,為了因應不同場景有不同的設計模式,像 cart 因為要處理比較多的功能,因此用不同的請求網址來區分:

或者也可以直接用 POST、PUT、DELETE 來請求 /cart/items 來新增、修改、刪除購物車內的商品內容:

傳送參數

Store API 該如何知道我們要把哪一個商品加入購物車?很簡單,把商品 ID 連同請求網址用 POST 的方法傳送過去即可,有些 API 直接把參數附加在網址後面來做傳送,像是「https://example-store.com/api/add-cart?productID=62」,但如果要傳送的參數太多這樣帶入就不方便。

還好 Store API 讓我們可以使用 JSON 的方式來整理需要傳送的參數,就如同取得商品資料的回傳結果一樣,我們只要先整理好商品 ID 與數量,就能一次傳送多個參數過去,稍後我們會用 Postman 進行實作。

隨機數 Nonce

Nonce = Number Once 也就是只使用一次的數字,在 WordPress 中常用在驗證發起 API 的請求者跟實際在瀏覽操作網頁的人是不是同一個人。理論上我們只希望讓正在瀏覽我們網站的使用者發請 API 請求,而不讓機器人或是其他惡意程式直接操作我們的 API 來做壞事。

WordPress 有一個函式叫做 wp_create_nonce() 來產出 Nonce,裡面可以帶驗證的字串,像是 Store API 就規定要用 wp_create_nonce( 'wc_store_api' ),然後在 API 中就會使用 wp_verify_nonce() 來檢查收到的 Nonce 是否正確,藉此驗證是否為同一個人發起請求,然後在請求 API 時我們會把 Nonce 一併傳送過去。

有這三個基本觀念後我們就來進行加入購物車的實作。

三、Store API 加入購物車

根據 WooCommerce 文件加入購物車的請求網址是 /cart/add-item,請求方法為 POST,需要帶入的參數有商品 ID、數量,並且要在 Header 標頭也就是 API 基本資訊的地方帶入 Nonce,我們先來產生給 Postman 用的隨機數。

在佈景主題或是任何一支外掛的主程式加入以下的勾點:

add_action(
    'init',
    function() {
        echo wp_create_nonce( 'wc_store_api' );
    }
);

然後用 Postman 先請求一次剛剛上面用過的讀取商品列表,就能在回傳結果看到一串由數字跟英文組成的隨機數:

複製好後把剛剛加的勾點註解掉,只要拿到隨機數後我們就不需要它了。接下來在 Postman 的介面中切換到 Headers 的頁籤,新增一筆 key 叫做 Nonce,然後 value 的地方貼上剛剛複製起來的隨機數:

搞定 Nonce 之後,我們還要告訴 Store API 我們要以 JSON 格式傳送參數給它,為了讓它有個心理準備,在 Nonce 下面再新增一筆 key 為 Content-Type,value 輸入 application/json,大小寫要注意:

接下來我們把請求方法跟請求網址設定好,也就是 POST 到 /cart/add-item,然後整理商品 ID 跟數量,我們先把頁籤切到 Body,然後勾選 raw,最後面的格式選擇 JSON,輸入以下內容:

{
    "id":62,
    "quantity":1
}

JSON 格式最外面的大括弧不要忘記,然後每一行一筆資料,每行用逗號分隔,有不是數字的地方要用雙引號包起來,完成以上步驟看起來會像下圖這樣:

至於該如何知道要傳送什麼參數、參數的名稱是什麼?很簡單,翻使用說明書就對了~以 Store API 加入購物車為例,有三個參數可以傳送:

需要注意的是 Type,integer 是整數,也就是你不能用 “id”:”小小兵公仔” 這樣的方式來傳送,一定要是商品 ID 的數字,Type array 是陣列,你可以傳下面這樣的參數:

{
    "id":62,
    "quantity":1,
    "variation" : [
        {
            "attribute":"可變商品屬性名稱"
        }
    ]
}

JSON 可以有很多階層延伸下去,注意有中括弧的地方代表的是陣列,每一筆陣列資料用大括弧跟逗號區分,Requried 的地方代表是否為必要傳送的參數,variation 只有在加入可變商品時才是必填,簡單商品的話就不需要。

Header 跟傳送參數都準備齊全後,按下右上角的 Send 按鈕,就能成功發出加入購物車的 API 請求,正確的話你會看到回傳的購物車資訊,失敗的話也會跟你說哪邊有問題,Store API 很貼心的回傳請求資料哪邊有誤。你可能會覺得這不是應該的嗎?但我接過太多 API 回傳一堆莫名其妙的錯誤訊息讓人摸不著頭緒 Orz…

請求加入購物車成功後會看到一大堆 JSON,找到 items 的陣列有看到小小兵就代表成功加入購物車了~

但數量 quantity 怪怪的,剛剛只加一隻怎麼出現的卻是 2?可能是我之前在測試的時候加入後忘記移掉的的,我們用 API 來修改成一個吧!要修改購物車的商品數量使用的是 POST /cart/update-item,要傳送的參數是剛剛收到的 key 跟新的數量 quantity 1,再次請求如下:

這樣就能把小小兵的商品數量改成 1 了,接下來我還想要買一台紅色的樂高金龜車,,一樣使用 POST /cart/add-item,並傳入以下參數:

{
    "id":"64",
    "quantity":1,
    "variation":[
        {
            "attribute":"顏色"
        }
    ]
}

要注意的地方是商品 ID 的欄位要提供的是可變商品的 ID 而非商品本身的 ID,然後要帶入可變商品的屬性名稱,記得這是要用「顏色」而不是「紅色」喔~

最後我們使用 GET /cart 就能查看目前購物車中有加了哪些商品以及商品數量,同時還可以看到訂單小計金額,你願意的話還可以試著用 DELETE /cart/remove-item 來刪除商品看看,這樣就能透過 Postman 來管理購物車了。

小結

我們已經學會了如何使用 Postman 來請求 Store API 讀取商品列表、商品資訊,以及使用不同的請求方式與網址來加入購物車跟修改商品資料,接下來我們會用 API 來實現結帳行為,像是使用折價券、選擇運送與付款方式,以及輸入訂購人資訊等等,我們下一篇繼續吧!

文章標籤Store API

目錄

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *

這個網站採用 Akismet 服務減少垃圾留言。進一步了解 Akismet 如何處理網站訪客的留言資料

Picture of 賴俊吾 / Oberon Lai
賴俊吾 / Oberon Lai

現為全職 WordPress 工程師,網站開發經歷 11 年,專攻前端工程與 WordPress 佈景主題、外掛客製化開發

訂閱電子報

Hi,我是 Oberon,我會固定在每週五早上發送接案心得以及與 WordPress 相關的電子報,同時也會分享一些實用的開發知識,讓你在 WordPress 的接案路上不孤單!

專注於分享 WordPress 開發、接案技巧、專案管理等自由工作者必備知識與心得

© 2024 想點創意科技有限公司

想點創意科技有限公司 | 統一編號 90516823
Designed by Hend Design | 隱私權政策

訂閱電子報

Hi,我是 Oberon,我會固定在每週五早上發送接案心得以及與 WordPress 相關的電子報,同時也會分享一些實用的開發知識,讓你在 WordPress 的接案路上不孤單!