Налаштування повідомлень про статус повернення 1С-Бітрікс

Налаштування сповіщень про статус повернення 1С-Бітрікс

Сповіщення при зміні статусу повернення — одна з точок, де магазин або викликає довіру, або втрачає клієнта. Покупець, який чекає на рішення по поверненню, хвилюється. Своєчасний лист зі статусом знімає дзвінки в підтримку та формує позитивний досвід навіть у ситуації повернення. У Бітрікс для цього використовується система поштових шаблонів (b_event_type, b_event_message) у зв'язці з подіями модуля sale.

Механізм сповіщень у Бітрікс

Сповіщення будуються на трьох рівнях:

1. Тип поштової події (b_event_type) — визначає набір доступних змінних
2. Шаблон поштової події (b_event_message) — HTML-тіло листа, тема, адресат
3. Виклик CEvent::Send() — тригер відправки, передає значення змінних

Реєстрація типів подій для статусів повернення

По одному типу події на кожен статус, де потрібно сповіщати покупця:

// /local/install/register_return_events.php
$returnEventTypes = [
    [
        'EVENT_NAME'  => 'RETURN_STATUS_REVIEW',
        'NAME'        => 'Повернення: прийнято на розгляд',
        'DESCRIPTION' => "RETURN_ID, ORDER_ID, ORDER_ACCOUNT_NUMBER, USER_NAME, USER_EMAIL, STATUS_NAME",
        'SORT'        => 100,
    ],
    [
        'EVENT_NAME'  => 'RETURN_STATUS_NEED_DOCS',
        'NAME'        => 'Повернення: необхідні документи',
        'DESCRIPTION' => "RETURN_ID, ORDER_ID, ORDER_ACCOUNT_NUMBER, USER_NAME, USER_EMAIL, STATUS_NAME, MANAGER_COMMENT",
        'SORT'        => 110,
    ],
    [
        'EVENT_NAME'  => 'RETURN_STATUS_APPROVED',
        'NAME'        => 'Повернення: схвалено',
        'DESCRIPTION' => "RETURN_ID, ORDER_ID, REFUND_AMOUNT, SHIPPING_INSTRUCTIONS",
        'SORT'        => 120,
    ],
    [
        'EVENT_NAME'  => 'RETURN_STATUS_RECEIVED',
        'NAME'        => 'Повернення: товар отримано на склад',
        'DESCRIPTION' => "RETURN_ID, ORDER_ID, REFUND_AMOUNT",
        'SORT'        => 130,
    ],
    [
        'EVENT_NAME'  => 'RETURN_STATUS_REFUND',
        'NAME'        => 'Повернення: гроші повернено',
        'DESCRIPTION' => "RETURN_ID, ORDER_ID, REFUND_AMOUNT, REFUND_DATE, PAYMENT_METHOD",
        'SORT'        => 140,
    ],
    [
        'EVENT_NAME'  => 'RETURN_STATUS_REJECTED',
        'NAME'        => 'Повернення: відхилено',
        'DESCRIPTION' => "RETURN_ID, ORDER_ID, MANAGER_COMMENT, APPEAL_INSTRUCTIONS",
        'SORT'        => 150,
    ],
];

$eventType = new \CEventType();

foreach ($returnEventTypes as $type) {
    $existing = \CEventType::GetList(['EVENT_NAME' => $type['EVENT_NAME']])->Fetch();
    if (!$existing) {
        $eventType->Add(array_merge($type, ['LID' => LANGUAGE_ID]));
    }
}

Відправка сповіщення при зміні статусу

namespace Local\Returns;

class Notifications
{
    private const STATUS_EVENT_MAP = [
        'REVIEW'    => 'RETURN_STATUS_REVIEW',
        'NEED_DOCS' => 'RETURN_STATUS_NEED_DOCS',
        'APPROVED'  => 'RETURN_STATUS_APPROVED',
        'RECEIVED'  => 'RETURN_STATUS_RECEIVED',
        'REFUND'    => 'RETURN_STATUS_REFUND',
        'REJECTED'  => 'RETURN_STATUS_REJECTED',
    ];

    public static function sendStatusChange(int $returnId, string $newStatus): void
    {
        $eventName = self::STATUS_EVENT_MAP[$newStatus] ?? null;
        if (!$eventName) return;

        $data = self::buildEventData($returnId, $newStatus);
        if (!$data) return;

        \CEvent::Send($eventName, SITE_ID, $data);
    }

    private static function buildEventData(int $returnId, string $status): ?array
    {
        $return = \Bitrix\Sale\OrderReturnTable::getList([
            'filter' => ['ID' => $returnId],
            'select' => ['ID', 'ORDER_ID', 'REFUND_AMOUNT', 'STATUS_ID', 'MANAGER_COMMENT'],
        ])->fetch();

        if (!$return) return null;

        $order = \Bitrix\Sale\Order::load($return['ORDER_ID']);
        if (!$order) return null;

        $user = \CUser::GetByID($order->getUserId())->Fetch();

        $data = [
            'RETURN_ID'           => $returnId,
            'ORDER_ID'            => $return['ORDER_ID'],
            'ORDER_ACCOUNT_NUMBER'=> $order->getField('ACCOUNT_NUMBER'),
            'USER_NAME'           => trim(($user['NAME'] ?? '') . ' ' . ($user['LAST_NAME'] ?? '')),
            'USER_EMAIL'          => $user['EMAIL'] ?? '',
            'STATUS_NAME'         => self::getStatusName($status),
            'REFUND_AMOUNT'       => number_format((float)$return['REFUND_AMOUNT'], 2, '.', ' ') . ' грн',
            'MANAGER_COMMENT'     => $return['MANAGER_COMMENT'] ?? '',
            'RETURN_URL'          => self::getReturnUrl($returnId),
        ];

        // Специфічні дані для статусів
        if ($status === 'APPROVED') {
            $data['SHIPPING_INSTRUCTIONS'] = self::getShippingInstructions();
        }

        if ($status === 'REFUND') {
            $data['REFUND_DATE']    = (new \Bitrix\Main\Type\DateTime())->format('d.m.Y');
            $data['PAYMENT_METHOD'] = self::getPaymentMethodName($order);
        }

        if ($status === 'REJECTED') {
            $data['APPEAL_INSTRUCTIONS'] = 'Ви можете звʼязатися з нами за телефоном +380 (800) 555-35-35';
        }

        return $data;
    }

    private static function getStatusName(string $statusId): string
    {
        $result = \CSaleOrderReturnStatus::GetByID($statusId);
        return $result['NAME'] ?? $statusId;
    }

    private static function getReturnUrl(int $returnId): string
    {
        return 'https://' . SITE_SERVER_NAME . '/personal/returns/' . $returnId . '/';
    }
}

Інтеграція з обробником зміни статусу

// В init.php — вішаємо сповіщення на події модуля sale
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'OnSaleOrderReturnStatusChange',
    function (\Bitrix\Main\Event $event) {
        $returnId  = $event->getParameter('RETURN_ID');
        $newStatus = $event->getParameter('NEW_STATUS_ID');

        \Local\Returns\Notifications::sendStatusChange($returnId, $newStatus);
    }
);

SMS-сповіщення

Для критичних статусів (гроші повернено, схвалено) додаємо SMS через SMSC, SMS.ru або іншого провайдера:

class SmsNotifier
{
    private const SMS_STATUSES = ['APPROVED', 'REFUND', 'REJECTED'];

    public static function maybeSend(int $returnId, string $status): void
    {
        if (!in_array($status, self::SMS_STATUSES, true)) return;

        $phone = self::getCustomerPhone($returnId);
        if (!$phone) return;

        $text = self::buildSmsText($returnId, $status);

        $client = new \Local\Sms\SmsClient();
        $client->send($phone, $text);
    }

    private static function buildSmsText(int $returnId, string $status): string
    {
        return match ($status) {
            'APPROVED' => "Повернення #{$returnId} схвалено. Надішліть товар за адресою: ...",
            'REFUND'   => "Повернення #{$returnId}: гроші відправлено. Надійдуть на картку протягом 3-5 днів.",
            'REJECTED' => "Повернення #{$returnId} відхилено. Причина — в листі на вашу пошту.",
            default    => "Статус заявки на повернення #{$returnId} змінено.",
        };
    }
}

Push-сповіщення в особистому кабінеті

Окрім email та SMS — сповіщення в браузері через Web Push або через механізм сповіщень особистого кабінету:

// Додаємо сповіщення в ЛК Бітрікс (якщо є модуль im або кастомний)
class LkNotifier
{
    public static function notify(int $userId, int $returnId, string $status): void
    {
        // Через модуль im (корпоративний портал)
        if (\Bitrix\Main\Loader::includeModule('im')) {
            \CIMNotify::Add([
                'FROM_USER_ID' => 0, // від системи
                'TO_USER_ID'   => $userId,
                'NOTIFY_TYPE'  => IM_NOTIFY_SYSTEM,
                'NOTIFY_MODULE'=> 'local.returns',
                'NOTIFY_TAG'   => 'RETURN_' . $returnId,
                'NOTIFY_MESSAGE' => "Статус заявки на повернення #{$returnId} змінено на «" .
                    \Local\Returns\Notifications::getStatusName($status) . "»",
                'NOTIFY_MESSAGE_OUT' => 'Статус заявки змінено',
            ]);
        }
    }
}

Шаблон листа: статус «Схвалено»

Приклад HTML-шаблону для події RETURN_STATUS_APPROVED:

Тема: Ваша заявка на повернення #[RETURN_ID] схвалена

Шановний(а) [USER_NAME],

Вашу заявку на повернення товару по замовленню [ORDER_ACCOUNT_NUMBER] схвалено.

Сума до повернення: [REFUND_AMOUNT]

Для завершення повернення, будь ласка, надішліть товар за адресою:
[SHIPPING_INSTRUCTIONS]

Після отримання товару на нашому складі гроші будуть переведені протягом 3 робочих днів.

Відстежувати статус заявки: [RETURN_URL]

Склад робіт

• Реєстрація типів поштових подій під кожен статус
• HTML-шаблони листів: тема, тіло, списки змінних
• Обробник OnSaleOrderReturnStatusChange → виклик CEvent::Send()
• SMS-сповіщення для критичних статусів
• Сповіщення в особистому кабінеті через IM-модуль або кастомний механізм
• Тестування: перевірка всіх статусних переходів та відправки листів

Терміни: повний набір сповіщень під усі статуси — 1–2 тижні.