Товары
- Комментарии по синхронизации товаров и остатков
- /api/lite/products
- /api/lite/products/attributes
- /api/lite/products/features
- /api/lite/products/filters
- /api/lite/products/image
- /api/lite/products/variants
- /api/lite/file/image
- /api/lite/pub/products
- /api/lite/pub/products/filters
- /api/lite/products/templates/items
- /api/lite/products/additional_descriptions
- /api/lite/products/reviews
- /api/lite/pub/products/reviews
- /api/lite/products/features/appearance
- /api/lite/pub/products/features/appearance
- /api/lite/products/export_ff
- /api/lite/products/accounting_attributes
- /api/lite/products/stock_revise
- /api/lite/products/wb_categories
- /api/lite/products/delete_barcodes_ff
- /api/lite/products/history
- /api/lite/products/history/diff
- /api/lite/products/batch
- /api/lite/products/batch/accounting/stocks
- /api/lite/products/variants/batch
- API загрузки уникальных номеров номенклатуры в Кактус
- /api/lite/products/variants/eshop_settings
- /api/lite/products/warehouse/categories
- /api/lite/products/stocks
Комментарии по синхронизации товаров и остатков
Для создания новых товаров и обновления существующих, следует использовать метод
Каждый продукт обязательно должен содержать хотя бы один вариант. Поэтому, при создании нового продукта, автоматически создается к нему один вариант.
Варианты - это реальные SKU, у них есть вес, размеры, штрихкоды и т.д. Продукт же содержит только общие параметры.
Момент к обсуждению - при синхронизации товаров с Cactus, надо ли выгружать иерархию с вариантами, либо “развернуть” варианты в плоский список в Кактусе (один вариант = один продукт Кактус).
Вариантами можно управлять как из метода products, так и напрямую, методом products/variants.
Кактус имеет систему резервирования. При оформлении заказа, Кактус пытается взять резерв. Это необходимое условие для допуска заказа к отгрузке.
/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": "Текст ошибки"
}
]
}
/api/lite/products/attributes
Атрибуты – дополнительные характеристики для описания номенклатуры. Используются для более полного отображения информации и продукте - в карточке продукта, а также для возможности фильтрации в каталоге товаров. Не являются обязательными к заполнению.
Справочник атрибутов является общим для аккаунта.
Атрибуты бывают строковыми и числовыми (в том числе могут быть дробными).
Значения атрибутов задаются в информации о продуктах.
Запрос справочника атрибутов
/api/lite/products/attributes
Метод возвращает список всех доступных атрибутов.
Поле | Тип / формат | Описание |
id | string | Идентификатор атрибута. |
code | string | Код атрибута - латиницей |
title | string | Наименование атрибута |
type | enum |
Тип значения атрибута:
|
Пример результата запроса:
{
"success": true,
"attributes": [
{
"id": "12345679",
"code": "roasting",
"title": "Степень обжарки",
"type": "string",
"ordering": 12,
"values": [
{
"stringValue": "XXL",
"ordering": 4
},
{
"stringValue": "XL",
"ordering": 3
}
]
},
{
"id": "12345",
"code": "coffee_strength",
"title": "Крепость кофе",
"type": "decimal",
"ordering": 1211,
"values": [
{
"decimalValue": 1.3,
"ordering": 100
},
{
"decimalValue": 2.5,
"ordering": 200
}
]
}
]
}
Создание/обновление атрибута
/api/lite/products/attributes
Создает или обновляет атрибут.
ID атрибута при создании/обновлении - обязательное поле, он задается явно для каждого атрибута.
Пример создания/обновления атрибута:
{
"code": "roasting",
"title": "Степень обжарки",
"type": "string",
"ordering": 1211,
"values": [
{
"stringValue": "XXL",
"ordering": 4
},
{
"stringValue": "XL",
"ordering": 3
}
]
}
/api/lite/products/features
По продуктам можно задавать варианты, и есть справочник опций и их значений на каждого клиента, по которым можно для продуктов устанавливать варианты.
Создать/обновить вариант со значением опции, не указанными в таком справочнике - можно, новое значение опции не попадет в общий справочник
Запрос списка опций
/api/lite/products/features
Метод возвращает справочник всех опций и их значений для клиента
Поле | Тип / формат | Описание |
id | string | Идентификатор опции |
code | string | Читаемый код опции |
title | string | Читаемое наименование опции |
type | string | Тип опции (string/decimal) |
values | array | Список значений опции |
stringValue | string | Значение опции (строка) |
decimalValue | decimal | Значение опции (число) |
ordering | decimal | сортировка |
Пример результата запроса:
{
"success": true,
"features": [
{
"id": "a2ebf183-f30d-417b-af89-e3ff86d2cca7",
"code": "size",
"title": "Размер",
"type": "string",
"values": [
{
"stringValue": "XXL",
"ordering": 4
},
{
"stringValue": "XL",
"ordering": 3
}
]
},
{
"id": "a2ebf183-f30d-417b-af89-e3ff86d2cca8",
"code": "coef",
"title": "Тестовый коэффициент",
"type": "decimal",
"values": [
{
"decimalValue": 1.3,
"ordering": 100
},
{
"decimalValue": 2.5,
"ordering": 200
}
]
}
]
}
Создание/обновление опции
/api/lite/products/features
Создает или обновляет опцию.
Поле code опции при создании/обновлении - обязательное поле, он задается явно для каждой опции.
Список значений опции при создании - необязателен
Пример создания/обновления атрибута:
{
"id": "a2ebf183-f30d-417b-af89-e3ff86d2cca7",
"code": "size",
"title": "Размер",
"type": "string",
"values": [
{
"stringValue": "XXL",
"ordering": 4
},
{
"stringValue": "XL",
"ordering": 3
}
]
}
/api/lite/products/filters
Получение блоков фильтров
/api/lite/products/filters
Возвращает для заданной коллекции перечень блоков и фильтров в них для поиска товаров.
Блоки бывают трех типов - Для атрибутов, для опций, и другие. Атрибуты и опции выделены в отдельные блоки ввиду потенциально большого количества справочников и значений в них.
Блоки можно запрашивать в режиме для покупателя и для владельца магазина.
В режиме для покупателя - загрузится список вручную сформированных блоков фильтров и выбранных значений фильтров, которые нужно отобразить покупателю.
В режиме для продавца - загрузятся автоматически сформированные блоки со всеми фильтрами и со всеми значениями фильтров и справочников в них - это будет использовать продавец для ручного поиска товаров для формирования заказов или других сценариях использования поиска товаров.
Значения в атрибутах, опциях и пр. - автозаполняются по факту их использования в том или ином товаре. Это будет делаться асинхронно по регламенту, а не при исполнении запроса поиска, т.к. операция дорогая по времени.
Обязательный параметр запроса - ?collectionId=123
Опциональный параметр - режим запроса - под покупателем или под продавцом. По умолчанию - под покупателем
?mode=client или ?mode=customer
Фронтенд при выборе покупателем значений тех или иных фильтров должен составить поисковый 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
Поля возвращаемого значения:
Параметр | Тип / формат | Описание |
filterBlocks | array | Массив блоков |
id | string | Идентификатор блока |
type | enum | Тип блока. ATTRIBUTES (только атрибуты товаров), FEATURES (только опции товаров), OTHER (остальные поля товаров) |
mode | enum |
Режим работы блока. CUSTOMER (покупатель, отображены выбранные продавцом фильтры в блоке), CLIENT (продавец - отображены все возможные поля и блоки) |
ordering | integer | Сортировка |
collectionId | string | Идентификатор коллекции к которой относится данный блок фильтров |
filters | Массив | Перечень фильтров в блоке |
enabled | boolean | Виден на витрине |
type | enum | Тип фильтра. PRICE, STOCK_AVAILABLE, SIZE_WIDTH, SIZE_DEPTH, SIZE_HEIGHT, WEIGHT, COUNTRY_OF_ORIGIN, ATTRIBUTES, FEATURES, DISCOUNT_AVAILABLE, IS_NOVELTY, BRAND, IS_BESTSELLER, |
ordering | integer | Сортировка |
fields | Массив | Поля фильтра |
name | string | Наименование поля |
nameReadable | string | Наименование поля для пользователя |
type | enum | Тип поля. string, decimal, boolean |
ordering | integer | Сортировка |
stringValues | Массив | Массив строковых значений поля |
decimalValues | Массив | Массив числовых значений поля |
Пример ответа:
{
"success": true,
"filterBlocks": [
{
"id": "1029",
"type": "OTHER", // ATTRIBUTES, FEATURES
"mode": "CUSTOMER", //CLIENT
"ordering": 10,
"collectionId": "123456"
"filters":[
{
"type":"PRICE", // STOCK_AVAILABLE, SIZE_WIDTH, SIZE_DEPTH, SIZE_HEIGHT, WEIGHT, COUNTRY_OF_ORIGIN, ATTRIBUTES, FEATURES, DISCOUNT_AVAILABLE, IS_NOVELTY, BRAND, IS_BESTSELLER
"enabled": true,
"ordering": 10,
"fields":[
{
"name" : "field1",
"nameReadable": "Поле 1",
"type": "string", // decimal, boolean
"ordering": 10,
"stringValues": [
"value1", "value2"
]
},
{
"name" : "field2",
"nameReadable": "Поле 2",
"type": "decimal",
"ordering": 11,
"decimalValues": [
15.2, 16.8
]
},
{
"name" : "field3",
"nameReadable": "Поле 3",
"type": "boolean",
"ordering": 12
}
]
}
]
}
]
}
Создание/обновление блока фильтров
/api/lite/products/filters
Создает или обновляет блок фильтров для покупателя.
Фильтры для продавца создаются и заполняются автоматом.
Если id указан - проводится обновление блока фильтров с указанным id, если не указан - создается новый блок.
Есть проверка - фильтры с типом ATTRIBUTES или FEATURES - можно добавлять только в отдельные блоки с аналогичными типами, в которых нет других фильтров
Поля в блоках фильтров (кроме типов ATTRIBUTES, FEATURES) отдельно не задаются, их бэкенд добавит автоматически по типу фильтра.
Пример обновления блока:
{
"id": "1029",
"type": "OTHER", // ATTRIBUTES, FEATURES
"ordering": 10,
"collectionId": "123456"
"filters":[
{
"type":"PRICE", // STOCK_AVAILABLE, SIZE_WIDTH, SIZE_DEPTH, SIZE_HEIGHT, WEIGHT, COUNTRY_OF_ORIGIN, ATTRIBUTES, FEATURES, DISCOUNT_AVAILABLE, IS_NOVELTY, BRAND, IS_BESTSELLER
"enabled": true,
"fields":[ // только для ATTRIBUTES, FEATURES
{
"name" : "field1",
"nameReadable": "Поле 1",
"type": "string", // decimal, boolean
"ordering": 10,
"stringValues": [
"value1", "value2"
]
},
{
"name" : "field2",
"nameReadable": "Поле 2",
"type": "decimal",
"ordering": 11,
"decimalValues": [
15.2, 16.8
]
},
{
"name" : "field3",
"nameReadable": "Поле 3",
"type": "boolean",
"ordering": 12
}
]
}
]
}
Пример ответа:
{
"success": true,
"id": "1029"
}
Удаление блока фильтров
/api/lite/products/filters
Для удаления блока фильтров, выполняется следующий DELETE запрос с указанием идентификатора блока в параметре id
В ответ возвращается результат операции и id удаленного блока.
Пример успешного ответа:
{
"success": true,
"id": "6F9619FF-8B86-D011-B42D-00CF4FC964FF"
}
Пример ошибки:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Блока фильтров с указанным id не существует"
}
]
}
/api/lite/products/image
Создание картинки к продукту (/api/lite/products/image)
/api/lite/products/image
Загружает на сервер картинку и привязывает изображение к товару.
Используется заголовок запроса Content-type: multipart/form-data.
В качестве параметров запроса передается:
- id - идентификатор продукта
- upfile - картинка
На стороне сервера:
- Сохраняется оригинал картинки (но с ограничением в максимальное количество пикселей) - original
В ответ возвращается информация о загруженной картинке:
Успех
{
"success": true,
"url": "https://img.kak2c.ru/i/H/E/Y8x2a2Zj.jpg",
"id": "42737a4a-8f76-4aa6-a3d1-ae553f2409cb",
"pos": "10000.000000000000000"
}
Параметры:
- url- прямая ссылка на оригинал картинки
- id - идентификатор картинки (для последующего обновления или удаления)
- pos - автоматически присвоенное значение для сортировки
Ошибка:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}
Удаление картинки у товарного предложения (/api/lite/products/image)
/api/lite/products/image
Для удаления метки, выполняется следующий DELETE запрос с указанием идентификатора картинки в параметре id
В ответ возвращается результат операции и id удаленной картинки.
Пример успешного ответа:
{
"success": true,
"id": "6F9619FF-8B86-D011-B42D-00CF4FC964FF"
}
В случае ошибки:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Картинки с указанным id не существует"
}
]
}
Обновление позиции картинки (/api/lite/products/image/pos)
/api/lite/products/image/pos
Обновляет значение позиции для сортировки картинок в списке
Запрос:
{
"id": "6F9619FF-8B86-D011-B42D-00CF4FC964FF",
"pos": 123.456
}
Ответ:
{
"success": true
}
В случае ошибки:
{
"success": false,
"errors": [
{
"code": 0,
"message": "текст ошибки"
}
]
}
/api/lite/products/variants
У каждого продукта есть хотя бы один вариант.
Вариант – реальный товар, имеющий характеристики, вес, размеры.
Создание/редактирование варианта (POST /api/lite/products/variants)
/api/lite/products/variants
Создает или обновляет вариант к указанному продукту.
Поле | Тип\формат | Описание |
productId | string | Идентификатор продукта, для которого создаются варианты |
variantId | string | Идентификатор варианта для обновления. Если не указан, создается новый вариант. |
extId | string | Дополнительный редактируемый код варианта. |
article | string | Артикул производителя товара. |
price | decimal | Цена розничной продажи. [deprecated] |
oldPrice | decimal | "Старая цена" - используется для отображения перечеркнутой цены. [deprecated] |
prices | object | Список цен |
defaultImage | string | Ссылка на стандартное изображение варианта (из набор изображений продукта). |
ordering | double | Число для сортировки между вариантами |
optionsUsed | array | Массив используемых опций данным вариантом |
code | string | Код варианта |
stringValue | string | Значение опции варианта (строка) |
decimalValue | decimal | Значение опции варианта (число) |
weight | decimal | Вес товара в граммах |
dimensions | object | Объект с характеристиками размеров товара. Задается в сантиметрах. |
barcodes | array | Список ШК варианта |
stock | object | Объект со списком кодов складов и остатков товаров на них |
warehouseCode | string | Код склада |
stockTotal | integer |
Опционально - установить общее количество товара в штуках на складе по умолчанию, включая количество в резерве. Только в сочетании с флагом updateStockTotal = true |
updateStockTotal | boolean |
Флаг активации корректировки общего количества товара из поля stockTotal на складе по умолчанию |
Пример вызова:
{
"productId": "1002",
"variantId": "1024",
"article": "POLO92/L/ЖЕЛ",
"price": 990, //deprecated
"oldPrice": 1200, //deprecated
"prices":[
{
"priceCode":"Розничная цена",
"value":990
},
{
"priceCode":"Цена до скидки",
"value":1200
}
],
"defaultImage": "8b16a469-2b8c-4df4-85f2-c9c9afa1f921",
"ordering": "123.123"
"optionsUsed": [
{
"code": "size",
"stringValue": "L"
},
{
"code": "color",
"stringValue": "желтый"
}
],
"weight": 500,
"dimensions": {
"height": 5,
"width": 5,
"depth": 10
},
"barcodes": [
{
"value": "42353456345345",
"isDefault": true,
"type": "COMMON"
},
{
"value": "34234232343",
"isDefault": false,
"type": "WILDBERRIES"
}
],
"stock": [
{
"warehouseCode": "9a84e96f-3e8c-8f74-3b7a-50a1d3c2a130",
"stockTotal": 111
}
],
"updateStockTotal":false
}
Обновление отдельных полей варианта(PATCH /api/lite/products/variants)
/api/lite/products/variants
Обновляет одно или несколько полей варианта, значения отсутствующих в запросе полей при этом не изменяются.
Тело запроса аналогично POST /api/lite/products/variants
productId и variantId - необходимо указывать обязательно
Пример вызова:
{
"productId":"1002",
"variantId":"1024",
"barcodes":[
{
"value":"42353456345345",
"isDefault":true,
"type":"COMMON"
}
]
}
ответ аналогичен POST /api/lite/products/variants
Удаление варианта (DELETE /api/lite/products/variants)
/api/lite/products/variants
Удаляет вариант продукта.
Невозможно удалить единственный вариант продукта. Также, невозможно удалить вариант, у которого есть складские остатки.
Параметры запроса: productId - код продукта, variantId - код варианта
Упорядочить значения опций продукта (POST /api/lite/product/options/reorder)
/api/lite/product/options/reorder
Упорядочивает значения опций для указанного продукта.
Если данной опции не существует - значение пропускается.
Поле | Тип\формат | Описание |
productId | string | Идентификатор продукта, для которого создаются варианты |
options | array | Массив опций |
code | string |
Код опции |
values | string | Массив значений для данной опции в требуемом порядке. |
Пример вызова:
{
"productId": "1002",
"options": [
{
"code": "size",
"values": [
"S",
"M",
"L",
"XL"
]
},
{
"code": "color",
"values": [
"желтый",
"красный",
"синий",
"бело-синий"
]
}
]
}
/api/lite/file/image
Закачка картинки в облако
/api/lite/file/image
Закачка картинки в облако и получение url
Одновременно выполняет ресайз картинки в несколько разрешений, аналогично методу POST /api/lite/products/image
Принимает файл в виде multipart запроса в параметре upfile.
Хедер - только Authorization
Пример из Postman:
{
"success": true,
"url": "https://storage.yandexcloud.net/images-k2c/66ac26ec-08b2-4d4a-ae22-44c182847984.jpg",
"id": "66ac26ec-08b2-4d4a-ae22-44c182847984.jpg"
}
/api/lite/pub/products
Запрос указанного продукта (публичный)
/api/lite/pub/products
Метод возвращает продукты с вариантами.
Продукт всегда содержит хотя бы один вариант.
Фильтрация по полям товара:
Можно задавать фильтр параметром ?query=test - для фильтрации по полям article , humanId, shortName
Дополнительно можно фильтровать по конкректному продукту параметром ?id=1000
Также можно запрашивать конкретный вариант продукта полями variantId и variantExtId
Параметр available позволяет фильтровать скрытые товары. Если флаг не передан, скрытые товары не филтьруются(отображаются активные + скрытые)
Фильтрация по фильтрам, атрибутам, вариантам товара:
Фронтенд при выборе покупателем значений тех или иных фильтров должен составить поисковый GET запрос и передать его в метод 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 коллекций (можно передавать списком)
Пейджинация
Для пейджинации используются параметры page и size: size - заказов на странице, page - номер страницы.
Пример: /api/lite/products?page=0&size=200
Если параметры не переданы, то дефолтные значения page=0&size=100
Также, для отображение пейджинации следует анализировать параметр recordsTotal, возвращающий общее количество записей (с учетом примененной фильтрации, если она есть).
Сортировка
Для сортировки задается параметр order, принимающий код поля для сортировки и направление сортировки (asc, desc), отделенное символом плюса.
Пример сортировки по имени (возрастание): /api/lite/products?order=shortname+asc
Пример сортировки по имени (убывание): /api/lite/products?order=shortname+desc
Доступные коды сортировки:
- shortname
- article
- price
-
amount
- discount
Пример вызова с одновременной фильтрацией, пейджинацией и сортировкой:
/api/lite/products?query=Поло&order=shortname+asc&page=0&size=200
Последовательность применения поисковых критериев:
- Если задан id продукта - поиск идет только по нему. Выход из поиска
- Если задан variantId конкретного варианта товара - поиск идет по нему (по внутреннему или внешнему коду варианта, согласно настройке аккаунта). Выход из поиска
- Если заданы параметры filters, attributes, features - будет поиск по ним (включая совместно по их комбинациям). Если одновременно задан параметр collections - он будет учтен. Выход из поиска
- Если заданы параметры query или collections - будет поиск по ним (включая совместно по обоим). Выход из поиска
- Иначе выводятся все продукты с учетом запрошенного флага deleted
Поле | Тип\формат | Описание |
recordsTotal | num | Общее количество записей в рамках заданной фильтрации. Используется для пейджинации. |
products |
array | Перечень товарных предложений |
id | string | Идентификатор продукта |
extId | string | Внешний код продукта |
shortName | string | Наименование продукта |
description | string | Описание (может содержать html) |
available | boolean | Отображение для продажи в онлайн-магазине |
deleted | boolean | Архивная карточка |
reviewScore | decimal | Оценка товара |
variants | array | Массив вариантов |
id | string | Уникальный идентификатор варианта. |
extId | string | Внешний код варианта |
article | string | Артикул (sku) товара |
price | decimal | Цена продажи |
oldPrice | decimal | "Старая" цена. Для визуализации скидки. |
stock | object | Остатки товара на всех складах |
pos | num | Порядковый номер варианта, относительно |
optionsUsed | array | Массив, указывающий соответствие опции и её значения для конкретного продукта. Значения указываются как ссылки на значение из общего словаря опций. |
defaultImage | string | Ссылка на изображение из общего массива изображений. Может быть не задан. |
weight | decimal | Вес товара |
dimensions | object | Содержит информацию о размерах |
options | array | Словарь возможных опций для продукта, и также значений опций. Каждое значение опции имеет собственный идентификатор. |
id | string | Идентификатор опции |
name | string | Наименование |
name_plural | string | Наименование во множественном числе |
values | array | Массив значений данной опции |
images | array | Массив изображений продукта. Первое изображение считается основным. |
id | string | Идентификатор изображения |
url | string | URL изображения |
pos | decimal | Позиция изображения в рамках продукта |
collections | array | Массив коллекций, в которые входит продукт |
id | string | Идентификатор коллекции |
attributes | array | Массив значений атрибутов продукта |
id | string | Идентификатор атрибута |
type | enum | Тип атрибута (см. описание атрибутов) |
stringValue | string | Значение атрибута (строка) |
decimalValue | decimal | Значение атрибута (число) |
ordering | decimal | Cортировка |
anyPublicCollections | boolean | Есть хотя бы одна коллекция в каталоге с этим товаром |
Пример результата запроса:
{
"success": true,
"recordsTotal": 2,
"products": [
{
"id": "1002",
"extId": "",
"shortName": "Футболка",
"description": "<p><h1><strong>Лучшие</strong> футболки</h1><br></p>",
"available": true,
"deleted": false,
"reviewScore": 4.0,
"anyPublicCollections": true,
"variants": [
{
"id": "1005",
"extId": null,
"article": "",
"price": 990,
"oldPrice": 1200,
"stock": [
{
"warehouseCode": "a8064680-6f8c-830c-1ea1-0ab8a032e244",
"stockTotal": 40,
"stockAvailable": 38,
"stockReserved": 2
}
],
"ordering": 1,
"optionsUsed": [
{
"id": "size",
"value": "L"
}
],
"defaultImage": "8b16a469-2b8c-4df4-85f2-c9c9afa1f921",
"weight": 500,
"dimensions": {
"height": 5,
"width": 5,
"depth": 10
}
},
{
"id": "1006",
"extId": null,
"article": "",
"price": 990,
"oldPrice": 1200,
"stock": [
{
"warehouseCode": "a8064680-6f8c-830c-1ea1-0ab8a032e244",
"stockTotal": 40,
"stockAvailable": 38,
"stockReserved": 2
}
],
"ordering": 2,
"optionsUsed": [
{
"id": "size",
"value": "M"
}
],
"defaultImage": null,
"weight": 500,
"dimensions": {
"height": 5,
"width": 5,
"depth": 10
}
}
],
"images": [
{
"id": "8b16a469-2b8c-4df4-85f2-c9c9afa1f921",
"url": "https://img.kak2c.ru/i/f/g/IA33pVkwd.jpg?1564511037",
"pos": "10000.000000000000000"
},
{
"id": "8b16a469-2b8c-4df4-85f2-c9c9afa1b323",
"url": "https://img.kak2c.ru/i/f/g/IA33pVkw.jpg?1564511037",
"pos": "5000.00000"
}
],
"collections": [
"1029", "1031"
],
"attributes": [
{
"id": "material",
"type": "string",
"stringValue": "Хлопок 97%, эластан 3%",
"ordering": 1
}
]
}
]
}
Запрос списка брендов по всем продуктам (публичный)
/api/lite/pub/products/brands
Параметр
|
Тип\формат | Описание |
searchString |
string | (необязательный) |
Запрос возвращает список всех существующих брендов магазина. Если задан параметр 'searchString' - возвращает только те бренды, в которых есть вхождение этой строки(в любом месте). Регистр не важен
Пример ответа (/api/lite/pub/products/brands?searchString=кактус)
:
Пример запроса:
{
"brands": [
"Кактус Дейли",
"Кактус ПРО"
]
}
/api/lite/pub/products/filters
Получение блоков фильтров
/api/lite/pub/products/filters
Возвращает для заданной коллекции перечень блоков и фильтров в них для поиска товаров.
Блоки бывают трех типов - Для атрибутов, для опций, и другие. Атрибуты и опции выделены в отдельные блоки ввиду потенциально большого количества справочников и значений в них.
Блоки возвращаются в режиме для покупателя - загрузится список вручную сформированных блоков фильтров и выбранных значений фильтров, которые нужно отобразить покупателю.
Значения в атрибутах, опциях и пр. - автозаполняются по факту их использования в том или ином товаре. Это будет делаться асинхронно по регламенту, а не при исполнении запроса поиска, т.к. операция дорогая по времени.
Обязательный параметр запроса - ?collectionId=123
Фронтенд при выборе покупателем значений тех или иных фильтров должен составить поисковый GET запрос и передать его в метод 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
Поля возвращаемого значения:
Параметр | Тип\формат | Описание |
filterBlocks | array | Массив блоков |
id | string | Идентификатор блока |
type | enum | Тип блока. ATTRIBUTES (только атрибуты товаров), FEATURES (только опции товаров), OTHER (остальные поля товаров) |
mode | enum |
Режим работы блока. CUSTOMER (покупатель, отображены выбранные продавцом фильтры в блоке), CLIENT (продавец - отображены все возможные поля и блоки) |
ordering | integer | Сортировка |
collectionId | string | Идентификатор коллекции к которой относится данный блок фильтров |
filters | Массив | Перечень фильтров в блоке |
type | enum | Тип фильтра. PRICE, STOCK_AVAILABLE, SIZE, WEIGHT, COUNTRY_OF_ORIGIN, ATTRIBUTES, FEATURES, DISCOUNT_AVAILABLE, IS_NOVELTY, BRAND, IS_BESTSELLER |
ordering | integer | Сортировка |
fields | Массив | Поля фильтра |
name | string | Наименование поля |
nameReadable | string | Наименование поля, выводимое покупателю |
type | enum | Тип поля. string, decimal, boolean |
ordering | integer | Сортировка |
stringValues | Массив | Массив строковых значений поля |
decimalValues | Массив | Массив числовых значений поля |
Пример ответа:
{
"success": true,
"filterBlocks": [
{
"id": "1029",
"type": "OTHER", // ATTRIBUTES, FEATURES
"mode": "CUSTOMER", //CLIENT
"ordering": 10,
"collectionId": "123456"
"filters":[
{
"type":"PRICE", // STOCK_AVAILABLE, SIZE, WEIGHT, PRICE, ATTRIBUTES, FEATURES, DISCOUNT_AVAILABLE, IS_NOVELTY, BRAND, IS_BESTSELLER
"ordering": 10,
"fields":[
{
"name" : "field1",
"nameReadable": "Поле 1",
"type": "string", // decimal, boolean
"ordering": 10,
"stringValues": [
"value1", "value2"
]
},
{
"name" : "field2",
"nameReadable": "Поле 2",
"type": "decimal",
"ordering": 11,
"decimalValues": [
15.2, 16.8
]
},
{
"name" : "field3",
"nameReadable": "Поле 3",
"type": "boolean",
"ordering": 12
}
]
}
]
}
]
}
/api/lite/products/templates/items
Получение шаблона импорта номенклатуры
/api/lite/products/templates/items
В ответ возвращается в бинарном виде с типом application/octet-stream xls файл для выгрузки в браузер пользователю
Можно задавать ему название "ItemTemplate.xls"
Успех:
application/octet-stream
Ошибка:
status 500
{
"timestamp": "2020-04-03T10:38:46.343+0000",
"status": 500,
"error": "Internal Server Error",
"message": "12345",
"path": "/api/lite/settings/templates/items"
}
/api/lite/products/templates/items
Загружает на сервер xls файл (не xlsx) и производит анализ и формирование списка позиций для потенциального заказа.
Используется заголовок запроса Content-type: multipart/form-data. (аналогично методу POST /api/lite/products/image)
В качестве параметр запроса передается:
- upfile - xls файл
- searchColumn - поле поиска номенклатуры HUMANID | EXTID | ARTICLE | BARCODE
Xls файл для анализа должен быть исправленным файлом метода:
/api/lite/products/templates/items
(удалены ненужные строки, проставлены значения в колонки Цена, Количество, НДС).
Возвращаемые данные клиентское приложение может использовать для формирования списка позиций заказа/заказа поставщика
На сервере никакой документ не изменяется при этом.
В ответ возвращается информация о распознанных товарах в списке items и перечень предупреждений по строкам xls файла, елис такие возникли.
Успешные позиции в items можно использовать для формирования заказа, предупреждения можно отображать для пользователя.
Успех
{
"success": false,
"errors": [
{
"code": 0,
"message": "Найдены следующие ошибки в строке 10 : не указано количество; - Артикул , Серые"
},
{
"code": 0,
"message": "Найдены следующие ошибки в строке 12 : не найден товар по полю Код в kak2c и значению 12345 - Артикул 456, Голубые"
}
],
"items": [
{
"num": 1,
"variantId": "1021",
"productId": "1021",
"variantExtId":"EXT0029",
"name": "Розовые",
"article": "",
"quantity": 2,
"vatRate": "VAT_20",
"price": 0,
"barcode": "600000000212"
},
{
"num": 2,
"variantId": "1024",
"productId": "1024",
"name": "Красные",
"article": "",
"quantity": 3,
"vatRate": "VAT_20",
"price": 0
},
{
"num": 3,
"variantId": "1025",
"productId": "1025",
"name": "Фиолетовые",
"article": "",
"quantity": 4,
"vatRate": "VAT_20",
"price": 0
},
{
"num": 4,
"variantId": "1023",
"productId": "1023",
"name": "Оранжевые",
"article": "",
"quantity": 5,
"vatRate": "VAT_20",
"price": 0
},
{
"num": 5,
"variantId": "1027",
"productId": "1027",
"name": "Белые",
"article": "",
"quantity": 6,
"vatRate": "VAT_20",
"price": 0
},
{
"num": 6,
"variantId": "1019",
"productId": "1019",
"name": "Флуоресцентно зеленые",
"article": "",
"quantity": 1,
"vatRate": "VAT_20",
"price": 0
},
{
"num": 7,
"variantId": "1018",
"productId": "1018",
"name": "Синие",
"article": "",
"quantity": 2,
"vatRate": "VAT_20",
"price": 0
},
{
"num": 8,
"variantId": "1017",
"productId": "1017",
"name": "Черные",
"article": "",
"quantity": 3,
"vatRate": "VAT_20",
"price": 0
},
{
"num": 9,
"variantId": "1022",
"productId": "1022",
"name": "Флуоресцентно желтые",
"article": "",
"quantity": 5,
"vatRate": "VAT_20",
"price": 0
}
]
}
Ошибка
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}
/api/lite/products/additional_descriptions
Дополнительные описания – текстовые характеристики для описания номенклатуры. Используются для отображения дополнительной информации в карточке продукта. Не являются обязательными к заполнению.
Справочник заголовков описаний является общим для аккаунта и заполняется при добавлении описаний с новыми уникальными заголовками.
Запрос справочника заголовков
/api/lite/products/additional_descriptions/titles
Метод возвращает список всех когда-либо добавленных заголовков.
Поле | Тип / формат | Описание |
title | string | Заголовок |
pos | double | Число для сортировки |
Пример результата запроса:
{
"success": true,
"titles": [
{
"title": "Применение",
"pos": "1915616.000000000000000"
},
{
"title": "Ингридиенты",
"pos": "1915655.000000000000000"
}
]
}
/api/lite/products/reviews
Получение отзывов
/api/lite/products/reviews
Возвращает отзывы на товары. Отзывы отсортированы по дате создания, начиная с новых.
Фильтрация
?productId=1030
- для фильтрации по идентификатору товара
?status=NEW
- для фильтрации по статусу отзыва
Пейджинация
Для пейджинации используются параметры page и size: size - отзывов на странице, page - номер страницы.
Пример: /api/lite/products/reviews?page=0&size=200
Если параметры не переданы, то дефолтные значения page=0&size=100
Также, для отображение пейджинации следует анализировать параметр recordsTotal, возвращающий общее количество записей (с учетом примененной фильтрации, если она есть).
Поле | Тип / формат | Описание |
id | string | Идентификатор отзыва. |
product | object | Информация о товаре |
id | string | Идентификатор товара |
shortName | string | Название товара |
images | array | Изображения товара |
url | string | Ссылка на изображение |
id | string | Имя файла |
pos | double | Позиция |
createTs | datetime | Время создания отзыва |
customerName | string |
Имя автора отзыва |
content | string |
Текст отзыва |
score | decimal |
Оценка (от 1 до 5) |
status | enum |
Статус отзыва
|
Пример результата запроса:
{
"success": true,
"recordsTotal": 1,
"reviews": [
{
"id": "e7951e18-8ee3-61b2-b616-018331a8fb06",
"product": {
"id": "1030",
"shortName": "Масло для бороды Бунтарь - Дамаск",
"images": [
{
"url": "https://storage.yandexcloud.net/images-k2c/aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"id": "aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"pos": "10000.000000000000000"
}
]
},
"createTs": "2020-08-07 19:35:36",
"customerName": "Петя",
"content": "текст отзыва",
"score": 5,
"status": "NEW"
}
]
}
Редактирование отзывов
/api/lite/products/reviews
Редактирует отзыв.
Пример запроса
{
"id": "6c62461f-fcf4-c388-c3b4-e09971590d6b",
"customerName": "Петя",
"content": "текст отзыва",
"status": "CONFIRMED"
}
В ответ возвращается
Успех:
{
"success": true,
"review": {
"id": "6c62461f-fcf4-c388-c3b4-e09971590d6b",
"product": {
"id": "1030",
"shortName": "Масло для бороды Бунтарь - Дамаск",
"images": [
{
"url": "https://storage.yandexcloud.net/images-k2c/aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"id": "aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"pos": "10000.000000000000000"
}
]
},
"createTs": "2020-08-07 18:53:46",
"customerName": "Петя",
"content": "текст отзыва",
"score": 5,
"status": "CONFIRMED"
}
}
Ошибка:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}
/api/lite/pub/products/reviews
Получение отзывов
/api/lite/pub/products/reviews
Возвращает подтвержденные отзывы на товары. Отзывы отсортированы по дате создания, начиная с новых.
?productId=1030
- обязательный параметр для фильтрации по идентификатору товара
Пейджинация
Для пейджинации используются параметры page и size: size - отзывов на странице, page - номер страницы.
Пример: /api/lite/pub/products/reviews?page=0&size=200
Если параметры не переданы, то дефолтные значения page=0&size=100
Также, для отображение пейджинации следует анализировать параметр recordsTotal, возвращающий общее количество записей (с учетом примененной фильтрации, если она есть).
Поле | Тип / формат | Описание |
id | string | Идентификатор отзыва. |
product | object | Информация о товаре |
id | string | Идентификатор товара |
shortName | string | Название товара |
images | array | Изображения товара |
url | string | Ссылка на изображение |
id | string | Имя файла |
pos | double | Позиция |
createTs | datetime | Время создания отзыва |
customerName | string |
Имя автора отзыва |
content | string |
Текст отзыва |
score | decimal |
Оценка (от 1 до 5) |
status | enum |
Статус отзыва
|
Пример результата запроса:
{
"success": true,
"recordsTotal": 1,
"reviews": [
{
"id": "e7951e18-8ee3-61b2-b616-018331a8fb06",
"product": {
"id": "1030",
"shortName": "Масло для бороды Бунтарь - Дамаск",
"images": [
{
"url": "https://storage.yandexcloud.net/images-k2c/aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"id": "aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"pos": "10000.000000000000000"
}
]
},
"createTs": "2020-08-07 19:35:36",
"customerName": "Петя",
"content": "текст отзыва",
"score": 5,
"status": "CONFIRMED"
}
]
}
Создание отзывов
/api/lite/pub/products/reviews
Добавляет новый отзыв.
Пример запроса
{
"productId": "1030",
"customerName": "Петя",
"content": "текст отзыва",
"score": 5
}
В ответ возвращается
Успех:
{
"success": true,
"review": {
"id": "6c62461f-fcf4-c388-c3b4-e09971590d6b",
"product": {
"id": "1030",
"shortName": "Масло для бороды Бунтарь - Дамаск",
"images": [
{
"url": "https://storage.yandexcloud.net/images-k2c/aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"id": "aff3c7f1-8b7c-47ea-a3a9-e9a52e476c12.jpg",
"pos": "10000.000000000000000"
}
]
},
"createTs": "2020-08-07 18:53:46",
"customerName": "Петя",
"content": "текст отзыва",
"score": 5,
"status": "NEW"
}
}
Ошибка:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}
/api/lite/products/features/appearance
По свойствам продуктов можно задавать дополнительно код цвета и url картинки
Запрос свойств отображения по продукту
/api/lite/products/features/appearance
Метод возвращает список кодов и url по используемым в данном продукте свойствам
обязательный параметр - id продукта
Пример результата запроса:
{
"success": true,
"appearanceFields": [
{
"feature": "color",
"value": "Синие",
"code": "#252525",
"imageUrl": ""
},
{
"feature": "color",
"value": "Черные",
"code": "#335522",
"imageUrl": "https://i.mycdn.me/image?id=803347578459&plc=WEB&tkn=*JEEWXMlfdErrCiuXFgcM6G0WGxs&fn=sqr_288"
}
]
}
Создание/обновление свойств отображения
/api/lite/products/features/appearance
Создает или обновляет свойства отображения (code, imageUrl) для указанного продукта + опции + значения опции.
Пример создания/обновления атрибута:
{
"productId": "1003",
"feature": "color",
"value": "Черные",
"code": "#335522",
"imageUrl": "https://i.mycdn.me/image?id=803347578459&plc=WEB&tkn=*JEEWXMlfdErrCiuXFgcM6G0WGxs&fn=sqr_288"
}
/api/lite/pub/products/features/appearance
По свойствам продуктов можно запрашивать дополнительно код цвета и url картинки
Запрос свойств отображения по продукту
/api/lite/pub/products/features/appearance
Метод возвращает список кодов и url по используемым в данном продукте свойствам
обязательный параметр - id продукта
Пример результата запроса:
{
"success": true,
"appearanceFields": [
{
"feature": "color",
"value": "Синие",
"code": "#252525",
"imageUrl": ""
},
{
"feature": "color",
"value": "Черные",
"code": "#335522",
"imageUrl": "https://i.mycdn.me/image?id=803347578459&plc=WEB&tkn=*JEEWXMlfdErrCiuXFgcM6G0WGxs&fn=sqr_288"
}
]
}
/api/lite/products/export_ff
Выгрузка номенклатуры в Темполайн
/api/lite/products/export_ff
Создает/обновляет указанную номенклатуру в складской системе
Пример вызова:
{
"warehouseCode": "2970c244-20f4-bab8-4c29-b04504281120",
"products": ["1042"]
}
Пример успешного ответа
{
"success": true
}
В случае ошибки:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}
/api/lite/products/accounting_attributes
Атрибуты учета – дополнительные характеристики для учета товара при отгрузке. Используются для проверки уникальных номеров товара. Не являются обязательными к заполнению.
Справочник атрибутов является общим для аккаунта.
Значения атрибутов задаются в информации о продуктах.
Запрос справочника атрибутов
/api/lite/products/accounting_attributes
Метод возвращает список всех доступных атрибутов.
Поле | Тип / формат | Описание |
id | string | Идентификатор атрибута. |
code | string | Код атрибута - латиницей |
title | string | Наименование атрибута |
values | array | Справочник значений атрибута |
stringValue | string | Значение |
Пример результата запроса:
{
"success": true,
"attributes": [
{
"id": "a629bb7c-331e-ef94-ebac-5955731bf142",
"code": "chestnyznak",
"title": "Честный знак",
"values": [
{
"stringValue": "1111"
},
{
"stringValue": "2222"
}
]
}
]
}
Создание/обновление атрибута
/api/lite/products/accounting_attributes
Создает или обновляет атрибут.
Code атрибута при создании/обновлении - обязательное поле, он задается явно для каждого атрибута.
Пример создания/обновления атрибута:
{
"code": "chestnyznak",
"title": "Честный знак",
"values": [
{
"stringValue": "1111"
},
{
"stringValue": "2222"
}
]
}
/api/lite/products/stock_revise
Сверка остатков с Темполайн
/api/lite/products/stock_revise
Возвращает списки расхождений по товарам
Параметр warehouse_id - ид склада(необязательный). Если не указан, автоматически ищется склад с типом FULFILLMENT
/api/lite/products/stock_revise?warehouse_id=e147712f-172c-8c1c-12e6-0feb0e4968c7
Пример успешного ответа
{
"success": true,
"moreItems": [
{
"item": {
"variantId": "demo1027",
"productId": "demo1009",
"name": "тест",
"img": "https://storage.yandexcloud.net/images-k2c/bb514759-b917-45fb-8267-8541ec586451.jpg",
"barcode": "6412600817669"
},
"available": 96,
"reserved": 0,
"external": 95,
"diff": 1,
"afterCorrection": 95,
"reviseError": false
},
{
"item": {
"variantId": "demo1031",
"productId": "demo1013",
"name": "Футболка №2 (демо товар)",
"img": "https://storage.yandexcloud.net/images-k2c/ce86c7c0-2b17-4d84-a914-c00d2d027b88.png",
"barcode": ""
},
"available": 3,
"reserved": 2,
"external": 0,
"diff": 3,
"afterCorrection": 2,
"reviseError": false
}
],
"lessItems": [
{
"item": {
"variantId": "demo1032",
"variantExtId": "ext12313123",
"productId": "demo1014",
"name": "Наушники",
"article": "121234134",
"img": "https://storage.yandexcloud.net/images-k2c/3d526d88-dcd8-48e6-8f45-9b09a19026ca.png",
"barcode": "6412600817222"
},
"available": 44,
"reserved": 32,
"external": 46,
"diff": 2,
"afterCorrection": 46,
"reviseError": false
},
{
"item": {
"variantId": "demo1000",
"productId": "demo1000",
"name": "Кактус Эуфобия Триангуларис",
"barcode": ""
},
"available": 67,
"reserved": 21,
"external": 68,
"diff": 1,
"afterCorrection": 68,
"reviseError": false
}
]
}
В случае ошибки:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}
/api/lite/products/wb_categories
Запрос категорий товаров Wildberries
/api/lite/products/wb_categories
Получает список вариантов категорий товаров для Wildberries
Пример результата запроса:
{
"success": true,
"categories": [
{
"title": "Общая категория",
"code": "COMMON",
"wbCode": "1"
},
{
"title": "Косметика, бытовая химия и питание",
"code": "COSMETICS_AND_HOUSEHOLD_CHEMICALS",
"wbCode": "2"
},
{
"title": "Верхняя одежда и товары на вешалках",
"code": "CLOTHES",
"wbCode": "3"
},
{
"title": "Обувь и товар в коробках",
"code": "FOOTWEAR",
"wbCode": "4"
},
{
"title": "Книжная продукция и полиграфия",
"code": "BOOKS",
"wbCode": "5"
},
{
"title": "Текстильные товары и аксессуары",
"code": "TEXTILE_AND_ACCESSORIES",
"wbCode": "6"
},
{
"title": "Товары из кожи",
"code": "LEATHER",
"wbCode": "7"
},
{
"title": "Посуда и кухонные принадлежности",
"code": "DISHES",
"wbCode": "8"
},
{
"title": "Очки и оправы",
"code": "GLASSES",
"wbCode": "9"
},
{
"title": "Товары для взрослых",
"code": "PRODUCTS_FOR_ADULTS",
"wbCode": "10"
},
{
"title": "Грунт",
"code": "SOIL",
"wbCode": "11"
},
{
"title": "Ювелирная продукция",
"code": "JEWELRY",
"wbCode": "12"
},
{
"title": "Продукты питания и зоотовары",
"code": "FOOD_AND_PET_SUPPLIES",
"wbCode": "13"
}
]
}
/api/lite/products/delete_barcodes_ff
Удаление ШК у номенклатуры в Темполайн
/api/lite/products/delete_barcodes_ff
Удаляет ШК у указанной номенклатуры в складской системе
Массив строк "barcodes" является приоритетным в поиске. Если он не пустой, поиск по id продукта не происходит
Пример вызова:
{
"warehouseCode": "2970c244-20f4-bab8-4c29-b04504281120",
"barcodes": ["4607043102393"]
"products": ["1042"]
}
Пример успешного ответа
{
"success": true
}
В случае ошибки:
{
"success": false,
"errors": [
{
"code": 0,
"message": "Текст ошибки"
}
]
}
/api/lite/products/history
Запрос истории изменения товаров
/api/lite/products/history
Метод возвращает список изменений по товару.
параметры:
productId - идентификатор продукта
page - страница результатов (по умолчанию 0)
size - число записей на странице (по умолчанию, 5)
jsonData - json товара, в формате /api/lite/products, если не передан, то jsonData не возвращается
id - идентификатор эвента(например, c9ae018d-2163-069c-b2fa-b46077652a73)
GET api/lite/products/history?productId=new0001
Пример результата запроса:
{
"events": [
{
"changeSource": "USER",
"description": "",
"eventDate": "2022-02-15 15:34:33.444",
"eventParameters": {
"from": "POST /products"
},
"id": "c9ae018d-2163-069c-b2fa-b46077652a73",
"level": "INFO",
"success": true,
"type": "SKU",
"userLogin": "z@z.zz"
},
{
"changeSource": "XLS",
"description": "",
"eventDate": "2022-02-15 15:32:58.070",
"eventParameters": {
"from": "XlsProductControllerService.sendProductMessages"
},
"id": "0c654d32-b1e3-d931-43ec-f92c01341806",
"level": "INFO",
"success": true,
"type": "SKU",
"userLogin": "z@z.zz"
}
],
"recordsTotal": 2,
"success": true
}
GET api/lite/products/history?id=c9ae018d-2163-069c-b2fa-b46077652a73
Пример результата запроса:
{
"events": [
{
"changeSource": "USER",
"description": "",
"eventDate": "2022-02-15 15:34:33.444",
"eventParameters": {
"from": "POST /products"
},
"id": "c9ae018d-2163-069c-b2fa-b46077652a73",
"jsonData": "{\"anyPublicCollections\":false,\"available\":true,\"brandName\":\"Levi's\",\"collections\":[\"1001\"],\"deleted\":false,\"description\":\"922\",\"expirationMode\":\"NO_EXPIRATION\",\"id\":\"new0001\",\"internationalDescription\":\"0\",\"isBestseller\":false,\"isNovelty\":false,\"shortName\":\"Джинсы (демо товар)1\",\"type\":\"SKU\",\"useBatchAccounting\":false,\"variants\":[{\"id\":\"100002\",\"isFfPhysicalSetSynchronized\":false,\"isFfSynchronised\":true,\"isPhysicalSet\":false,\"ordering\":\"1971940.000000000000000\",\"stock\":[{\"stockAvailable\":0,\"stockDefective\":0,\"stockDefectiveReserved\":0,\"stockReserved\":0,\"stockTotal\":0,\"warehouseCode\":\"27f650d9-7378-33c1-bae1-6aea66140bbd\"},{\"stockAvailable\":0,\"stockDefective\":0,\"stockDefectiveReserved\":0,\"stockReserved\":0,\"stockTotal\":0,\"warehouseCode\":\"374f35a6-633f-bc9d-917a-ce37cb74bd49\"}],\"type\":\"SKU\",\"vat\":\"NO_VAT\"}],\"vat\":\"NO_VAT\"}",
"level": "INFO",
"success": true,
"type": "SKU",
"userLogin": "z@z.zz"
}
],
"recordsTotal": 1,
"success": true
}
/api/lite/products/history/diff
Запрос разницы между двумя состояниями истории товара
/api/lite/products/history/diff
Метод возвращает список человекочитаемых изменений товара.
leftId и rightId - идентификаторы записей истории изменений товара, полученных в методе /api/lite/products/history
Пример запроса:
{
"items":[
{
"leftId":"8df52d29-7f75-c272-6894-d2c00e653c8c",
"rightId":"a5c42f70-c634-21cf-b25e-f2e585db221e"
},
{
"leftId":"63120d8b-b0b5-145e-ff44-d1bea50a77e7",
"rightId":"8df52d29-7f75-c272-6894-d2c00e653c8c"
}
]
}
Пример результата запроса:
{
"items": [
{
"diff": "Цена: \"21000.00\" -> \"20000.00\", Розничная цена: \"21000.00\" -> \"20000.00\", Габариты: \"Ш:101 В:60 Г:30\" -> \"Ш:100 В:60 Г:30\"",
"leftId": "8df52d29-7f75-c272-6894-d2c00e653c8c",
"rightId": "a5c42f70-c634-21cf-b25e-f2e585db221e"
},
{
"diff": "Название: \"Компьютер (демо товар)2\" -> \"Компьютер (демо товар)1\"",
"leftId": "63120d8b-b0b5-145e-ff44-d1bea50a77e7",
"rightId": "8df52d29-7f75-c272-6894-d2c00e653c8c"
}
],
"success": true
}
/api/lite/products/batch
Создание/обновление нескольких продуктов (POST /api/lite/products/batch)
/api/lite/products/batch
Создает или обновляет продукты, переданные списком. Ограничение - 1000 продуктов.
Структура продуктов в списке аналогична методу POST /api/lite/products
Пример вызова:
{
"products":[
{
"id":"BATCH2500",
"shortName":"BATCH2500",
"variantsToUpdate":[
{
"variantId":"BATCH2500",
"productId":"BATCH2500",
"barcodes":[
{
"value":"bc9194352",
"isDefault":true
}
]
}
]
},
{
"id":"BATCH2501",
"shortName":"BATCH2501",
"variantsToUpdate":[
{
"variantId":"BATCH2501",
"productId":"BATCH2501",
"barcodes":[
{
"value":"bc7216735",
"isDefault":true
}
]
}
]
},
{
"id":"BATCH2502",
"shortName":"BATCH2502",
"variantsToUpdate":[
{
"variantId":"BATCH2502",
"productId":"BATCH2502",
"barcodes":[
{
"value":"bc6271942",
"isDefault":true
}
]
}
]
}
]
}
Пример положительного ответа:
{
"finishTime": "2022-03-29 19:14:47",
"products": [
{
"id": "BATCH2500",
"product": {
"available": true,
"collections": [
"1001"
],
"deleted": false,
"id": "BATCH2500",
"shortName": "BATCH2500",
"type": "SKU",
"useBatchAccounting": false,
"variants": [
{
"barcodes": [
{
"isDefault": true,
"type": "COMMON",
"value": "bc9900111"
}
],
"id": "BATCH2500",
"isFfPhysicalSetSynchronized": false,
"isFfSynchronised": true,
"isPhysicalSet": false,
"ordering": "1976406.000000000000000",
"stock": [
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "5cb8dd66-836d-6c1a-a84b-e71fcf97104c"
},
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "e55cd8ab-09f3-26b7-00df-27e3642f5b79"
}
],
"type": "SKU",
"vat": "NO_VAT"
}
],
"vat": "NO_VAT"
},
"success": true,
"variantsResult": [
{
"productId": "BATCH2500",
"success": true,
"variantId": "BATCH2500"
}
]
},
{
"id": "BATCH2501",
"product": {
"available": true,
"collections": [
"1001"
],
"deleted": false,
"id": "BATCH2501",
"shortName": "BATCH2501",
"type": "SKU",
"useBatchAccounting": false,
"variants": [
{
"barcodes": [
{
"isDefault": true,
"type": "COMMON",
"value": "bc5524020"
}
],
"id": "BATCH2501",
"isFfPhysicalSetSynchronized": false,
"isFfSynchronised": true,
"isPhysicalSet": false,
"ordering": "1976406.000000000000000",
"stock": [
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "5cb8dd66-836d-6c1a-a84b-e71fcf97104c"
},
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "e55cd8ab-09f3-26b7-00df-27e3642f5b79"
}
],
"type": "SKU",
"vat": "NO_VAT"
}
],
"vat": "NO_VAT"
},
"success": true,
"variantsResult": [
{
"productId": "BATCH2501",
"success": true,
"variantId": "BATCH2501"
}
]
},
{
"id": "BATCH2502",
"product": {
"available": true,
"collections": [
"1001"
],
"deleted": false,
"id": "BATCH2502",
"shortName": "BATCH2502",
"type": "SKU",
"useBatchAccounting": false,
"variants": [
{
"barcodes": [
{
"isDefault": true,
"type": "COMMON",
"value": "bc6869740"
}
],
"id": "BATCH2502",
"isFfPhysicalSetSynchronized": false,
"isFfSynchronised": true,
"isPhysicalSet": false,
"ordering": "1976406.000000000000000",
"stock": [
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "5cb8dd66-836d-6c1a-a84b-e71fcf97104c"
},
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "e55cd8ab-09f3-26b7-00df-27e3642f5b79"
}
],
"type": "SKU",
"vat": "NO_VAT"
}
],
"vat": "NO_VAT"
},
"success": true,
"variantsResult": [
{
"productId": "BATCH2502",
"success": true,
"variantId": "BATCH2502"
}
]
}
],
"startTime": "2022-03-29 19:14:47",
"success": true
}
Пример положительного ответа с ошибкой сохранения:
{
"finishTime": "2022-03-29 19:22:30",
"products": [
{
"errors": [
{
"code": 0,
"message": "Заданный ID продукта \"№BATCH2500\" не соответствует требованиям: ID должен содержать только цифры, латиницу, тире, подчеркивание, #, или точку "
}
],
"success": false
},
{
"id": "BATCH2501",
"product": {
"available": true,
"collections": [
"1001"
],
"deleted": false,
"id": "BATCH2501",
"shortName": "BATCH2501",
"type": "SKU",
"useBatchAccounting": false,
"variants": [
{
"barcodes": [
{
"isDefault": true,
"type": "COMMON",
"value": "bc7216735"
}
],
"id": "BATCH2501",
"isFfPhysicalSetSynchronized": false,
"isFfSynchronised": true,
"isPhysicalSet": false,
"ordering": "1976406.000000000000000",
"stock": [
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "5cb8dd66-836d-6c1a-a84b-e71fcf97104c"
},
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "e55cd8ab-09f3-26b7-00df-27e3642f5b79"
}
],
"type": "SKU",
"vat": "NO_VAT"
}
],
"vat": "NO_VAT"
},
"success": true,
"variantsResult": [
{
"productId": "BATCH2501",
"success": true,
"variantId": "BATCH2501"
}
]
},
{
"id": "BATCH2502",
"product": {
"available": true,
"collections": [
"1001"
],
"deleted": false,
"id": "BATCH2502",
"shortName": "BATCH2502",
"type": "SKU",
"useBatchAccounting": false,
"variants": [
{
"barcodes": [
{
"isDefault": true,
"type": "COMMON",
"value": "bc6271942"
}
],
"id": "BATCH2502",
"isFfPhysicalSetSynchronized": false,
"isFfSynchronised": true,
"isPhysicalSet": false,
"ordering": "1976406.000000000000000",
"stock": [
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "5cb8dd66-836d-6c1a-a84b-e71fcf97104c"
},
{
"stockAvailable": 0,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockReserved": 0,
"stockTotal": 0,
"warehouseCode": "e55cd8ab-09f3-26b7-00df-27e3642f5b79"
}
],
"type": "SKU",
"vat": "NO_VAT"
}
],
"vat": "NO_VAT"
},
"success": true,
"variantsResult": [
{
"errors": [
{
"code": 0,
"message": "Штрихкод bc7216735 уже используются в варианте [BATCH2501] BATCH2501, ШК: bc7216735 "
}
],
"productId": "BATCH2502",
"success": false,
"variantId": "BATCH2502"
}
]
}
],
"startTime": "2022-03-29 19:22:30",
"success": true
}
Обновление отдельных полей нескольких продуктов (PATCH /api/lite/products/batch)
/api/lite/products/batch
Обновляет одно или несколько полей продукта, значения отсутствующих в запросе полей при этом не изменяются.
Тело запроса аналогично POST /api/lite/products/batch
id - необходимо указывать обязательно
Пример вызова:
{
"products":[
{
"id":"1015",
"shortName":"Limited Edition Паста (помада) для укладки волос",
"internationalDescription":"abc"
},
{
"id":"1016",
"shortName":"Товар 2"
}
]
}
ответ аналогичен POST /api/lite/products/batch
/api/lite/products/batch/accounting/stocks
Запрос остатков по партиям товаров (GET/api/lite/products/batch/accounting/stocks)
/api/lite/products/batch/accounting/stocks
Запрос остатков по товарам, для которых ведется учет по партиям.
Пример вызова:
GET/api/lite/products/batch/accounting/stocks?warehouseCode=12345&variantId=1234&format=json
warehouseCode - Код склада, обязательный
variantId - список id вариантов товаров, через запятую, опциональный
format - формат данных - json или xls, опциональный. В случае xls в ответе будет ссылка на файл
Пример положительного ответа:
{
"items": [
{
"batchAccountingStocks": [
{
"available": 50,
"batchAccountingNumber": "2478 01.01.2033 0:00:00",
"expirationDays": 0,
"expirationDaysLimit": 0,
"productionDate": "2022-11-01",
"expirationDate": "2022-12-01",
"manufacturer": "",
"manufacturerRequisites": "",
"useBatchAccounting": true,
"useExpiration": true
},
{
"available": 8,
"batchAccountingNumber": "2478 09.01.2021 0:00:00",
"expirationDays": 0,
"expirationDaysLimit": 0,
"productionDate": "2022-11-01",
"expirationDate": "2022-12-01",
"manufacturer": "",
"manufacturerRequisites": "",
"useBatchAccounting": true,
"useExpiration": true
},
{
"available": 52,
"batchAccountingNumber": "2478 09.08.2025 0:00:00",
"expirationDays": 0,
"expirationDaysLimit": 0,
"productionDate": "2022-11-01",
"expirationDate": "2022-12-01",
"manufacturer": "",
"manufacturerRequisites": "",
"useBatchAccounting": true,
"useExpiration": true
}
],
"variantId": "2478"
}
],
"success": true
}
{
"file": "https://link_to_file.xls",
"success": true
}
/api/lite/products/variants/batch
Обновление отдельных полей нескольких вариантов(PATCH /api/lite/products/variants/batch)
/api/lite/products/variants/batch
Обновляет одно или несколько полей варианта, значения отсутствующих в запросе полей при этом не изменяются.
productId и variantId - необходимо указывать обязательно
Пример вызова:
{
"variantsToUpdate":[
{
"weight":200000,
"productId":"demo1012",
"variantId":"demo1030",
"extId":"11011"
},
{
"weight":233,
"productId":"demo1013",
"variantId":"demo1031",
"extId":"11012"
}
]
}
API загрузки уникальных номеров номенклатуры в Кактус
Загрузка уникальных номеров через json файл
/api/lite/products/load/unique_number/json
Пример вызова:
{
"items" : [
{
"variantId" : "1000",//variant_id номенклатуры
"uniqueNumbers" : [
{
"uniqueNumber" : "1232344456777",//уникальный номер
"type" : "UIT"// пока только UIT
}
]
}
]
}
Пример успешного ответа
{
"success": true
}
Загрузка уникальных номеров через excel файл
/api/lite/products/load/unique_number/excel
Эксель файл должен быть в формате xls, в первой колонке varian_id номенклатуры, вторая колонка уникальный номер, третья тип уникального номера. Например 1000, njkjnw9i98, UIT.
upFile - файл excel в formData.
Пример успешного ответа
{
"success": true
}
Получить список загруженных уникальных номеров номенклатуры
/api/lite/products/unique_numbers/list?variantId=1000&isUsed=false&page=0&size=10
variantId - ид варианта номенклатуры
isUsed - использованный/не использованные уникальные номенклатуры
page и size - для пагинации
Пример успешного ответа
{
"success": true,
"uniqueNumbers": [
{
"disabled": false,
"isReserved": false,
"physicalSet": "",
"purchaseOrder": "",
"uniqueNumber": "0104064211748539215%HefMSHYlegL9100BE92IlF/M3RjtFd4KI5xnWnri5ZHCNIlndYdSVKLoG2VvWg3BZ3dPM1EnijDoPSuNJmVI63clfwHgXLVy3vDCXKvnw==",
"type": "UIT"
},
{
"disabled": false,
"isReserved": false,
"physicalSet": "",
"purchaseOrder": "",
"uniqueNumber": "0104064211296115217>dGPovOMpiDH␝918093␝92gbLYtaYLYnFIUsQilCOiicPOKJZMiuKKUeAIvO3R9wgWoEip5FjubkxPpXsOuCr9N4nMGXuD6VgS8oK/jkfvJw==␝",
"type": "UIT"
}
]
}
Получить уникальный номер для номенклатуры, поставке или комплектации
/api/lite/products/unique_number
Данный метод возвращает уникальный номер, и ставит галку что данный уникальный номер зарезервирован.
variant_id - ид варианта номенклатуры
type_unique_number - тип уникального номера
id(необязательный) - номер документа(поставки, комплектации)
doc_type - тип документа (PURCHASE_ORDER, PHYSICAL_SET_ORDER)
Пример успешного ответа
{
"success" : true,
"variantId" : "1000",
"uniqueNumber" : "mlkmkjnjkmkjnjk"
}
Проставить флаг использования уникальному номеру
/api/lite/products/unique_number/used
Пример вызова:
{
"variantId" : "1000",
"uniqueNumber" : "njkdhbjcs"
}
Данный метод ставит флаг что данный уникальный номер использован.
Пример успешного ответа
{
"success": true
}
/api/lite/products/variants/eshop_settings
Изменение внешних кодов для интеграций (POST /api/lite/products/variants/eshop_settings)
/api/lite/products/variants/eshop_settings
Обновляет настройки для вариантов. Ограничение - 1000 вариантов.
Пример вызова:
{
"variants": [
{
"variantId": "1000",
"eshopSettings": [
{
"enabled": true,
"eshopId": "44fce711-e809-59ed-895a-661a32886d7f",
"extId": "HTW-LX3",
"zeroStock": true
},
{
"enabled": true,
"eshopId": "4f4509b3-3b5b-1474-cabd-dfe8fce1b9ca",
"extId": "HTW-LX3"
}
]
}
]
}
Пример положительного ответа:
{
"success": true,
"variants": [
{
"success": true,
"variantId": "1000"
}
]
}
Пример положительного ответа с ошибкой сохранения:
{
"success": true,
"variants": [
{
"success": false,
"errors": [
{
"code": 0,
"message": "Не найдена интеграция с указанным ID"
}
],
"variantId": "1000"
}
]
}
/api/lite/products/warehouse/categories
Категории товаров (продуктов) хранятся в таблице oms_domain_sku_category. Кактус еженочно синхронизируется с WMS, получая оттуда актуальные категории.
Запрос справочника атрибутов
/api/lite/products/warehouse/categories
Метод возвращает список категорий товаров.
Поле | Тип / формат | Описание |
format | string | Формат ответа (json/xls) |
Пример результата запроса:
{
"items": [
{
"code": "weak",
"title": "Хрупкое"
},
{
"code": "strong",
"title": "Сильное"
},
{
"code": "bubble",
"title": "Булькающее"
}
],
"success": true
}
/api/lite/products/stocks
Метод возвращает остатки товарных предложений (с возможностью фильтрации по дате изменения остатков).
Запрос остатков
/api/lite/products/stocks
Параметры запроса:
stock_updated_from - дата, с момента которой изменились остатки, формат yyyy-MM-dd'T'HH:mm:ss[.SSS]
Пример: /api/lite/products/stocks?stock_updated_from=2024-05-21T00:00:00.000
Пейджинация
Для пейджинации используются параметры page и size: size - заказов на странице, page - номер страницы.
Пример: /api/lite/products/stocks?page=0&size=200
Если параметры не переданы, то дефолтные значения page=0&size=1000
Максимальное количество записей на одной странице - 100 000. Даже если указано значение более 100 000
Пример результата запроса:
"id": "215606" - ИД варианта
{
"recordsTotal": 2873,
"success": true,
"variants": [
{
"id": "215606",
"stock": [
{
"stockAvailable": 8,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockExpired": 0,
"stockReserved": 2,
"stockTotal": 10,
"warehouseCode": "d7a490e3-7dd6-0104-60b6-ca222b03bf18"
}
]
},
{
"id": "213485",
"stock": [
{
"stockAvailable": 25,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockExpired": 0,
"stockReserved": 1,
"stockTotal": 26,
"warehouseCode": "d7a490e3-7dd6-0104-60b6-ca222b03bf18"
}
]
},
{
"id": "206949",
"stock": [
{
"stockAvailable": 14,
"stockDefective": 0,
"stockDefectiveReserved": 0,
"stockExpired": 0,
"stockReserved": 1,
"stockTotal": 15,
"warehouseCode": "d7a490e3-7dd6-0104-60b6-ca222b03bf18"
}
]
}
]
}