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

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

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

Повну синхронізацію всіх товарів виконуйте не частіше ніж 1 раз на добу.

Для частішого оновлення використовуйте інкрементальну синхронізацію через фільтри updated_from і updated_to: передавайте час останньої успішної синхронізації й отримуйте тільки товари, які змінилися після неї. Такий запит можна виконувати частіше, наприклад раз на 10 хвилин, якщо інтеграції потрібні оперативні зміни каталогу.

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

Endpoint-и

Метод	Endpoint	Призначення
GET	/v1/products	отримати список товарів
GET	/v1/products/:id	отримати один товар
POST	/v1/products	створити товар
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	Додати додаткові поля.
with_features	Додати характеристики товару або модифікацій.
stock_id	Склад для розрахунку показників у extended.

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

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

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

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

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

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

Поле	Що означає
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.
features	Характеристики, якщо передано with_features=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	Додаткові поля.
features	Характеристики товару.

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

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

Поле 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.

Характеристики

Характеристики передаються у features.

{
  "product": {
    "features": [
      {
        "parent": "feature-id",
        "child": "feature-value-id"
      }
    ]
  }
}

У відповіді характеристика містить:

Поле	Що означає
feature_id	ID характеристики.
feature_title	Назва характеристики.
value_id	ID значення, якщо характеристика має значення з довідника.
value	Значення характеристики.
datatype	Тип значення характеристики.

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

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

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

Поле	Що означає
id	ID модифікації.
title	Назва модифікації.
visible_in_shop	Видимість модифікації в інтернет-магазині.
shopwire_status	Статус модифікації для інтеграцій інтернет-магазинів.
use_prices	Чи використовує модифікація власні ціни.
code	Код модифікації.
sku	Артикул модифікації.
price_min	Мінімальна ціна.
price_supply	Прихідна ціна.
price_retail	Роздрібна ціна.
price_wholesale	Гуртова ціна.
custom_prices	Додаткові ціни.
features	Характеристики, якщо передано with_features=true.
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_at товару. Для регулярної синхронізації кількості використовуйте updated_from і updated_to, а в запит додавайте extended=true.

Світлини

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

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

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

Endpoint:

DELETE /v1/products/:id

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

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

Чеклист

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

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

Повʼязані матеріали

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

Підсумок

API товарів відповідає за каталог, властивості товарів і базові складські показники у відповіді з extended=true. Для структури каталогу використовуйте Категорії через API, для агрегованих і датованих звітних даних - Звіти через API.