# 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>


---

# 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-1.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.