> For the complete documentation index, see [llms.txt](https://docs.archisketch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archisketch.com/guide/dev-kr/api-sdk/api-integration/3d-product-integration/product.md).

# 상품 등록하기

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

모든 API 요청 헤더에 `X-API-KEY`를 포함해야 합니다. 발급 방법은 [API 사용 방법](/guide/dev-kr/api-sdk/how-to-use.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" }
  ]
}
```