상품 등록하기

컴포넌트를 기반으로 상품을 생성하고 관리하는 방법을 안내합니다.

상품은 컴포넌트를 기반으로 구성되는 판매 단위입니다. 앞 단계에서 생성한 컴포넌트 ID를 사용하여 상품을 생성합니다.

모든 API 요청 헤더에 X-API-KEY를 포함해야 합니다. 발급 방법은 API 사용 방법을 참고하세요.

X-API-KEY: {x-api-key}

상품 생성하기

POST /api/v1/sales

1

필요한 정보 준비하기

상품을 생성할 때는 상품 기본정보와 앞 단계에서 생성한 컴포넌트 ID가 필요합니다.

필드	타입	필수	설명
info	object	✅	상품 기본정보 (아래 참고)
isPersonal	boolean	✅	개인 여부
images	array	✅	이미지 ID 목록 (빈 배열 [] 가능)
previewImage	string		대표 이미지 ID
category	object		카테고리
components	object		구성품 (컴포넌트 ID 포함)

상품 기본정보 (info)

필드	타입	필수	설명
name	string	✅	이름
translatedNames	array	✅	다국어 이름
description	array	✅	설명
tags	array	✅	태그
brandCode	string		브랜드 코드
code	string		코드
website	string		웹사이트

2

요청 보내기

POST /api/v1/sales
X-API-KEY: {x-api-key}

{
  "info": {
    "name": "소파",
    "translatedNames": [
      { "code": "en", "value": "Sofa" },
      { "code": "ko", "value": "소파" }
    ],
    "description": [
      { "code": "ko", "value": "편안한 3인용 소파입니다." }
    ],
    "tags": ["소파", "거실"],
    "brandCode": "BRAND_001"
  },
  "images": ["img_001"],
  "isPersonal": false,
  "components": {
    "options": [
      {
        "componentId": "cmp_def456",
        "optionValue1": "기본",
        "price": { "value": 350000, "unit": "KRW" }
      }
    ]
  }
}

3

응답 확인하기

{
  "result": "SUCCESS",
  "data": {
    "id": "sale_ghi789",
    "enterpriseId": "ENT_ABC123",
    "userId": "usr_xyz",
    "name": "소파",
    "translatedNames": [
      { "code": "en", "value": "Sofa" },
      { "code": "ko", "value": "소파" }
    ],
    "description": [
      { "code": "ko", "value": "편안한 3인용 소파입니다." }
    ],
    "tags": ["소파"ㅇㅇ, "거실"],
    "brandCode": null,
    "code": null,
    "website": null,
    "minPrice": { "value": 0, "unit": "KRW" },
    "categories": [],
    "previewImage": {
      "id": "img_001",
      "name": "sofa_preview",
      "url": "https://..."
    },
    "images": [],
    "components": {
      "optionKeys": ["옵션"],
      "records": [
        {
          "id": "rec_001",
          "order": 0,
          "price": { "value": 0, "unit": "KRW" },
          "options": [{ "key": "옵션", "value": "기본" }],
          "previewImage": null
        }
      ]
    },
    "createdAt": "2026-04-04T10:02:00Z",
    "updatedAt": "2026-04-04T10:02:00Z"
  }
}

상품 목록 조회하기

GET /api/v1/sales

파라미터	타입	필수	설명
offset	integer	✅	페이지 번호 (0부터 시작)
limit	integer	✅	페이지 크기 (1~100)
userId	string		사용자 ID 필터
name	string		이름 검색어
code	string		코드
sku	string		SKU
brandCode	string		브랜드 코드
categoryIds	array		카테고리 ID 목록
sortType	string		정렬 기준

GET /api/v1/sales?offset=0&limit=20&name=소파
X-API-KEY: {x-api-key}

상품 단건 조회하기

GET /api/v1/sales/{id}

GET /api/v1/sales/sale_ghi789
X-API-KEY: {x-api-key}

상품 수정하기

전체 수정

PUT /api/v1/sales/{id}

상품 생성과 동일한 Request Body 구조입니다.

기본정보만 수정

PATCH /api/v1/sales/{id}/info

PATCH /api/v1/sales/sale_ghi789/info
X-API-KEY: {x-api-key}

{
  "name": "소파 (업데이트)",
  "translatedNames": [{ "code": "ko", "value": "소파 (업데이트)" }],
  "description": [{ "code": "ko", "value": "업데이트된 설명입니다." }],
  "tags": ["소파", "거실", "3인용"]
}

상품 옵션 관리하기

상품에 색상, 사이즈 등 옵션을 추가하여 여러 컴포넌트를 하나의 Sale로 구성할 수 있습니다.

옵션 추가

POST /api/v1/sales/{id}/options

{
  "optionKey1": "색상",
  "options": [
    { "componentId": "cmp_def456", "optionValue1": "베이지" },
    { "componentId": "cmp_def789", "optionValue1": "그레이" }
  ]
}

옵션 수정

PATCH /api/v1/sales/{id}/options

옵션 추가와 동일한 Request Body 구조입니다.

옵션 가격 수정

PATCH /api/v1/sales/{id}/options/{componentId}/price

{
  "price": {
    "value": 350000,
    "unit": "KRW"
  }
}

옵션 삭제

DELETE /api/v1/sales/{id}/options

{
  "ids": ["rec_001"],
  "deleteSaleIfEmpty": false
}

deleteSaleIfEmpty를 true로 설정하면 모든 옵션 삭제 시 Sale도 함께 삭제됩니다.

상품 분해 / 병합하기

분해

POST /api/v1/sales/decompose

하나의 상품을 개별 컴포넌트 단위로 분해합니다.

{
  "saleIds": ["sale_ghi789"]
}

병합

POST /api/v1/sales/merge

여러 상품을 하나로 병합합니다.

{
  "name": "소파 통합 상품",
  "optionKey": "색상",
  "salesToMerge": [
    { "saleId": "sale_ghi789" },
    { "saleId": "sale_jkl012" }
  ]
}