# 컴포넌트 등록하기

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

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

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

## 컴포넌트 생성하기

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

{% stepper %}
{% step %}

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

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

* **modelingId**: [모델링 등록하기](/dev/api-2/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` 값을 저장해두세요. 다음 단계인 [상품 생성](/dev/api-2/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  |  ✅  | 파일 목록 |


---

# 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/component.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.