# Вебхуки Bimp: налаштування та формати подій

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

> Вебхук — це HTTP-запит, який Bimp сам надсилає на ваш URL, коли змінюється залишок, створюється чи змінюється товар або змінюється статус замовлення покупця. Вебхук додають у «Налаштування компанії → Webhooks»: вказують назву, URL і тип, а для залишків і статусів ще й склади або статуси.

## Що таке вебхук у Bimp

Вебхук — це автоматичний HTTP-запит від Bimp на вашу адресу (endpoint) у момент події. Ваш сервіс приймає запит і виконує дії, наприклад оновлює залишки на сайті.

У Bimp є три типи вебхуків:

| Тип в інтерфейсі | Коли надсилається | Додатково обирають |
|---|---|---|
| «Залишки» | змінилися залишки (продаж, надходження, списання, [переміщення](https://bimpsoft.com/help/inventory/stock-transfer/) тощо) | склади |
| «Товари» | товар створено або змінено | — |
| «Статуси замовлень покупців» | у [замовлення покупця](https://bimpsoft.com/help/sales/customer-order/) змінився статус | статуси |

Вебхуки доповнюють REST API: початкове вивантаження даних виконують запитами до API (див. [Початок роботи з API](https://bimpsoft.com/help/developers/api-getting-started/)), а подальші зміни приходять вебхуками.

## Як налаштувати вебхук

Щоб додати вебхук, відкрийте налаштування компанії, вкладку Webhooks і створіть запис.

1. Відкрийте **Налаштування компанії → Webhooks**.
2. Натисніть **Додати**.
3. У вікні «Додати webhook» заповніть поля:
   - «Найменування» — довільна назва;
   - «URL» — адреса вашого endpoint, на яку надсилатимуться запити, наприклад `https://mysite.com/webhook`;
   - «Тип» — «Товари», «Залишки» або «Статуси замовлень покупців» (обов'язкове).

   ![Вікно «Додати webhook» з полями «Найменування» (Мій вебхук), URL (https://mysite.com/webhook) і розкритим списком «Тип» з варіантами «Товари», «Залишки», «Статуси замовлень покупців»](https://bimpsoft.com/help/_img/5a92fc07-8456-4ebf-b883-7120ca38e795.webp)

4. Для типу «Залишки» у полі «[Склад](https://bimpsoft.com/help/inventory/warehouses/)» відмітьте склади, за якими надсилати події.

   ![Вікно «Додати webhook» з типом «Залишки» і розкритим обов'язковим полем «Склад» зі списком складів «Основний склад» і «warehouse» з прапорцями](https://bimpsoft.com/help/_img/4b2906ee-b978-45f1-a8d6-9c91c06be297.webp)

5. Для типу «Статуси замовлень покупців» у полі «Статус» відмітьте статуси, при переході в які надсилати подію (наприклад, «Новий», «Оплачено», «Відвантажено», «Скасовано» — список залежить від статусів вашої компанії).

   ![Вікно «Додати webhook» з типом «Статуси замовлень покупців» і списком статусів з прапорцями: Архів, В роботі, Виробництво, Відвантажено, Відкладено, Відмова, Завершено, Залишилася переплата, Не відвантажений, Не сплачено, Новий, Оплачено, Частково відвантажено, Частково сплачено](https://bimpsoft.com/help/_img/f48eb523-5d8f-4bf0-a3f2-f1af0edde25d.webp)

6. Збережіть вебхук. Він з'явиться в списку на вкладці Webhooks з колонками «Найменування», «URL», «Тип», «Склад», «Статус». Вебхуки відрізняються за колонкою «Тип».

   ![Список вебхуків на вкладці Webhooks: три рядки «Мій вебхук» з типами «Статуси замовлень покупців» (статуси «В роботі, Відвантажено»), «Залишки» (склад «Основний склад») і «Товари»; праворуч у кожному рядку меню «три крапки», угорі кнопка «Додати»](https://bimpsoft.com/help/_img/fc373708-628c-4bd9-bf7a-0672ddbfd859.webp)

Щоб змінити або видалити вебхук, скористайтеся меню «три крапки» в кінці його рядка.

## Яким має бути endpoint

Endpoint — це публічний HTTPS-URL вашого сервісу, який приймає `POST` із JSON-тілом. Опис нижче складено за форматами подій; вимоги до відповіді не задокументовані.

- Приймайте запит, розбирайте JSON і швидко відповідайте; важку обробку виносьте в чергу.
- Очікуйте повторні й невпорядковані події: ідентифікуйте об'єкт за `uuid`/`id`, а свіжість визначайте за полем `timestamp` (де воно є).
- Не покладайтеся на подію як на єдине джерело: періодично звіряйте дані з API.

## Вебхук «Залишки»

Вебхук «Залишки» надсилається, коли змінюються залишки товару: при продажах, надходженнях, [списаннях](https://bimpsoft.com/help/inventory/write-off/), переміщеннях. Він підходить, коли потрібні актуальні залишки на сайті без очікування 10–30 хвилин до наступного запуску за розкладом.

Приклад тіла події:

```json
{
  "id": "product-id",
  "barcode": "product_barcode",
  "sku": "product_sku",
  "name": "Product Name",
  "total_physical": -1,
  "total_reserved": 1,
  "total_available": -2,
  "stock_details": [
    {
      "storage_id": "Warehouse-Id",
      "storage_name": "Storage Name",
      "physical": -1,
      "reserved": 1,
      "available": -2
    },
    {
      "storage_id": "Storage-Id",
      "storage_name": "Основний склад",
      "physical": 0,
      "reserved": 0,
      "available": 0
    }
  ],
  "timestamp": "2026-01-01T00:00:00.000Z"
}
```

| Поле | Що означає |
|---|---|
| `id` | ідентифікатор товару в Bimp |
| `barcode`, `sku`, `name` | штрихкод, SKU і назва товару |
| `total_physical` | фізичний залишок за всіма складами |
| `total_reserved` | [зарезервована](https://bimpsoft.com/help/sales/reserves/) кількість |
| `total_available` | доступна кількість (фізичний залишок мінус резерв) |
| `stock_details` | розбивка за складами: `storage_id`, `storage_name`, `physical`, `reserved`, `available` |
| `timestamp` | час події, ISO 8601 UTC |

Доступний залишок дорівнює фізичному мінус резерв, і може бути від'ємним (у прикладі: -1 фізично, 1 у резерві, -2 доступно).

## Вебхук «Товари»

Вебхук «Товари» надсилається, коли в Bimp створюють або змінюють товар. Він потрібен, щоб синхронізувати довідник товарів (назви, артикули, SKU, опис, габарити) із зовнішньою системою без затримки.

Приклад для товару без [модифікацій](https://bimpsoft.com/help/products/variants/):

```json
{
  "product": {
    "uuid": "product-id",
    "name": "Product Name",
    "article": "product-article",
    "sku": "product-sku",
    "description": "product description",
    "picture": "product-picture.com",
    "isModification": false,
    "measurements": {
      "weight": 1,
      "length": 10,
      "width": 20,
      "height": 30
    }
  },
  "timestamp": "2026-01-01T00:00:00.000Z"
}
```

Для модифікації товару `isModification` дорівнює `true`, а в `product` додається блок `parent` з даними батьківського товару (той самий набір полів, без `isModification`):

```json
{
  "product": {
    "uuid": "product-id",
    "name": "Product Name",
    "article": "product-article",
    "sku": "product-sku",
    "description": "product description",
    "picture": "product-picture.com",
    "isModification": true,
    "measurements": { "weight": 1, "length": 10, "width": 20, "height": 30 },
    "parent": {
      "uuid": "parent-product-id",
      "name": "Parent Name",
      "article": "parent-article",
      "sku": "parent-sku",
      "description": "parent description",
      "picture": "parent-picture.com",
      "measurements": { "weight": 2, "length": 20, "width": 30, "height": 40 }
    }
  },
  "timestamp": "2026-01-01T00:00:00.000Z"
}
```

| Поле | Що означає |
|---|---|
| `product.uuid`, `name`, `article`, `sku`, `description` | UUID, назва, артикул, SKU і опис товару |
| `product.picture` | посилання на фото |
| `product.isModification` | `true`, якщо це модифікація іншого товару |
| `product.measurements` | `weight`, `length`, `width`, `height` |
| `product.parent` | батьківський товар; є лише для модифікацій |
| `timestamp` | час події, ISO 8601 UTC |

## Вебхук «Статуси замовлень покупців»

Вебхук «Статуси замовлень покупців» надсилається, коли в замовлення покупця змінюється статус на один із вибраних у налаштуванні вебхука, наприклад «Оплачено», «Відвантажено», «Скасовано». Він корисний, коли від статусу залежать наступні процеси: доставка, резерв, фіскалізація. Про статуси — див. [Статуси замовлення](https://bimpsoft.com/help/sales/order-statuses/).

Тіло події містить усе замовлення:

```json
{
  "order_id": "order-id",
  "comment": "order comment",
  "buyer": { "uuid": "buyer-id", "name": "Buyer Name" },
  "date": "2026-01-01T00:00:00",
  "name": "Buyer's order № 1 from 01.01.2026",
  "organization": { "uuid": "organization-id", "name": "Organization Name" },
  "quantityOrdered": 1,
  "quantityShipped": 1,
  "status": { "uuid": "status-id", "name": "Status Name" },
  "sumPayed": 0,
  "sumShipped": 0,
  "TTN": "",
  "docNumber": "1",
  "paymentEntity": { "uuid": "payment-id", "name": "Основна каса" },
  "project": { "uuid": "project-id", "name": "Project Name" },
  "contract": { "uuid": "contract-id", "name": "Contract Name" },
  "lineOfBusiness": { "uuid": "line-of-business-id", "name": "Line Of Business Name" },
  "warehouse": { "uuid": "warehouse-id", "name": "Warehouse Name" },
  "VATaccounted": false,
  "priceList": { "uuid": "Price-List-id", "name": "Price List Name" },
  "VATamount": 0,
  "products": [
    {
      "nomenclature": { "uuid": "nomenclature-id", "name": "Nomenclature Name" },
      "count": 1,
      "VAT": { "uuid": "VAT-id", "name": "VAT Name" },
      "VATamount": 0,
      "cost": 291.1,
      "amount": 291.1,
      "comment": "product comment",
      "discount": 0,
      "discountPercentage": 0,
      "shiped": 1,
      "warehouse": { "uuid": "warehouse-id", "name": "Warehouse Name" },
      "reserve": 1,
      "modification": null,
      "machinery": { "uuid": "machinery-id", "name": "Machinery Name" }
    }
  ]
}
```

Поля верхнього рівня:

| Поле | Що означає |
|---|---|
| `order_id`, `docNumber`, `name`, `date`, `comment` | ідентифікатор, номер, назва, дата й коментар замовлення |
| `status` | новий статус (`uuid`, `name`) |
| `buyer`, `organization`, `contract`, `project`, `lineOfBusiness`, `warehouse`, `priceList`, `paymentEntity` | пов'язані об'єкти з `uuid` і `name`: покупець, організація, договір, проєкт, напрям діяльності, склад, [прайс-лист](https://bimpsoft.com/help/pricing/price-lists/), каса чи рахунок оплати |
| `quantityOrdered`, `quantityShipped` | замовлена і відвантажена кількість |
| `sumPayed`, `sumShipped` | сплачена сума і сума [відвантаження](https://bimpsoft.com/help/sales/shipment/) |
| `TTN` | номер накладної (порожній рядок, якщо немає) |
| `VATaccounted`, `VATamount` | ознака обліку ПДВ і сума ПДВ |
| `products` | позиції замовлення |

Поля позиції в `products`: `nomenclature`, `count`, `VAT`, `VATamount`, `cost` (ціна), `amount` (сума), `comment`, `discount`, `discountPercentage`, `shiped` (відвантажено), `warehouse`, `reserve` (резерв), `modification`, `machinery` (техніка).

## Типові проблеми

**Вебхук не надходить.** Причини: URL недоступний із зовнішньої мережі, не обрано склади чи статуси, або подія не відповідає обраним. Рішення: перевірте URL і те, що в списку вебхуків у колонках «Склад» чи «Статус» вказано потрібні значення.

**Вебхук надходить, але дані застарілі.** Причина: події можуть приходити не в порядку відправлення. Рішення: порівнюйте `timestamp` з уже збереженим і ігноруйте старіші події.

## FAQ

**Які події підтримують вебхуки Bimp?**

Три типи: «Залишки» (зміна залишків), «Товари» (створення або зміна товару) і «Статуси замовлень покупців» (зміна статусу документа).

**Чим вебхук кращий за періодичний запит залишків?**

Вебхук надходить одразу після зміни, тож не потрібно чекати 10–30 хвилин до наступного запуску за розкладом. Для початкового повного вивантаження все одно використовуйте API.

**Як обмежити вебхук залишків певними складами?**

При виборі типу «Залишки» з'являється обов'язкове поле «Склад»: відмітьте склади, зміни за якими треба надсилати. Для типу «Статуси замовлень покупців» аналогічно обирають статуси.

**Чи можна змінити або видалити вебхук?**

Так. У списку на вкладці Webhooks вебхук можна відредагувати або видалити через меню «три крапки» в кінці рядка.