QUINCE API. Товари
Список методів
| Метод | Опис |
|---|---|
/api/v2/product/list | Отримання списку товарів |
/api/v2/product/add | Створення товарів |
/api/v2/product/update | Оновлення товарів |
/api/v2/product/markasdelete | Видалення або архівування товару |
/api/v2/product/restore | Відновлення товару з архіву |
/api/v2/product/folder/list | Отримання списку папок товарів |
/api/v2/product/folder/add | Створення папок товарів |
/api/v2/product/folder/update | Оновлення папок товарів |
Отримання списку товарів
Назва методу: /api/v2/product/list
Повертає список товарів. Для навігації використовується номер сторінки page. Розмір сторінки фіксований і дорівнює 100 елементам.
Параметри запиту
| Поле | Тип | Опис |
|---|---|---|
filter | object | Необов’язковий фільтр. Поля фільтра працюють з логікою AND. |
filter.ParentFolder | array | Ідентифікатори папок. Значення перетворюються в список через кому. Передайте null або порожній масив, щоб отримати товари першого рівня. |
filter.FolderRecursive | boolean | Керує глибиною вибірки за filter.ParentFolder. За замовчуванням true: повертаються товари вказаних папок і всіх вкладених підпапок. Передайте false, щоб отримати тільки прямий вміст указаних папок. |
filter.Id | integer | Ідентифікатор товару. |
filter.Name | string | Назва товару. |
filter.Article | string | Артикул. |
filter.Barcode | string | Штрихкод. |
filter.Search | string | Пошуковий рядок. |
filter.PriceType | array | Ідентифікатори типів цін, які треба повернути в блоці Prices. |
filter.Date | string | Дата, для якої розрахувати ціни в Prices і знижки акцій. Формат: yyyy-mm-dd. Якщо не передати, використовується поточна дата сервера. На залишки та інші дані товару не впливає. |
filter.IncludePromotions | boolean | Якщо true, у ціни додаються поля з розрахованою знижкою акції. За замовчуванням false, як у попередніх версіях API. |
filter.Store | array | Ідентифікатори складів, для яких треба повернути Stock. |
filter.Archive | boolean | Ознака повернення архівних товарів. |
filter.Kind | string | Тип товару: P - товар, K - набір, M - модифікація, U - товар SKU, B - базовий товар SKU. Якщо не передано або передано невідоме значення, використовується P. |
filter.LastChangeTime | string | Дата й час останньої зміни товару, ціни або залишків. Повертає товари зі змінами від цієї дати. |
filter.MobileApp | boolean | Якщо true, API використовує збільшений ліміт вибірки. |
page | integer | Номер сторінки. Якщо не передати, використовується перша сторінка. |
Якщо Store не передано, API повертає залишки для всіх складів. Для Kind: K і Kind: B залишки не повертаються.
Значення filter.FolderRecursive за замовчуванням збережене для сумісності з наявними інтеграціями. Якщо ви будуєте покрокову навігацію деревом папок, передавайте "FolderRecursive": false разом із filter.ParentFolder і окремо отримуйте підпапки через /api/v2/product/folder/list.
Основні поля відповіді
| Поле | Опис |
|---|---|
Id | Ідентифікатор товару. |
Name | Назва товару. |
ParentFolder | Ідентифікатор батьківської папки. |
SkuParentProduct | Ідентифікатор базового товару для SKU. |
MainSKUProduct | Ідентифікатор базового товару для SKU у відповіді API. |
PrintName | Назва для друку. |
Memo | Коментар. |
Barcode | Штрихкод. |
UnitName | Назва одиниці виміру. |
Description | Опис товару. |
Article | Артикул. |
Brands | Бренди товару. |
MainSuppliers | Основні постачальники. |
WarrantyPeriod | Гарантійний строк. |
Country | Країна. |
Store | Основний склад. |
Manufacturer | Виробник. |
CustomsCode | Митний код. |
CustomsCodeId | Ідентифікатор митного коду. |
CustomsCodeName | Назва митного коду. |
Images | Зображення товару. Основне зображення йде першим у масиві. |
Prices | Ціни вибраних типів; без filter.PriceType — ціни всіх типів. За filter.IncludePromotions: true кожен запис містить також PriceWithoutDiscount, PercentDiscount, PriceWithDiscount і поля Promotion*; ті самі поля додаються у відповідних цінах SKU: Sku[].SkuPrices[]. Деталі полів і правил розрахунку наведені в описі методу списку цін. |
Stock | Залишки по складах, якщо в запиті передано filter.Store. |
Category | Категорія. |
UserFields | Користувацькі поля. |
Parents | Ієрархія батьківських папок. |
LastChangeTime | Дата й час останньої зміни товару, ціни або залишків. |
Користувацькі поля товару
Поле UserFields містить значення власних полів, заповнених у картці товару. Якщо для товару немає заповнених власних полів, масив може бути порожнім.
| Поле | Опис |
|---|---|
UserFields[].Id | Ідентифікатор користувацького поля. |
UserFields[].Name | Назва користувацького поля. |
UserFields[].Value | Значення користувацького поля у текстовому вигляді. |
Приклад фрагмента відповіді:
{
"Id": 12345,
"Name": "Товар",
"UserFields": [
{
"Id": 10,
"Name": "Послуга",
"Value": "true"
},
{
"Id": 11,
"Name": "Складський",
"Value": "true"
}
]
}
Поля акції у Prices[] та Sku[].SkuPrices[] мають такий самий зміст, як у price/list. Price залишається базовою ціною, тому для отримання ціни акції використовуйте PriceWithDiscount. Під час запиту без filter.IncludePromotions: true API повертає звичайні ціни без цих додаткових полів.
filter.Date задає дату оцінювання ціни й акції, але не дату складських залишків: запит повертає залишки, актуальні на момент запиту. Якщо поле не передано, сервер використовує поточну дату. Редагування або початок акції не змінює LastChangeTime товару, тому для синхронізації промоційних цін періодично оновлюйте повний перелік потрібних цін, а не лише товари зі змінами після LastChangeTime.
Для створення документа через API промоція автоматично не застосовується: передавайте кінцеву Price або повний набір Price=PriceWithDiscount, PriceWithoutDiscount = базова ціна, PercentDiscount = відсоток акції. Докладніше про ці поля — в описі замовлень.
Приклад запиту
{
"filter": {
"ParentFolder": [110],
"PriceType": [335],
"Date": "2026-11-28",
"IncludePromotions": true,
"Store": [113],
"Kind": "P"
},
"page": 1
}
Створення та оновлення товарів
Назва методу створення: /api/v2/product/add
Назва методу оновлення: /api/v2/product/update
Методи додають або оновлюють товари пакетами до 100 елементів. Для /api/v2/product/update поле Id обов’язкове. Якщо переданий Id не знайдено, елемент не потрапляє в оновлення.
Під час передавання постачальника пошук відбувається за назвою або реєстраційним кодом. Якщо збіг не знайдено, створюється новий контрагент і встановлюється як основний постачальник.
Якщо передати одне з полів PriceType або PriceValue, треба передати й друге. Інакше API поверне помилку If one of the fields PriceType or PriceValue is present, the other must also be filled in.
Параметри запиту
| Поле | Опис |
|---|---|
array | Масив товарів. Обов’язковий. |
array[].Id | Ідентифікатор товару. Обов’язковий для /api/v2/product/update. |
array[].Kind | Тип товару для створення: P, B або U. Якщо не передати, використовується P. |
array[].Name | Назва товару. |
array[].ParentFolder | Ідентифікатор папки. |
array[].PrintName | Назва для друку. |
array[].Memo | Коментар. |
array[].Barcode | Штрихкод. |
array[].UnitName | Одиниця виміру. |
array[].Brand | Бренд. |
array[].Description | Опис. |
array[].MainSupplierName | Назва основного постачальника. |
array[].MainSupplierRegCode | Реєстраційний код основного постачальника. |
array[].Article | Артикул. |
array[].IsManufacture | Ознака продукції. |
array[].PriceType | Ідентифікатор типу ціни. |
array[].PriceValue | Значення ціни. |
array[].SkuParentProduct | Ідентифікатор базового товару для прямого створення SKU-товару (Kind: U). |
array[].SkuParams | Параметри SKU з полями Name і Value. |
array[].Sku | Масив SKU-товарів під час створення базового товару (Kind: B). |
Для створення звичайного товару (Kind: P) поле Name обов’язкове. Для прямого створення SKU (Kind: U) обов’язковий SkuParentProduct, а назва SKU формується з SkuParams.
Формат відповіді
| Поле | Опис |
|---|---|
success | true або false. |
data | Масив ідентифікаторів створених або оновлених товарів. |
error | Код і текст помилки, якщо success = false. |
Видалення, архівування та відновлення товарів
Товари входять до довідників з уніфікованим контрактом видалення й відновлення (/api/v2/product/markasdelete і /api/v2/product/restore, той самий контракт і для папок товарів). Повний опис формату запиту, відповіді та кодів відмов - у розділі Видалення, архівування та відновлення довідників. Товар з ненульовим залишком на складі видалити не можна - відмова з кодом HAS_STOCK_BALANCE; непорожню папку - з кодом FOLDER_NOT_EMPTY.
Папки товарів
Назва методу списку: /api/v2/product/folder/list
Назва методу створення: /api/v2/product/folder/add
Назва методу оновлення: /api/v2/product/folder/update
Метод списку повертає папки товарів сторінками по 100 елементів. Фільтр filter.ParentFolder працює за загальним правилом з розділу Папки довідників: якщо поле не передати, повертаються всі папки; null повертає папки першого рівня; Id повертає прямі підпапки. У списку також підтримуються filter.Archive і filter.MobileApp.
Параметри списку папок
| Поле | Опис |
|---|---|
filter.ParentFolder | Ідентифікатор батьківської папки або null для першого рівня. |
filter.Id | Ідентифікатор папки. |
filter.Archive | Ознака повернення архівних папок. |
filter.MobileApp | Якщо true, API використовує збільшений ліміт вибірки. |
page | Номер сторінки. |
Поля відповіді списку папок
| Поле | Опис |
|---|---|
Id | Ідентифікатор папки. |
Name | Назва папки. |
ParentFolder | Ідентифікатор батьківської папки або null для першого рівня. |
Void | Ознака архівності. |
Параметри створення та оновлення папок
| Поле | Опис |
|---|---|
array | Масив папок. Обов’язковий. |
array[].Id | Ідентифікатор папки. Обов’язковий для /api/v2/product/folder/update. |
array[].Name | Назва папки. |
array[].ParentFolder | Ідентифікатор батьківської папки. |
Для створення папки Name обов’язковий, а переданий Id ігнорується. Для оновлення Id має бути цілим числом; якщо передати порожній Name, API поверне помилку.