Структура веб-хука и создание веб-хука

Во вкладке «Веб-хуки» для каждой пары «сущность / событие», которую поддерживает модуль, выводится отдельный блок «Сущность: … / Событие: …». В нём показаны все веб-хуки этой пары, установленные в аккаунте МойСклад, — в том числе созданные другими приложениями. Веб-хуки на другие сущности и события во вкладке не показываются.

Поддерживаемые пары:

• customerorder — CREATE, UPDATE
• paymentin — CREATE, UPDATE, DELETE
• cashin — CREATE, UPDATE, DELETE
• demand — CREATE, UPDATE

Что есть в каждом блоке:

• Тип выполнения веб-хука — моментально, в очереди или смешанно (см. ниже)
• Список установленных веб-хуков — адрес, на который МойСклад отправляет уведомления, и статус: «Активен» (зелёный) или «Неактивен» (красный). Если веб-хука нет, выводится надпись «Веб-хук … на событие … не установлен»
• Напротив каждого установленного веб-хука — галочки «Обновить» и «Удалить»
• Внизу блока — галочка «Создать»

Все действия выполняются при сохранении настроек модуля: отметьте нужные галочки и нажмите «Сохранить».

Галочка	Что делает при сохранении
Создать	Создаёт в МойСклад новый веб-хук на эту сущность и событие с адресом из поля «Полный путь до веб-хука» и текущей проверочной строкой. Если МойСклад вернул ошибку, она выводится вверху страницы
Обновить	Переписывает адрес выбранного веб-хука на текущий адрес из настроек вместе с проверочной строкой
Удалить	Удаляет выбранный веб-хук из аккаунта МойСклад

Важно!

Обновляйте и удаляйте только те веб-хуки, где указан адрес вашего сайта. Другие веб-хуки работают от других приложений — их трогать не нужно: галочка «Обновить» перенаправит такой веб-хук на ваш сайт, а «Удалить» удалит его из МойСклад, и другое приложение перестанет получать уведомления.

Что делать:

• Первая установка модуля — создавайте новые веб-хуки
• Веб-хуки уже созданы — при изменении URL или проверочной строки обновляйте существующие веб-хуки модуля

Не создавайте второй веб-хук на ту же сущность и событие с адресом вашего сайта: МойСклад будет присылать каждое уведомление дважды.

Веб-хук «Неактивен»

Неактивный веб-хук МойСклад не вызывает. Чтобы пересоздать его, отметьте у него галочку «Удалить», в этом же блоке — «Создать», и сохраните настройки: модуль сначала удалит старый веб-хук, затем создаст новый.

Тип выполнения веб-хука

Новая функция

Опция доступна с версии 3.0.0. В ней реализован функционал очереди задач для выполнения веб-хуков.

Данная опция настраивается для каждой пары «сущность / событие» отдельно. Это позволяет точечно выбирать, какие веб-хуки выполнять моментально, а какие — в очереди. По умолчанию — «Выполнять моментально».

Варианты выполнения веб-хука

1. Выполнять моментально

• Веб-хук выполняется сразу же при получении
• Если в веб-хуке пришло больше сущностей, чем задано в ограничении, лишние уходят в очередь

2. Выполнять отложенно в очереди

• Все сущности из веб-хука направляются в очередь и выполняются поэтапно агентом
• Преимущество: нет ограничений на количество изменяемых сущностей, нагрузка на сайт в момент получения веб-хука минимальна
• Недостаток: изменения попадут на сайт с задержкой — при следующем запуске агента очереди

3. Первый элемент выполнять моментально, остальные отложенно в очереди

• Смешанный режим выполнения
• При получении нескольких сущностей в одном веб-хуке: первая обрабатывается сразу, остальные добавляются в очередь
• Удобно, когда обычно меняется один заказ (он обновится сразу), а массовые изменения не должны нагружать сайт

Как работает очередь веб-хуков?

Шаг 1: Настройка после обновления

После обновления до версии 3.0.0:

1. Зайдите в настройки модуля
2. Сохраните настройки

Это создаст:

• Нужные таблицы для очередей
• Новый агент \Rbs\Moysklad\Agent::webhook_tasker_worker() для обработки очереди

Если таблицу очереди создать не удалось, при сохранении настроек вверху страницы появится сообщение об ошибке.

Шаг 2: Работа системы

Когда хотя бы один веб-хук настроен на выполнение в очереди (или в веб-хуке пришло больше сущностей, чем позволяет ограничение):

• Изменения из МойСклад для этого веб-хука добавляются в очередь
• Агент запускается с интервалом из опции «Интервал срабатывания агентов (сек)» во вкладке Прочее (по умолчанию каждую минуту) и обрабатывает за один шаг столько задач, сколько задано в ограничениях
• Все действия логируются в разделе диагностики

Обязательный веб-хук

Обязательно для работы модуля

Для первичной настройки модуля необходимо установить веб-хук:

• Сущность: customerorder
• Событие: UPDATE

Этот веб-хук отслеживает изменения заказов в МойСклад и передает их на сайт.

После установки веб-хук появится в списке:

Что делает модуль при получении customerorder / UPDATE:

• находит заказ на сайте по заказу МойСклад; если заказа нет или обмен по нему отключён — пропускает уведомление;
• переносит изменения в заказ на сайте согласно включённым настройкам обмена: статус, отмену, комментарии, свойства, трек-номера, склад, способы доставки и оплаты, стоимость доставки, состав корзины и т.д.;
• если изменилась сумма заказа — дополнительно обновляет название и данные платёжной системы, пересчитывает корзину и сверяет оплаты (если включены соответствующие опции).

к сведению

Если во вкладке «Импорт заказа» выбран способ создания заказа [UPDATE], этот же веб-хук импортирует на сайт заказ, которого там ещё нет и у которого в МойСклад отмечен флажок импорта. Подробнее — Способы импорта заказа из МС.

Изменение настроек веб-хука

Для изменения URL или проверочной строки:

1. Измените настройки в разделе Настройка URL
2. Отметьте галочку «Обновить» напротив веб-хуков, созданных модулем (с адресом вашего сайта)
3. Сохраните настройки модуля

Модуль перепишет адрес отмеченных веб-хуков на новый вместе с проверочной строкой.

Дополнительные веб-хуки

Импорт заказов

Веб-хук: customerorder / CREATE

Когда нужен

Устанавливайте этот веб-хук, если хотите импортировать заказы из МойСклад на сайт.

Настройки: находятся во вкладке "Импорт заказа". Без включённого импорта заказов веб-хук CREATE заказ на сайте не создаёт.

После импорта заказа модуль также подтягивает его оплаты (при полном обмене оплатами [full]) и выгружает отгрузки (при полном обмене отгрузками [full] с направлением из сайта в МойСклад). Если заказ не удалось создать с первого раза, модуль делает до 5 попыток.

Управление платежами

Веб-хуки для входящих платежей:

• paymentin / CREATE, UPDATE, DELETE

Веб-хуки для приходных ордеров:

• cashin / CREATE, UPDATE, DELETE

Когда нужны

Устанавливайте эти веб-хуки, если во вкладке "Оплаты" включён обмен оплатами и выбран тип обмена full — см. Параметры полного обмена оплат. При другом типе обмена модуль такие уведомления пропускает.

Важно: устанавливайте сразу все три события (CREATE, UPDATE, DELETE) для каждой сущности.

Что делает модуль: находит заказы на сайте, к которым привязан платёж в МойСклад, и при CREATE / UPDATE создаёт или обновляет оплату в заказе, при DELETE — удаляет её. Затем сверяет оплаты этих заказов.

Управление отгрузками

Веб-хуки: demand / CREATE, UPDATE

Когда нужны

Устанавливайте эти веб-хуки, если во вкладке "Отгрузки" выбран тип обмена отгрузками full и направление обмена включает передачу из МойСклад на сайт — см. Полное соответствие отгрузок БУС-МС. Иначе модуль такие уведомления пропускает.

Важно: устанавливайте сразу оба события (CREATE, UPDATE).

Что делает модуль: находит заказ на сайте, к которому относится отгрузка, и обновляет по ней отгрузку в заказе. Если изменилась стоимость доставки и включена её синхронизация, модуль обновляет стоимость доставки в заказе и сверяет оплаты.

Удаление отгрузки в МойСклад на сайт не переносится.