> 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/component.md).

# 컴포넌트 등록하기

컴포넌트는 모델링을 기반으로 구성되는 부품 단위입니다. 앞 단계에서 생성한 모델링 ID를 사용하여 컴포넌트를 생성합니다. 생성된 컴포넌트 ID는 이후 [상품 생성](/guide/dev-kr/api-sdk/api-integration/3d-product-integration/product.md)에 사용됩니다.

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

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

## 컴포넌트 생성하기

**POST** `/api/v1/components`

{% stepper %}
{% step %}

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

컴포넌트를 생성할 때는 아래 정보가 필요합니다.

* **modelingId**: [모델링 등록하기](/guide/dev-kr/api-sdk/api-integration/3d-product-integration/modeling.md)에서 생성한 모델링 ID
* **dimension**: 컴포넌트의 실제 치수 (mm 또는 inch 단위)
* **translatedNames**: 다국어 이름 목록 (언어 코드 + 이름)

| 필드              | 타입      |  필수 | 설명                        |
| --------------- | ------- | :-: | ------------------------- |
| name            | string  |  ✅  | 이름                        |
| translatedNames | array   |  ✅  | 다국어 이름 목록                 |
| dimension       | object  |  ✅  | 치수 (mm/inch 단위)           |
| isFinal         | boolean |  ✅  | 최종 부품 여부                  |
| childComponents | array   |  ✅  | 자식 컴포넌트 목록                |
| codeRelations   | array   |  ✅  | 코드 관계 목록                  |
| images          | array   |  ✅  | 이미지 URL 목록 (빈 배열 `[]` 가능) |
| modelingId      | string  |     | 모델링 ID                    |
| code            | string  |     | 코드                        |
| brandCode       | string  |     | 브랜드 코드                    |
| sku             | string  |     | SKU                       |
| retailPrice     | object  |     | 소비자가                      |
| factoryPrice    | object  |     | 공장가                       |
| isPersonal      | boolean |     | 개인 라이브러리 업로드 여부           |
| category        | object  |     | 카테고리                      |
| {% endstep %}   |         |     |                           |

{% step %}

### 요청 보내기

```json
POST /api/v1/components
X-API-KEY: {x-api-key}

{
  "name": "소파",
  "translatedNames": [
    { "code": "en", "value": "Sofa" },
    { "code": "ko", "value": "소파" }
  ],
  "dimension": {
    "mm": {
      "width": 900,
      "depth": 800,
      "height": 750
    }
  },
  "isFinal": true,
  "images": ["https://..."],
  "childComponents": [],
  "codeRelations": [],
  "modelingId": "mdl_abc123"
}
```

{% endstep %}

{% step %}

### 응답 확인하기

```json
{
  "result": "SUCCESS",
  "data": {
    "id": "cmp_def456",
    "enterpriseId": "ENT_ABC123",
    "userId": "usr_xyz",
    "name": "소파",
    "translatedNames": [
      { "code": "en", "value": "Sofa" },
      { "code": "ko", "value": "소파" }
    ],
    "modelingId": "mdl_abc123",
    "isFinal": true,
    "isRaw": false,
    "dimension": {
      "mmWidth": 900,
      "mmDepth": 800,
      "mmHeight": 750,
      "inchWidth": 35.4,
      "inchDepth": 31.5,
      "inchHeight": 29.5
    },
    "previewImage": null,
    "images": [],
    "hdViewerAssets": [],
    "childComponents": [],
    "categories": [],
    "createdAt": "2026-04-04T10:01:00Z",
    "updatedAt": "2026-04-04T10:01:00Z"
  }
}
```

`data.id` 값을 저장해두세요. 다음 단계인 [상품 생성](/guide/dev-kr/api-sdk/api-integration/3d-product-integration/product.md)에 사용합니다.
{% endstep %}
{% endstepper %}

## 컴포넌트 목록 조회하기

**GET** `/api/v1/components`

| 파라미터       | 타입      |  필수 | 설명              |
| ---------- | ------- | :-: | --------------- |
| offset     | integer |  ✅  | 페이지 번호 (0부터 시작) |
| limit      | integer |  ✅  | 페이지 크기 (1\~100) |
| categoryId | string  |     | 카테고리 ID 필터      |
| name       | string  |     | 이름 검색어          |
| sortType   | string  |     | 정렬 기준           |

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

## 컴포넌트 단건 조회하기

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

```http
GET /api/v1/components/cmp_def456
X-API-KEY: {x-api-key}
```

## 컴포넌트 기본정보 수정하기

**PATCH** `/api/v1/components/{id}`

| 필드              | 타입     |  필수 | 설명     |
| --------------- | ------ | :-: | ------ |
| name            | string |  ✅  | 이름     |
| translatedNames | array  |  ✅  | 다국어 이름 |
| dimension       | object |  ✅  | 치수     |

## Flat BOM 조회하기

**GET** `/api/v1/components/{id}/bom`

컴포넌트의 BOM(Bill of Materials) 구조를 평탄화하여 조회합니다. 컴포넌트가 여러 하위 부품으로 구성된 경우 전체 구조를 한 번에 확인할 수 있습니다.

```http
GET /api/v1/components/cmp_def456/bom
X-API-KEY: {x-api-key}
```

## 에셋 업로드하기

**POST** `/api/v1/components/{id}/assets`

컴포넌트에 이미지 등 에셋 파일을 업로드합니다.

| 필드        | 타입     |  필수 | 설명    |
| --------- | ------ | :-: | ----- |
| assetType | string |  ✅  | 에셋 타입 |
| files     | array  |  ✅  | 파일 목록 |