Skip to main content

/api/lite/products

Запрос списка продуктов (GET /api/lite/products)

/api/lite/products

Метод возвращает перечень всех продуктов / товарных предложений (активных и неактивных).

Продукт всегда содержит хотя бы один вариант.

Правильно рассматривать Продукт - как виртуальную сущность (группу), а вариант - как физический товар. В рамках одного Продукта может быть несколько Вариантов (например, различные цвета и размеры).

Каждый Вариант имеет набор Опций, характеризующих именно этот вариант (например Цвет=blue, Размер=XL). Не может существовать более одного Варианта с одинаковым набором Опций.

 

Фильтрация по полям товара

Можно задавать фильтр параметром ?query=test - для фильтрации по полям article , humanId, shortName, fullName, description

Дополнительно можно фильтровать по конкректному продукту параметром ?id=1000 

 

Фильтрация по фильтрам, атрибутам, вариантам товара

Фронтенд при выборе покупателем значений тех или иных фильтров должен составить поисковый GET запрос и передать его в метод:

/pub/products

в виде суммы параметров:

?filters=field_name1:field_value1,field_value2;field_name2:field_value3-field_value4  для всех фильтров в блоке OTHER

?attributes=field_name1:field_value1,field_value2;field_name2:field_value3-field_value4 для всех фильтров в блоке ATTRIBUTES

?features=field_name1:field_value1,field_value2;field_name2:field_value3-field_value4 для всех фильтров в блоке FEATURES

где field_name - это значение поля filters.fields.name, field_value - это значение поля filters.fields.stringValues для filters.fields.type: "string" или decimalValues для filters.fields.type: "decimal" или true/false для filters.fields.type: "boolean".

Для filters.fields.type: "decimal" также можно передавать диапазон, указывая начальное и конечное значение через дефис: field_name2:field_value3-field_value4

 

Коллекции

Можно задавать фильтр по коллекциям параметром ?collections=1007,1008 - для фильтрации по id коллекций (можно передавать списком)

 

Архивные карточки

Можно дополнительно выводить архивные карточки товаров параметром deleted=true

 

Пейджинация

Для пейджинации используются параметры page и size: size - заказов на странице, page - номер страницы.

Пример: /api/lite/products?page=0&size=200

Если параметры не переданы, то дефолтные значения page=0&size=100

Максимальное количество продуктов - 100. Даже если указано значение более 100

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

Сортировка

Для сортировки задается параметр order, принимающий код поля для сортировки и направление сортировки (asc, desc), отделенное символом плюса.

Пример сортировки по имени (возрастание): /api/lite/products?order=shortname+asc

Пример сортировки по имени (убывание): /api/lite/products?order=shortname+desc

Доступные коды сортировки:

  • shortname
  • article
  • price
  • amount

Пример вызова с одновременной фильтрацией, пейджинацией и сортировкой:

/api/lite/products?query=Поло&order=shortname+asc&page=0&size=200

Структура ответа:

Поле Тип / формат Описание
recordsTotal num Общее количество записей в рамках заданной фильтрации. Используется для пейджинации.

products

array Перечень товарных предложений
id string Идентификатор продукта
extId string Дополнительный идентификатор продукта
extId2 string Дополнительный идентификатор продукта
extId3 string Дополнительный идентификатор продукта
extId4 string Дополнительный идентификатор продукта
extId5 string Дополнительный идентификатор продукта

shortName

string Наименование продукта
description string Описание (может содержать html)
tnvedCode string Код ТНВЭД
internationalDescription string Описание на анлийском
additionalDescriptions array Блоки с дополнительным текстовым описанием
available boolean Отображение для продажи в онлайн-магазине
deleted boolean Архивная карточка
type enum Тип продукта. SKU/SKUSET/SERVICE.    Товар, набор товаров, услуга
vat enum НДС товара. NO_VAT/VAT_0/VAT_10/VAT_20
reviewScore decimal Оценка товара
variants array Массив вариантов
id string Уникальный идентификатор варианта.
article string Артикул (sku) товара
price decimal Цена продажи
oldPrice decimal "Старая" цена. Для визуализации скидки. 
isFfSynchronised
boolean Статус выгрузки товара на ФФ
ffSyncError
string Ошибка выгрузки товара на ФФ
isPhysicalSet
boolean Является ли товар физическим набором
isFfPhysicalSetSynchronized
boolean Статус выгрузки набора на ФФ
ffPhysicalSetSyncError
string Ошибка выгрузки набора на ФФ
discountPercent
decimal Скидка, в процентах
discountFix
decimal Скидка, фикс
bundleOptionalCount
num Размер опциональной части набора для выбора
autoPriceCalculation
boolean Авторасчет цены набора
autoDimensionsCalculation
boolean Авторасчет габаритов набора
prices object Список всех присвоенных цен
stock array Массив данных об остатках (если остатки на складах имеются)
warehouseCode string Код склада
stockTotal decimal Текущее количество на складе хранения
stockAvailable decimal Количество товара, доступного к продаже (stockTotal за минусом резерва)
stockReserved decimal Количество товара, зарезервированного под заказы.
pos num Порядковый номер варианта, относительно 
optionsUsed array Массив, указывающий соответствие опции и её значения для конкретного продукта. 
defaultImage string Ссылка на изображение из общего массива изображений. Может быть не задан.
weight decimal Вес товара
dimensions object Содержит информацию о размерах
barcodes object Список штрихкодов товара
isDefault boolean ШК является по умолчанию
value string Значение ШК
images array Массив изображений продукта. Первое изображение считается основным.
id string Идентификатор изображения
url string URL изображения
pos decimal Позиция изображения в рамках продукта
collections array Массив коллекций, в которые входит продукт
id string Идентификатор коллекции
attributes array Массив значений атрибутов продукта
code string Код атрибута
type enum Тип атрибута (см. описание атрибутов)
stringValue string Значение атрибута (строка)
decimalValue decimal Значение атрибута (число)
ordering decimal Cортировка
accountingAttributes
array Массив значений атрибутов учета
code
string Код атрибута
title string Название атрибута
stringValue string Значение атрибута
subscriptionInfo object Описание подписок (Не отображается, если пустой)
eshopSettings
array Массив внешних кодов для интеграций
eshopId
string ID интеграции
eshopType
string Тип интеграции
eshopName
string Название интеграции
enabled
boolean Включает товар для интеграции
extId
string Внешний код товара для интеграции
only_stock boolean  

 

Пример результата запроса:

{
    "success": true,
    "recordsTotal": 1,
    "products": [
        {
            "id": "1000",
            "extId": null,
          	"extId2": null,
            "extId3": null,
            "extId4": null,
            "extId5": null,
            "shortName": "Кактус Эуфобия Триангуларис",
            "description": "Кактус Эуфобия Триангуларис",
            "tnvedCode": "123",
            "internationalDescription": "abc",
            "additionalDescriptions":[{"title":"some title", "description":"some description"}],
            "available": true,
            "deleted": false,
            "brandName": null,
            "countryOfOrigin": null,
            "isBestseller": null,
            "isNovelty": null,
            "type": "SKU",
            "vat": "VAT_20",
            "reviewScore": 4.0,
            "options": null,
            "images": null,
            "variants": [
                {
                    "id": "1000",
                    "extId": null,
                  	"extId2": null,
                    "extId3": null,
                    "extId4": null,
                    "extId5": null,
                    "article": null,
                    "price": 2190,
                    "oldPrice": 1590,
                    "isFfSynchronised": true,
                    "ffSyncError": null,
                    "isPhysicalSet": false,
                    "isFfPhysicalSetSynchronized": false,
                    "ffPhysicalSetSyncError": null,
                  	"discountPercent": 0,
                    "discountFix": 0,
                    "bundleOptionalCount": 0,
                    "autoPriceCalculation": false,
                    "autoDimensionsCalculation": false,
                  	"prices":[
                        {
                           "priceCode":"Розничная цена",
                           "priceName":"Розничная цена",
                           "value":2190
                        },
                      	{
                           "priceCode":"Цена до скидки",
                           "priceName":"Цена до скидки",
                           "value":1590
                        }
                     ],
                    "stock": [
                        {
                            "warehouseCode": "9a84e96f-3e8c-8f74-3b7a-50a1d3c2a130",
                            "stockTotal": 111,
                            "stockAvailable": 111,
                            "stockReserved": 0
                        }
                    ],
                    "ordering": "123.000000000000000",
                    "defaultImage": null,
                    "weight": 500,
                    "dimensions": {
                        "height": 4,
                        "width": 20,
                        "depth": 4
                    },
                    "barcodes": [
                        {
                            "value": "42353456345345",
                            "isDefault": true,
                            "type": "COMMON"
                        },
                        {
                            "value": "34234232343",
                            "isDefault": false,
                          	"type": "WILDBERRIES"
                        }
                    ],                 
                    "optionsUsed": null,
                  	"eshopSettings": [
                        {
                            "eshopId": "e4a1920d-f154-7284-bad4-a7b9546032fe",
                            "eshopType": "BERU",
                            "eshopName": "Магазин на Беру",
                            "enabled": true,
                            "extId": "variant-ext-id-for-beru"
                        }
                    ]
                }
            ],
            "collections": [
                "1001"
            ],
            "attributes": null,
            "accountingAttributes": [
                {
                    "code": "chestnyznak",
                    "title": "Честный знак",
                    "stringValue": "11111"
                }
            ],
          	"eshopSettings": [
                {
                  "eshopId": "e4a1920d-f154-7284-bad4-a7b9546032fe",
                  "eshopType": "BERU",
                  "eshopName": "Магазин на Беру",
                  "enabled": true,
                  "extId": "product-ext-id-for-beru"
                }
            ]
          	"subscriptionInfo": {
              "productId": "1002",
              "variantId": "1002",
              "onlinePaymentType": "recurrent",
              "type": "SUBSCRIPTION",
              "useShipmentDelayInterval": true,
              "items": [
                  {
                      "productId": "1002",
                      "variantId": "1006",
                      "count": 1,
                      "subscriptionShipmentNum": 1,
                      "shipmentDelayIntervalDays": 30,
                      "subscriptionStartDate": "2020-09-10",
                      "itemPrice": 120.0
                  },
                  {
                      "productId": "1002",
                      "variantId": "1007",
                      "count": 1,
                      "subscriptionShipmentNum": 1,
                      "shipmentDelayIntervalDays": 30,
                      "subscriptionStartDate": "2020-09-10",
                      "itemPrice": 120.0
                  },
                  {
                      "productId": "1002",
                      "variantId": "1008",
                      "count": 1,
                      "subscriptionShipmentNum": 2,
                      "shipmentDelayIntervalDays": 20,
                      "subscriptionStartDate": "2020-09-30",
                      "itemPrice": 150.0
                  },
                  {
                      "productId": "1002",
                      "variantId": "1009",
                      "count": 1,
                      "subscriptionShipmentNum": 2,
                      "shipmentDelayIntervalDays": 20,
                      "subscriptionStartDate": "2020-09-30",
                      "itemPrice": 150.0
                  },
                  {
                      "productId": "1002",
                      "variantId": "1010",
                      "count": 1,
                      "subscriptionShipmentNum": 3,
                      "shipmentDelayIntervalDays": 20,
                      "subscriptionStartDate": "2020-10-20",
                      "itemPrice": 250.0
                    }
                   ]
                }
          }
        }
    ]
}

Выгружать только остатки (специальный режим выгрузки)

Дополнительно можно передать параметр ?only_stock=true. Если он присутствует в запросе, то выгружается минимально необходимое кол-во полей.

Пример: /api/lite/products?only_stock=true

Максимальное количество продуктов в режиме остатков - 1000. Даже если указано значение более 1000

Пример результата запроса(режим остатков):

{
    "success": true,
    "recordsTotal": 1322,
    "products": [
        {
            "id": "1000",
            "extId": null,
            "extId2": null,
            "extId3": null,
            "extId4": null,
            "extId5": null,
            "variants": [
                {
                    "id": "1000",
                    "extId": null,
                    "extId2": null,
                    "extId3": null,
                    "extId4": null,
                    "extId5": null,
                    "stock": [
                        {
                            "warehouseCode": "5a93f7e7-4785-0332-8324-bf3a03ee8211",
                            "stockTotal": 10,
                            "stockAvailable": 8,
                            "stockReserved": 2,
                            "stockDefective": 0,
                            "stockDefectiveReserved": 0
                        }
                    ]
                }
            ]
        }
    ]
}

 

 

Создание/обновление продукта (POST /api/lite/products)

/api/lite/products

Создает или обновляет продукт.

Если id указан - проводится обновление продукта с указанным id, если не указан - создается новый. Опционально можно передавать список вариантов товара для обновления, в поле variantsToUpdate. Обновление продукта выполняется первым, если успешно - то начинается обновление вариантов.

Этот список не означает, что коллекция вариантов данного продукта будет приведена к виду в переданном списке вариантов. Будет выполнено только обновление указанных вариантов, безотносительно остальных вариантов их продукта.

Если передан список вариантов - то в ответе в поле variantsResult будет список результатов обновления по каждому варианту, для сопоставления на вызывающей стороне (по полям productId + variantId)

Поле Тип / формат

Описание

id string

Идентификатор продукта. Если не указан, создается новый продукт. Если указан, обновляется продукт с данным id.

extId string Дополнительный идентификатор продукта
shortName string Наименование продукта
description string Описание (может содержать html)
tnvedCode string Код ТНВЭД
internationalDescription string Описание на анлийском
available boolean Отображение для продажи в онлайн-магазине
deleted boolean Архивная карточка
type enum Тип продукта. SKU/SKUSET/SERVICE.    Товар, набор товаров, услуга
vat enum НДС товара. NO_VAT/VAT_0/VAT_10/VAT_20
collections array Массив идентификаторов коллекций, в который входит данный продукт
attributes array Массив значений атрибутов продукта
code string Код атрибута
stringValue string Значение атрибута (строка)
decimalValue decimal Значение атрибута (число)
accountingAttributes array Массив значений атрибутов учета
code string Код атрибута
stringValue string Значение атрибута
eshopSettings
array Массив внешних кодов для интеграций
eshopId
string ID интеграции
enabled boolean Включает товар для интеграции
extId
string Внешний код продукта для интеграции
variantsToUpdate объект Объект варианта товара (см. POST /api/lite/products/variants)

 

Пример вызова:

Пример запроса
{
      "id": "1015",
      "extId": "FAQ-D-000112",
      "extId2": null,
      "extId3": null,
      "extId4": null,
      "extId5": null,
      "shortName": "Limited Edition Паста (помада) для укладки волос Bro Cosmetics // средняя фиксация, матовый эффект",
      "description": "Limited Edition Паста (помада) для укладки волос Bro Cosmetics // средняя фиксация, матовый эффект",
  	  "additionalDescriptions":[{"title":"some title", "description":"some description"}],
      "available": true,
      "deleted": false,
      "brandName": null,
      "countryOfOrigin": null,
      "tnvedCode": "123",
      "internationalDescription": "abc",
      "isBestseller": null,
      "isNovelty": null,
      "type": "SKU",
      "vat": "NO_VAT",
    "collections": [
        "1029",
        "1031"
    ], 
    "attributes": [
        {
            "code": "material",        
            "stringValue": "Хлопок 97%, эластан 3%"        
        }
    ],
    "accountingAttributes": [
        {
          "code": "chestnyznak",
          "stringValue": "11111"
        }
    ],
  	"eshopSettings": [
        {
          "eshopId": "e4a1920d-f154-7284-bad4-a7b9546032fe",
          "enabled": true,
          "extId": "product-ext-id-for-beru"
        }
    ],
    "variantsToUpdate": [
            {
                    "productId":"1002",
                    "variantId": "1007",
              		"extId": null,
                    "extId2": null,
                    "extId3": null,
                    "extId4": null,
                    "extId5": null,
                    "article": "well done",
                    "price": 6000, //deprecated
                    "oldPrice": 6500, //deprecated
              		"prices":[
                        {
                           "priceCode":"Розничная цена",
                           "value":6000
                        },
                      	{
                           "priceCode":"Цена до скидки",
                           "value":6500
                        }
                     ],
                    "stock": [
                        {
                           "warehouseCode": "9a84e96f-3e8c-8f74-3b7a-50a1d3c2a130",                         
                           "stockTotal": 111                          
                        }
                    ],
                    "updateStockTotal": true,                  
                    "ordering": "300.000000000000000",
                    "defaultImage": null,
                    "weight": 500,
                    "dimensions": {
                        "height": 30,
                        "width": 31,
                        "depth": 32
                    },
                    "optionsUsed": [
                        {
                            "code": "color",
                            "stringValue": "синий",
                            "decimalValue": null,
                            "name": "Цвет"
                        }
                    ],
                    "eshopSettings": [
                        {
                          "eshopId": "e4a1920d-f154-7284-bad4-a7b9546032fe",
                          "enabled": true,
                          "extId": "variant-ext-id-for-beru"
                        }
                    ],
              		"discountType": "PERCENT", // FIX
              		"discountValue": 50
                }
        ]
}

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

Пример ответа
{
    "success": true,
    "id": "1002",
    "product": {
        "id": "1002",
        "extId": "FAQ-D-000112",
        "extId2": null,
        "extId3": null,
        "extId4": null,
        "extId5": null,
        "shortName": "Limited Edition Паста (помада) для укладки волос Bro Cosmetics // средняя фиксация, матовый эффект",
        "description": "Limited Edition Паста (помада) для укладки волос Bro Cosmetics // средняя фиксация, матовый эффект",
      	"additionalDescriptions":[{"title":"some title", "description":"some description"}],
        "available": true,
        "deleted": false,
        "brandName": null,
        "countryOfOrigin": null,
        "tnvedCode": "123",
        "internationalDescription": "abc",
        "isBestseller": null,
        "isNovelty": null,
        "type": "SKU",
        "vat": "NO_VAT",
        "reviewScore": null,
        "options": null,
        "images": null,
        "variants": [
            {
                "productId":"1002",
                "variantId": "1007",
              	"extId": null,
                "extId2": null,
                "extId3": null,
                "extId4": null,
                "extId5": null,
                "article": "well done",
                "price": 6000,
                "oldPrice": 6500,
              	"prices":[
                        {
                           "priceCode":"Розничная цена",
                           "priceName":"Розничная цена",
                           "value":6000
                        },
                      	{
                           "priceCode":"Цена до скидки",
                           "priceName":"Цена до скидки",
                           "value":6500
                        }
                     ],
                "stock": [
                        {
                            "warehouseCode": "9a84e96f-3e8c-8f74-3b7a-50a1d3c2a130",
                            "stockTotal": 111,
                            "stockAvailable": 111,
                            "stockReserved": 0
                        }
                    ],
                "ordering": "300.000000000000000",
                "defaultImage": null,
                "weight": 500,
                "dimensions": {
                    "height": 30,
                    "width": 31,
                    "depth": 32
                },
                "barcodes": null,
                "vat": "NO_VAT",
                "type": "SKU",
                "optionsUsed": [
                    {
                        "code": "color",
                        "stringValue": "синий",
                        "decimalValue": null,
                        "name": "Цвет"
                    }
                ]
            }
        ],
        "collections": [
            "1029",
            "1031"
        ], 
        "attributes": [
            {
                "code": "material",        
                "stringValue": "Хлопок 97%, эластан 3%"        
            }
        ],
        "accountingAttributes": [
            {
              "code": "chestnyznak",
              "title": "Честный знак",
              "stringValue": "11111"
            }
        ],
    },
    "variantsResult": [
        {
            "success": true,
            "productId": "1002",
            "variantId": "1003"
        }
    ]
}

Пример положительного ответа с ошибкой сохранения по указанному варианту:

Пример ответа
{
    "success": true,
    "id": "1002",
    "variantsResult": [
        {
            "success": false,
            "errors": [
                {
                    "code": 0,
                    "message": "Вариант с указанным id не найден"
                }
            ],
            "productId": "1002",
            "variantId": "100343"
        }
    ],
    "product": {
        "id": "1002",
        "extId": "FAQ-D-000112",
      	"extId2": null,
        "extId3": null,
        "extId4": null,
        "extId5": null,
        "shortName": "Limited Edition Паста (помада) для укладки волос Bro Cosmetics // средняя фиксация, матовый эффект",
        "description": "Limited Edition Паста (помада) для укладки волос Bro Cosmetics // средняя фиксация, матовый эффект",
        "available": true,
        "deleted": false,
        "brandName": null,
        "countryOfOrigin": null,
        "tnvedCode": "123",
        "internationalDescription": "abc",
        "isBestseller": null,
        "isNovelty": null,
        "type": "SKU",
        "vat": "NO_VAT",
        "reviewScore": null,
        "options": null,
        "images": null,
        "variants": [
            {
                "productId":"1002",
                "variantId": "1007",
               	"extId": null,
                "extId2": null,
                "extId3": null,
                "extId4": null,
                "extId5": null,
                "article": "well done",
                "price": 6000,
                "oldPrice": 6500,
                "stock": [
                        {
                            "warehouseCode": "9a84e96f-3e8c-8f74-3b7a-50a1d3c2a130",
                            "stockTotal": 111,
                            "stockAvailable": 111,
                            "stockReserved": 0
                        }
                    ],
                "ordering": "300.000000000000000",
                "defaultImage": null,
                "weight": 500,
                "dimensions": {
                    "height": 30,
                    "width": 31,
                    "depth": 32
                },
                "barcodes": null,
                "vat": "NO_VAT",
                "type": "SKU",
                "optionsUsed": [
                    {
                        "code": "color",
                        "stringValue": "синий",
                        "decimalValue": null,
                        "name": "Цвет"
                    }
                ]
            }
        ],
        "collections": [
            "1029",
            "1031"
        ], 
        "attributes": [
            {
                "code": "material",        
                "stringValue": "Хлопок 97%, эластан 3%"        
            }
        ],
        "accountingAttributes": [
            {
              "code": "chestnyznak",
              "title": "Честный знак",
              "stringValue": "11111"
            }
        ],
    }
}

 

 

Копирование продукта

/api/lite/products/copy

id - код существующего продукта для копирования

 

Запрос

{
     "id": "1234"            
}

 

Пример успешного ответа

{
    "success": true,
    "id": "1234-copy"
}

В случае ошибки:

{
    "success": false,
    "errors": [
        {
            "code": 0,
            "message": "Текст ошибки"
        }
    ]  
}