Настройка статусов возврата на 1С-Битрикс

Настройка статусов возврата на 1С-Битрикс

Статусы возврата в Битрикс — это не просто метки в базе данных. От того, как они настроены, зависит весь бизнес-процесс: что видит покупатель, какие действия доступны менеджеру на каждом этапе, когда автоматически срабатывают уведомления и интеграции с внешними системами. Стандартный набор из коробки минимален и не покрывает реальные сценарии.

Управление статусами: где это живёт

Статусы возврата хранятся в таблице b_sale_order_return_status и управляются через класс \CSaleOrderReturnStatus. Административный интерфейс: Интернет-магазин → Статусы возвратов.

Поля статуса:

• ID — строковый идентификатор (WAIT, REVIEW, APPROVED и т.д.)
• NAME — название для отображения
• DESCRIPTION — описание для внутреннего использования
• SORT — порядок отображения
• COLOR — цвет метки в интерфейсе (hex)
• NOTIFY — флаг: отправлять ли уведомление покупателю при переходе в этот статус
• TEMPLATE — шаблон email-уведомления

Создание кастомного набора статусов

// /local/install/return_statuses.php — скрипт установки статусов
$statuses = [
    [
        'ID'          => 'WAIT',
        'NAME'        => 'Ожидает рассмотрения',
        'DESCRIPTION' => 'Заявка поступила, не обработана',
        'SORT'        => 100,
        'COLOR'       => '#f0ad4e',
        'NOTIFY'      => 'N',
    ],
    [
        'ID'          => 'REVIEW',
        'NAME'        => 'На рассмотрении',
        'DESCRIPTION' => 'Менеджер проверяет заявку',
        'SORT'        => 200,
        'COLOR'       => '#5bc0de',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_REVIEW',
    ],
    [
        'ID'          => 'NEED_DOCS',
        'NAME'        => 'Нужны документы',
        'DESCRIPTION' => 'Запрошены дополнительные документы или фото',
        'SORT'        => 250,
        'COLOR'       => '#d9534f',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_NEED_DOCS',
    ],
    [
        'ID'          => 'APPROVED',
        'NAME'        => 'Одобрен',
        'DESCRIPTION' => 'Возврат одобрен, ожидаем отправку товара',
        'SORT'        => 300,
        'COLOR'       => '#5cb85c',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_APPROVED',
    ],
    [
        'ID'          => 'RECEIVED',
        'NAME'        => 'Товар получен',
        'DESCRIPTION' => 'Склад принял возвращённый товар',
        'SORT'        => 400,
        'COLOR'       => '#337ab7',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_RECEIVED',
    ],
    [
        'ID'          => 'REFUND',
        'NAME'        => 'Деньги возвращены',
        'DESCRIPTION' => 'Платёж проведён',
        'SORT'        => 500,
        'COLOR'       => '#3c763d',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_REFUND',
    ],
    [
        'ID'          => 'EXCHANGE',
        'NAME'        => 'Обмен',
        'DESCRIPTION' => 'Вместо возврата денег произведён обмен',
        'SORT'        => 450,
        'COLOR'       => '#8a6d3b',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_EXCHANGE',
    ],
    [
        'ID'          => 'REJECTED',
        'NAME'        => 'Отклонён',
        'DESCRIPTION' => 'Возврат отклонён',
        'SORT'        => 600,
        'COLOR'       => '#a94442',
        'NOTIFY'      => 'Y',
        'TEMPLATE'    => 'RETURN_STATUS_REJECTED',
    ],
];

foreach ($statuses as $statusData) {
    // Проверяем, не существует ли уже
    $existing = \CSaleOrderReturnStatus::GetByID($statusData['ID']);
    if ($existing) {
        \CSaleOrderReturnStatus::Update($statusData['ID'], $statusData);
    } else {
        \CSaleOrderReturnStatus::Add($statusData);
    }
}

Матрица переходов между статусами

Не все переходы должны быть доступны. Например, нельзя перейти из «Деньги возвращены» обратно в «Ожидает рассмотрения». Реализуем матрицу разрешённых переходов:

namespace Local\Returns;

class StatusTransitionMatrix
{
    // [текущий статус] => [разрешённые следующие статусы]
    private const ALLOWED_TRANSITIONS = [
        'WAIT'      => ['REVIEW', 'REJECTED'],
        'REVIEW'    => ['NEED_DOCS', 'APPROVED', 'REJECTED'],
        'NEED_DOCS' => ['REVIEW', 'REJECTED'],
        'APPROVED'  => ['RECEIVED', 'EXCHANGE'],
        'RECEIVED'  => ['REFUND', 'EXCHANGE'],
        'REFUND'    => [],       // терминальный статус
        'EXCHANGE'  => [],       // терминальный статус
        'REJECTED'  => ['WAIT'], // можно пересмотреть решение
    ];

    // Переходы, доступные только администратору
    private const ADMIN_ONLY = [
        'REJECTED' => ['WAIT'],
    ];

    public function canTransition(string $from, string $to, bool $isAdmin = false): bool
    {
        $allowed = self::ALLOWED_TRANSITIONS[$from] ?? [];

        if (!in_array($to, $allowed, true)) {
            return false;
        }

        // Проверяем ограничения по роли
        if (isset(self::ADMIN_ONLY[$from]) && in_array($to, self::ADMIN_ONLY[$from], true)) {
            return $isAdmin;
        }

        return true;
    }

    public function getAvailableTransitions(string $from, bool $isAdmin = false): array
    {
        $transitions = self::ALLOWED_TRANSITIONS[$from] ?? [];

        if (!$isAdmin) {
            $adminOnly = self::ADMIN_ONLY[$from] ?? [];
            $transitions = array_diff($transitions, $adminOnly);
        }

        return $transitions;
    }
}

Валидация перехода при смене статуса

// Перехватываем попытку сменить статус
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'OnBeforeSaleOrderReturnStatusChange',
    function (\Bitrix\Main\Event $event) {
        $newStatus = $event->getParameter('STATUS_ID');
        $return    = $event->getParameter('ENTITY');
        $oldStatus = $return->getField('STATUS_ID');

        $isAdmin = \CUser::IsAdmin();
        $matrix  = new \Local\Returns\StatusTransitionMatrix();

        if (!$matrix->canTransition($oldStatus, $newStatus, $isAdmin)) {
            $result = new \Bitrix\Main\EventResult(
                \Bitrix\Main\EventResult::ERROR,
                "Переход из '{$oldStatus}' в '{$newStatus}' недопустим"
            );
            return $result;
        }

        // Валидация данных для конкретных статусов
        if ($newStatus === 'APPROVED') {
            if (!$return->getField('REFUND_AMOUNT')) {
                return new \Bitrix\Main\EventResult(
                    \Bitrix\Main\EventResult::ERROR,
                    "Укажите сумму к возврату перед одобрением"
                );
            }
        }

        if ($newStatus === 'REJECTED') {
            if (!$return->getField('MANAGER_COMMENT')) {
                return new \Bitrix\Main\EventResult(
                    \Bitrix\Main\EventResult::ERROR,
                    "При отклонении необходимо указать причину"
                );
            }
        }
    }
);

Локализация: названия статусов на нескольких языках

Для мультиязычных сайтов название статуса для покупателя берётся из языкового файла:

// /local/lang/ru/lib/returns/status_labels.php
$MESS['RETURN_STATUS_WAIT']      = 'Ожидает рассмотрения';
$MESS['RETURN_STATUS_REVIEW']    = 'На рассмотрении';
$MESS['RETURN_STATUS_NEED_DOCS'] = 'Требуются документы';
$MESS['RETURN_STATUS_APPROVED']  = 'Одобрен';
$MESS['RETURN_STATUS_RECEIVED']  = 'Товар получен';
$MESS['RETURN_STATUS_REFUND']    = 'Деньги возвращены';
$MESS['RETURN_STATUS_EXCHANGE']  = 'Обмен';
$MESS['RETURN_STATUS_REJECTED']  = 'Отклонён';

// /local/lang/en/lib/returns/status_labels.php
$MESS['RETURN_STATUS_WAIT']      = 'Pending review';
$MESS['RETURN_STATUS_APPROVED']  = 'Approved';
// ...

В шаблоне личного кабинета:

$statusLabel = \Bitrix\Main\Localization\Loc::getMessage(
    'RETURN_STATUS_' . $returnStatusId
) ?: $returnStatusId;

Состав работ

• Проектирование набора статусов под конкретный бизнес-процесс
• Установочный скрипт создания/обновления статусов
• Матрица допустимых переходов с ролевыми ограничениями
• Валидатор перехода через событие OnBeforeSaleOrderReturnStatusChange
• Шаблоны email-уведомлений для каждого «публичного» статуса
• Локализация меток для личного кабинета

Сроки: настройка статусов и матрицы переходов — 3–7 рабочих дней.