Вебхуки

Содержание

Введение

Вебхуки в REGOS используются для уведомления внешних систем о событиях, связанных с документами, операциями или кассовыми действиями. Каждое событие отправляется на указанный URL интеграции методом POST в формате JSON. Вебхуки содержат информацию о типе события (action), данных (data) и токене интеграции (connected_integration_id).

Эта документация описывает все поддерживаемые вебхуки, их структуру и примеры обработки.

Общая структура вебхука

Каждый вебхук отправляется в следующем формате:

{
  "action": "HandleWebhook",
  "event_id": "6b6b0a3a-9e5e-4d3a-9f6e-0c6e9ф8b2a11",
  "occurred_at": "2025-10-11T09:21:34Z",
  "connected_integration_id": "string",
  "data": {
    "action": "DocOrderDeliveryAdded",
    "data": {
      "id": 54321
    }
  }
}
  • action: Всегда "HandleWebhook".
  • event_id: Уникальный идентификатор события (UUID). Используйте для идемпотентности/дедупликации — при ретраях остаётся тем же.
  • occurred_at: Время возникновения события в REGOS в формате ISO 8601 (UTC), например 2025-10-11T09:21:34Z.
  • connected_integration_id: Токен интеграции для аутентификации.
  • data.action: Тип события (например, DocOrderDeliveryAdded).
  • data.data: Полезная нагрузка, содержащая идентификаторы и параметры события (например, id, uuid, status, stock_id и т.п. — в зависимости от типа события).

Как обрабатывать вебхуки

  1. Метод: Вебхуки отправляются методом POST.
  2. Аутентификация: Проверьте connected_integration_id для подтверждения источника.
  3. Формат ответа: Ожидается HTTP-статус 200 OK.
  4. Таймаут запроса — 3 секунды.
  5. Повторные попытки: REGOS повторяет отправку до 3 раз в случае недоступности сервера.

Список вебхуков

DocOrderDelivery — Розничные заказы
Название вебхука Данные Источник вызова Описание
DocOrderDeliveryAdded id /v1/DocOrderDelivery/Add Создание нового розничного заказа
DocOrderDeliveryEdited id /v1/DocOrderDelivery/Edit Редактирование заказа
DocOrderDeliveryDeleted id /v1/DocOrderDelivery/Delete Удаление заказа
DocOrderDeliveryStatusSet id, status /v1/DocOrderDelivery/SetStatus Изменение статуса заказа
DocOrderDeliveryStockSet id, stock_id /v1/DocOrderDelivery/SetStock Назначение склада
DocOrderDeliveryCourierSet id, courier_id /v1/DocOrderDelivery/SetCourier Назначение курьера
DocOrderDeliveryReturned id /v1/DocOrderDelivery/Return Возврат заказа
DocOrderDeliveryActualized id /v1/DocOrderDelivery/Actualize Актуализация заказа
DocOrderDeliveryDeleteMarked id /v1/DocOrderDelivery/DeleteMark Пометка заказа как удаленного
DocOrderDeliveryFiscalInfoSet id /v1/DocOrderDelivery/FiscalInfo Установка фискальной информации
DocOrderDeliveryResetToBeginning id /v1/DocOrderDelivery/ResetToBeginning Сброс заказа к начальному состоянию
DocPurchase — Поступления от контрагента
Название вебхука Данные Источник вызова Описание
DocPurchaseAdded id /v1/DocPurchase/Add Создание поступления
DocPurchaseEdited id /v1/DocPurchase/Edit Редактирование поступления
DocPurchaseDeleteMarked id /v1/DocPurchase/DeleteMark Пометка поступления как удаленного
DocPurchasePerformed id /v1/DocPurchase/Perform Выполнение поступления
DocPurchasePerformCanceled id /v1/DocPurchase/PerformCancel Отмена выполнения поступления
DocOrderToPartner — Заказы контрагенту
Название вебхука Данные Источник вызова Описание
DocOrderToPartnerAdded id /v1/DocOrderToPartner/Add Создание заказа контрагенту
DocOrderToPartnerEdited id /v1/DocOrderToPartner/Edit Редактирование заказа контрагенту
DocOrderToPartnerDeleteMarked id /v1/DocOrderToPartner/DeleteMark Пометка заказа как удаленного
DocReturnsToPartner — Возвраты контрагенту
Название вебхука Данные Источник вызова Описание
DocReturnsToPartnerAdded id /v1/DocReturnsToPartner/Add Создание возврата контрагенту
DocReturnsToPartnerEdited id /v1/DocReturnsToPartner/Edit Редактирование возврата
DocReturnsToPartnerDeleteMarked id /v1/DocReturnsToPartner/DeleteMark Пометка возврата как удаленного
DocReturnsToPartnerPerformed id /v1/DocReturnsToPartner/Perform Выполнение возврата
DocReturnsToPartnerPerformCanceled id /v1/DocReturnsToPartner/PerformCancel Отмена выполнения возврата
DocWholeSale — Отгрузки контрагенту
Название вебхука Данные Источник вызова Описание
DocWholeSaleAdded id /v1/DocWholeSale/Add Создание отгрузки контрагенту
DocWholeSaleEdited id /v1/DocWholeSale/Edit Редактирование отгрузки
DocWholeSaleDeleteMarked id /v1/DocWholeSale/DeleteMark Пометка отгрузки как удаленной
DocWholeSalePerformed id /v1/DocWholeSale/Perform Выполнение отгрузки
DocWholeSalePerformCanceled id /v1/DocWholeSale/PerformCancel Отмена выполнения отгрузки
DocOrderFromPartner — Заказы от контрагентов
Название вебхука Данные Источник вызова Описание
DocOrderFromPartnerAdded id /v1/DocOrderFromPartner/Add Создание заказа от контрагента
DocOrderFromPartnerEdited id /v1/DocOrderFromPartner/Edit Редактирование заказа
DocOrderFromPartnerDeleteMarked id /v1/DocOrderFromPartner/DeleteMark Пометка заказа как удаленного
DocWholeSaleReturn — Возвраты от контрагентов
Название вебхука Данные Источник вызова Описание
DocWholeSaleReturnAdded id /v1/DocWholeSaleReturn/Add Создание возврата от контрагента
DocWholeSaleReturnEdited id /v1/DocWholeSaleReturn/Edit Редактирование возврата
DocWholeSaleReturnDeleteMarked id /v1/DocWholeSaleReturn/DeleteMark Пометка возврата как удаленного
DocWholeSaleReturnPerformed id /v1/DocWholeSaleReturn/Perform Выполнение возврата
DocWholeSaleReturnPerformCanceled id /v1/DocWholeSaleReturn/PerformCancel Отмена выполнения возврата
DocMovement — Перемещения
Название вебхука Данные Источник вызова Описание
DocMovementAdded id /v1/DocMovement/Add Создание документа перемещения
DocMovementEdited id /v1/DocMovement/Edit Редактирование перемещения
DocMovementMarkedDeleted id /v1/DocMovement/DeleteMark Пометка перемещения как удаленного
DocMovementPerformed id /v1/DocMovement/Perform Выполнение перемещения
DocMovementPerformCanceled id /v1/DocMovement/PerformCancel Отмена выполнения перемещения
DocOrderToMovement — Заказы на перемещение
Название вебхука Данные Источник вызова Описание
DocOrderToMovementAdded id /v1/DocOrderToMovement/Add Создание заказа на перемещение
DocOrderToMovementEdited id /v1/DocOrderToMovement/Edit Редактирование заказа
DocOrderToMovementDeleteMarked id /v1/DocOrderToMovement/DeleteMark Пометка заказа как удаленного
DocInventory — Инвентаризация
Название вебхука Данные Источник вызова Описание
DocInventoryAdded id /v1/DocInventory/Add Создание инвентаризации
DocInventoryEdited id /v1/DocInventory/Edit Редактирование инвентаризации
DocInventoryDeleteMarked id /v1/DocInventory/DeleteMark Пометка инвентаризации как удаленной
DocInventoryClosed id /v1/DocInventory/Close Закрытие инвентаризации
DocInventoryOpened id /v1/DocInventory/Open Открытие инвентаризации
DocInOut — Списание/внесение
Название вебхука Данные Источник вызова Описание
DocInOutAdded id /v1/DocInOut/Add Создание списания/внесения
DocInOutEdited id /v1/DocInOut/Edit Редактирование списания/внесения
DocInOutDeleteMarked id /v1/DocInOut/DeleteMark Пометка списания/внесения как удаленного
DocInOutPerformed id /v1/DocInOut/Perform Выполнение списания/внесения
DocInOutPerformCanceled id /v1/DocInOut/PerformCancel Отмена выполнения списания/внесения
PromoBonus — Бонусные операции
Название вебхука Данные Источник вызова Описание
PromoBonusPaymentPerformed uuid, value /v1/PromoBonus/PaymentPerformed Выполнение бонусного платежа
PromoBonusEnrollmentPerformed uuid, value /v1/PromoBonus/EnrollmentPerformed Начисление бонусов
PromoBonusPaymentCanceled uuid, value /v1/PromoBonus/PaymentCanceled Отмена бонусного платежа
PromoBonusManualIncomeOperationCreated uuid, value /v1/PromoBonus/ManualIncome Создание ручного начисления бонусов
PromoBonusManualOutcomeOperationCreated uuid, value /v1/PromoBonus/ManualOutcome Создание ручного списания бонусов
Касса и чеки
Название вебхука Данные Источник вызова
DocChequeClosed uuid /POS/Cheque/Close, /SyncAdd/DocRetailSale (status=Closed)
DocChequeCanceled uuid /POS/Cheque/Cancel, /SyncAdd/DocRetailSale (status=Canceled)
DocSessionOpened uuid /pos/Session/Open, /v1/SyncAdd/DocCashSession (closed=false)
DocSessionClosed uuid /pos/Session/Close, /v1/SyncAdd/DocCashSession (closed=true)
DocPayment — Платежи
Название вебхука Данные Источник вызова Описание
DocPaymentAdded id /v1/DocPayment/Add Создание платежа
DocPaymentEdited id /v1/DocPayment/Edit Редактирование платежа
DocPaymentDeleteMarked id /v1/DocPayment/DeleteMark Пометка платежа как удаленного
DocPaymentPerformed id /v1/DocPayment/Perform Выполнение платежа
DocPaymentPerformCanceled id /v1/DocPayment/PerformCancel Отмена выполнения платежа
SMS — Отправка одиночных SMS
Название вебхука Данные Источник вызова Описание
SMSAdded id Не указан Создание одиночного SMS
SMSStatus id, status Не указан Изменение статуса SMS
Campaign — Массовая рассылка SMS
Название вебхука Данные Источник вызова Описание
CampaignAdded id Не указан Создание массовой рассылки SMS
CampaignSetRecipientsStatusSet id, status Не указан Изменение статуса получателей рассылки
RetailCustomer — Розничный покупатель
Название вебхука Данные Источник вызова Описание
RetailCustomerAdded id RetailCustomer/Add, RetailCard/Addwithcustomer Создание розничного покупателя (в т.ч. при создании карты с покупателем)
RetailCustomerEdited id RetailCustomer/Edit Редактирование розничного покупателя
RetailCustomerDeleteMarked id RetailCustomer/DeleteMark Пометка розничного покупателя как удалённого
RetailCustomerDeleted id RetailCustomer/Delete Удаление розничного покупателя
RetailCard — Карта лояльности
Название вебхука Данные Источник вызова Описание
RetailCardAdded id RetailCard/Add, RetailCard/Addwithcustomer Создание карты лояльности
RetailCardEdited id RetailCard/Edit Редактирование карты лояльности
RetailCardDeleted id RetailCard/Delete Удаление карты лояльности
Partner— Контрагент
Название вебхука Данные Источник вызова Описание
PartnerAdded id Partner/Add Создание контрагента
PartnerEdited id Partner/Edit Редактирование контрагента
PartnerDeleteMarked id Partner/DeleteMark Пометка контрагента как удалённого
PartnerDeleted id Partner/Delete Удаление контрагента
Item — Номенклатура
Название вебхука Данные Источник вызова Описание
ItemAdded id /Item/Add, /Item/Copy, /Item/Import Создание номенклатуры
ItemEdited id /Item/Edit, /Item/AddToCompound (compound_id), /Item/DeleteFromCompound (compound_id) Редактирование номенклатуры
ItemDeleted id /Item/Delete Удаление номенклатуры
ItemDeleteMarked id /Item/DeleteMark Пометка номенклатуры как удалённой

Примеры вебхука

{
  "action": "HandleWebhook",
  "event_id": "6b6b0a3a-9e5e-4d3a-9f6e-0c6e9ф8b2a11",
  "occurred_at": "2025-10-11T09:21:34Z",
  "connected_integration_id": "string",
  "data": {
    "action": "DocOrderDeliveryAdded",
    "data": {
      "id": 54321
    }
  }
}