728x90

본 포스트 시리즈는 Joom for Merchants API의 공식 레퍼런스를 번역한 문서입니다.
(출처: https://api-v3-docs.merchant.joom.com/)
Joom API v2 포스트 시리즈와는 별개의 시리즈 입니다. 읽으실때 혼동 없으시길 바랍니다

이 API 문서는 Joom for Merchants API와의 통합을 구축하는 판매자 및 개발자가 사용하기 위한 것입니다. Product 생성 및 주문 이행에 대한 모든 중요한 기본 정보를 포함하는 Joom의 웹버전에 대한 programmable한 대안입니다. 이 문서는 Joom과의 성공적인 통합에 필요한 모든 정보를 가지고 있습니다.

이 API에서 특정 정보를 찾을 수 없으면 어떻게 합니까?

판매자와 Joom의 상호작용에 대한 자세한 요구 사항 및 기타 정보는 Joom 도움말 센터를 참조하십시오. Joom 도움말 센터의 특정 부분에 대한 유용한 링크는 이 문서이 특정 부분에서 제공됩니다.

참고: Joom 도움말 센터는 일부 판매자가 여전히 이전 버전의 API를 사용하고 있기 때문에 이 문서의 이전 버전을 참조 할 수 있습니다.

이 버전의 Joom-API는 현재 최신 버전이므로 플래폼의 각 새 릴리스를 지원하기 위해 여기에 새로운 기능과 정보가 추가됩니다.

시작하기

이 섹션에서는 Joom API v3 문서를 성공적으로 사용하기 위해 알아야할 모든 기본사항과 기본원칙을 다룹니다.

request들와 response들의 형식 (인증코드와 HTTP상태 코드 정보를 포함)
오류를 보고하는 방법
Joom API v3에서 사용하는 특정 데이터 형식(예: 날짜, 가격)
Joom이 request 한도를 제한하는 방법

참고:
- 문서의 간결성을 위해 대부분의 예시에서 Authorization Header들을 생략했습니다.
- 모든 날짜 및 시간은 달리 명시되지 않는 한 항상 UTC를 기준으로 합니다.

Request

basic

이 문서의 모든 request 경로는 상대적입니다.
Joom API v3의 기본 URL은 https://api-merchant.joom.com/api/v3입니다.

샌드박스의 경우 관련 페이지를 확인하십시오
(번역자 주석: 샌드박스에 관한 레퍼런스 번역 포스트도 업로드 예정입니다
추후 올라올 해당 포스트를 참조하셔도 됩니다.)

참고: 모든 request는 HTTPS를 통해 이루어져야합니다. HTTP를 통한 모둔 호출은 거부됩니다.

Authentication

Joom은 더 나은 보안을 제공하기 위해 OAuth 2.0을 사용합니다. 누구도 먼저 자신을 인증하고 귀하의 허가를 받지 않고는 API를 통해 귀하의 데이터에 액세스 할 수 없습니다.

간단히 말해서, 이것은 Facebook / WeChat 계정으로 일부 웹사이트에 로그인하기 위해 통과하는 것과 동일한 보안 인증 프로세스입니다.

인증된 request를 하려면 Access Token을 발급받고 아래 request header에 추가하여 request를 보내십시오.

Authorization: Bearer {aceess_token}

Responses

HTTP 상태코드

이 API 는 request 성공과 실패를 나타내기 위해 전통적인 HTTP response code들을 참조합니다.

2xx 상태코드는 일반적으로 request가 성공한 것으로 간주됩니다.
4xx 상태코드는 입력에 문제가 있어 오류가 발생했다는 것을 의미합니다.
5xx 상태코드는 예기치 못한 오류가 발생했음을 의미합니다. (주로 Joom 서버측 장애와 같은 상황)

귀하의 code는 response의 일부이므로 Joom API에서 반환한 HTTP 상태코드를 올바르게 해석해야합니다. 오류 response의 경우, JSON response body에서 더 자세한 정보를 찾을 수 있습니다

Joom API가 보통 사용하는 HTTP 상태 코드:

No.	코드	의미	트러블슈팅
1	200	성공한	모든것이 잘되었습니다. response를 받으세요.
2	400	잘못된	request를 수정해야합니다. JSON response에서 오류 세부정보를 참조하세요. request 파라미터에 오류가 있거나 (예: JSON 정수 필드에 문자열을 넣은 경우) 리소스의 현재 상태와 일치하지 않는 작업을 수행하려고 할 수 있습니다. (예: 취소된 주문을 이행하려는 경우).
3	401	인증되지 않은	request에 유요한 Access Token을 제공하십시오.
4	403	금지된	액세스가 허용되지 않은 리소스에 액세스하려고 합니다. 예를 들어 판매자가의 상점 중 하나로 인증되었지만 다른 상점의 Product 또는 주문에 액세스하려하는 경우가 있습니다.
5	404	찾을 수 없는	존재하지 않는 리소스에 액세스 하려고 합니다. 예를 들어 실수로 'sku' 필드에 Joom Product ID를 기입하여 해당 SKU를 가진 Product를 찾을 수 없는 경우가 있습니다.
6	429	너무 많은 request	request 제한을 초과했습니다. 요구사항에 따라 request 제한을 구현하십시오
7	500	서버 장애	Joom 측에서 문제가 발생했습니다. 나중에 요청을 다시시도하십시오. 아마도 Joom은 이미 문제를 알고 있으며 이를 해결하기 위해 최선을 다할 것이지만 시간이 걸릴 수 있습니다. 상당한 시간 동안 여러번 재시도한 후에도 이 오류가 계속 발생하면 Joom Merchant Support에 문의하십시오.

Request ID

Joom API 관련 문제를 Joom Merchant Support에 신고할 때 해당 request에 대한 request ID를 제공하라는 요청을 받을 수 있습니다.

각 response에는 다음 header가 포함됩니다.

request-id: {request id}

reqeust ID는 라틴 문자와 숫자가 포함된 짧은 문자열이며 일반적으로 j symbol로 시작합니다. Joom 개발자가 특정 request의 문제를 디버깅하는 데 도움이 될 수 있는 reqeust의 고유 식별자입니다.

이 request ID를 request 로그에 저장하십시오 (Joom API와 상호 작용할 때 로깅을 사용하시기 바랍니다.)

참고: Joom Merchant Support에 문제를 보고할 때 request ID를 제공하지 않으면 Joom 개발자가 케이스를 조사하지 못할 수도 있습니다.

Response Schema

파일 데이터(예: PDF)를 포함하는 response을 제외하고 Joom API의 모든 response는 JSON 형식으로 제공됩니다.

모든 JSON response는 다음과 같은 최상위 필드 중 일부로 구성됩니다.

No.	이름	데이터 타입	반환하는 상황	설명
1	data	object	성공시 (해당되는 경우)	request된 response 데이터입니다
2	paging	object	성공시 (해당되는 경우)	결과 수가 request 제한을 초과하는 경우 이 파라미터는 클라이언트가 모든 결과를 수집하도록 페이징하는데 도움이 됩니다.
3	errors	array of object	오류시	request 처리 중에 발생한 오류 목록입니다.

Pagination

일부 엔드 포인트는 여러 아이템을 반환합니다. 보다 효율적인 성능을 위해 API는 각 request에서 반환되는 결과 수를 제한해야합니다.

결과 수가 너무 많은 경우 여러 request로 모든 결과를 페이징할 수 있습니다.

기본 제한은 request 당 아이템 100개입니다.
pagination이 필요한 request에서 limit 쿼리 파라미터를 통해 사용자정의 제한을 제공할 수 있습니다.
최대한도는 request 당 아이템 500개입니다. 쿼리 파라미터 limit 가 500개를 초과하더라도 response에는 500개 이하의 아이템만 포함됩니다.
결과에 페이지를 매겨야하는 경우 paging 필드가 response에 존재합니다.
paging 속성은 다음 데이터 페이지를 가져오기 위한 URL인 next 를 포함할 것입니다.
이 URL은 원래 request와 동일한 limit를 갖습니다.

예:
{
  "data": {/* results will be here */},
  "paging": {
    "next": "https://api-merchant.joom.com/api/v3/products/multi?after=after_token&limit=10"
  }
}

Pagination Response 파라미터 형식

API 오류

Joom API는 오류가 발생하면 JSON response에 특정 오류 데이터를 반환합니다.

오류 세부정보는 HTTP 상태코드 4xx (예: 400, 401, 403, 404)의 response에 유용합니다. HTTP 상태코드가 200인 response에는 오류 세부정보가 포함되지 않습니다. HTTP 상태코드가 5xx (예: 500) 인 response에는 도움이 될 수 있는 오류 세부정보가 포함되어있지 않습니다.

errors 필드

이 errors필드는 request 처리중에 발생한 오류 세부정보의 배열입니다. 대부분의 경우 오류는 하나뿐이지만 가끔 (예: 일관 처리에서) 여러 오류가 있을 수 있습니다.

errors필드가 있는 응답의 OpenAPI 스키마는 아래 표에 있습니다.

request 예제

curl https://api-merchant.joom.com/api/v3/orders/multi?updatedFrom=invalid_date

response 예제

{
   "errors": [
     {
       "code": "invalid_argument",
       "field": "updatedFrom",
       "message": "Invalid argument `updatedFrom`: expected date/time, got `invalid_date`"
     }
   ]
 }

이 request 예제에는 HTTP 상태코드 400 (잘못된 request)도 있습니다.
참고: 이 예는 실제 request가 아니라 받을 수 있는 내용의 구조를 보여줍니다.

API 오류 시 Response 파라미터 형식

데이터 형식

Date/Time

타임스탬프는 RFC3339 형식의 문자열로 표시됩니다.

예: "2006-01-02T15:04:05Z".

별도의 언급이없는 한 API의 모든 날짜와 시간은 UTC를 기준으로 합니다.

쿼리 파라미터 타임스탬프로 사용되는경우 RFC3339 형식과 그 보다 더 짧은 형식(2006-01-02T15:04:05 and 2006-01-02)을 사용할 수 있습니다.

Price

가격은 소수점 구분 기호로 점이 있는 문자열로 표시됩니다.

예: 10.3 USD 는 "10.3"로 나타내야만 합니다.

통화는 ISO 4217 code로 별도 지정됩니다.

예: "USD", "EUR", "RUB".

Request 속도 제한

개요

여기에 달리 명시되지 않는 한 속도 제한은 per minute per store입니다.
일반 속도 제한은 2000 rpm (분당 요청)입니다. 이 할당량은 여기에 구체적으로 명시된 경우를 제외하고 모든 엔드 포인트 간에 공유 됩니다.
속도 제한에 도달하면 해당 엔드 포인트는 제한 주기가 끝날 때까지 HTTP 상태코드 429 (Too Many Requests)와 함께 오류 response를 반환합니다.

사용자 지정 제한이 있는 엔드 포인트

한 번에 여러 object를 반환하는 엔드 포인트는 Joom의 서버에 더 많은 부담을 주고 덜 자주 호출해야하므로 공유 속도 제한이 50 rpm 입니다.

No.	하한이 있는 엔드 포인트
1	GET products/multi
2	GET orders/unfulfilled
3	GET orders/multi

하한이 있는 엔드 포인트

Response Headers

각 API response에는 현재 속도 제한 상태를 보여주는 다음 header가 포함되어있습니다.

No.	Header 이름	설명
1	X-Rate-Limit-Limit	분 당 허용되는 request 수 입니다.
2	X-Rate-Limit-Reset	현재 제한 기간이 끝날 때까지 남은 시간(초)입니다.
3	X-Rate-Limit-Remaining	현재 제한 창에 남아있는 request 수 입니다. 한게에 도달하면 0입니다.

현재 속도 제한 상태를 보여주는 API response headers