[Joom API v2] 1. Getting Started

Joom

본 포스트 시리즈는 Joom for Merchants API의 공식 레퍼런스를 번역한 문서입니다.
(출처: https://docs.merchant.joom.com/)

Joom for Merchants API

---

Joom for Merchants는 Joom에서 작업하는 판매자를 위한 서비스입니다. 이 서비스를 통해 판매자는 Joom에서 재고를 관리하고 주문을 이행할 수 있습니다. 판매자는 아래 링크를 통해 Joom for Merchants에 액세스 할 수 있습니다.

https://merchant.joom.com/auth/signin/

Joom for Merchants

지금 읽고 있는 문서는 Joom for Merchants API에 대해 설명합니다. 이 API는 Joom for Merchants 서비스를 이용한 웹솔루션 개발에 적합한 대안입니다. 이 API를 통해 판매자는 ERP를 Joom과 통합시킬 수 있습니다.

Joom의 플랫폼은 지속적으로 진화하고 있습니다. Joom for Merchants API를 이미 사용하고 있는 경우 “What’s New” 페이지를 확인하여 최신 업데이트를 숙지하십시오.

---

Joom 판매자 플랫폼은 전자 상거래 플랫폼입니다. 판매자는 Joom에서 판매할 인벤토리(제품)을 업로드하고 관리할 수 있습니다. 이 플랫폼은 판매자가 재고를 관리하고 주문을 이행할 수 있도록 모든 기능을 갖추고 있습니다.

API 버전

본 레퍼런스는 Joom for Merchants API V2 및 최신버전을 서술합니다.

날짜/시간 형식

API의 모든 날짜와 시간은 달리 언급되지 않는 한 항상 UTC를 기반으로 합니다.

인증방식

Joom은 OAuth 2.0을 사용하여 요청을 인증합니다. 인증 방법에 대한 자세한 가이드는 설명서를 참조하세요. 모든 API request은 Access Token으로 인증되어야합니다. API request 시 Access Token을 GET 또는 POST request 의 파라미터로 제공하십시오.

No.	Parameter	Example
1	access_token	1qaz2wsx3edc4rfv5tgb

또는 Access Token을 다음 형식으로 header에 포함시킬 수 있습니다.

"Authorization: Bearer {access_token}"

모든 API request은 HTTPS를 통해 request되어야합니다. HTTP를 통한 모든 request는 거부됩니다.

Response Scheme

Joom API에서 반환된 모든 response는 동일한 Schema를 갖습니다. 이 Schema는 request 상태를 확인하고 데이터를 가져올 위치를 알 수 있는 예측 가능한 방법을 제공하기 위한 것입니다.

No.	Name	Description
1	code	API 요청에 대한 상태 코드를 나타냅니다. 0은 성공을 의미하고 다른 숫자는 실패를 의미합니다.
2	data	이 속성은 요청 된 응답 데이터를 저장합니다.
3	message	디버깅을 돕기 위해 사람이 읽을 수 있는 형태의 메세지를 저장하는 속성입니다. 일반적으로 오류 상황에만 사용됩니다.
4	paging	요청 결과 수가 요청 제한을 초과하는 경우 이 매개 변수는 모든 결과를 수집하기 위해 클라이언트가 페이징을 하는데 도움이됩니다.

예:
참고: 간결성을 위해 Access Token 및 형식이 URL에서 제거되었습니다.

{
  "code": 0,
  "data": [
    /* 요청결과가 저장되는 위치 */
  ],
  "message": "",
  "paging": {
    "next": "https://api-merchant.joom.com/api/v2/product/multi-get?start=20&limit=10",
    "prev": "https://api-merchant.joom.com/api/v2/product/multi-get?start=10&limit=10"
  }
}

API 오류

Joom API는 오류 발생시 특정 오류 데이터를 Client에 반환합니다. 파라미터 설명은 아래 표를 참조하십시오.

No.	Name	Type	Description	Example
1	code	number	발생한 오류를 나타내는 고유 번호	4001
2	type	string	사람이 읽을 수 있는 고유한 오류 표현	'not_found'
3	message	string	발생한 오류를 설명하는 메세지	'We could not find a product for id: 'aaa' '
4	data	Object	대부분 오류 상황에서는 비어있습니다

Request 예시

> curl https://api-merchant.joom.com/api/v2/order/fulfill-one
-d "tracking_provider=USPSSSSSSSSSSSSSSSSSSSSSSSSS&tracking_number=12345679&id=098765432112345678901234&access_token=an_example_access_token"

Response 예시

{
  "code": 1000,
  "data": 2003,
  "message": "Tracking provider is not one of the accepted providers on Joom"
}

HTTP 상태 코드

Joom API는 오류 발생시 특정 오류 코드를 사용하는 것뿐만 아니라 기존 HTTP 응답 코드를 준수하여 request 성공 또는 실패를 나타냅니다. 2xx 형식의 모든 response 코드는 일반적으로 성공한 것으로 간주됩니다. 상태 코드 4xx는 입력에 오류가 있음을 의미합니다. 5xx 범위의 코드는 서버에 예기치 않은 오류가 발생했음을 의미하여 우리가 망했음을 의미합니다!(?)

HTTP 상태 코드는 빠른 참조로 사용해야하지만 구체적인 세부정보를 얻으려면 response에 제공된 오류 코드를 참조하십시오.

Pagination

성능상의 이유로 Joom API는 각 request에서 반환되는 결과 수를 제한해야합니다. 이 제한은 request마다 다르지만 모든 response에서 반환되는 항목 수에는 항상 상한이 있습니다. 결과 수가 너무 많은 경우 여러 request로 모든 결과를 페이징 할 수 있습니다.

결과에 페이지를 매겨야하는 경우 paging 파라미터가 response에 존재합니다. 이 파라미터는 다음(또는 이전) 데이터 페이지를 가져오기 위한 URL을 가진 next와 prev를 포함합니다.

예:
참고: 간결성을 위해 Access Token 및 형식이 URL에서 제거되었습니다.

{
  "code": 0,
  "data": [
    /* 요청결과가 저장되는 위치 */
  ],
  "message": "",
  "paging": {
    "next": "https://api-merchant.joom.com/api/v2/product/multi-get?start=20&limit=10",
    "prev": "https://api-merchant.joom.com/api/v2/product/multi-get?start=10&limit=10"
  }
}

디버깅 방법

API 오류가 발생하면 여전히 JSON response를 반환합니다. 반환된 response에는 정확한 오류 원인에 대한 정보가 포함되어있습니다.

자세한 내용은 API Errors를 확인하세요.

request 예시 1

> curl https://api-merchant.joom.com/api/v2/order/fulfill-one
-d "tracking_provider=USPSSSSSSSSSSSSSSSSSSSSSSSSS&tracking_number=12345679&id=098765432112345678901234&access_token=an_example_access_token"

response 예시 1

{
  "code": 1000,
  "data": 2003,
  "message": "Tracking provider is not one of the accepted providers on Joom"
}

디버깅

USPSSSSSSSSSSSSSSSSSSSSSSSSS는 배송업체가 아니므로 수정하려면 USPS로 변경하세요

request 예시 2

> curl https://api-merchant.joom.com/api/v2/order/fulfill-one
-d "tracking_provider=USPS&tracking_number=12345679&id=098765432112345678901234&access_token=an_example_access_token"

response 예시 2

{
  "code": 0,
  "data": {
    "success": "True"
  },
  "message": "Your order is been processed right now!"
}