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

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

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

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

Тип в інтерфейсі	Коли надсилається	Додатково обирають
«Залишки»	змінилися залишки (продаж, надходження, списання, переміщення тощо)	склади
«Товари»	товар створено або змінено	—
«Статуси замовлень покупців»	у замовлення покупця змінився статус	статуси

Вебхуки доповнюють REST API: початкове вивантаження даних виконують запитами до API (див. Початок роботи з API), а подальші зміни приходять вебхуками.

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

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

1. Відкрийте Налаштування компанії → Webhooks.

2. Натисніть Додати.

3. У вікні «Додати webhook» заповніть поля:

   • «Найменування» — довільна назва;
   • «URL» — адреса вашого endpoint, на яку надсилатимуться запити, наприклад https://mysite.com/webhook;
   • «Тип» — «Товари», «Залишки» або «Статуси замовлень покупців» (обов’язкове).

   

4. Для типу «Залишки» у полі «Склад» відмітьте склади, за якими надсилати події.

   

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

   

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

   

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

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

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

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

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

Вебхук «Залишки» надсилається, коли змінюються залишки товару: при продажах, надходженнях, списаннях, переміщеннях. Він підходить, коли потрібні актуальні залишки на сайті без очікування 10–30 хвилин до наступного запуску за розкладом.

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

{
  "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	зарезервована кількість
total_available	доступна кількість (фізичний залишок мінус резерв)
stock_details	розбивка за складами: storage_id, storage_name, physical, reserved, available
timestamp	час події, ISO 8601 UTC

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

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

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

Приклад для товару без модифікацій:

{
  "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):

{
  "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

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

Вебхук «Статуси замовлень покупців» надсилається, коли в замовлення покупця змінюється статус на один із вибраних у налаштуванні вебхука, наприклад «Оплачено», «Відвантажено», «Скасовано». Він корисний, коли від статусу залежать наступні процеси: доставка, резерв, фіскалізація. Про статуси — див. Статуси замовлення.

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

{
  "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: покупець, організація, договір, проєкт, напрям діяльності, склад, прайс-лист, каса чи рахунок оплати
quantityOrdered, quantityShipped	замовлена і відвантажена кількість
sumPayed, sumShipped	сплачена сума і сума відвантаження
TTN	номер накладної (порожній рядок, якщо немає)
VATaccounted, VATamount	ознака обліку ПДВ і сума ПДВ
products	позиції замовлення

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

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

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

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