close
프로필 배경
프로필 로고

BetaMan의 공사장

SW/Joom API · 2021. 11. 21. fullscreen 넓게보기

[Joom API v2] 3. Product

728x90
반응형

joom

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

Joom for Merchants API

Joom for Merchants API Joom for Merchants is a service for sellers working on Joom. This service allows merchants to manage their inventory and fulfill...

docs.merchant.joom.com

Product Entity는 Joom에서 판매되는 항목을 의미합니다. 각 Product에는 다양한 크기와 색상으로 구성된 다양한 Variation이 있을 수 있습니다. 각 Product에는 하나 이상의 Variation이 있습니다. Product가 아닌 Product Variation은 User들이 구매합니다. 각 Product에는 여러 관련 SKU가 포함되어있습니다.

Joom API를 사용하여 Product를 만들고 업데이트 할 수 있습니다. 하나 이상의 Product를 검색 할 수도 있습니다.

다음은 Product를 구성하는 파라미터입니다

Product 파라미터

id (type: string, 필수):

  • Joom에 등록된 Product의 ID

parent_sku (type: string, 필수):

  • 귀하의 시스템에 등록된 Product 별로 사용하는 고유식별자입니다. 특히 이 식별자를 사용하여 제품에 추가 Variation을 추가할 수 있습니다.
  • 이 파라미터가 지정되지 않은 경우 부모의 SKU Variation을 사용하지만, 항상 이 파라미터를 지정하는 것이 좋습니다.

brand (type: string):

  • Product의 브랜드 또는 제조업체

description (type: string):

  • 일반 텍스트로 해석되는 Product에 대한 설명입니다
    (HTML 마크업이 적용되지 않습니다.)
  • \n 이스케이프 문자를 사용하여 줄바꿈을 사용할 수 있습니다. 총 길이는 4,000자로 제한되며 초기 검색 페이지에는 처음 250자까지만 표시됩니다.
  • 상점 정책, 기타 상점 별 언어 또는 여러 행에 대한 세부사항을 포함하지 마십시오. 크기, 핏, 치수 등에 대한 정보는 의류 품목에 유용합니다.
  • 좋은예: “이 드레스 셔츠는 면 100%이며 정 사이즈입니다.”
    나쁜예: “이 <b>드레스 셔츠</b>는 100% 면이며 <i>정 사이즈</i>입니다.”

extra_images (type: string):

  • Product의 추가사진 URL입니다. 이미지가 있는 페이지가 아니라 이미지에 대한 URL을 직접 링크하세요. main_image 파라미터와 동일한 형식 및 크기 요구 사항, | 문자로 구분하여 하나 이상의 추가 이미지를 지정할 수 있습니다.

landing_page_url (type: string):

  • Product 상세 페이지의 URL

main_image (type: string, 필수):

  • Product 기본 이미지의 URL입니다. 이미지가 있는 페이지가 아니라 이미지에 대한 URL을 직접 링크하세요.
  • JPEG, PNG 또는 GIF 형식을 지원합니다. 이미지 내에 회사 로고, 이름, 홍보 또는 기타 식별 텍스트를 포함시키지 마십시오. 이미지 크기는 최소 550 x 550 px 이어야 합니다. 절대 “image not found” 이미지의 URL을 포함시키지 마십시오.

name (type: string, 필수):

  • Product에 부여한 이름입니다. 다음 템플릿을 사용하여 Product 이름을 작성하십시오.
(기본 브랜드) (하위브렌드), (제품군 또는 제품명) (최대 3개의 주요속성) (일반 제품유형)
  • Product 이름은 명확하고 간결해야하며 판매되는 제품을 설명해야 합니다. 위 템플릿은 소비자가 Product를 식별하는데 도움이 됩니다.
  • 좋은예: “남성용 캐쥬얼 셔츠 네이비”, “여성용 단색 검정 드레스 바지”
    나쁜예: “최저 가격!!! 저렴한 유모차!!!”

tags (type: array[object], 필수):

  • 피드의 각 Product에 할당된 비계층적 키워드 또는 용어입니다. 이러한 종류의 메타데이터는 항목을 설명하는데 도움이 되며 Joom.it에서 찾아보건 검색하여 항목을 분류하고 다시 찾을 수 있습니다.
  • 제품 당 최대 5개를 하십시오. 태그는 쉼표로 구분해야겠지만 개별 태그에 쉼표를 사용하지 마십시오. 태그를 더 많이 추가하고 태그가 정확할수록 사용자가 귀하의 제품을 찾을 가능성이 높아집니다. 제품당 허용되는 태그는 최대 10개입니다.
  • 좋은예: “셔츠, 남성용 패션, 네이비, 블루, 캐주얼, 의류”, “여성용 패션, 보석 및 시계”, “남성용 패션, 수트, 마피아, 실크 타이, 타이”
    나쁜예: “재고 품목”, “저렴한 싸구려”
  • 하위 파라미터:
    Tag (type: object):
    — id (type: string)
    — name (type: string)

dangerous_kind (type: string):

  • 위험한 Product를 나타내는 파라미터입니다. 위험 분류에 대해 해당하는 파라미터 값을 지정하고, 만약 Product가 위험하지 않다면 꼭 “notDangerous”를 파라미터 값으로 지정하세요.
  • 사용가능한 파라미터 값:
    notDangerous, liquid, battery, powder, withBattery, aerosoleAndGases, weapon, magnetizedItems, flammable, plants, teaLeafs, hair, adult, highDensity, lookAlikeWeapon, perfumes, semiLiquid

gtin (type: string):

  • Product의 GTIN(Global Trade Item Number) 코드 입니다. GTIN 코드는 8, 12, 13 또는 14 자리 “숫자”입니다. GTIN은 문자 또는 기타 문자를 포함할 수 없습니다.

date_uploaded (type: string):

  • Product가 생성된 날짜

enabled (type: boolean):

  • Product의 판매가능 상태입니다.
  • true인 경우 Product를 판매 할 수 있습니다.

is_promoted (type: string):

  • Product가 광고에 사용되는 상태입니다.
  • “True”인 경우 Product가 광고에 사용됩니다.
  • 사용 가능한 파라미터 값:
    True, False

number_saves (type: string):

  • Product가 즐겨찾기목록에 추가된 횟수

number_sold (type: string):

  • Product의 판매수

number_orders (type: integer):

  • Product의 주문수

number_refunds (type: integer):

  • Product의 환불된 주문수

refund_rate (type: number):

  • Product의 환불 비율
  • (환불비율) = (환불횟수) / (주문횟수)

number_ratings (type: integer):

  • Product의 평점

average_rating (type: number):

  • Product의 평점 평균

original_image_url (type: string):

  • Product가 생성될 때의 최초 이미지 URL

diagnosis (type: array[object]):

  • Joom이 감지한 Product의 문제 목록입니다. 선택적 파라미터는 특정 문제와 관련된 세부정보를 지정합니다.
  • 하위 파라미터:
    — code (type: string, 필수): Joom 위반 코드
    — kind (type: string, 필수): 문제의 심각도
    — description (type: string, 필수): 위반에 대한 설명
    — where (type: string): 문제를 포함한 파라미터
    — variant_id (type: string): Variant SKU (문제의 원인이 Variant인 경우)
    — variant_sku (type: string): Variant SKU (문제의 원인이 Variant인 경우)
    — index (type: string): 문제에 해당하는 문자열 또는 배열의 위치 (예: 제품 이름에서 잘못된 문자의 위치)
    — brand_id (type: string): Joom 브랜드 ID (예: 인증되지 않은 브랜드명 사용시)
    — danger_kind_by_joom (type: string): Joom이 감지한 제품 위험 종류 (예 판매자가 제공한 danerous_kind가 잘못된 경우)
    — note (type: string): 자유 형식의 선택적 메모 (예: 문제를 설명하는 중재자의 메모)

review_note (type: string):

  • Product가 거부된 것으로 표시되었을 때의 매모

review_status (type: string):

  • Product의 검토상태입니다. 이 값은 approved,pending,rejected 가 될 수 있습니다.

variants (type: array[object]):

  • Product Variation의 항목 목록
  • 하위 파라미터:
    — variant (type: object):
    — — id (type: string):     Product Variation의 Joom ID
    — — original_image_url (type: string): Product Variation이 생성될때의 최초 이미지URL
    — — product_id (type: string): Product Variation이 속한 Product의 Joom ID
    — — inventory (type: number): 이 Variation에 대한 물리적인 수량, 최대 100,000
    — — sku (type: string): 귀하의 시스템에서 이 Variation을 인식하는 특별한 식별자
    - 사용가능: “HSC0424PP”, “112123343455432”
    - 사용불가: “2”, “a”
    — — parent_sku (type: string): 새 Product Vatiation을 추가해야하는 Product의 parent_sku
    — — enabled (type: boolean): 이 Product Variation을 구매할 수 있는지 여부
    — — color (type: string): 색상 Variation, 특히 의류 또는 쥬얼리와 관련된 경우, 두가지 색상(예: “검정 및 빨강”)을 표시하려면 &(예: “검정 & 빨강”)로 색상을 분리하면 됩니다 (참고: 두 가지 다른 색상 변형을 가진 제품과 혼동하지 마십시오.)
    색상 이름은 꼭 현재 허용된 색상 리스트 안에서 사용해야합니다.
    - 사용가능: “red”, “black & blue”
    - 사용불가: “red, blue”, “black & blue & green”
    — — hs_code (type: string): HS(Harmonized System) 코드입니다. 최소 길이 6, 최대 길이 13, 패턴은 ^(\d+\.){0,3}\d+$을 준수해야 합니다.
    — — main_image (type: string): 이 Product Variation에 대한 사진의 URL입니다. Product의 다른 Product Variation에 대해 다른 사진이 있을 때 이 파라미터를 제공하십시오. 만약 이 파라미터를 사용하지 않았다면, 제공된 parent_sku에 대한 Product의 main_image를 사용할 것입니다. 이미지에 대한 직접적인 URL을 제공하십시오(이미지가 위치한 페이지의 URL이 아닙니다.)
    — — msrp (type: string): 제조사가 제안한 Variation의 소매가입니다. 이 필드는 Joom에서 strikethrough 가격으로 표시되고 제품 판매 가격보다 높게 나타나므로 권장됩니다. 이 파라미터는 꼭 추가적인 텍스트를 포함하지 않아야합니다.
    - 사용가능: “$19.00”, “19.99”
    - 사용불가:     “19.99 + S/H”
    — — price (type: string): 사용자가 하나를 구매할 때의 Variation 가격입니다.
    - 사용가능: “$19.00”, “19.99”
    - 사용불가:     “19.99 + S/H”
    — — shipping (type: string): 사용자가 하나를 구매할 때의 Variation 배송비입니다.
    - 사용가능: “$4.00”, “4.99”
    - 사용불가: “$4.99 + S/H”
    — — shipping_height (type: string): 배송물 높이는 cm 단위로 제공되어야합니다. 부동 소수점 값을 사용하여 크기를 밀리미터로 표현합니다. 높이, 길이 및 너비는 항상 하나의 요청으로 함께 설정되어야합니다.
    — — shipping_length (type: string): 배송물 길이는 cm단위로 제공되어야합니다. 부동 소수점 값을 사용하여 크기를 밀리미터로 표현합니다. 높이, 길이 및 너비는 항상 하나의 요청으로 함께 설정되어야합니다.
    — — shipping_weight (type: string): 배송물의 총 중량 (kg단위)
    — — shipping_width (type: string): 배송물 너비는 cm단위로 제공되어야합니다. 부동 소수점 값을 사용하여 크기를 밀리미터로 표현합니다. 높이, 길이 및 너비는 항상 하나의 요청으로 함께 설정되어야합니다.
    — — size (type: string): 특히 의휴, 신발 또는 쥬얼리와 관련된 Variation의 크기입니다. 숫자 또는 현재 허용되는 크기 목록에 있어야합니다.
    - 사용가능: “S”,“XXL”,“6”,“6.5”
    - 사용불가: “소형”,“S, M”
    — — declaredValue (type: string): 세관 신고 금액입니다. 이 파라미터가 비어있는 경우 price 파라미터 값이 사용됩니다.
    — — gtin (type: string): Product의 GTIN(Global Trade Item Number) 코드 입니다. GTIN 코드는 8, 12, 13 또는 14 자리 “숫자”입니다. GTIN은 문자 또는 기타 문자를 포함할 수 없습니다.

허용되는 색상이름 목록

이 파트에 대한 정보는 아래 링크를 클릭하여 공식 레퍼런스의 색상 코드 표를 참조하세요.

https://docs.merchant.joom.com/product/list-of-accepted-colors

Product 생성

POST /product/add

/product/add엔드 포인트는 새로운 Product를 생성합니다. 또한 해당 Product의 첫 번째 Variation을 생성하므로 Product에 단일 Variation이있는 경우이 엔드 포인트를 사용하여 Product와 Variation을 모두 생성 할 수 있습니다. 추가 Variation이있는 경우 /variant/add엔드 포인트를 사용하여 생성할 수 있습니다 .

이 엔드 포인트에서 main_image파라미터는 Product의 기본 이미지를 설정합니다. Variation에 대해 다른 기본 이미지를 설정하려면 variant_main_image파라미터를 사용하십시오 .

Product에 대한 여러 Variation을 만들려는 경우 이 엔드 포인트에서 첫 번째 Variation을 제공해야합니다. 그렇지 않고 /variant/add엔드 포인트을 사용하여 모든 Variation을 만드는 경우이 /product/add엔드 포인트에서 만든 Variation을 제거해야 할 수 있습니다.

Returns

성공하면, Product가 생성되고 반환됩니다. id파라미터는 할당 된 Joom Product 식별자를 얻는 데 사용할 수 있습니다.

위에서 서술한 Product 파라미터와 아래 표를 참고하여 Access Token과 Product 파라미터를 request body에 포함시키고 보냅니다.

 

Product 생성 Request 파라미터 형식

Product 생성 Response 파라미터 형식

Product 검색

GET /product

/product엔드 포인트는 지정한 상위 SKU 또는 Product 생성 시 반환된 Joom Product ID가 지정된 Product를 검색합니다.

유요한 식별자가 제공된 경우 Product Entity를 반환합니다.

 

Product 검색 Request 파라미터 형식

 

Product 검색 Respoce 파라미터 형식

Product 업데이트

POST /product/update

request에 전달 된 파라미터로 지정된 Product를 업데이트합니다. 제공되지 않은 파라미터는 변경되지 않습니다. 예를 들어 name 파라미터를 전달하면 Product 이름이 업데이트되고 다른 파라미터는 변경되지 않습니다. 이 request는 Product 파라미터만 업데이트 할 수 있습니다. 단일 Variation이있는 제품의 경우에도 Variation 파라미터를 수정할 수 없습니다.

이 request가 성공하면 HTTP 상태 코드 200이 반환되고 응답에 코드 0이 있고 데이터가 없습니다.

 

Product 업데이트 Request 파라미터 형식

 

Product 업데이트 Response 파라미터 형식

Product 활성화

POST /product/enable

/product/enable엔드 포인트는 Product와 그 Variation들을 판매할 수 있게 만들어 줍니다. 이전에 비활성화 한 경우에만 제품을 활성화하면됩니다.

이 request가 성공하면 HTTP 상태 코드 200이 반환되고 응답에 코드 0이 있고 데이터가 없습니다.

 

Product 활성화 Request 파라미터 형식

 

Product 활성화 Response 파라미터 형식

Product 비활성화

POST /product/disable

/product/disable엔드 포인트는 Product와 그 모든 Variation들을 판매할 수 없게 비활성화합니다.

이 request가 성공하면 HTTP 상태 코드 200이 반환되고 응답에 코드 0이 있고 데이터가 없습니다.

 

Product 비활성화 Request 파라미터 형식

 

Product 비활성화 Response 파라미터 형식

국가 배송 검색

GET /products/shipping

주의: 이 메소드는 URL 경로 접두사 api/v2대신 api/v3를 가지고 있습니다. 또한, Product SKU의 파라미터 이름은 parent_sku가 아니라 sku입니다.

모든 Product Variation에 대해 모든 국가의 배송비를 검색합니다.

유효한 식별자가 제공된 경우 배송비 항목이 있는 배송 Variation을 반환합니다.

일반적인 사용 사례

  1. 모든 Product Variation의 현재 배송비를 확인하려면 /products/shipping 엔드 포인트를 이용하세요.
  2. 특정 제품 변형에 대한 새 가격을 설정하려면 “국가 배송 업데이트” 엔드 포인트를 이용하세요.
 

국가 배송 검색 Request 파라미터 형식

 

국가 배송 검색 Response 파라미터 형식

Response 예시

{
  "code": 0,
  "message": "",
  "data": {
    "variants": [
      {
        "id": "1234567",
        "sku": "sku123456",
        "shippingRegions": [
          {
            "countryCode": "UA",
            "price": "10.0",
            "currency": "USD",
            "type": "default"
          },
          {
            "countryCode": "US",
            "price": "11.0",
            "currency": "USD",
            "type": "custom"
          },
          {
            "countryCode": "SA",
            "type": "joomLogistics",
            "details": {
              "minPrice": "5"
            }
          },
          {
            "countryCode": "BR",
            "type": "noShipping",
            "details": {
              "message": "delivery blocked by merchant"
            }
          }
        ]
      }
    ]
  }
}

모든 Product 나열

GET /product/multi-get

현재 Joom 플랫폼에 등록되어있는 모든 Product 목록을 반환합니다. Product 수가 많은 경우 response에 페이지가 매겨집니다. response에는 Product의 다음 페이지를 가져 오기위한 URL이 포함됩니다.

request가 성공하면 request에 Product 엔티티 목록과 paging필요한 경우 페이징 옵션이 있는 파라미터가 포함됩니다.

 

모든 Product 나열 Request 파라미터 형식

 

모든 Product 나열 Response 파라미터 형식

Product에서 추가 이미지 제거

POST /product/remove-extra-images

이렇게하면 Product에서 모든 추가 이미지가 제거됩니다. 주요 상품 이미지 및 Variation 이미지는 영향을받지 않습니다.

이 request가 성공하면 HTTP 상태 코드 200이 반환되고 응답에 코드 0이 있고 데이터가 없습니다.

 

Product에서 추가 이미지 제거 Request 파라미터 형식

 

Product에서 추가 이미지 제거 Response 파라미터 형식

728x90
반응형
저작자표시 비영리 동일조건

'SW > Joom API' 카테고리의 다른 글

[Joom API v3] 2. Products  (0) 2021.11.21
[Joom API v3] 1. Getting Started  (0) 2021.11.21
[Joom API v2] 2. Joom OAuth  (0) 2021.11.21
[Joom API v2] 1. Getting Started  (0) 2021.11.21
SW/Joom API 관련 글
더 보기

티스토리툴바