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

URL: https://bimpsoft.com/help/developers/sync-catalog/
Updated: 2026-11-06

> Щоб синхронізувати каталог, зіставте товари двох систем через nomenclature/api-saveExternalId, а створюйте нові товари методом nomenclature/api-create (можна відразу з полем integration). Зміни товарів у Bimp отримуйте вебхуком product_upsert або через nomenclature/api-readList з фільтрами created і updated.

## Що будуємо

Узгоджений каталог товарів між Bimp і вашою системою: інтернет-магазином, маркетплейсом чи PIM. Bimp зазвичай є джерелом правди для номенклатури, ціни та залишки; сайт може бути джерелом описів і фото. Нижче — як зіставити товари, завантажити нові й підтримувати зміни. Токен компанії передається в заголовку `access-token` ([Початок роботи з API](https://bimpsoft.com/help/developers/api-getting-started/)). Про самі товари в інтерфейсі — [Товари та послуги](https://bimpsoft.com/help/products/products-and-services/).

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

| Крок | Метод | Навіщо |
|---|---|---|
| 1 | [`nomenclature-group/api-readList`](/help/developers/api-reference/nomenclature-group/#api-read-list) | Отримати дерево груп (`uuid`, `name`, `parentuuid`) |
| 2 | [`unitsOfMeasurment/api-readList`](/help/developers/api-reference/units-of-measurment/#api-read-list) | Отримати одиниці виміру для створення товарів |
| 3 | [`nomenclature/api-readList`](/help/developers/api-reference/nomenclature/#api-read-list) | Початкове читання каталогу з пагінацією |
| 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`:

```bash
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` повертає лише товари, яких у вашій системі ще немає, — зручно для поетапної роботи:

```bash
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`.

```bash
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` — модифікацію. Про модифікації в інтерфейсі — [Модифікації](https://bimpsoft.com/help/products/variants/).

### Групи

Групу створює `nomenclature-group/api-create` (`name`, необов'язково `description` і `parentuuid`). Список груп повертає `api-readList` (поле `uuid` у запиті — необов'язковий фільтр за списком uuid). Дерево будуйте за `parentuuid`: [Групи номенклатури](https://bimpsoft.com/help/products/product-groups/).

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

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

```bash
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`](/help/developers/api-reference/webhook/#api-upsert):

```bash
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` з даними батьківського товару. Формат — у статті [Вебхуки](https://bimpsoft.com/help/developers/webhooks/).

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

```bash
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](https://bimpsoft.com/help/developers/api-external-ids/).

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

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

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

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

**Переривається вигрузка великого каталогу.** Причина: ліміт 15 запитів на секунду. Рішення: пакети по 100, пауза при 429 — див. [Ліміти](https://bimpsoft.com/help/developers/api-limits/).

## FAQ

**Як знайти товари Bimp, яких ще немає у моїй системі?**

Викличте nomenclature/api-readWithoutExternalId зі своїм source: метод поверне товари без зіставлення з цією системою.

**Як створити товар через API, щоб одразу зв'язати його з моїм ID?**

У nomenclature/api-create передайте об'єкт integration з полями system і externalId. Альтернатива — створити товар і викликати api-saveExternalId.

**Як передати модифікацію (розмір, колір)?**

Створіть модифікацію з isModification=true і parent — uuid батьківського товару. У readList батьківський товар має isParent=true, а модифікація — isModification=true і parent.

**Як отримати лише змінені товари?**

Використайте фільтр updated (пара дат [від, до]) або created у nomenclature/api-readList. Або підпишіться на вебхук product_upsert.