API 자주 묻는 질문

API 연동 및 사용에 대한 FAQ

0. API 공통 / 일반

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

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

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

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

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

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

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

x-api-key는 외부에 노출되지 않도록 안전하게 보관하세요.

Q. API 요청 한도가 있나요?

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

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

Q. String 파라미터의 최대 길이

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

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

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

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

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

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

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

Q. isFinal이 무엇인가요?

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

Q. Flat BOM이 무엇인가요?

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

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

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

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

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

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

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

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

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

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

Last updated 1 month ago

Was this helpful?