/api/lite/products
Запрос списка продуктов (GET /api/lite/products)
/api/lite/products
Метод возвращает перечень всех продуктов / товарных предложений (активных и неактивных).
Продукт всегда содержит хотя бы один вариант.
Правильно рассматривать Продукт - как виртуальную сущность (группу), а вариант - как физический товар. В рамках одного Продукта может быть несколько Вариантов (например, различные цвета и размеры).
Каждый Вариант имеет набор Опций, характеризующих именно этот вариант (например Цвет=blue, Размер=XL). Не может существовать более одного Варианта с одинаковым набором Опций.
Фильтрация по полям товара
Можно задавать фильтр параметром ?query=test - для фильтрации по полям article, humanId, shortName, fullName, description
Дополнительно можно фильтровать по конкректному продукту параметром ?id=1000
Имеется поддержка фильтрации и по другим полям:
- по Id варианта - ?variantId=1001
- по ШК (штрихкоду товара) - ?barcode=0000000000001
Фильтрация по фильтрам, атрибутам, вариантам товара
Фронтенд при выборе покупателем значений тех или иных фильтров должен составить поисковый 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
-
stockUpdateFrom
Пример вызова с одновременной фильтрацией, пейджинацией и сортировкой:
/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 | Отображение для продажи в онлайн-магазине |
boxNeeded | boolean | Требуется обрешётка (при отгрузке товара) |
deleted | boolean | Архивная карточка |
type | enum | Тип продукта. SKU/PHYSICAL_SET/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 | Содержит информацию о размерах |
weightFact | decimal | Вес товара (по данным склада) |
dimensionsFact
|
object | Содержит информацию о размерах (по данным склада) |
canBeRotated
|
boolean | Определяет можно ли товар укладывать на бок при перевозке |
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 | Включает товар для интеграции |
zeroStock | boolean | Включает выгрузку нулевых остатков по товару |
extId
|
string | Внешний код товара для интеграции |
useBatchAccounting | boolean |
Флаг использования партионного учета Для ведения учёта сроков годности в партиях необходимо также передать значение USE_EXPIRATION в поле expirationMode и указать срок годности товара в поле expirationMonthsLimit |
expirationMode | enum | NO_EXPIRATION, USE_EXPIRATION - использование сроков годности в партиях |
expirationMonthsLimit | integer | Срок годности в мес |
manufacturedBy | string | Производитель |
composition | string | Состав продукта |
warranty | integer | Срок гарантии в мес |
warehouseCategoryCode
|
string | Код категории товара (из WMS) |
warehouseCategoryTitle
|
string | Наименование категории товара (из WMS) |
Пример результата запроса:
{
"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,
"useBatchAccounting": true,
"expirationMode": "USE_EXPIRATION",
"expirationMonthsLimit": 6,
"warranty": 12,
"warehouseCategoryCode": "000000001",
"warehouseCategoryTitle": "Парфюмерия"
"manufacturedBy": "Название производителя",
"composition": "Состав",
"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
},
"weightFact": 500,
"dimensionsFact": {
"height": 4,
"width": 20,
"depth": 4
},
"canBeRotated": true,
"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,
"zeroStock": false,
"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 или создаётся новый продукт с пользовательским id. |
extId | string | Дополнительный идентификатор продукта |
shortName | string | Наименование продукта |
description | string | Описание (может содержать html) |
tnvedCode | string | Код ТНВЭД |
internationalDescription | string | Описание на анлийском |
available | boolean | Отображение для продажи в онлайн-магазине |
deleted | boolean | Архивная карточка |
type | enum | Тип продукта. SKU/PHYSICAL_SET/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) |
warehouseCategoryCode | string | Код категории товара (из WMS) |
Пример вызова:
{
"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",
"warehouseCategoryCode": "000000001",
"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
},
"canBeRotated": true,
"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"
}
{
"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"
}
],
}
}
Обновление отдельных полей продукта (PATCH /api/lite/products)
/api/lite/products
Обновляет одно или несколько полей продукта, значения отсутствующих в запросе полей при этом не изменяются.
Тело запроса аналогично POST /api/lite/products
id - необходимо указывать обязательно
Пример вызова:
{
"id": "1015",
"shortName": "Limited Edition Паста (помада) для укладки волос",
"internationalDescription": "abc"
}
ответ аналогичен POST /api/lite/products
Копирование продукта
/api/lite/products/copy
id - код существующего продукта для копирования
Запрос
{
"id": "1234"
}
Пример успешного ответа
{
"success": true,
"id": "1234-copy"
}
В случае ошибки:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}