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

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

Повернення — окремий бізнес-процес, який у більшості інтернет-магазинів на Бітрікс організований погано: покупець телефонує або пише, менеджер вручну розбирається із замовленням, статуси оновлюються в кращому разі через коментарі. 1С-Бітрікс (модуль sale) має вбудовану систему повернень, але вона потребує налаштування. З коробки — лише базовий функціонал: створення повернення та повернення коштів через платіжну систему.

Архітектура повернень у модулі sale

Ключові сутності:

• \Bitrix\Sale\PaymentCollectionReturn — повернення платежу
• \Bitrix\Sale\BasketItem — позиція замовлення, для якої здійснюється повернення
• Таблиця b_sale_order_return — записи про повернення
• Таблиця b_sale_order_return_basket — позиції у поверненні

Створення повернення через API

namespace Local\Returns;

use Bitrix\Sale;

class ReturnManager
{
    /**
     * Створюємо повернення по замовленню
     *
     * @param int   $orderId    ID замовлення
     * @param array $items      [['basket_id' => int, 'quantity' => float, 'reason' => string], ...]
     * @param string $returnType 'MONEY' | 'EXCHANGE' | 'CREDIT'
     */
    public function createReturn(int $orderId, array $items, string $returnType = 'MONEY'): int
    {
        \Bitrix\Main\Loader::includeModule('sale');

        $order = Sale\Order::load($orderId);
        if (!$order) {
            throw new \RuntimeException("Order #{$orderId} not found");
        }

        // Перевіряємо, що замовлення оплачене
        if (!$order->isPaid()) {
            throw new \RuntimeException("Order #{$orderId} is not paid");
        }

        $returnCollection = $order->getPaymentCollection();

        // Створюємо об'єкт повернення
        $orderReturn = Sale\OrderReturn::create($order);
        $orderReturn->setField('TYPE', $returnType);
        $orderReturn->setField('REASON', 'Заявка покупця');

        // Додаємо позиції повернення
        $basketCollection = $order->getBasket();

        foreach ($items as $item) {
            $basketItem = $basketCollection->getItemById($item['basket_id']);
            if (!$basketItem) continue;

            $maxQty = $basketItem->getQuantity();
            $qty    = min((float)$item['quantity'], $maxQty);

            $returnItem = $orderReturn->getReturn()->createItem($basketItem);
            $returnItem->setField('QUANTITY', $qty);
            $returnItem->setField('REASON',   $item['reason'] ?? '');
        }

        $result = $orderReturn->save();

        if (!$result->isSuccess()) {
            throw new \RuntimeException('Return creation failed: ' . implode('; ', $result->getErrorMessages()));
        }

        return $orderReturn->getId();
    }
}

Налаштування статусів повернення

В адміністративній панелі: Інтернет-магазин → Статуси повернень. Стандартний мінімальний набір:

Створення статусу через PHP:

\CSaleOrderReturnStatus::Add([
    'ID'   => 'WAIT',
    'NAME' => 'Очікує розгляду',
    'SORT' => 100,
    'COLOR' => '#f0ad4e',
]);

Інтеграція з 1С для списання та оприбуткування

При поверненні товару на склад потрібно оновити залишки. Якщо склад управляється в 1С — при зміні статусу повернення на «Товар отримано» відправляємо повідомлення в 1С через чергу:

\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'sale',
    'OnSaleOrderReturnStatusChange',
    function (\Bitrix\Main\Event $event) {
        $returnId  = $event->getParameter('RETURN_ID');
        $newStatus = $event->getParameter('NEW_STATUS_ID');

        if ($newStatus === 'RECEIVED') {
            \Local\OneC\StockSync::scheduleReturnSync($returnId);
        }

        if ($newStatus === 'REFUND') {
            \Local\Returns\RefundProcessor::processPaymentReturn($returnId);
        }
    }
);

Повернення грошей через платіжну систему

Більшість платіжних систем Бітрікс (ЮKassa, Тінькофф, Ощадбанк) підтримують API-повернення. У Бітрікс це реалізується через обробник платіжної системи:

namespace Local\Returns;

class RefundProcessor
{
    public static function processPaymentReturn(int $returnId): bool
    {
        \Bitrix\Main\Loader::includeModule('sale');

        $return = \Bitrix\Sale\OrderReturn::loadById($returnId);
        if (!$return) return false;

        $order      = \Bitrix\Sale\Order::load($return->getField('ORDER_ID'));
        $payments   = $order->getPaymentCollection();
        $amount     = $return->getField('REFUND_AMOUNT'); // сума до повернення

        foreach ($payments as $payment) {
            if (!$payment->isPaid()) continue;

            // Метод повернення залежить від платіжної системи
            $paySystem = $payment->getPaySystem();
            if (!$paySystem) continue;

            $result = $paySystem->refund($payment, $amount);

            if ($result->isSuccess()) {
                $return->setField('STATUS_ID', 'REFUND');
                $return->setField('REFUND_DATE', new \Bitrix\Main\Type\DateTime());
                $return->save();

                return true;
            }
        }

        return false;
    }
}

Права доступу до повернень

У Бітрікс права на роботу з поверненнями управляються через ролі в модулі sale. Налаштування: Інтернет-магазин → Налаштування → Права доступу.

Рекомендовані ролі:

• Менеджер повернень: перегляд усіх повернень, зміна статусів до «Схвалено»
• Старший менеджер: повні права на повернення, включно з поверненням коштів
• Покупець: створення заявки на повернення через особистий кабінет

Особистий кабінет: компонент заявки на повернення

Стандартний компонент bitrix:sale.order.return.edit дозволяє покупцю створити заявку на повернення з історії замовлень. Підключення в шаблоні особистого кабінету:

$APPLICATION->IncludeComponent(
    'bitrix:sale.order.return.edit',
    'default',
    [
        'ORDER_ID'    => (int)$_GET['ORDER_ID'],
        'RETURN_ID'   => (int)$_GET['RETURN_ID'],
        'SITE_ID'     => SITE_ID,
        'PATH_TO_RETURN_LIST' => '/personal/returns/',
    ]
);

Склад робіт

• Налаштування статусів повернення під бізнес-процес
• Компонент створення заявки в особистому кабінеті
• Обробники подій зміни статусу (повідомлення, синхронізація зі складом)
• Інтеграція повернення коштів через API платіжних систем
• Адміністративний інтерфейс: список повернень, фільтри, експорт
• Налаштування прав доступу для ролей співробітників

Терміни: базове налаштування з особистим кабінетом і статусами — 1–2 тижні. Повна система з автоматичним поверненням коштів та інтеграцією 1С — 3–5 тижнів.