# 상품 등록하기

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

모든 API 요청 헤더에 `X-API-KEY`를 포함해야 합니다. 발급 방법은 [API 사용 방법](/dev/api.md)을 참고하세요.

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

## 상품 생성하기

**POST** `/api/v1/sales`

{% stepper %}
{% step %}

### 필요한 정보 준비하기

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

| 필드           | 타입      |  필수 | 설명                               |
| ------------ | ------- | :-: | -------------------------------- |
| info         | object  |  ✅  | 상품 기본정보 ([아래 참고](#상품-기본정보-info)) |
| 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 |     | 웹사이트   |
| {% endstep %}   |        |     |        |

{% step %}

### 요청 보내기

```json
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" }
      }
    ]
  }
}
```

{% endstep %}

{% step %}

### 응답 확인하기

```json
{
  "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"
  }
}
```

{% endstep %}
{% endstepper %}

## 상품 목록 조회하기

**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  |     | 정렬 기준           |

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

## 상품 단건 조회하기

**GET** `/api/v1/sales/{id}`

```http
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`

```json
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`

```json
{
  "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`

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

### 옵션 삭제

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

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

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

## 상품 분해 / 병합하기

### 분해

**POST** `/api/v1/sales/decompose`

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

```json
{
  "saleIds": ["sale_ghi789"]
}
```

### 병합

**POST** `/api/v1/sales/merge`

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.archisketch.com/dev/api-2/3d-product-integration/product.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.