Товари через API

API товарів дозволяє читати, створювати, оновлювати й видаляти товари, послуги, комплекти та продукцію. Через цей ресурс інтеграції синхронізують каталог, ціни, ознаки товару, додаткові поля, модифікації та базові складські показники.

Повʼязані інструкції:

• Картотека товарів;
• Створення товару;
• Модифікації;
• Комплекти;
• Серійні номери;
• Терміни придатності;
• Додаткові ціни;
• Додаткові поля;
• Категорії через API;
• Звіти через API.

Endpoint-и

Метод	Endpoint	Призначення
GET	/v1/products	отримати список товарів
POST	/v1/products	створити товар
GET	/v1/products/:id	отримати один товар
PUT	/v1/products/:id	оновити товар
DELETE	/v1/products/:id	видалити товар

Отримання списку товарів

GET /v1/products підтримує:

Параметр	Призначення
offset	Сторінка або зміщення списку.
limit	Кількість записів. За замовчуванням 100, максимум 1000.
query	Пошук за назвою, кодом або SKU.
producer_id	Фільтр за виробником.
product_type	Фільтр за типом товару.
category_id	Фільтр за категорією.
archive	Показувати архівні товари.
updated_from	Оновлено від.
updated_to	Оновлено до.
extended	Додати залишки, резерви й очікування.
with_images	Додати світлини.
with_custom_fields	Додати додаткові поля.
stock_id	Склад для розрахунку показників у extended.

Доступні значення product_type:

• goods;
• kit;
• service;
• product.

Отримання одного товару

GET /v1/products/:id повертає один товар за внутрішнім ID Skynum.

Для картки товару також можна використовувати параметри extended, with_images і with_custom_fields, якщо інтеграції потрібні залишки, світлини або додаткові поля.

Поля у відповіді

Поле	Що означає
id	Внутрішній ID товару.
title	Назва товару.
code	Код товару.
sku	Артикул.
product_type	Тип товару.
discount_disabled	Чи заборонені знижки для товару.
barcode_accounting	Чи ведеться облік модифікацій.
datevalid_accounting	Чи ведеться облік термінів придатності.
serial_accounting	Чи ведеться облік серійних номерів.
contragent_id	Контрагент, привʼязаний до товару.
novelty	Ознака новинки.
visible_in_shop	Видимість в інтернет-магазині.
shopwire_status	Статус товару для інтеграцій інтернет-магазинів.
top_sales	Ознака топ-продажу.
available_in_skypos	Доступність у Skynum.Каса.
availability_in_shop	Доступність в інтернет-магазині.
archive	Чи товар в архіві.
international_code	Міжнародний код товару.
category_id	ID категорії.
category_title	Назва категорії.
kingroup_id	ID спорідненої групи.
kingroup_code	Код спорідненої групи.
kingroup_title	Назва спорідненої групи.
measure_id	ID одиниці виміру.
measure_title	Назва одиниці виміру.
producer_id	ID виробника.
producer_title	Назва виробника.
nds_rate	Ставка ПДВ.
warranty_period	Гарантійний термін.
multiplicity	Кратність продажу або відвантаження.
min_shop_quantity	Мінімальна кількість для інтернет-магазину.
price_min	Мінімальна ціна.
price_supply	Прихідна ціна.
price_retail	Роздрібна ціна.
price_wholesale	Гуртова ціна.
price_promo	Перекреслена ціна.
custom_prices	Додаткові ціни товару.
modifications	Модифікації, якщо товар ведеться з модифікаціями.
archivated_at	Дата архівації.
description	Опис товару мовою за замовчуванням.
short_description	Короткий опис мовою за замовчуванням.
market_description	Опис для маркетплейсів мовою за замовчуванням.
images	Світлини, якщо передано with_images=true.
custom_fields	Додаткові поля, якщо передано with_custom_fields=true.
remains	Залишок, якщо передано extended=true.
reserve	Резерв, якщо передано extended=true.
waiting	Очікування, якщо передано extended=true.
title_{language}	Назва товару вторинною мовою, якщо в компанії ввімкнена багатомовність.
description_{language}	Опис вторинною мовою, якщо в компанії ввімкнена багатомовність.
short_description_{language}	Короткий опис вторинною мовою, якщо в компанії ввімкнена багатомовність.
market_description_{language}	Опис для маркетплейсів вторинною мовою, якщо в компанії ввімкнена багатомовність.
created_at	Дата створення.
updated_at	Дата оновлення.

Створення товару

Для створення товару потрібен обʼєкт product. Обовʼязкове поле - title.

{
  "product": {
    "title": "Кросівки чоловічі",
    "code": "10001",
    "sku": "SHOES-10001",
    "category_id": "category-id",
    "measure_id": "measure-id",
    "price_retail": 2500,
    "price_supply": 1500
  }
}

Якщо measure_id не передати, код API встановлює одиницю виміру за замовчуванням із налаштувань компанії.

Поля для запису

API приймає такі основні поля товару:

Поле	Призначення
title	Назва товару.
code	Код товару.
sku	Артикул.
category_id	Категорія товару. У внутрішній моделі це group_id.
measure_id	Одиниця виміру.
producer_id	Виробник.
kingroup_id	Споріднена група.
contragent_id	Контрагент, якщо товар привʼязується до постачальника або іншого контрагента.
weighted	Ознака вагового товару.
visible_in_shop	Видимість в інтернет-магазині.
shopwire_status	Статус товару для інтеграцій інтернет-магазинів.
available_in_skypos	Доступність у Skynum.Каса.
availability_in_shop	Доступність в інтернет-магазині.
discount_disabled	Заборонити знижки для товару.
novelty	Новинка.
top_sales	Топ продажів.
nds_rate	Ставка ПДВ.
warranty_period	Гарантійний термін.
multiplicity	Кратність продажу або відвантаження.
min_shop_quantity	Мінімальна кількість для інтернет-магазину.
datevalid_accounting	Облік термінів придатності.
serial_accounting	Облік серійних номерів.
archivated_at	Дата архівації.
price_min	Ціна мінімум.
price_supply	Ціна прихідна.
price_retail	Ціна роздрібна.
price_wholesale	Ціна гуртова.
price_old	Ціна перекреслена для запису через API.
custom_prices	Додаткові ціни.
custom_fields	Додаткові поля.

Системні ціни

Для запису підтримуються системні ціни:

Поле API	Ціна в Skynum
price_supply	Ціна прихідна
price_retail	Ціна роздрібна
price_wholesale	Ціна гуртова
price_min	Ціна мінімум
price_old	Ціна перекреслена

У відповіді API перекреслена ціна повертається як price_promo, тому що це технічна назва поля в моделі.

інформація

Додаткові ціни не є системними. Їх передають у custom_prices, де ключем є ID додаткової ціни, а значенням - ціна товару.

Додаткові ціни

Приклад custom_prices:

{
  "product": {
    "custom_prices": {
      "custom-price-id": 2300
    }
  }
}

Список додаткових цін можна отримати через Додаткові ціни через API.

Додаткові поля

Додаткові поля передаються у custom_fields.

{
  "product": {
    "custom_fields": {
      "field-id-1": "Значення",
      "field-id-2": true,
      "field-id-3": 15
    }
  }
}

Для значень власних довідників використовуйте Власні довідники через API.

Модифікації у відповіді

Якщо для товару ввімкнений облік модифікацій, у відповіді може бути масив modifications.

Поля модифікації у відповіді:

Поле	Що означає
id	ID модифікації.
title	Назва модифікації.
visible_in_shop	Видимість модифікації в інтернет-магазині.
shopwire_status	Статус модифікації для інтеграцій інтернет-магазинів.
use_prices	Чи використовує модифікація власні ціни.
code	Код модифікації.
sku	Артикул модифікації.
price_min	Мінімальна ціна.
price_supply	Прихідна ціна.
price_retail	Роздрібна ціна.
price_wholesale	Гуртова ціна.
custom_prices	Додаткові ціни.
images	Світлини, якщо передано with_images=true.
remains	Залишок, якщо передано extended=true.
reserve	Резерв, якщо передано extended=true.
waiting	Очікування, якщо передано extended=true.
created_at	Дата створення.
updated_at	Дата оновлення.

попередження

Якщо зовнішня система продає або резервує товари з модифікаціями, у документах потрібно передавати не тільки товар, а й конкретну модифікацію.

Залишки в товарному ресурсі

Параметр extended=true додає:

• remains;
• reserve;
• waiting.

stock_id уточнює, по якому складу рахувати ці показники.

попередження

Зміна залишків, резервів або очікувань не означає, що товар потрапить у вибірку updated_from. Для регулярної синхронізації кількості використовуйте Звіти через API.

Світлини

Параметр with_images=true додає до відповіді масив URL світлин товару або модифікації.

API товарів читає світлини, але в поточних полях запису товару немає окремого сценарію завантаження зображень.

Видалення товару

Endpoint:

DELETE /v1/products/:id

попередження

Не використовуйте видалення як звичайний сценарій синхронізації каталогу. Якщо товар уже використовується в документах, залишках, серійних номерах, партіях або звітах, видалення може бути неможливим або шкідливим для обліку.

Чеклист

Перед запуском синхронізації товарів перевірте:

• яка система є головною для назви, коду, SKU і категорії;
• чи використовуються модифікації;
• чи потрібно передавати серійний облік або терміни придатності;
• які системні й додаткові ціни синхронізуються;
• чи потрібні додаткові поля;
• чи потрібні світлини у відповіді;
• чи потрібні залишки через extended, чи краще використовувати звіти;
• як інтеграція обробляє архівні товари;
• як інтеграція уникає дублювання товарів.

Підсумок

API товарів відповідає за каталог і властивості товарів. Для структури каталогу використовуйте Категорії через API, для залишків і резервів - Звіти через API.