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

# API 자주 묻는 질문

## 0. API 공통 / 일반

<details>

<summary>Q. API 응답 성공/실패 확인 방법</summary>

A. 모든 API 응답에는 `result` 필드가 포함됩니다. 이 값이 `SUCCESS`인지 `FAIL`인지로 성공 여부를 판단하세요. 장애 상황에서만 5xx 응답이 내려옵니다.

```json
{
  "result": "SUCCESS",
  "data": { ... }
}
```

```json
{
  "result": "FAIL",
  "error": {
    "errorType": "NOT_FOUND",
    "message": "리소스를 찾을 수 없습니다."
  }
}
```

</details>

<details>

<summary>Q. x-api-key는 어디서 발급받나요?</summary>

A. Archisketch 대시보드에 로그인한 후 API 키를 발급받을 수 있습니다. 발급받은 키는 모든 API 요청 헤더에 포함해야 합니다.

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

{% hint style="warning" %}
`x-api-key`는 외부에 노출되지 않도록 안전하게 보관하세요.
{% endhint %}

</details>

<details>

<summary>Q. API 요청 한도가 있나요?</summary>

A. 기업당 각 API별로 요청 횟수를 제한하고 있습니다.

* 쓰기: 초당 30회 이하
* 읽기: 초당 50회 이하

초과 시 일부 요청에 대해 `TOO_MANY_REQUEST` 에러가 반환됩니다.

</details>

<details>

<summary>Q. String 파라미터의 최대 길이</summary>

A. 필드마다 다르지만 대부분 **255자** 이내입니다.

</details>

## 1. 모델링

<details>

<summary>Q. 어떤 3D 파일 형식을 지원하나요?</summary>

A. 모델링 생성 시 `multipart/form-data` 형식으로 파일을 업로드합니다. 지원 형식은 담당자에게 문의해주세요.

</details>

<details>

<summary>Q. 모델링 생성 후 렌더링 완료 여부를 어떻게 확인하나요?</summary>

A. 모델링 조회 API(`GET /api/v1/modelings/{id}`)의 `renderingStatus` 필드로 확인할 수 있습니다.

* `PENDING`: 렌더링 대기 중
* `IN_PROGRESS`: 렌더링 진행 중
* `COMPLETED`: 렌더링 완료 (`renderAsset`에 결과물이 채워집니다)
* `FAILED`: 렌더링 실패

</details>

## 2. 컴포넌트

<details>

<summary>Q. 모델링 없이 컴포넌트를 생성할 수 있나요?</summary>

A. 네, 가능합니다. `modelingId`는 선택 필드입니다. 모델링을 나중에 연결하려면 `PATCH /api/v1/components/{id}/modeling`을 사용하세요.

</details>

<details>

<summary>Q. isFinal이 무엇인가요?</summary>

A. `isFinal`은 해당 컴포넌트가 더 이상 하위 부품으로 분해되지 않는 최종 부품인지를 나타냅니다.

* `true`: 최종 부품 (더 이상 분해되지 않음)
* `false`: 하위 컴포넌트(`childComponents`)를 가질 수 있는 조합 부품

</details>

<details>

<summary>Q. Flat BOM이 무엇인가요?</summary>

A. BOM(Bill of Materials)은 제품을 구성하는 부품 목록입니다. Flat BOM은 계층 구조를 평탄화하여 모든 하위 부품을 한 번에 조회할 수 있는 형태입니다. `GET /api/v1/components/{id}/bom`으로 조회할 수 있습니다.

</details>

## 3. 상품

<details>

<summary>Q. 상품 분해(decompose)와 병합(merge)이 무엇인가요?</summary>

A.

* **분해(decompose)**: 하나의 상품을 구성 컴포넌트 단위의 개별 상품으로 분리합니다.
* **병합(merge)**: 여러 상품을 하나의 상품으로 통합합니다. 색상, 사이즈 등 옵션 키를 지정하여 옵션 구조로 묶을 수 있습니다.

</details>

<details>

<summary>Q. 상품 옵션 키(optionKey)가 무엇인가요?</summary>

A. 옵션 키는 상품의 옵션 구분 기준입니다. 예를 들어 `optionKey1`을 "색상"으로 설정하면, 각 옵션 레코드의 `optionValue1`에 "베이지", "그레이" 등의 값을 지정할 수 있습니다. 최대 5개의 옵션 키를 사용할 수 있습니다.

</details>

<details>

<summary>Q. 상품에 컴포넌트를 여러 개 연결할 수 있나요?</summary>

A. 네, 가능합니다. `components.records`에 여러 컴포넌트를 배열로 전달하거나, 상품 생성 후 `POST /api/v1/sales/{id}/options`로 옵션을 추가할 수 있습니다.

</details>

## 4. 파라메트릭 컴포넌트

<details>

<summary>Q. 일반 컴포넌트와 파라메트릭 컴포넌트의 차이가 무엇인가요?</summary>

A. 일반 컴포넌트는 고정된 형태의 3D 오브젝트입니다. 파라메트릭 컴포넌트는 너비, 높이, 색상 등의 파라미터를 사용자가 아키스케치 에디터에서 직접 조정할 수 있는 동적 컴포넌트입니다. 맞춤 가구처럼 치수를 자유롭게 변경해야 하는 경우에 사용합니다.

</details>

<details>

<summary>Q. 파라메트릭 컴포넌트도 상품(Sale)으로 등록할 수 있나요?</summary>

A. 네, 파라메트릭 컴포넌트도 일반 컴포넌트와 동일하게 상품으로 등록할 수 있습니다. `POST /api/v1/sales` 요청 시 `components.records`에 파라메트릭 컴포넌트 ID를 사용하면 됩니다.

</details>