Разработка модуля реферальной программы 1С-Битрикс

Разработка модуля реферальной программы 1С-Битрикс

Задача реферальной программы — отследить цепочку «кто кого привёл» и корректно начислить вознаграждение реферреру при каждой оплате реферала. Звучит просто, но на практике возникают вопросы: как хранить реферальную ссылку при переходе через браузер с другого устройства? как не начислить дважды при возврате заказа? как сделать многоуровневую систему без рекурсивных запросов? Штатных инструментов для этого в Битрикс нет.

Модель данных

Модуль vendor.referral:

• b_vendor_ref_link — реферальные ссылки: id, user_id, code (уникальный 8-символьный код), clicks, registrations, orders_count, earned_total, created_at, is_active
• b_vendor_ref_relation — связи реферер-реферал: id, referrer_id, referral_id, link_id, created_at
• b_vendor_ref_transaction — начисления: id, referrer_id, referral_id, order_id, level (1/2/3 для многоуровневых), amount, status (pending/approved/paid/cancelled), created_at
• b_vendor_ref_withdrawal — запросы на вывод: id, user_id, amount, method (bank/card/wallet), details (JSON), status, processed_at

Отслеживание перехода и регистрации

При клике на реферальную ссылку ?ref=ABCD1234:

// В init.php — перехватываем параметр
if ($refCode = $_GET['ref'] ?? null) {
    setcookie('ref_code', $refCode, time() + 30 * 86400, '/', '', true, true);
    // 30 дней cookie, httponly, secure
    RefLinkTable::incrementClicks($refCode);
}

При регистрации нового пользователя:

AddEventHandler('main', 'OnAfterUserAdd', ['\Vendor\Referral\EventHandler', 'onUserRegistered']);

public static function onUserRegistered(array &$fields): void
{
    $refCode = $_COOKIE['ref_code'] ?? null;
    if (!$refCode) return;

    $link = RefLinkTable::getByCode($refCode);
    if (!$link || $link['USER_ID'] === $fields['ID']) return; // не реферрим сами себя

    RefRelationTable::add([
        'REFERRER_ID' => $link['USER_ID'],
        'REFERRAL_ID' => $fields['ID'],
        'LINK_ID'     => $link['ID'],
    ]);

    RefLinkTable::incrementRegistrations($link['ID']);
}

Начисление вознаграждения

Вознаграждение начисляется при оплате заказа реферала:

AddEventHandler('sale', 'OnSaleOrderPaid', ['\Vendor\Referral\EventHandler', 'onOrderPaid']);

public static function onOrderPaid(\Bitrix\Main\Event $event): void
{
    $orderId  = $event->getParameter('id');
    $order    = \Bitrix\Sale\Order::load($orderId);
    $referral = $order->getUserId();

    // Ищем цепочку рефереров (до 3 уровней)
    $chain = RefRelationTable::getChain($referral, 3);
    $rules = Option::get('vendor.referral', 'reward_rules'); // JSON с % по уровням

    foreach ($chain as $level => $referrerId) {
        $percent = $rules["level_{$level}"] ?? 0;
        if (!$percent) continue;

        $amount = $order->getPrice() * $percent / 100;

        RefTransactionTable::add([
            'REFERRER_ID' => $referrerId,
            'REFERRAL_ID' => $referral,
            'ORDER_ID'    => $orderId,
            'LEVEL'       => $level,
            'AMOUNT'      => $amount,
            'STATUS'      => 'pending', // ожидает подтверждения
        ]);
    }
}

Статусы начислений и защита от фрода

Начисление создаётся со статусом pending. Переводится в approved только после того, как:

1. Прошло N дней с момента оплаты (период возврата)
2. Заказ не был отменён или возвращён

При отмене заказа транзакция переводится в cancelled. Агент ежедневно проверяет просроченный период возврата и одобряет pending-транзакции.

Дополнительные защиты:

• Один реферер не может быть рефералом самого себя
• Регистрация с того же IP, что и реферрер, — флаг для ручной проверки
• Лимит начислений в сутки с одного реферала (защита от массовых фиктивных заказов)

Личный кабинет реферрера

• Уникальная реферальная ссылка с QR-кодом
• Статистика: переходы, регистрации, заказы рефералов, заработано
• История начислений с разбивкой по рефералам и заказам
• Баланс к выводу и история выплат
• Форма запроса вывода средств

Многоуровневая структура

Уровень 1: реферрер получает 5% от каждого заказа прямого реферала
Уровень 2: 2% от заказов рефералов рефералов
Уровень 3: 1% от третьего уровня

Цепочка строится рекурсивным запросом по b_vendor_ref_relation с ограничением глубины.

Сроки разработки

Итого: 12 рабочих дней. Интеграция с платёжными системами для автоматической выплаты вознаграждений — отдельная оценка.