Як працювати з товарами та залишками в API

Розповідаємо, як створювати товар та варіанти товари та передавати по ним залишки
Написано Анастасія Останіна
Оновлено 1 місяць тому

За допомогою API можна створити категорії,  товари, варіанти (властивості) до товарів, а також оновлювати залишки товарів.

Зверніть увагу! В API KeyCRM є обмеження до 60 запитів на хвилину з однієї IP-адреси по API-ключу. Тому рекомендуємо налаштовувати паузу між запитами в 1 секунду, для запобігання перевищення ліміту.

Як створити категорію та підкатегорію товару 

Якщо категорії створені в кабінеті, то отримайте їх GET запитом або створіть потрібні по API:  

  • Для нової категорії потрібно лише вказати її назву;
  • Щоб додати підкатегорію, в запиті передайте назву та параметр "parent_id" (батьківську категорію).

Як створити товар по API

Створити товари можна по одному або списком до 100 шт. за один запит і відразу передати дані в кастомні поля.

Враховуйте основні моменти

  • Кожен товар має мати свій унікальний артикул, назву та штрихкод, оскільки виступає окремою одиницею складського обліку;
  • Якщо  товар з варіантами, то назва товару загальна, а кожний варіант має унікальний артикул та штрихкод.
  • Синхронізація даних між системами відбувається по артикулу товару. Тому переконайтесь, що він однаковий в одному товарі в усіх системах і передайте його в параметрі sku;
  • Щоб поле штрихкод був доступний, спочатку потрібно увімкнути в розділі «Налаштування» → «Товари» перемикач «Використовувати штрихкоди».

Після створення товару у відповіді ви отримаєте ідентифікатор товару (productId), який можна використовувати для оновлення товарів або створення варіантів до них.

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

Як створити варіант товару

Щоб створити варіант товару, потрібно:

  1. Отримати ідентифікатор товару (productId) до якого плануєте додати варіант товару. Ви отримуєте його в параметрі «id» у відповіді після створення товару або можна отримати список товарів використовуючи фільтри, щоб знайти потрібне і зберегти його «id»;
  2. Відправити запит для додавання варіантів до цього товару (до 100 шт. в запиті), вказавши ідентифікатор товару (productId)  у форматі JSON.
    Приклад URL для товару №12:
    POST https://openapi.keycrm.app/v1/products/12/offers 

Як оновити залишки по API

Для роботи з залишками, перш за все активуйте складський облік та додайте склади

В одному запиті доступна передача залишків для до 10000 товарів з одного складу.

Залишки можна оновити тільки передавши артикул (sku) та кількість:

{
  "warehouse_id": 1,     // ідентифікатор складу, відображається в списку складів
  "stocks": [
    {
      "sku": "001-242",     // артикул товару
      "quantity": 3     // кількість залишків
    },
   {
      "sku": "002-242",     // артикул товару
      "quantity": 5      // кількість залишків
    }
  ]
}

Для оновлення залишків по ідентифікаторах варіантів потрібно: 

  1. Отримати зі списку варіантів товарів offer_id (ідентифікатор варіанту товару);
  2. Відправити запит на оновлення залишків вказавши offer_id в параметрі "id". Якщо передати також артикул (sku), то система спочатку буде шукати потрібний товар по "id", а якщо не знайде — спробує знайти по "sku".
Важливо! Потрібно передавати саме offer_id - ідентифікатор варіанта товару, він не дорівнює product_id (ідентифікатор товару).

Навіть якщо у вас товари без варіантів, кожен з них має offer_id. Оскільки для системи товар без варіантів означає товар в одному варіанті.

Після передачі залишків в цьому товарі буде оновлений залишок на вказаному складі. 
Скасувати переданий залишок по
API не можна, запис про оновлення залишку буде відображатись в історії змін по кожному товару та в розділі рух товарів.

Теги: створити товар по Апі, API, додати варіанти до товару, оновити залишки, створення категорії, підкатегорії.
Чи була наша стаття корисною?