Событие перед удалением по веб-хуку

[OnBeforeDeleteItem] Удаление сущности в МойСклад

Доступно с версии 3.9.0

На более ранних версиях событие не вызывается.

Событие OnBeforeDeleteItem вызывается, когда из МойСклад пришёл веб-хук с действием DELETE. Срабатывает до любых изменений: до того, как модуль удалит запись из своего HL-кеша и начнёт искать элемент в инфоблоке. Проверки самого веб-хука — соль, принадлежность href API МойСклад, дедупликация, реестр OnBuildWebhookEntityList — к этому моменту уже пройдены.

Главное отличие от остальных событий модуля: событие приходит даже если элемента в каталоге Битрикс нет вообще. Сущность могла никогда не импортироваться, попадать под фильтр по группе или быть архивной — веб-хук об удалении всё равно придёт, и кастомный код получит о нём сигнал.

к сведению

Обработчик может отменить штатную обработку, вернув EventResult::ERROR. Тогда модуль выйдет, не тронув ни HL-кеш, ни элемент инфоблока.

Для каких сущностей срабатывает

Сущность	Что делает модуль после события
product, variant, bundle, service	Удаляет или деактивирует элемент инфоблока — в зависимости от настройки «Удалять элемент при удалении в МойСклад»
productfolder	Удаляет запись из HL-кеша разделов и удаляет/деактивирует раздел инфоблока. Если HL-кеша разделов нет или записи для href в нём нет — не делает ничего

Событие вызывается только для действия DELETE. Веб-хуки CREATE и UPDATE до него не доходят.

Событие не вызывается:

• для productfolder, если импорт групп выключен;
• для variant, если модификации загружаются агентом (опция variant_load_agent);
• если сущность объявлена в реестре OnBuildWebhookEntityList в режиме replace (или DELETE не входит в объявленные действия), либо обработчик в режиме before отменил обработку.

Исключения не перехватываются

Исключение из обработчика модуль не ловит: оно обрывает обработку остальных событий этого веб-хука. Оборачивайте свой код в try/catch.

Описание события

Параметры события

Параметр	Тип	Описание
hook	object	Объект веб-хука от МойСклад целиком
entity	string	Сущность: product, variant, bundle, service, productfolder
href	string	Ссылка на удалённую сущность в API МойСклад
xmlId	string	Внешний код (XML_ID) элемента в Битрикс, если модулю удалось его разрешить

предупреждение

Что лежит в xmlId, зависит от режима идентификации:

• по идентификатору МойСклад — UUID из href. Он приходит всегда, поэтому непустой xmlId не значит, что элемент есть в Битрикс: проверяйте наличие элемента сами;
• по внешним кодам (HL-кеш ExtCodes) и для групп (HL-кеш PFolder) — код из кеша. Пустая строка значит, что записи для этого href в кеше нет: сущность, скорее всего, не импортировалась.

Возвращаемое значение

Возвращать ничего не обязательно — событие можно использовать как информационное.

Чтобы отменить штатное удаление или деактивацию:

return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::ERROR);

Отмена работает целиком: запись HL-кеша остаётся на месте, элемент инфоблока не трогается. Если обработчиков несколько, достаточно ERROR от любого из них.

Пример вызова события

//Пример кода нужно вставить в файл init.php

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'rbs.moyskladstocks',
    'OnBeforeDeleteItem',
    'OnBeforeDeleteItemHandler'
);

function OnBeforeDeleteItemHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();

    // $hook — объект веб-хука МойСклад:
    // $hook->action          // 'DELETE'
    // $hook->meta->type      // 'product' | 'variant' | 'bundle' | 'service' | 'productfolder'
    // $hook->meta->href      // 'https://api.moysklad.ru/api/remap/1.2/entity/product/...'
    $hook = $eventParams['hook'];

    $entity = $eventParams['entity']; // тип сущности МойСклад
    $href   = $eventParams['href'];   // ссылка на сущность в API МойСклад
    $xmlId  = $eventParams['xmlId'];  // внешний код элемента, может быть пустым

    #WORK_AREA#
}

Примеры использования

Журнал удалений, включая непроимпортированные сущности

function OnBeforeDeleteItemHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();

    YourAuditLogger::log([
        'event'     => 'ms_entity_deleted',
        'entity'    => $eventParams['entity'],
        'href'      => $eventParams['href'],
        'xml_id'    => $eventParams['xmlId'],
        'timestamp' => date('Y-m-d H:i:s'),
    ]);
}

Запретить удаление товаров, участвующих в незавершённых заказах

function OnBeforeDeleteItemHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();

    if ($eventParams['entity'] !== 'product' || $eventParams['xmlId'] === '') {
        return;
    }

    // Проверка — на стороне разработчика
    if (YourOrderChecker::hasActiveOrders($eventParams['xmlId'])) {
        // Модуль не тронет ни HL-кеш, ни элемент инфоблока
        return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::ERROR);
    }
}

Своя логика вместо штатной: перенос в архивный раздел

function OnBeforeDeleteItemHandler(\Bitrix\Main\Event $event)
{
    $eventParams = $event->getParameters();

    if ($eventParams['xmlId'] === '') {
        return;
    }

    // Переносим элемент в свой раздел «Снято с продажи»
    YourArchiver::moveToArchive($eventParams['xmlId'], $eventParams['entity']);

    // Отменяем штатное удаление/деактивацию
    return new \Bitrix\Main\EventResult(\Bitrix\Main\EventResult::ERROR);
}