Отправка партии товаров#

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

Тело запроса#

Передавайте processImages как булево значение JSON (true или false), а не как строку, например "true" или "false". Существующим интеграциям, которым требуется предварительная обработка изображений, теперь необходимо явно передавать processImages: true.

Поля товара#

Повторный импорт существующих товаров#

Чтобы обновить данные товара, повторно отправьте его через POST /product-import/products. Товары сопоставляются по shopId и sku. Если такой SKU уже есть в магазине, существующая запись обновляется вместо создания дубликата. Значения последнего импорта перезаписывают соответствующие сохранённые значения, в том числе name, URL товара, статус и размеры.

Конечная точка пакетного импорта не является конечной точкой частичного обновления. Каждый отправленный элемент должен соответствовать всем правилам обязательных полей товара, даже если 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. В будущем мы планируем добавить действие генерации в интерфейс или предоставить отдельный API генерации 3D. Если 3D-модели нужны сейчас, напишите по электронной почте своему контактному лицу в Ideal House, чтобы мы могли организовать генерацию отдельно.

Поведение SKU и обновления#

Ideal House идентифицирует товар по комбинации shopId и sku:

• Если SKU не существует для магазина, создается новый товар.
• Если SKU уже существует для магазина, существующий товар обновляется.

Поэтому при неопределённом результате сетевого запроса безопасно повторно отправить товар с тем же SKU. Используйте стабильные SKU и не создавайте новый SKU при повторной отправке того же товара. Не отправляйте один SKU несколько раз в одной партии.

Требования к изображениям#

• Адрес URL должен быть доступен серверам Ideal House без использования файлов cookie, сеансов входа или пользовательских заголовков запроса.
• Используйте стабильный 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. Дождитесь завершения текущего задания перед отправкой другой партии.