商品バッチの送信#

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 で安全に商品を再送信できます。固定の SKUs を使用し、同じ商品の再試行で新しい SKU を生成しないでください。同じバッチ内で同一の SKU を複数回送信しないでください。

画像の要件#

• URL は、Cookie、ログインセッション、独自のリクエストヘッダーなしで Ideal House のサーバーからアクセスできる必要があります。
• 画像を直接返す安定した 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 を返します。現在のジョブが終了するまで待ってから、次のバッチを送信してください。