상품 일괄 제출#

POST https://sdkapi.ideal.house/product-import/products

요청 본문#

processImages는 "true" 또는 "false" 같은 문자열이 아닌 JSON 불리언(true 또는 false)으로 보내세요. 이미지 전처리가 필요한 기존 연동은 이제 processImages: true를 명시적으로 전송해야 합니다.

상품 필드#

기존 상품 다시 가져오기#

상품 데이터를 수정하려면 POST /product-import/products로 상품을 다시 제출하세요. 상품은 shopId와 sku로 매칭됩니다. 스토어에 동일한 SKU가 이미 있으면 중복 상품을 생성하는 대신 기존 상품 레코드를 수정하며, 최신 가져오기에서 제공한 값이 name, 상품 URLs, 상태 및 치수 등의 해당 저장 값을 덮어씁니다.

일괄 가져오기 엔드포인트는 부분 수정 엔드포인트가 아닙니다. SKU가 이미 있더라도 제출하는 모든 항목은 상품 필드의 필수 규칙을 모두 충족해야 합니다.

SKU는 가져오기 식별자이며 다시 가져오기로 이름을 바꿀 수 없습니다. 다른 SKU를 제출하면 다른 상품을 생성하거나 수정합니다. SKU를 교체하려면 기존 상품을 논리적으로 삭제하고 새 SKU로 상품을 가져오세요.

이미지가 바뀌지 않아도 상품 정보는 수정됩니다. 이미지 처리는 제출할 때마다 선택할 수 있으며 필요한 경우 processImages: true를 설정하세요. 이전에 이미지 처리 없이 가져온 상품도 이 옵션을 활성화하여 다시 제출할 수 있습니다.

지원 상품 유형#

API는 아래의 정확하고 대소문자를 구분하는 productType 값을 허용합니다. 한 행에 있는 여러 이름은 동일한 Ideal House 상품 유형의 별칭입니다.

예를 들어 "Rugs", "Area Rugs" 및 "Area Rug"는 모두 유효하며 같은 상품 유형으로 처리됩니다. 위에 없는 값은 400 Bad Request를 반환합니다.

가져오기 상태#

선택 사항인 status 필드는 다음의 정확한 값을 허용합니다.

sold_out을 포함한 다른 값은 모두 400 Bad Request를 반환합니다.

가구의 경우 비활성 상태로 제출하면 상품 status: inactive를 반환합니다. 활성 상태의 제출은 unprocessed를 반환할 수 있으며 이는 아직 표시할 준비가 되지 않았다는 뜻입니다. 3D 생성이 요청되었다는 의미는 아닙니다.

가구 3D 모델 생성#

가구 3D 모델 생성은 시간이 걸리고 크레딧을 사용하므로 processImages가 true여도 상품 가져오기 중에는 수행되지 않습니다. 향후 사용자 인터페이스의 생성 기능 또는 별도의 3D 생성 API를 제공할 예정입니다. 지금 3D 모델이 필요하면 Ideal House 담당자에게 이메일로 문의해 주세요. 별도로 생성을 진행할 수 있도록 안내해 드리겠습니다.

SKU 및 수정 동작#

Ideal House는 shopId와 sku의 조합으로 상품을 식별합니다.

• 스토어에 SKU가 없으면 새 상품을 생성합니다.
• 스토어에 SKU가 이미 있으면 기존 상품을 수정합니다.

따라서 네트워크 결과가 불확실한 경우 동일한 SKU로 상품을 안전하게 다시 제출할 수 있습니다. 안정적인 SKU를 사용하고 같은 상품을 재시도할 때 새 SKU를 생성하지 마세요. 한 배치에서 같은 SKU를 두 번 이상 보내지 마세요.

이미지 요건#

• Ideal House 서버가 쿠키, 로그인 세션 또는 사용자 정의 요청 헤더 없이 URL에 접근할 수 있어야 합니다.
• 이미지를 직접 반환하는 안정적인 URL을 사용하세요.
• 가져오기 작업이 종료 상태에 도달할 때까지 원본 이미지를 사용할 수 있도록 유지하세요.
• 이미지 다운로드 또는 처리 문제는 항목별 실패로 보고됩니다.
• 바닥재 판재 이미지를 생성하려면 processImages: true와 processFloorImages: true를 모두 설정하세요.

선택적 이미지 처리 및 크레딧#

이미지 전처리는 기본적으로 비활성화되어 있습니다.

• processImages: false이거나 필드를 생략하면 활성 상품은 배경 제거, 텍스처 최적화 또는 바닥재 이미지 분할 없이 원본 이미지를 사용합니다. 상품 정보는 계속 가져오거나 수정하며 이미지 처리 크레딧은 부과되지 않습니다. 비활성 상품은 앞서 설명한 상태 규칙을 따릅니다.
• processImages: true이면 지원되는 활성 상품에 아래의 이미지 처리가 적용됩니다. 가구 3D 생성은 포함되지 않습니다.

주요 처리 동작은 다음과 같습니다.

Mural과 Wall Mural에는 벽지와 동일한 이미지 개선이 적용됩니다. 최상의 결과를 위해 온전하고 선명한 상품 이미지를 제공하세요. 러그와 일반적인 벽 장식은 흰색 또는 흰색에 가까운 배경을 사용하고 벽지 이미지는 심한 원근 왜곡을 피해야 합니다.

위의 이미지 처리는 벽지 텍스처 최적화를 포함하여 새로 처리하는 이미지당 1크레딧이 소요됩니다. 기존 처리 결과를 사용할 수 있으면 추가 처리 크레딧은 부과되지 않습니다. 이 옵션을 활성화하기 전에 충분한 크레딧을 확보하세요. 크레딧이 부족하면 이미지 처리가 진행되지 않고 상품이 unprocessed 상태로 남을 수 있습니다. 가져오기 배치가 completed라고 해서 모든 상품 이미지가 성공적으로 처리되었다고 확인되는 것은 아닙니다.

치수 요건#

API에는 별도의 치수 단위 필드가 없습니다. width는 필수입니다. 일반적으로 height도 필수이지만 바닥재 상품은 대신 length를 제공할 수 있습니다. 둘 다 있으면 length를 바닥 판재 길이로 사용합니다. 단위 없는 숫자와 숫자 문자열은 인치로 해석합니다. 문자열에는 in, ft, cm, mm 또는 m을 포함할 수 있습니다. 값이 양수 치수인지 검증한 다음 인치로 정규화하여 저장합니다. thickness는 선택 사항이며 "3-4 mm" 같은 범위도 허용하고 이를 "0.1-0.2 in"으로 정규화합니다.

dimension_display는 선택적인 표시 라벨이며 크기 검증 또는 단위 변환에 사용되지 않습니다. 고객에게 보여 줄 단위와 형식을 사용할 수 있습니다. 예: "24 in x 36 in" 또는 "26 cm x 36 cm".

요청 예제#

{
  "shopId": "shop_123",
  "processImages": false,
  "processFloorImages": false,
  "products": [
    {
      "sku": "SKU-10001",
      "name": "Gold Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
      "productUrl": "https://www.example.com/products/SKU-10001",
      "width": "24.0 in",
      "height": "36.0 in",
      "thickness": "2.0 in",
      "dimension_display": "24 in x 36 in",
      "category": "Mirror",
      "color": "Gold",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "active",
      "groupId": "mirror-series-01"
    },
    {
      "sku": "SKU-10002",
      "name": "Black Wall Mirror",
      "imageUrl": "https://cdn.example.com/products/SKU-10002.png",
      "productUrl": "https://www.example.com/products/SKU-10002",
      "width": "2 ft",
      "height": "3 ft",
      "thickness": "3-4 mm",
      "dimension_display": "2 ft x 3 ft",
      "category": "Mirror",
      "color": "Black",
      "brand": "Example Brand",
      "productType": "Wall Art",
      "status": "out_of_stock",
      "groupId": "mirror-series-01"
    }
  ]
}

cURL 예제 (이미지 처리 활성화)#

이 예제는 이미지 전처리를 명시적으로 활성화합니다. 새 배경 제거 결과에는 1크레딧이 소요됩니다.

curl --request POST \
  'https://sdkapi.ideal.house/product-import/products' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
  --header 'X-Client-Secret: <YOUR_CLIENT_SECRET>' \
  --data-raw '{
    "shopId": "shop_123",
    "processImages": true,
    "products": [
      {
        "sku": "SKU-10001",
        "name": "Gold Wall Mirror",
        "imageUrl": "https://cdn.example.com/products/SKU-10001.png",
        "productUrl": "https://www.example.com/products/SKU-10001",
        "width": 24,
        "height": 36,
        "thickness": 2,
        "dimension_display": "24 in x 36 in",
        "category": "Mirror",
        "color": "Gold",
        "brand": "Example Brand",
        "productType": "Wall Art",
        "status": "active",
        "groupId": "mirror-series-01"
      }
    ]
  }'

접수 응답#

유효한 요청은 202 Accepted를 반환합니다. 처리는 비동기로 계속됩니다.

{
  "jobId": "1930000000000000000",
  "shopId": "shop_123",
  "status": "pending",
  "totalCount": 1,
  "processedCount": 0,
  "successCount": 0,
  "failedCount": 0,
  "failures": [],
  "createdAt": "2026-07-21T06:30:00.000Z",
  "startedAt": null,
  "updatedAt": "2026-07-21T06:30:00.000Z",
  "completedAt": null,
  "error": null
}

스토어에 이미 pending 또는 running 작업이 있으면 API는 409 Conflict를 반환합니다. 현재 작업이 완료된 후 다음 배치를 제출하세요.