Есть ситуации, когда использование товарного каталога YML невозможно:
- Слишком много товаров в базе (больше 200 000).
- Часто появляются новые товары (в небольших количествах) и часто товары заканчиваются на складе (тоже в небольших количествах), поэтому загружать сотни тысяч товаров ради изменения нескольких сотен расточительно по трафику и ресурсам.
- Необходимо оперативно управлять наличием товаров (чаще, чем 1 раз в 3 часа).
Для этого разработан HTTP API.
Данный интерфейс имеет ограничения по отраслевым параметрам, в отличие от YML.
Лимит запросов к API (Rate Limit) ограничен 40 запросами в минуту.
Обратите внимание – загружать товары можно только после выполнения подготовительных загрузок категорий и городов:
Виды запросов
Существует три типа загрузки товаров по API:
Название операции | Тип HTTP запроса | Описание |
---|---|---|
Перезапись | POST | Загрузить новые товары и выключить все существующие в REES46 товары. |
Добавление/изменение | PUT | Добавить новые товары, не отключая существующие, либо обновить существующие. |
Синхронизация | PATCH | Синхронизировать наличие товаров. |
Удаление | DELETE | Удалить в БД REES46 товары, перечисленные в запросе (отметить как "не в наличии"). |
Если отсутствует техническая возможность отправлять запросы типа DELETE
, PUT и PATCH
, то можно отправлять запросы POST
и переменную method
в теле JSON
, равную PUT, PATCH
или DELETE
(верхний регистр).
URL запроса
Это производится через HTTP API путем отправки POST/PUT/PATCH/DELETE-запроса на http://api.rees46.com/import/products
Необходимо указать заголовок:
Content-Type: application/json
Данные отправляются в виде JSON-строки, которая является телом запроса.
Жизненный цикл запроса
- Сервер API REES46 принимает запрос.
- Выполняет первичную проверку доступа (
shop_id
,shop_secret
). Еслиshop_id
иshop_secret
не соответствуют существующим, сервер возвращает ошибку400 Bad request
. - Отправляет задачу в фоновую обработку.
- Возвращает код
204 No body
. - В случае успешной обработки фоновой задачи счетчики товаров пересчитываются в личном кабинете магазина.
- В случае ошибочной обработки фоновой задачи приходит уведомление на адрес электронной почты, указанной в личном кабинете пользователя.
Обратите внимание, что все ключи регистрозависимы.
Описание данных в запросе:
{ shop_id: '...', shop_secret: '...', items: [item1, item2, ...] }
items
- массив JSON-объектов с описанием товаров.
Пример структуры объекта товара:
{ id: '...', // String (max 64). Required name: '...', // String (max 255). Required price: ..., // Float (positive). Required oldprice: ..., // Float (positive). Optional currency: '...', // Currency code: USD, RUB, EUR. Required. url: '...', // String (URL). Required picture: '...', // String (URL). Required available: ..., // Boolean (true, false). Required categories:[...], // Array of categories IDs. Required. locations: [location_price_1, location_price_2, ...], // Array of prices in locations. See below. Optional customer_recommendations: [...], // Array of product IDs. Optional brand: '...', // String. Optional barcode: '...', // String. Optional price_margin: ...,// Integer. Optional tags: [...], // Array of strings. Optional is_child: ..., // Boolean (true, false). Optional is_fashion: ..., // Boolean (true, false). Optional is_new: ..., // Boolean (true, false). Optional fashion: { fashion_data }, // Object. See below. Optional cosmetic: { cosmetic_data }, //Object. See below. Optional book: { book_data }, //Object. See below. Optional params: [ params_data, params_data, ... ], //Array of params data. See below. Optional }
Пример вложенной структуры информации об одежде fashion
(допустимые значения параметров см. в документе Одежда, обувь, аксессуары):
{ gender: '...', // String. Required if gender is set. Not required for unisex items. sizes: [], // Array of String or Object. Optional. type: '...', // String. Required if sizes are set. }
Пример вложенной структуры информации о размере fashion
для поля sizes
если данные передаются как объект:
{ size: '...', // String. Required locations: [], // Array of String. Optional. colors: [{color: "red", picture: "https://my-store.com/product/100500/images/red.jpg"}, {color: "...", picture: "..."}, ...], // An array of objects with params of color. Optional. params: [ params_data, params_data, ... ], //Array of params data. Optional }
Пример вложенной структуры информации об одежде cosmetic
(допустимые значения параметров см. в документе Косметика и парфюмерия):
{ gender: '...', // String. Required if gender is set. Not required for unisex items. hypoallergenic: '...', // Boolean. Optional. skin: { ... }, // Object. Optional. hair: { ... }, // Object. Optional. nail: { ... }, // Object. Optional. perfume: { ... }, // Object. Optional. periodic: '...', // Boolean. Optional. professional: '...' //Boolean. Optional. }
Пример вложенной структуры информации об одежде child
(допустимые значения параметров см. в документе Детские товары):
{ gender: '...', // String. Required if gender is set. Not required for unisex items. type: '...', // String. age: { min: ..., // Float. max: ... // Float. } }
Объект "Цена и наличие в городе" показывает, что товар есть в наличии в городе и его цена отличается от базовой цены. Если цена в объекте не указана, то для указанного города будет использоваться базовая цена. Если объект "Цена и наличие в городе" указан, то во всех других городах, которые не перечислены в свойстве locations
товар будет считаться не в наличии.
{ location: '...', // String. Required price: ... // Float (positive). Optional. oldprice: ... // Float (positive). Optional. }
Пример вложенной структуры информации о книгах book (допустимые значения параметров см. в документе Книги):
{ author: '...', // String. Optional. publisher: '...', // String. Optional. series: '...', // String. Optional. year: ..., // Integer. Optional. isbn: [ ... ] // Array of strings. Optional. }
Пример вложенной структуры информации о параметрах params:
{ name: '...', // String. Required value: [...], // Array. Required unit: '...', // String. Optional }
Для цифровых значений параметра необходимо указывать поле unit, например: см, гр и т.д.
Пример структуры (POST, PUT запросы)
Ниже представлен пример с заполненными данными и пояснениями
{ // Shop key, берется в личном кабинете REES46 на экране настроек магазина "shop_id": "eehj3eu84299kg5ghw5a6743r8", // Secret key, берется в личном кабинете REES46 на экране настроек магазина "shop_secret": "pmd5362597thrgq8k256ep01t0", // Список товаров "items": [ // Товар 1 { // Идентификатор товара в магазине "id": "6335" // Название "name": "Велосипед X3", // Цена "price": 13000, // Валюта цены "currency": "RUB", // URL товара, без UTM-меток и прочих параметров отслеживания источников перехода "url": "https://myste.com/products/6335.html", // URL фотографии товара "picture": "https://mysite.com/pictures/6335.jpg", // Товар в наличии "available": true, // Массив идентификаторов категорий, в которых лежит товар (не хлебные крошки, только конечные категории) "categories": [17, 3], // Штрих-код товара "barcode": 17333838374318, // Маржинальность товара 10% "price_margin": 10, // Наличие товаров в определенных городах: доступен только в Москве и СПб "locations": [ // Есть в наличии в Москве и его цена равна базовой { "location": "msk" } // Есть в наличии в СПб и его цена отличается { "location": "spb", "price": 12500 } ], // Производитель "brand": "Marine", // Характеризующие теги "tags": ["alluninium", "sport"], // Детский велосипед "is_child": true, // Параметры товара "params": [ { "name": "интерфейс", "value": ["bluetooth", "wi-fi"] }, { "name": "энергопотребление", "value": [23], "unit": "вт" } ] }, // Товар 2 { "id": "133" "name": "Куртка красная", "price": 123000, "currency": "RUB", "url": "https://myste.com/products/133.html", "picture": "https://mysite.com/pictures/133.jpg", "available": true, "categories": [33], // Доступен только в Москве "locations": [ { "location": "msk" } ], "brand": "Racoon", "tags": ["winter", "sport"], // Это одежда "is_fashion": true "fashion": { // Мужская "gender": "m", // В размерах 48, 50, 52 российской размерной сетки "sizes": [48, 50, 52] // Тип: куртка "type": "jacket" } } ] }
Рекомендуется отправлять не более 5000 товаров в одном запросе.
Особенности отправки DELETE запроса
При отправке запроса типа DELETE (удаление товаров из базы REES46) достаточно перечислить идентификаторы товаров, которые необходимо удалить. Пример:
{ "shop_id": "eehj3eu84299kg5ghw5a6743r8", "shop_secret": "pmd5362597thrgq8k256ep01t0", "items": ["635", "3373", "75778"] }
Особенности отправки PATCH запроса
При отправке запроса типа PATCH (синхронизация наличия товаров в базе REES46) достаточно перечислить идентификаторы товаров, которые необходимо пометить как "в наличии".
TIP
Товары из текущей базы данных REES46, идентификаторы которых не включены в PATCH запрос, будут помечены как "не в наличии".
Пример:
{ "shop_id": "eehj3eu84299kg5ghw5a6743r8", "shop_secret": "pmd5362597thrgq8k256ep01t0", "items": ["635", "3373", "75778"] }