Налаштування статусів повернення на 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 робочих днів.