Есть ситуации, когда использование товарного каталога 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"]
}