OPEN API Test 가이드

2-2. 다운로드 및 설치

설치프로그램은 https://www.getpostman.com/ 에서 본인의 OS 환경에 맞는 설치파일을 다운 받아 설치하면 됩니다.
Postman은 Windows, Mac, Linux 환경에서 설치하여 사용가능합니다.

Note
Postman은 쿠팡에서 제공하는 툴이 아니므로, 일반적인 설치방법만 안내하고 postman 자체의 설치 및 사용상의 정보는 제공하지 않습니다.

3. POSTMAN 환경설정(Environment)

Postman에서는 자주 사용되는 파라메터 값(API 호출에 사용되는 매개변수 값)을 Key/Value 쌍의 형태로 미리 정의해 놓고 필요시 변경하면서 사용할 수 있습니다.

본 가이드에서는 다음의 값들을 Environment에 설정해 놓고 사용하기를 권장합니다.

• vendorId : 업체 아이디(Wing 에서 확인 가능)
• OPENAPI KEY : 쿠팡 Wing에서 발급받은 Openapi Key
• SECRET KEY : 쿠팡 Wing에서 발급받은 Openapi secret Key

우측 상단의 콤보박스에서 Environment set을 변경하거나 설정할 수 있습니다.

Environment Set의 목록을 클릭하면 개별 항목을 추가하거나 변경 또는 삭제할 수 있습니다.

여기서는 Wing에서 제공되는 항목을 참고로 하여 위와 같이 구성하도록 합니다.

참고
관리하는 업체아이디나 Openapi key 정보가 한 벌인 경우 굳이 Environment를 작성하지 않고 API 호출 시 직접 입력하여도 무방합니다만, 활용하는 편이 좀 더 간편하게 API Test 정보를 구성할 수 있습니다.

4. API 테스트

여기서는 상품 목록 페이징 조회 API를 Postman을 사용하여 호출하는 방법을 알아보겠습니다.

4-1. URI & Method 입력

개발자 포탈에서 해당 API의 URI(Path)와 Method(GET/POST/PUT/DELETE 등) 을 확인합니다. 이때 Path Segment Parameter 이 URI내에 존재하는지 같이 확인합니다. 여기서는 sellerProductId가 필요합니다.

개발자 포탈에서 확인한 내용을 바탕으로 위의 이미지와 같이 API 요청을 구성합니다.

Environment 설정
앞장에서 설명한 Environment가 올바르게 지정되어있는지 확인합니다.

바인딩 파라메터(:변수명) 활용
sellerProductId 값을 URI 입력창에 바로 입력해도 되지만, 해당 값을 바꾸어가면서 테스트할 경우에는 위와 같이 ":변수명" 형식으로 URI를 구성하면 위의 그림처럼 Params 탭에서 해당 항목의 값을 key/value 형태로 입력할 수 있습니다.

4-2. Request Header 입력

API 를 호출할 때는 URI와 Method외에도 Parameter와 Header 라는 값을 전달하여야 합니다. 쿠팡의 OPENAPI는 `Authorization` 과 `X-Requeted-By` 라는 두 개의 헤더 값을 필요로 합니다.

• Authorization : API 인증 처리를 위한 HMAC 문자열 값을 전달, 4-4 절에서 다룰 Pre-Script 를 통해 동적으로 생성하여 제공가능합니다. \{\{signature\}\} 와 같은 형식으로 입력하면 pre-request script에서 생성한 값을 global variable 형태로 참조하여 전달합니다.
• X-Reqeusted-By : API 요청자 확인을 위한 vendorId, \{\{vendorId\}\} 형식으로 입력하면 Environment에 설정한 vendorId값을 자동 제공합니다.
• X-MARKET: 한국 시장을 타겟으로 하는 매장인 경우 KR을 입력하세요. 대만 시장을 타겟으로 하는 매장인 경우 TW를 입력하세요.

4-3. Request Parameter 입력

아래 예제 이미지 내의 출고지 조회 API 처럼 URI `?` 뒤에 searchType=FULL 처럼 부터는 파라메터를 `Querystring Parameter` 라고 합니다. 아래 이미지 처럼 URI 창 내에 입력된 querystring parameter는 하단 Params 탭에도 표시되며 여기서 수정한 값을 URI창에서 동시에 반영됩니다.

개발자 포탈에서 확인한 API 호출 명세에 맞게 Header와 Query String 파라메터를 입력/작성합니다.

4-4. HMAC 생성을 위한 Pre-script 작성

OPENAPI 테스트를 위해서는 HMAC(Hash-based Message Authentication Code) 문자열이 필요합니다. Postman은 pre-request script 기능을 통해 HMAC을 동적으로 생성할 수 있는데, pre-request script 코드는 아래와 같습니다.

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. Message Body 입력

API 요청 Method가 `POST`나 `PUT` 인 경우에는 파라메터를 메시지 본문에 작성해야 하는 경우가 있습니다. 이러한 파라메터를 메시지 Body라고 합니다. 상품 등록 API를 예제로 확인해 보겠습니다.

Body 탭을 선택한 후 메시지 형식을 `raw` 로 그리고 컨텐트 타입을 `JSON(aplication/json)` 으로 선택하고 개발자 포탈의 API 명세를 참고하여 Message Body를 작성합니다.

4-6. API 호출

여기까지 API 호출에 필요한 URI, Method, Header, Parameter, Message 를 모두 입력하였다면 Send 버튼을 클릭하여 실제 API 요청을 전달할 수 있습니다. 여기에 응답받은 결과값을 가지고 성공했다면, 어떤식으로 응답이 돌아오는지, 실패했다면, 어떤 전달 요청에 문제가 있었는지를 확인해 볼 수 있습니다.

정상적으로 응답이 온 경우 하단 Response 창에 응답메시지가 출력되며, HTTP 200 응답코드가 전달됩니다.

오류가 발생한 경우에는 해당 오류코드와 함께 오류 메시지가 전달됩니다.

5. API 호출 트러블 슈팅

API 서비스 개발과정에 있어서 중요한 건 Postman의 사용법을 잘 아는 것이 아니라 API 호출시 돌려받은 응답메시지를 잘 이해하는 데 있습니다.

5-1. FAQ 활용

쿠팡 개발자 포탈은 FAQ를 통해 응답메시지 이해를 위한 가이드를 제공하고 있습니다.

 자주 문의되는 질문들을 검색기능을 사용하여 쉽게 확인할 수 있으니, 문의 전 FAQ 검색을 추천드립니다.

5-2. 오류 코드 및 메시지 확인

• 4XX 오류 :
• 400 번대 오류는 대부분 API 요청 형식에 관련한 문제인 경우가 많습니다.
• 이 경우에는 오류 메시지를 잘 확인하여 올바른 정보를 입력하시면 바로 해결할 수 있는 가능성이 높습니다.
• 우선 호출 시 사용한 데이터와 개발자 포탈에서 안내한 API 명세가 일치하는지 확인하신 후 그래도 문제해결이 되지 않을 경우 "호출 전문" 과 "응답 메시지"를 첨부하여 문의해 주시면 최대한 빠르게 해결할 수 있도록 도와드리겠습니다.
• 5XX 오류 :
• 500 번대 오류는 API 응답을 위한 처리과정에서 발생하는 내부 오류인 경우가 많습니다.
• 정확한 원인 파악을 위해 "호출 전문" 과 "응답 메시지"를 첨부하여 문의해 주시면 최대한 빠르게 해결할 수 있도록 도와드리겠습니다.

6. POSTMAN 호출 및 응답메시지 확인 방법

쿠팡 OPENAPI 호출 시 발생한 문제를 문의를 통해 접수하실 때 아래 내용을 참고하여 호출 전문과 응답메시지를 함께 기재하여 접수해주시면 보다 빠른 대응이 가능합니다.

6-1. 호출 전문 제공

전송 창 우측 상단의 code 버튼을 클릭합니다.

팝업 창과 함께 호출 전문을 클립보드로 복사할 수 있습니다.

호출 전문은 여러 형태로 표시할 수 있으나 `cURL` 형식을 추천합니다.

6-2. 응답 메시지 제공

다운로드 버튼을 사용하여 json 형태로 전문을 다운받거나, 클립보드 복사버튼을 통해 본문에 붙여넣기 하는 것도 가능합니다. 그리고 http 응답코드도 같이 포함하여 전달해주시면 됩니다.