提交商品批次#

http

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

请求体#

字段	类型	必填	约束	描述
`shopId`	string	是	最多 64 个字符	由 Ideal House 提供的 Shop ID。
`products`	array	是	1–500 项	要创建或更新的商品。
`processImages`	boolean	否	默认为 `false`	适用于整个批次。设为 `true` 以处理商品图片。省略或为 `false` 时，导入商品数据并使用原始图片而不进行处理。
`processFloorImages`	boolean	否	默认为 `false`	需要 `processImages: true`。对于 Floor 商品，从 `imageUrl` 创建独立的板材图片。图片处理禁用或对其他商品类型时忽略此字段。

将 processImages 作为 JSON 布尔值（true 或 false）发送，而非 "true"（"true"）或 "false"（"false"）等字符串。需要图片预处理的现有集成现在必须显式发送 processImages: true。

商品字段#

字段	类型	必填	最大长度	描述
`sku`	string	是	120	店铺内唯一的商品标识符。相同的 SKU 会更新现有商品。
`name`	string	是	255	商品名称。
`imageUrl`	string	是	1,000	源商品图片的公共可访问 HTTP 或 HTTPS URL。
`productUrl`	string	是	1,000	商品详情页面的 HTTP 或 HTTPS URL。
`width`	string or number	是	64	商品宽度。无单位值以英寸为单位；支持的单位将转换为英寸。
`length`	string or number	否	64	商品长度。对于 Floor 商品，可提供此字段替代 `height`，并用作板材长度。
`height`	string or number	条件必填	64	商品高度。当 Floor 商品提供 `length` 时除外，否则必填。无单位值以英寸为单位。
`thickness`	string or number	否	64	商品厚度或厚度范围，提供时转换为英寸。
`dimension_display`	string	否	120	仅用于显示的尺寸文本，例如 `"24 in x 36 in"` 或 `"26 cm x 36 cm"`。
`category`	string	否	120	您目录中的商品类别。
`color`	string	否	120	商品颜色。
`brand`	string	否	120	商品品牌。
`productType`	string	是	120	下列受支持的商品类型名称之一。
`status`	string	否	—	`active`、`inactive`、`out_of_stock` 或 `invalid` 之一。默认为 `active`。
`groupId`	string	否	120	客户定义的标识符，用于分组相关商品。

重新导入现有商品#

要更新商品数据，请通过 POST /product-import/products 再次提交商品。商品通过 shopId 和 sku 匹配。当店铺中已存在相同的 SKU 时，将更新现有商品记录而非创建重复项，最新导入提供的值将覆盖相应存储的值，包括 name、商品 URLs、状态和尺寸等字段。

批量导入端点不是部分更新端点。即使 SKU 已存在，每个提交的商品也必须满足所有必填商品字段规则。

SKU 是导入标识符，无法通过重新导入重命名。提交不同的 SKU 将创建或更新不同的商品。要替换 SKU，请逻辑删除旧商品并在新的 SKU 下导入商品。

即使图片未发生变化，商品信息也会更新。图片处理在每次提交时均为可选：在需要时设置 processImages: true。先前未进行图片处理的商品可以再次提交并启用此选项。

支持的商品类型#

API 接受以下精确且区分大小写的 productType 值。同一表格行中的多个名称是同一 Ideal House 商品类型的别名。

Ideal House 商品类型	接受的 `productType` 值
壁纸	`"Wall"`、`"Wallpaper"`
地毯	`"Rugs"`、`"Area Rugs"`、`"Area Rug"`
墙艺	`"Wall Art"`
家具	`"Furniture"`
壁画	`"Mural"`、`"Wall Mural"`
贴画	`"Decals"`
地板	`"Floor"`

例如，"Rugs"、"Area Rugs" 和 "Area Rug" 均有效，被视为同一商品类型。上述列表中未列出的任何值将返回 400 Bad Request。

导入状态#

可选的 status 字段接受以下精确值：

值	含义
`active`	导入商品及其图片。如需图片处理，请设置 `processImages: true`。省略 `status` 时此为默认值。
`inactive`	跳过处理。商品以 `status: inactive` 和 `availability: inactive` 存储。
`out_of_stock`	跳过处理。商品以 `status: inactive` 和 `availability: out_of_stock` 存储。
`invalid`	跳过处理。商品以 `status: invalid` 和 `availability: invalid` 存储。

任何其他值（包括 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 超过一次。

图片要求#

URL 必须能够被 Ideal House 服务器访问，无需 cookies、登录会话或自定义请求头。
使用直接返回图片的稳定 URL。
在导入任务达到终止状态之前，请保持源图片可用。
图片下载或处理问题将作为条目级失败报告。
要创建 Floor 板材图片，请同时设置 processImages: true 和 processFloorImages: true。

可选图片处理与积分#

图片预处理默认禁用：

当 processImages: false 或未提供该字段时，活跃商品使用其原始图片，不进行背景去除、纹理优化或地板拆分。商品信息仍会导入或更新，且不收取图片处理积分。非活跃商品遵循上述状态规则。
当 processImages: true 时，受支持的活跃商品将接收如下图片处理。不包含家具 3D 生成。

主要处理行为如下：

API 商品类型	图片处理
`Wall`、`Wallpaper`	去除外圈白色边框，减少不均匀光照和阴影以改善重复铺贴效果。背景保持不透明。不保证完全无缝纹理和透视校正。
`Rugs`、`Area Rugs`、`Area Rug`	去除白色背景和周围阴影，同时保留白色或浅色地毯图案。清洁并柔化边缘，修剪空白边距，生成透明背景商品图片。
`Wall Art`（墙饰）	去除带框艺术品和不规则墙饰的周围背景。保留常规艺术品内的白色内容，并修剪空白边距，生成透明背景商品图片。

Mural 和 Wall Mural 获得与 Wall 相同的图片改进。为获得最佳效果，请提供完整、清晰的商品图片；地毯和常规墙艺应具有白色或近白色背景，墙面图片应避免严重的透视畸变。

上述图片处理每张新处理图片消耗 1 积分，包括墙面纹理优化。如果可以使用已有的处理结果，则不收取额外处理积分。启用此选项前请确保积分充足。积分不足时，图片处理将不会进行，商品可能保持 unprocessed 状态。completed 导入批次本身并不能确认每张商品图片均已成功处理。

尺寸要求#

API 没有独立的尺寸单位字段。width 为必填。height 通常必填，而 Floor 商品可改为提供 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"。

示例请求#

json

{
  "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 积分。

bash

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。处理将继续异步进行。

json

{
  "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。请在提交另一批次前等待当前任务完成。