Coupang Open API 測試指南

Coupang 為賣家的商業成功提供了各種開放 API。然而，對於不熟悉 IT 服務開發的賣家來說，可能很難知道從哪裡開始。一般來說，利用API進行業務開發流程如下：

• 步驟 1：檢查並了解 API 規範
  • Coupang 在開發者入口網站（http://developers.coupang.com）中提供了我們可以提供的所有 API 規格。
  • 首先，需要檢查提供了哪些 API，需要哪些資料以及網站提供了哪些資料。
• 步驟2：基於訊息的開放API呼叫測試
  • 查看API規範後，需要基於HTTP訊息呼叫API。
  • 在這個過程中，您可以了解如何編寫訊息資料並了解 API 的實際工作原理。
  • 透過這個過程，您將獲得識別基於程式碼實作 API 呼叫服務時可能遇到的各種問題的經驗。
• 步驟3: 開發實際的API呼叫程式碼
  • Coupang不僅提供API規範，還提供各種工程語言的實作範例。
  • 在此基礎上開發API呼叫服務。
  • 這一步驟可以透過對比檢查開放式API呼叫測試來判斷這一步的問題是開發錯誤還是資料組件問題。

這裡以免費軟體Postman為例，介紹基於訊息的開放API的呼叫方法。

1. 發行OPENAPI Key

若要使用 Coupang 開放 API，您必須註冊成為賣家並從賣家入口網站 WING 取得開放 API 金鑰。要註冊成為賣家，您需要一個營業執照號碼。請參閱此處以了解更詳細的流程。

2. 安裝 POSTMAN

2-1. Postman?

Postman 是一款免費的 API 測試工具，提供直覺、方便的使用者介面和功能。付費版本也提供協作功能。

2-2. 下載並安裝

請從 https://www.getpostman.com/ 下載並設定適合您作業系統的安裝程式。您可以在 Windows、Mac 和 Linux 上安裝和使用 Postman。

Note
由於 Coupang 不提供 Postman，我們僅提供有關如何設定的一般信息，而不提供有關 Postman 的整體信息。

3. 設定Postman環境

您可以預先在Postman中以鍵/值對的形式定義經常使用的參數（用於API呼叫的參數），並在必要時變更使用它們。

在本指南中，我們建議在環境中設定以下值以使用它們。

• vendorId ：供應商ID（您可以在Wing上查看）
• OPENAPI KEY : Coupang Wing 頒發的 Openapi 金鑰
• SECRET KEY : Coupang Wing 頒發的 Openapi secret key

您可以從右上角的組合框變更或設定環境。

如果您按一下環境設定列表，您可以新增、變更或刪除單一項目。

這裡我們參考Wing上提供的項目進行如上配置。

Note
當供應商 ID 或 Openapi 金鑰資訊是一對時，無需建立環境，在呼叫 API 時可以自行輸入，但如果使用它，您可以更輕鬆地配置 API 測試資訊。

4. API測試

讓我們研究一下如何使用 Postman 呼叫產品清單分頁查詢 API。

4-1. 輸入 URI 和方法

從開發人員入口網站檢查 API 的 URI（路徑）和方法（GET/POST/PUT/DELETE 等），並檢查 URI 中是否存在路徑段參數。這裡，您需要sellerProductId。

根據您從開發人員入口網站檢查的內容，請按照上圖設定 API 請求。

設定環境
檢查上一章所述的環境是否正確指定。

使用綁定參數（：參數名稱）
您可以在 URI 欄位中輸入 sellerProdcutId 值，但當您測試變更值時，請使用「：參數名稱」格式設定 URI。然後，您可以在 Params 標籤中以鍵/值格式輸入值，如圖所示。

4-2. 輸入請求標頭

呼叫 API 時，不僅需要傳送 URI 和方法，還需要傳送參數和標頭值。 Coupang 開放式 API 需要兩個標頭值：「Authorization」和「X-Requested-By」。

• Authorization : 在呼叫 API 時為了進行驗證，需要 HMAC 字串，4-4 中所述的預腳本會動態建立並提供該字串。當以 \{\{signature\}\}  格式輸入參數時，預先請求腳本所建立的值以全域變數格式提供。
• X-Reqeusted-By : 用於檢查 API 請求者的 VendorId。以 \{\{vendorId\}\} 格式輸入參數時，會自動提供環境中設定的 vendorID 值。
• X-MARKET : 如果店舖是面向韓國市場，請輸入 KR。 如果店鋪是面向台灣市場，請輸入 TW。

4-3. 輸入請求參數

如下例查詢出貨地API中，'?'結尾帶有searchType=FULL的參數URI 稱為‘查詢字串參數’。如下圖所示，在 URI 視窗中輸入的查詢字串參數也會顯示在 Params 標籤中，且此處變更的值也會反映到 URI 視窗中。

根據您從開發人員入口網站檢查的 API 呼叫規格輸入標頭和查詢字串參數。

4-4. 編寫pre-script來生成 HMAC

對於 OpenAPI 測試，需要 HMAC（Hash-based Message Authentication Code）字串。 Postman 可以透過預先請求腳本功能動態建立 HMAC，如下所示：

var CLIENT_KEY = pm.environment.get('CLIENT_KEY');
var SECRET_KEY = pm.environment.get('SECRET_KEY');
var AUTH_TYPE = 'CEA algorithm=HmacSHA256';

function getPath(url) {
          var pathRegex = /.+?\:\/\/.+?(\/.+?)(?:#|\?|$)/;
          var result = url.match(pathRegex);
          return result && result.length > 1 ? result[1] : '';
}

function getQueryString(url) {
          var arrSplit = url.split('?');
          return arrSplit.length > 1 ? url.substring(url.indexOf('?')+1) : '';
}

function getAuthHeader(httpMethod, requestUrl, requestBody) {

          var requestPath = getPath(requestUrl);
          var queryString = getQueryString(requestUrl);

          var timestamp = new Date().toISOString().split('.')[0]+"Z";
          timestamp = timestamp.replace(/:/gi, "").replace(/-/gi, "").substring(2);

          var requestData = [timestamp, httpMethod, requestPath, queryString].join("");
          requestData = replaceVariables(requestData);
          var hash = CryptoJS.HmacSHA256(requestData, SECRET_KEY);
          var hmacDigest = CryptoJS.enc.Hex.stringify(hash);
          var authHeader = AUTH_TYPE + ", access-key=" + CLIENT_KEY + ', signed-date=' + timestamp + ', signature=' + hmacDigest;
          return authHeader;
}

function replaceVariables(templateString) {
          let tokens = _.uniq(templateString.match(/{{\w*}}/g))

    _.forEach(tokens, t => {
       let variable = t.replace(/[{}]/g, '')
       let value = environment[variable] || globals[variable]
       templateString = templateString.replace(new RegExp(t,'g'), value)
    });

    return templateString
}

pm.globals.set('signature', getAuthHeader(request['method'], request['url'], request['data']));

複製上述內容後，貼上到Pre-request script選項卡中，如下圖所示。

4-5. 輸入訊息正文

當API請求方式為‘POST’或‘PUT’時，有時必須在訊息體中寫入參數。此參數稱為訊息體。我們以產品註冊API為例。

選擇“Body”選項卡，訊息類型為“raw”，內容類型為“JSON(aplication/json)”，並參考開發者入口網站的 API 規格編寫訊息正文。

4-6. API 呼叫

如果您已經輸入了 API 呼叫所需的所有 URI、方法、標頭、參數和訊息，請按一下「Send」按鈕傳送 API 請求。您可以找到請求成功時回應的情況以及請求失敗時出現的問題。

當您順利收到回應時，回應訊息將列印在回應視窗中，並傳送 HTTP200 回應代碼。

當出現錯誤時，會傳送錯誤訊息以及相關錯誤代碼。

5. API呼叫故障排除

在API服務開發中重要的不是懂得如何使用Postman而是了解API呼叫回應訊息。

5-1. 利用 FAQ

Coupang 開發者入口網站透過常見問題解答提供了瞭解回應訊息的指南。

您可以使用搜尋功能尋找常見問題。在提出問題之前，請先搜尋常見問題。

5-2. 檢查錯誤代碼和訊息

• 4XX錯誤:
  • 大多數 4XX 錯誤都是 API 請求類型問題。  
  • 在這種情況下，您很可能可以輸入正確的資訊來檢查錯誤訊息來解決問題。
  • 首先，檢查您呼叫時使用的資料是否與開發者入口網站中的 API 規格相符。如果問題仍然存在，請提出問題並附上「呼叫訊息」和「回覆訊息」。我們將盡快協助解決問題。
• 5XX 錯誤 :
  • 大多數 5xx 錯誤都是在處理 API 回應內部發生的錯誤。
  • 為了準確判斷原因，請在諮詢時附上「呼叫訊息」和「回應訊息」。我們將盡快協助解決問題。

6. 如何查看 POSTMAN 呼叫和回應訊息

當您透過問題提出詢問時，如果您同時包含下面引用的呼叫訊息和回應訊息，我們可以更快地回覆您的詢問。

6-1. 提供呼叫程式碼

點選視窗右上角的程式碼按鈕

您可以將彈出視窗中的整個通話訊息複製到剪貼簿。

您可以以多種格式顯示呼叫訊息，但我們推薦“cURL”格式。

6-2.提供回應訊息

使用下載按鈕下載 json 格式的訊息。您也可以使用剪貼簿的複製按鈕將其貼上到正文。也請包含 http 回應代碼。