Webhook: документи і товари

Вебхуки дозволяють автоматично отримувати повідомлення з QUINCEFIN про зміни документів і товарів. Це зручно для інтеграцій з інтернет-магазинами, CRM, зовнішніми складами, аналітикою або власним middleware.

Профілі вебхуків знаходяться в меню Налаштування / Інтеграції / Інтернет-магазини:

Webhook: Документи - для подій з документами;
Webhook: Товари - для оновлень товарів, цін і доступної кількості.

Як увімкнути вебхук

Відкрийте потрібний пункт меню: Webhook: Документи або Webhook: Товари.
Створіть профіль.
Вкажіть URL, на який QUINCEFIN має надсилати події.
Натисніть Перевірити з’єднання.
Збережіть профіль.

Після збереження активного профілю система починає додавати події в чергу та надсилати їх на вказаний URL.

Під час перевірки з’єднання QUINCEFIN надсилає тестовий POST-запит з порожнім масивом Documents або Products. Тому ваш endpoint має приймати не тільки робочі пакети з подіями, а й тестовий запит без елементів.

Як відправляються події

QUINCEFIN надсилає події пакетами через POST-запити з JSON у тілі запиту.

Пакет вважається доставленим, якщо ваш сервер повернув HTTP-статус 2xx, наприклад 200, 201 або 202.

Якщо сервер не відповів або повернув помилку, пакет залишається в черзі. Система повторить спробу пізніше з паузою:

2 хвилини;
4 хвилини;
8 хвилин;
16 хвилин;
32 хвилини.

Після 32 хвилин пауза більше не збільшується. Події залишаються в черзі, а спроби відправки продовжуються.

Один пакет зазвичай містить до 50 подій.

Формат вебхука документів

Приклад тіла запиту:

{
  "Documents": [
    {
      "QueueId": 30,
      "DocumentId": 494872,
      "Type": "OUTGOING_INVOICE",
      "Event": "update",
      "EventDate": "2026-05-15T12:20:16.817"
    },
    {
      "QueueId": 31,
      "DocumentId": 494869,
      "Type": "OUTGOING_ORDER",
      "Event": "unapply",
      "EventDate": "2026-05-15T12:21:23.960"
    },
    {
      "QueueId": 32,
      "DocumentId": 494869,
      "Type": "OUTGOING_ORDER",
      "Event": "apply",
      "EventDate": "2026-05-15T12:21:23.973"
    }
  ]
}

Поля:

Поле	Опис
`QueueId`	Службовий ідентифікатор події в черзі.
`DocumentId`	Id документа в QUINCEFIN.
`Type`	Тип документа.
`Event`	Тип події.
`EventDate`	Дата і час події в UTC.

Можливі значення Event:

Значення	Опис
`create`	Створення документа.
`update`	Оновлення документа.
`apply`	Проведення документа.
`unapply`	Скасування проведення документа.

Вебхуки документів надсилають ті події, які відображаються в історії змін документа.

Формат вебхука товарів

Приклад тіла запиту:

{
  "Products": [
    {
      "QueueId": 2253,
      "ProductId": 4229,
      "IsFolder": false,
      "Kind": "P",
      "EventDate": "2026-05-06T08:21:26"
    },
    {
      "QueueId": 2252,
      "ProductId": 1800,
      "IsFolder": false,
      "Kind": "P",
      "EventDate": "2026-05-06T08:21:31"
    },
    {
      "QueueId": 2251,
      "ProductId": 1799,
      "IsFolder": false,
      "Kind": "P",
      "EventDate": "2026-05-06T08:21:35"
    }
  ]
}

Поля:

Поле	Опис
`QueueId`	Службовий ідентифікатор події в черзі.
`ProductId`	Id товару, послуги, набору або папки в QUINCEFIN.
`IsFolder`	Ознака папки. `true` означає, що подія стосується папки, а не товарної позиції.
`Kind`	Тип товарної позиції.
`EventDate`	Дата і час оновлення в UTC.

Можливі значення Kind:

Значення	Опис
`S`	Послуга.
`P`	Товар.
`K`	Набір.
`B`	Головний товар SKU.
`U`	Конкретний елемент SKU.

Товар або папка потрапляє в чергу при оновленні картки, зміні ціни або зміні доступної кількості. Доступна кількість може змінюватися після проведення документа з цим товаром.

Для товарів вебхук зараз передає тільки час оновлення без деталізації конкретної дії.

Що має зробити ваш endpoint

Endpoint, який приймає вебхуки, має:

Приймати POST-запити з Content-Type: application/json.
Коректно обробляти пакети з масивом Documents або Products.
Коректно обробляти тестовий запит з порожнім масивом.
Повертати HTTP-статус 2xx тільки після того, як пакет прийнято в обробку.

Якщо ваш сервер поверне помилку, QUINCEFIN повторить відправку цього пакета пізніше.