# Загрузка через REST API

Есть ситуации, когда использование товарного каталога YML невозможно:

  • Слишком много товаров в базе (больше 200 000).
  • Слишком большой файл XML-файл (больше 300 мегабайт).
  • Часто появляются новые товары (в небольших количествах) и часто товары заканчиваются на складе (тоже в небольших количествах), поэтому загружать сотни тысяч товаров ради изменения нескольких сотен расточительно по трафику и ресурсам.
  • Необходимо оперативно управлять наличием товаров (чаще, чем 1 раз в 3 часа).

Для этого разработан REST API.

Rate limit

Лимит запросов к API (Rate Limit) ограничен 40 запросами в минуту.

# Порядок импорта

Обратите внимание – загружать товары можно только после выполнения подготовительных загрузок категорий и городов.

Последовательность шагов:

  1. Загрузка информации о категориях.
  2. Загрузка информации о городах/локациях.
  3. Первичная загрузка всех товаров.
  4. Итеративное обновление товарного каталога по мере необходимости.

# Загрузка категорий

XML

Не используйте этот метод, если используете способ загрузки товаров через YML/XML.

Прежде, чем загружать товары, необходимо загрузить в базу данных актуальный перечень категорий. Загружайте только те категории, которые используются в товарах (и промежуточные элементы дерева категорий). Нет смысла загружать конечные элементы дерева категорий (листья), в которых нет товаров.

# Описание метода

POST https://api.rees46.com/import/categories

Необходимо указать заголовок:

Content-Type: application/json

Данные отправляются в виде JSON-строки, которая является телом запроса.

# Жизненный цикл запроса

  1. Сервер API REES46 принимает запрос.
  2. Выполняет первичную проверку доступа (shop_id, shop_secret). Если shop_id и shop_secret не соответствуют существующим, сервер возвращает ошибку 400 Bad request.
  3. Отправляет задачу в фоновую обработку.
  4. Возвращает код 204 No body.
  5. В случае успешной обработки фоновой задачи ничего не происходит. Задача обрабатывается быстро, поэтому спустя минуту уже можно загружать информацию о товарах.
  6. В случае ошибочной обработки фоновой задачи приходит уведомление на адрес электронной почты сотрудников, подписанных на технические уведомления.

# Структура данных

{
    shop_id: '...',
    shop_secret: '...',
    categories: [category, category, ...]
}

Структура информации о категории:

{
    id:     '...', // String. Required
    name:   '...', // String. Required
    parent: '...', // String or null. Required
    url:    '...', // String. Required
    alias:  '...'  // String. Optional
}

Вложенность подкатегорий не ограничена.

# Пример тела запроса

{
    // Shop key, берется в личном кабинете на экране настроек магазина
    "shop_id":      "eehj3eu84299kg5ghw5a6743r8",  
     
    // Secret key, берется в личном кабинете на экране настроек магазина
    "shop_secret":  "pmd5362597thrgq8k256ep01t0",  
     
    // Список категорий
    "categories":   [
        {
            "id":           1,
            "name":         "Главная категория",
            "parent":       null,
            "url":          "https://mysite.com/catalog"
        },
        {
            "id":           2,
            "name":         "Одежда",
            "parent":       1,
            "url":          "https://mysite.com/catalog/apparel"
        },
        {
            "id":           3,
            "name":         "Велосипеды",
            "parent":       1,
            "url":          "https://mysite.com/catalog/bicycles"
        },
        {
            "id":           100,
            "name":         "Детские",
            "parent":       3,
            "url":          "https://mysite.com/catalog/bicycles/child",
            "alias":        "bicycles/child"
        }
    ]
}

# Загрузка локаций

XML

Не используйте этот метод, если используете способ загрузки товаров через YML/XML.

Прежде, чем загружать товары, необходимо загрузить в базу данных актуальный перечень локаций. Загружайте только те локации, которые используются в товарах (и промежуточные элементы дерева локаций). Нет смысла загружать конечные элементы дерева локаций (листья), в которых нет товаров.

# Описание метода

POST https://api.rees46.com/import/locations  

Необходимо указать заголовок:

Content-Type: application/json

Данные отправляются в виде JSON-строки, которая является телом запроса.

# Жизненный цикл запроса

  1. Сервер API REES46 принимает запрос.
  2. Выполняет первичную проверку доступа (shop_id, shop_secret). Если shop_id и shop_secret не соответствуют существующим, сервер возвращает ошибку 400 Bad request.
  3. Отправляет задачу в фоновую обработку.
  4. Возвращает код 204 No body.
  5. В случае успешной обработки фоновой задачи ничего не происходит. Задача обрабатывается быстро, поэтому спустя минуту уже можно загружать информацию о товарах.
  6. В случае ошибочной обработки фоновой задачи приходит уведомление на адрес электронной почты сотрудников, подписанных на технические уведомления.

# Структура данных

{
    shop_id: '...',
    shop_secret: '...',
    locations: [location, location, ...]
}

Структура информации о локации:

{
    id:     '...', // String. Required
    name:   '...', // String. Required
    parent: '...', // String. Required
    type:   '...', // String. Optional
    group:  '...', // String or Array of string. Optional
}

Вложенность элементов не ограничена.

# Пример тела запроса

{
    // Shop key, берется в личном кабинете REES46 на экране настроек магазина
    "shop_id":      "eehj3eu84299kg5ghw5a6743r8",  
     
    // Secret key, берется в личном кабинете REES46 на экране настроек магазина
    "shop_secret":  "pmd5362597thrgq8k256ep01t0",  
     
    // Список городов
    "locations":    [
        {
            "id":           1,
            "name":         "Москва",
            "type":         "city",
            "parent":       null,
            "group":        "ДенежныеГорода"
        },
        {
            "id":           145,
            "name":         "Пункт выдачи на Арбате",
            "type":         "store",
            "parent":       1
        },
        {
            "id":           2,
            "name":         "Санкт-Петербург",
            "parent":       null,
            "group":        "ДенежныеГорода"
        },
        {
            "id":           3,
            "name":         "Приморский край",
            "parent":       1
        },
        {
            "id":           4,
            "name":         "Владивосток",
            "parent":       3,
            "group":        "ДальнийВосток"
        }
    ]
}

# Загрузка товаров c использованием Location

# Описание метода

POST https://api.rees46.com/import/products  

Необходимо указать заголовок:

Content-Type: application/json

Данные отправляются в виде JSON-строки, которая является телом запроса.

Есть следующие виды запросов:

Название операции Тип HTTP запроса Описание
Перезапись POST Загрузить новые товары и выключить все существующие в платформе товары.
Добавление/изменение PUT Добавить новые товары, не отключая существующие, либо обновить существующие.
Синхронизация PATCH Синхронизировать наличие товаров.
Удаление DELETE Удалить товары, перечисленные в запросе (отметить как "не в наличии").

Помощь

Если отсутствует техническая возможность отправлять запросы типа DELETE, PUT и PATCH, то можно отправлять запросы POST и переменную method в теле JSON, равную PUT, PATCH или DELETE (верхний регистр).

# Жизненный цикл запроса

  1. Сервер API REES46 принимает запрос.
  2. Выполняет первичную проверку доступа (shop_id, shop_secret). Если shop_id и shop_secret не соответствуют существующим, сервер возвращает ошибку 400 Bad request.
  3. Отправляет задачу в фоновую обработку.
  4. Возвращает код 204 No body.
  5. В случае успешной обработки фоновой задачи ничего не происходит. Задача обрабатывается быстро, поэтому спустя минуту уже можно загружать информацию о товарах.
  6. В случае ошибочной обработки фоновой задачи приходит уведомление на адрес электронной почты сотрудников, подписанных на технические уведомления.

Обратите внимание

Все ключи регистрозависимы.

# Описание данных в запросе

{
    shop_id: '...',
    shop_secret: '...',
    items: [item1, item2, ...]
} 

Пример структуры объекта товара item:

{
    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
} 

# Особенности location

Объект "Цена и наличие в городе" показывает, что товар есть в наличии в определенной локации и его цена отличается от базовой цены. Если цена в объекте не указана, то для указанного города будет использоваться базовая цена. Если объект "Цена и наличие в городе" указан, то во всех других городах, которые не перечислены для данного товара в свойстве locations, товар будет считаться не в наличии.

{
    location: '...', // String. Required
    price:     ...  // Float (positive). Optional.
    oldprice:     ...  // Float (positive). Optional.
}

# Особенности params

Пример вложенной структуры информации о параметрах params:

{
    name: '...',  // String. Required
    value: [...], // Array. Required
    unit: '...', // String. Optional
} 

# Нишевые параметры

Для обогащения пользовательских профилей и усиления эффекта персонализации рекомендуется добавлять нишевые параметры товаров в секцию offer.

# Пример структуры (POST, PUT запросы)

Лимит

Рекомендуется отправлять не более 5000 товаров в одном запросе.

Ниже представлен пример с заполненными данными и пояснениями:

{
    // 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"
            }
  
        }
    ]
}

# Особенности отправки DELETE запроса

При отправке запроса типа DELETE (удаление товаров из платформы) достаточно перечислить идентификаторы товаров, которые необходимо удалить. Пример:

{
    "shop_id":      "eehj3eu84299kg5ghw5a6743r8",  
    "shop_secret":  "pmd5362597thrgq8k256ep01t0",  
    "items":        ["635", "3373", "75778"]
}

# Особенности отправки PATCH запроса

При отправке запроса типа PATCH (синхронизация наличия товаров в базе данных платформы) достаточно перечислить идентификаторы товаров, которые необходимо пометить как "в наличии". Товары из текущей базы данных платформы, идентификаторы которых не включены в PATCH запрос, будут помечены как "не в наличии".

Пример:

{
    "shop_id":      "eehj3eu84299kg5ghw5a6743r8",  
    "shop_secret":  "pmd5362597thrgq8k256ep01t0",  
    "items":        ["635", "3373", "75778"]
}

# Загрузка товаров c использованием Variant

Обратите внимание!

Для использования данного функционала отправьте запрос по адресу desk@rees46.com

# Описание метода

POST https://api.rees46.com/import/products  

Необходимо указать заголовок:

Content-Type: application/json

Данные отправляются в виде JSON-строки, которая является телом запроса.

Есть следующие виды запросов:

Название операции Тип HTTP запроса Описание
Перезапись POST Загрузить новые товары и выключить все существующие в платформе товары.
Добавление/изменение PUT Добавить новые товары, не отключая существующие, либо обновить существующие.
Синхронизация PATCH Синхронизировать наличие товаров.
Удаление DELETE Удалить товары, перечисленные в запросе (отметить как "не в наличии").

Помощь

Если отсутствует техническая возможность отправлять запросы типа DELETE, PUT и PATCH, то можно отправлять запросы POST и переменную method в теле JSON, равную PUT, PATCH или DELETE (верхний регистр).

# Жизненный цикл запроса

  1. Сервер API REES46 принимает запрос.
  2. Выполняет первичную проверку доступа (shop_id, shop_secret). Если shop_id и shop_secret не соответствуют существующим, сервер возвращает ошибку 400 Bad request.
  3. Отправляет задачу в фоновую обработку.
  4. Возвращает код 204 No body.
  5. В случае успешной обработки фоновой задачи ничего не происходит. Задача обрабатывается быстро, поэтому спустя минуту уже можно загружать информацию о товарах.
  6. В случае ошибочной обработки фоновой задачи приходит уведомление на адрес электронной почты сотрудников, подписанных на технические уведомления.

Обратите внимание

Все ключи регистрозависимы.

# Описание данных в запросе

{
    shop_id: '...',
    shop_secret: '...',
    items: [item1, item2, ...]
} 

Пример структуры объекта товара item:

{
    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.
    variants: [ {Variant}, {Variant}, ...], // * Array of {Variant} objects with locations, sizes, stocks (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
} 

# Особенности Variant

Только для фильтрации в поиске

Варианты используются только для фильтрации в результатах полного поиска и не участвуют в обработке расчетного профиля.

Объект "Вариант" показывает, что товар есть в наличии в определенной локации и его цена отличается от базовой цены. Если цена в объекте не указана, то для указанного города будет использоваться базовая цена. Если объект Variant указан, то во всех других городах, которые не перечислены для данного товара в свойстве variants, товар будет считаться не в наличии.

Помимо этого можно передавать дополнительные параметры:

Параметр Тип Обязательность Описание
sku Строка Не обязательно Уникальный SKU варианта
color Массив строк Не обязательно Массив доступных цветов варианта
size Массив строк Не обязательно Массив доступных размеров варианта
location Массив строк Рекомендуется Массив локаций, в которых доступен текущий вариант
price Число Не обязательно Цена, по которой доступен данный вариант в указанных локациях
delivery_types Объект Не обязательно Объект, где ключ - тип склада, в котором вариант есть в наличии, а значение - количество единиц варианта в наличии
image_url Строка Не обязательно Ссылка на индивидуальную фотографию варианта, если она отличается от основной фотографии оффера
name Строка Не обязательно Индивидуальное название варианта варианта, если оно отличается от названия основного оффера
{
  "sku": "...",
  "color": ["red"],
  "size": ["16", "18"],
  "location": ["msk"],
  "price": 305,
  "delivery_types": { "store": 30, "warehouse": 400 },
  "image_url": "...",
  "name": "..."
},
{
  "sku": "...",
  "color": ["red"],
  "size": ["17"],
  "location": ["msk"],
  "price": 304,
  "delivery_types": { "store": 2 },
  "image_url": "...",
  "name": "..."
},
{
  "sku": "...",
  "color": ["blue"],
  "size": ["16"],
  "location": ["msk"],
  "price": 305,
  "delivery_types": { "store": 3, "warehouse": 14 },
  "image_url": "...",
  "name": "..."
}

# Особенности params

Пример вложенной структуры информации о параметрах params:

{
    name: '...',  // String. Required
    value: [...], // Array. Required
    unit: '...', // String. Optional
} 

# Нишевые параметры

Для обогащения пользовательских профилей и усиления эффекта персонализации рекомендуется добавлять нишевые параметры товаров в секцию offer.

# Пример структуры (POST, PUT запросы)

Лимит

Рекомендуется отправлять не более 5000 товаров в одном запросе.

Ниже представлен пример с заполненными данными и пояснениями:

{
    // 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,
  
            // Варианты товаров, доступные в разных локациях в разных цветах и размерах
            "variants": [
                // Есть в красном цвете и размерах 16 и 18 в Москве по цене 305.
                // В наличии в магазине 30 шт., на удаленном складе 400 шт.
                // Имеет индивидуальное название и фотографию
                {
                  "color": ["red"],
                  "size": ["16", "18"],
                  "location": ["msk"],
                  "price": 305,
                  "delivery_types": { "store": 30, "warehouse": 400 },
                  "image_url": "...",
                  "name": "..."
                },
                // Есть в красном цвете в размере 1 в Москве по цене 304.
                // В наличии только в магазине 2 шт.
                // Название и фотография берутся из основного оффера.
                {
                  "sku": "...",
                  "color": ["red"],
                  "size": ["17"],
                  "location": ["msk"],
                  "price": 304,
                  "delivery_types": { "store": 2 }
                },
                // Есть в синем и зеленом цветах и размере 16 в Москве и СПб по цене из основного оффера.
                // В наличии в магазине 3 шт., на удаленном складе 14 шт.
                // Имеет индивидуальное название и фотографию
                {
                  "color": ["blue", "green"],
                  "size": ["16"],
                  "location": ["msk", "spb"],
                  "delivery_types": { "store": 3, "warehouse": 14 },
                  "image_url": "...",
                  "name": "..."
                }
            ],
  
            // Производитель
            "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"
            }
  
        }
    ]
}

# Особенности отправки DELETE запроса

При отправке запроса типа DELETE (удаление товаров из платформы) достаточно перечислить идентификаторы товаров, которые необходимо удалить. Пример:

{
    "shop_id":      "eehj3eu84299kg5ghw5a6743r8",  
    "shop_secret":  "pmd5362597thrgq8k256ep01t0",  
    "items":        ["635", "3373", "75778"]
}

# Особенности отправки PATCH запроса

При отправке запроса типа PATCH (синхронизация наличия товаров в базе данных платформы) достаточно перечислить идентификаторы товаров, которые необходимо пометить как "в наличии". Товары из текущей базы данных платформы, идентификаторы которых не включены в PATCH запрос, будут помечены как "не в наличии".

Пример:

{
    "shop_id":      "eehj3eu84299kg5ghw5a6743r8",  
    "shop_secret":  "pmd5362597thrgq8k256ep01t0",  
    "items":        ["635", "3373", "75778"]
}