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

Для кого ця інструкція

Вебхук потрібен, якщо ваш сайт, CRM або складська система мають автоматично отримувати повідомлення про зміни в QUINCEFIN. Він передає подію, а повні дані можна отримати окремим запитом до системи.

Сценарій роботи

Створіть профіль вебхука в QUINCEFIN і вкажіть адресу системи-одержувача.
Перевірте тестове повідомлення та переконайтеся, що ваша система приймає його.
Обробляйте отримані події та повертайте успішну відповідь після прийняття повідомлення.
Перевіряйте чергу подій, якщо одержувач тимчасово недоступний.

Вебхуки дозволяють автоматично отримувати повідомлення з 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",
      "DocumentNumber": "РН-000145",
      "DocumentDate": "2026-05-15T12:10:00",
      "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.
`DocumentNumber`	Номер документа, якщо він доступний.
`DocumentDate`	Дата документа, якщо вона доступна.

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

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

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

Webhook передає факт зміни документа, але не є методом читання повного складу документа або пов’язаних сутностей. Якщо інтеграції потрібен актуальний список відправлень Нової Пошти, викличте /api/v2/document/nova_poshta/list. Якщо потрібні продажі разом із пов’язаними ТТН, перечитайте продаж через /api/v2/document/outgoing_invoice/list, де ТТН повертаються в масиві NovaPoshtaNotes.

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

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

{
  "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 повторить відправку цього пакета пізніше.