Ответы об ошибках#

Ошибка валидации может использовать следующий формат:

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

Текст в message может различаться. Для программной логики используйте код состояния HTTP и задокументированные поля ответа.

Рекомендации по повторным попыткам и восстановлению#

• Выполняйте опрос каждые 2–5 секунд, пока задание находится в состоянии pending или running.
• Для ответов 429, 500, 502 и 503 используйте экспоненциальную задержку со случайным смещением и установите максимальное количество повторных попыток.
• Не выполняйте автоматические повторные попытки для ответов 400, 401 или 403 без исправления запроса или учетных данных.
• После 409 дождитесь, пока активное задание не перейдет в состояние completed или failed.
• Если при отправке истекло время ожидания до получения ответа, запросите конечную точку статуса перед повторной отправкой партии.
• Повторная отправка того же товара с тем же SKU безопасна, так как импорт использует поведение «создать или обновить».
• После завершения задания с ошибками отдельных товаров отправьте новую партию, включающую только товары, обработка которых завершилась ошибкой.
• После ошибки на уровне задания товары, учтенные в successCount, могли уже быть обновлены. Повторная отправка исходной партии с теми же SKU безопасна.
• Удаление могло уже вступить в силу, даже если запрос возвращает 503. Повторная попытка того же запроса на удаление безопасна.

Конечная точка статуса предназначена для отслеживания активного или последнего задания, а не для постоянного журнала импорта. Храните отправленную партию, jobId, ответы о статусе и итоговый результат в собственной системе для сверки и поддержки.

Чек-лист для рабочей среды#

• Храните Client Secret в менеджере секретов или защищенной серверной среде.
• Используйте стабильный и уникальный SKU для каждого товара.
• Отправляйте не более 500 товаров за один запрос.
• Убедитесь, что URL изображений общедоступны и остаются доступными во время обработки.
• Явно устанавливайте processImages: true только в том случае, если требуется предварительная обработка изображений и вы принимаете связанную с ней плату за обработку в размере 1 кредита за изображение. В противном случае опустите это поле или установите значение false.
• Включайте разделение изображений напольного покрытия, только установив оба значения processImages и processFloorImages в true.
• Предоставляйте name, imageUrl, productUrl, width, height и поддерживаемый productType для каждого товара.
• Если поле предоставлено, установите status в значение active, inactive, out_of_stock или invalid.
• Отправляйте размеры как положительные значения с поддерживаемой единицей измерения или опускайте единицу для использования дюймов; сохраняемые значения нормализуются в дюймы.
• Сохраняйте возвращенный jobId и сравнивайте его с последующими ответами о статусе.
• Рассматривайте completed с failedCount > 0 как частичный успех.
• Используйте постраничную навигацию по списку товаров вместо запроса неограниченного каталога.
• Для операций удаления предоставляйте ровно одно из значений: productId или sku.
• Реализуйте ограниченные повторные попытки с экспоненциальной задержкой и случайным смещением.

По вопросам учетных данных, значений для подключения, сопоставления типов товаров или постоянных проблем с интеграцией обращайтесь к вашему представителю по интеграции Ideal House.