Синхронізація каталогу товарів через API

Що будуємо

Узгоджений каталог товарів між Bimp і вашою системою: інтернет-магазином, маркетплейсом чи PIM. Bimp зазвичай є джерелом правди для номенклатури, ціни та залишки; сайт може бути джерелом описів і фото. Нижче — як зіставити товари, завантажити нові й підтримувати зміни. Токен компанії передається в заголовку access-token (Початок роботи з API). Про самі товари в інтерфейсі — Товари та послуги.

Які методи і в якому порядку

Крок	Метод	Навіщо
1	nomenclature-group/api-readList	Отримати дерево груп (uuid, name, parentuuid)
2	unitsOfMeasurment/api-readList	Отримати одиниці виміру для створення товарів
3	nomenclature/api-readList	Початкове читання каталогу з пагінацією
4	nomenclature/api-readWithoutExternalId	Знайти товари Bimp, які ще не зіставлені з вашою системою
5	nomenclature/api-saveExternalId	Зіставити товар Bimp із ID у вашій системі
6	nomenclature/api-readByExternalId	Знайти товар Bimp за ID у вашій системі
7	nomenclature/api-create	Створити товар (або модифікацію), якого немає
8	nomenclature/api-update	Оновити назву, артикул, опис, габарити тощо
9	nomenclature-group/api-create	Створити групу, якої бракує

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

Початкове зіставлення роблять один раз. Є два підходи.

За артикулом або штрихкодом. Прочитайте каталог Bimp пакетами по 100 і порівняйте з вашою базою за article або sku (у полі sku Bimp зберігає штрихкод). Для знайденої пари викликайте nomenclature/api-saveExternalId:

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-saveExternalId \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nomenclatureUuid": "<product-uuid>", "source": "myshop", "externalId": "SKU-48215" }'

Через список без зіставлення. nomenclature/api-readWithoutExternalId зі source повертає лише товари, яких у вашій системі ще немає, — зручно для поетапної роботи:

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-readWithoutExternalId \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pagination": { "offset": 0, "count": 100 }, "source": "myshop" }'

Відповідь — масив nomenclatureUuid та name. Після кожного зіставлення товар зникає зі списку, тож цикл завершується, коли список порожній.

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

Метод nomenclature/api-create приймає обов’язкові name і unitOfMeasurementUuid, а тип товару задає type: goods (товар) або service (послуга). Додатково: fullName, article, sku, group, supplier, description, comment, measurements (height, length, width у сантиметрах, weight у кілограмах — усі чотири поля разом) і VATaccounted.

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-create \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "goods",
    "name": "Кавоварка Aroma 2000",
    "article": "AR-2000",
    "sku": "4820000000012",
    "unitOfMeasurementUuid": "<unit-uuid>",
    "group": "<group-uuid>",
    "description": "Крапельна кавоварка, 1,2 л",
    "measurements": { "height": 30, "length": 20, "width": 15, "weight": 2.4 },
    "integration": { "system": "<integration-system-uuid>", "externalId": "48215" }
  }'

Відповідь: { "success": true, "data": { "uuid": "<product-uuid>" } }.

Поле integration необов’язкове: воно одразу зв’язує товар з об’єктом зовнішньої системи, і за цим зв’язком товар можна шукати в nomenclature/api-readList (фільтр integration з system і externalId). Значення system — це UUID інтеграційної системи, а не рядок source; для простоти користуйтеся парою «api-create + api-saveExternalId».

Модифікації

Модифікація — окремий товар із посиланням на батьківський. Щоб її створити, додайте isModification: true і parent — uuid батьківського товару. Модифікації батька читайте через nomenclature/api-readList з параметром parentUuid. У відповіді isParent позначає батьківський товар, а isModification і parent — модифікацію. Про модифікації в інтерфейсі — Модифікації.

Групи

Групу створює nomenclature-group/api-create (name, необов’язково description і parentuuid). Список груп повертає api-readList (поле uuid у запиті — необов’язковий фільтр за списком uuid). Дерево будуйте за parentuuid: Групи номенклатури.

Як оновити товар

nomenclature/api-update приймає uuid і лише ті поля, що змінюються: name, fullName, article, sku, group, unitOfMeasurementUuid, description, comment, picture, measurements, VATaccounted.

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-update \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "<product-uuid>", "description": "Крапельна кавоварка, 1,2 л, чорна" }'

У api-update не передається type, тому тип товару після створення змінити не можна.

Як отримувати зміни каталогу

Вебхук product_upsert. Подія надходить, коли товар створено або змінено. Створіть вебхук методом webhook/api-upsert:

curl -X POST https://app.bimpsoft.com/org2/webhook/api-upsert \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventKind": "product_upsert",
    "name": "Товари для сайту",
    "url": "https://shop.example.com/hooks/bimp-product",
    "enabled": true
  }'

У події є product: uuid, name, article, sku, description, picture, isModification, measurements (weight, length, width, height) та timestamp. Для модифікації додається блок parent з даними батьківського товару. Формат — у статті Вебхуки.

Опитування за часом. Фільтри created і updated у nomenclature/api-readList приймають пару дат ["від", "до"] у ISO 8601 (будь-яку з меж можна замінити null):

curl -X POST https://app.bimpsoft.com/org2/nomenclature/api-readList \
  -H "access-token: $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": { "offset": 0, "count": 100 },
    "updated": [["2026-11-05T00:00:00.000Z", null]]
  }'

Запам’ятовуйте час початку попереднього запиту, а наступного разу передавайте його як нижню межу.

Як не створити дублі товарів

1. Перед api-create викличте nomenclature/api-readByExternalId з вашим source і externalId. Відповідь null означає, що товару немає.
2. Для пошуку за вашою назвою або артикулом використовуйте фільтри article, name, nameContains у api-readList, а не порівняння на вашому боці.
3. Після створення негайно викличте api-saveExternalId (або передайте integration при створенні).
4. Для ширшого огляду зіставлень застосовуйте api-readExternalIdsList (фільтри source, nomenclatureGuid). Видалення зіставлення — api-deleteExternalId: якщо не передати source, видаляться всі зіставлення цього товару.

Правила зовнішніх ID спільні для всіх ресурсів: Зовнішні ID.

Типові помилки

Помилка валідації при створенні товару. Причина: не передано name, unitOfMeasurementUuid або type, або measurements заповнено не повністю (усі чотири значення обов’язкові разом). Рішення: передайте всі обов’язкові поля.

Модифікація створилась як окремий товар. Причина: не передано isModification: true разом із parent. Рішення: змініть структуру запиту; уже створений товар не можна перетворити на модифікацію методом api-update .

Після видалення зіставлення товар знову потрапив у readWithoutExternalId. Це очікувана поведінка: метод показує всі товари без зіставлення з вказаним source.

Переривається вигрузка великого каталогу. Причина: ліміт 15 запитів на секунду. Рішення: пакети по 100, пауза при 429 — див. Ліміти.