ВойтиПодключить склад

Документация ·Вебхук

Вебхук событий

Склад сам отправляет события на ваш адрес — опрашивать API не нужно. Вебхук подключается как канал обмена: у него своя периодичность и свои строки в журнале обменов.

Подключение

«Настройки → Каналы → Вебхук»: адрес, куда слать, и секрет подписи. Секрет хранится шифрованным и в кабинете больше не показывается. Кнопка проверки шлёт на адрес пустой пакет — { warehouseId, events: [], ping: true }, подписанный так же, как настоящие, но без заголовка X-Zantor-Events, — так адрес проверяют до первого настоящего события.

Подпись

Каждый запрос подписан: заголовок X-Zantor-Signature содержит sha256=<HMAC-SHA256 тела запроса вашим секретом>. Считайте подпись по сырому телу до разбора JSON и сравнивайте её постоянным по времени сравнением. Запрос с неверной подписью отклоняйте.

В заголовке X-Zantor-Events — сколько событий в пакете. Тело — { warehouseId, events }, где каждое событие несёт id, type и его название словами — title, время at, кто сделал — actor, предмет события subject и содержимое payload. У события документа — ещё document: вид kind кодом — receipt, order, trip, move, count, wave, kit или service, — уточнение source (return, replen, supplier, owner, unkit; у обычного документа null), номер no и для работ — что делали, service. Товар назван артикулом; рядом идёт наш внутренний itemId — опираться на него не нужно.

Какие события приходят

  • Документы: запущен и закрыт, акт расхождения при приёмке, рейс погружен.
  • Комплектация и работы: набор собран или разобран, работа с товаром сделана — артикул и сколько; спецификация набора изменена.
  • Приёмка: принят товар с незнакомым штрихкодом — штрихкод, количество и документ.
  • Заказ площадки отменён.
  • Решения старшего смены: вопрос задан и ответ дан.
  • Остаток: списание, применённый пересчёт, место выведено из работы.

События до подключения не приходят: отсчёт идёт с момента, когда канал подключили. В пакете события идут по возрастанию id, и следующий пакет продолжает с того места, где остановился прошлый. Событие долгой операции может прийти в следующем пакете с id меньше уже полученных: записано раньше, завершилось позже. Сортируйте по id у себя, если порядок важен.

Ответ и повтор

Ответьте кодом 2xx — пакет считается принятым. Любой другой код или молчание дольше пятнадцати секунд — ошибка: отметка о принятом не сдвигается, и те же события придут снова. Поэтому обработчик должен быть идемпотентным: тот же id события — та же запись у вас.

Отказ виден в кабинете: что ответил адрес и когда.