상품 API

상품 API는 서버용 비공개 키가 필요합니다.

Authorization: Bearer {SERVER_PRIVATE_API_KEY}
Accept: application/json

상품 목록 조회

GET /api/public/v1/products

Query parameters

이름	필수	타입	설명
page	선택	integer	페이지 번호. 기본값 1
limit	선택	integer	페이지당 개수. 기본값 20, 최대 100
status	선택	string	publish, pending, paused 등 상태 필터
category_id	선택	integer	특정 카테고리의 상품만 조회
category_ids	선택	array 또는 comma string	여러 카테고리 중 하나에 속한 상품 조회
tag_id	선택	integer	특정 태그의 상품만 조회
tag_ids	선택	array 또는 comma string	여러 태그 중 하나가 붙은 상품 조회
search	선택	string	상품명 검색

curl -X GET "https://{site_host}/api/public/v1/products?page=1&limit=20" \
  -H "Authorization: Bearer {SERVER_PRIVATE_API_KEY}" \
  -H "Accept: application/json"

상품 상세 조회

GET /api/public/v1/products/{productId}

Query parameters

이름	필수	타입	설명
language	선택	string	ko, en, ja. 기본값은 사이트 언어

상품 생성

POST /api/public/v1/products

application/json 또는 multipart/form-data로 전송합니다.

필수 필드

이름	타입	설명
title	string	상품명
category_id	integer	상품 카테고리 ID
featured_image	file 또는 string	메인 이미지. 파일, URL, data URI 가능

주요 선택 필드

이름	타입	설명
description_html	string	상품 상세 HTML
status	string	pending 또는 publish. 기본값 pending
base_price	number	기본가. 기본값 0
sale_price	number	할인가
is_on_sale	boolean	할인 여부
is_free	boolean	무료 상품 여부
requires_shipping	boolean	배송 필요 여부
is_shipping_free	boolean	무료 배송 여부
shipping_price	number	배송비
is_over_50000_free	boolean	조건부 무료배송 사용 여부. 레거시 필드명이며 free_shipping_min_purchase를 보낼 때 true로 설정합니다.
free_shipping_min_purchase	integer	조건부 무료배송 기준 금액. 유료배송과 조건부 무료배송일 때만 사용
is_extra_shipping_fee	boolean	추가 배송비 여부
is_purchase_agency	boolean	구매대행 여부
tax_type	string	과세 타입
options	array	옵션명 목록. 최대 5개이며 배열 순서가 옵션 선택 순서입니다.
variants	array	옵션 조합별 가격, 재고, SKU, 판매 여부. option1부터 옵션 개수만큼 값을 보냅니다.
no_option_sku	string	옵션 없는 상품의 관리 코드(SKU)
option_display_settings	array	옵션별 표시 방식과 표시명
option_value_display_settings	array	옵션값별 표시명, 색상, 이미지, 정렬 순서
buyer_input_options	array	구매자가 주문 전에 입력할 항목
images	array	추가 이미지 목록
related_product_ids	array	관련 상품 ID 목록
tag_ids	array	상품 태그 ID 목록. 현재 상품당 1개까지 선택 가능

최소 상품 생성 payload

아래 payload로 상품 생성을 시작할 수 있습니다.

{
  "title": "러닝 후디",
  "category_id": 11,
  "featured_image": "https://example.com/main.jpg",
  "status": "publish",
  "base_price": 39000,
  "sale_price": 29000,
  "is_on_sale": true,
  "requires_shipping": true,
  "shipping_price": 3000,
  "tag_ids": [17],
  "options": ["색상", "사이즈", "포장"],
  "variants": [
    {
      "option1": "블랙",
      "option2": "M",
      "option3": "선물 포장",
      "price": 29000,
      "stock": 10,
      "sku": "BLK-M-GIFT",
      "is_active": true
    }
  ],
  "option_display_settings": [
    {
      "attribute_index": 0,
      "display_type": "color_swatch",
      "label": "색상",
      "is_required": true
    },
    {
      "attribute_index": 1,
      "display_type": "radio",
      "label": "사이즈",
      "is_required": true
    }
  ],
  "option_value_display_settings": [
    {
      "attribute_index": 0,
      "value_text": "블랙",
      "display_label": "블랙",
      "color_hex": "#111111",
      "sort_order": 0
    }
  ],
  "buyer_input_options": [
    {
      "label": "받는 분 성함",
      "input_type": "text",
      "placeholder": "입력해주세요",
      "is_required": true,
      "max_length": 50,
      "sort_order": 0,
      "status": "active"
    }
  ]
}

핵심 규칙:

• category_id는 단일 숫자입니다.
• featured_image는 파일, URL, data URI 중 하나를 보낼 수 있습니다.
• options는 최대 5개입니다. 옵션이 없으면 options, variants를 생략하거나 빈 배열로 보냅니다.
• option_display_settings[].attribute_index와 option_value_display_settings[].attribute_index는 0부터 시작하는 options 배열의 위치입니다.
• display_type은 dropdown, radio, color_swatch 중 하나입니다. color_swatch 값은 color_hex에 #RRGGBB 형식을 사용합니다.
• variants[].is_active가 false인 옵션 조합은 보관되지만 구매 가능한 옵션으로 노출하면 안 됩니다. 보내지 않으면 true입니다.
• buyer_input_options[].input_type은 text, textarea, date, time, datetime 중 하나입니다. status는 active 또는 hidden입니다.
• 태그를 붙일 때는 tag_ids를 사용합니다.

curl -X POST "https://{site_host}/api/public/v1/products" \
  -H "Authorization: Bearer {SERVER_PRIVATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "러닝 후디",
    "category_id": 11,
    "featured_image": "https://example.com/main.jpg",
    "status": "publish",
    "base_price": 39000,
    "sale_price": 29000,
    "is_on_sale": true,
    "requires_shipping": true,
    "shipping_price": 3000,
    "tag_ids": [17],
    "options": ["색상", "사이즈"],
    "variants": [
      {
        "option1": "블랙",
        "option2": "M",
        "price": 29000,
        "stock": 10,
        "sku": "BLK-M"
      }
    ]
  }'

multipart/form-data 기준

대표 이미지를 파일 업로드로 보낼 때는 multipart/form-data를 사용합니다.

curl -X POST "https://{site_host}/api/public/v1/products" \
  -H "Authorization: Bearer {SERVER_PRIVATE_API_KEY}" \
  -H "Accept: application/json" \
  -F "title=러닝 후디" \
  -F "category_id=11" \
  -F "status=publish" \
  -F "base_price=39000" \
  -F "featured_image=@/absolute/path/main.jpg"

이미지 배열, variants, options 같은 구조화 필드는 JSON 문자열 또는 반복 필드 형태로 보낼 수 있습니다. 처음 연동은 JSON + URL 이미지 방식으로 시작하고, 파일 업로드가 필요할 때 multipart/form-data를 사용합니다.

상품 수정

PUT /api/public/v1/products/{productId}

전달한 필드만 업데이트합니다. 전달하지 않은 필드는 기존 값을 유지합니다.

curl -X PUT "https://{site_host}/api/public/v1/products/1234" \
  -H "Authorization: Bearer {SERVER_PRIVATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "러닝 후디 v2",
    "sale_price": 27000,
    "is_on_sale": true,
    "tag_ids": [17]
  }'

최소 상품 수정 payload

{
  "title": "러닝 후디 v2",
  "sale_price": 27000,
  "is_on_sale": true,
  "tag_ids": [17]
}

생성/수정 응답

상품 생성과 수정은 저장된 상품 전체가 아니라 아래 결과를 반환합니다. 최신 상품 데이터가 필요하면 이어서 GET /products/{productId}를 호출합니다.

{
  "success": true,
  "message": "Product created successfully",
  "product_id": 12001,
  "tag_ids": [17]
}

수정 규칙:

• 보내지 않은 필드는 유지됩니다.
• tag_ids: []를 보내면 태그가 제거됩니다.
• images, variants, related_product_ids, option_display_settings, option_value_display_settings, buyer_input_options를 보내면 각각 전체 교체로 처리됩니다. 비우려면 빈 배열 []을 보내고, 유지하려면 해당 필드를 생략합니다.

대표 응답 필드

필드	설명
product_id	상품 ID
title	상품명
description_html	상품 상세 HTML
category_id	상품 카테고리 ID
status	상품 상태
language	언어 코드
base_price	기본가
sale_price	할인가
is_on_sale	할인 여부
is_free	무료 상품 여부
requires_shipping	배송 필요 여부
options	옵션명 배열. 최대 5개
variants	옵션 조합 목록
variants[].is_active	해당 옵션 조합의 판매 가능 여부
no_option_sku	옵션 없는 상품의 관리 코드
option_display_settings	옵션별 표시 방식과 표시명
option_value_display_settings	옵션값별 색상, 표시명, 이미지, 정렬 설정
buyer_input_options	구매자 입력 항목 정의
featured_image	대표 이미지
images	추가 이미지
tag_ids	연결된 상품 태그 ID
related_product_ids	관련 상품 ID
created_at	생성 일시
updated_at	수정 일시

End-to-end 예시: 상품 서버 연동

1. GET /api/public/v1/product-categories/search?query=후디로 카테고리 ID를 찾습니다.
2. 자체 DB 또는 CMS에서 상품 데이터를 읽습니다.
3. 새 상품이면 POST /api/public/v1/products를 호출합니다.
4. 기존 상품이면 PUT /api/public/v1/products/{productId}를 호출합니다.
5. 응답의 product_id 또는 생성 결과 ID를 자체 시스템에 매핑 저장합니다.

오류 처리 cookbook

401 Unauthorized

• private API key 누락 또는 오타
• 서버에 저장한 private API key 값을 확인

403 Forbidden

• 해당 사이트에 접근 권한 없는 key
• 다른 사이트 key를 잘못 사용한 경우

422 Unprocessable Entity

• 잘못된 category_id
• variants/options 구조 불일치
• 이미지 필드 형식 오류

422 응답을 받으면 message와 errors를 확인하고 payload를 수정한 뒤 다시 호출합니다.