Бонусы, кэшбэк и реферальная программа
Модуль codebrain.loyalty — программа лояльности для интернет-магазина на 1С-Битрикс. Покупатели получают бонусные баллы за заказы и действия, оплачивают ими следующие покупки, растут по уровням и приглашают друзей. Магазин видит, сколько стоит программа и какой долг перед покупателями накоплен, и проверяет правила на истории заказов до запуска.
Модуль бесплатный. Оплата бонусами работает как обычная скидка корзины: сумма заказа, чеки и выгрузка в 1С остаются корректными, бонусы распределяются по позициям до копейки.
#Возможности
- Начисление по правилам: процент, фиксированная сумма, баллы за единицу товара, N баллов за каждые X рублей, значение из свойства товара или формула. Условия по заказу, покупателю и товарам; потолок от суммы заказа и от наценки.
- Бонусы за действия: регистрация, день рождения, отзыв о товаре, подписка на рассылку, заполненная анкета.
- Акции: «×2 в выходные», «×3 в чёрную пятницу» — множитель на выбранные даты, дни недели и часы.
- Уровни: процент начисления и доля оплаты бонусами для каждого уровня, повышение по сумме или числу покупок.
- Оплата бонусами в корзине и оформлении заказа без правки шаблона, со всеми ограничениями; проверка баланса при сохранении заказа.
- Срок жизни бонусов, напоминание перед сгоранием, период возврата перед тем, как бонусы станут доступны.
- Реферальная и партнёрская программы с защитой от накруток, промокоды на бонусы.
- Уведомления: e-mail, SMS, Telegram, MAX; чат-бот показывает баланс.
- Личный кабинет с картой (QR-код и штрихкод), страницы правил и согласия из настроек.
- Отчёты: долг магазина, стоимость программы в % выручки, сегменты RFM, эффект по контрольной группе; симуляция правил на прошлых заказах.
- Веб-касса для офлайн-магазина, REST API и обработка-пример для 1С, интеграции с МоимСкладом и Битрикс24.
#Требования
| Что | Требование |
|---|---|
| Платформа | 1С-Битрикс: Управление сайтом, главный модуль 20.0 или новее; модули «Информационные блоки», «Торговый каталог», «Интернет-магазин» |
| PHP | 7.3 или новее, расширения json, mbstring |
| Кодировка | UTF-8 |
| Агенты | Агенты Битрикса на cron: активация бонусов после периода возврата, сгорание, уведомления и уровни работают по расписанию |
| Боты и вебхуки | Сайт доступен из интернета по https. Если сайт закрыт по IP, откройте адрес /bitrix/tools/codebrain_loyalty_bot.php |
| SMS | Подключённая в Битриксе служба сообщений (SMS.ru, SMSC и др.) с одобренным именем отправителя |
Если на сайте работал другой бонусный модуль, выключите его: два модуля будут начислять бонусы за одни и те же заказы. «Диагностика» предупреждает об этом.
#Установка
- Установите модуль из Маркетплейса: Marketplace → Каталог решений, найдите «Бонусы, кэшбэк и реферальная программа» и нажмите «Установить». Модуль проверит окружение и сообщит, если чего-то не хватает.
- В главном меню административной панели появится раздел Codebrain → Бонусы. Модуль создаст программу «Бонусная программа» (выключена), правило «Бонусы за покупки» (5 % от суммы) и правило корзины «Оплата бонусами (codebrain.loyalty)».
#Быстрый старт
- Настройки → Общие: стоимость балла (по умолчанию 1 балл = 1 ₽), сайты, кто участвует.
- Настройки → Начисление: когда начислять (после выполнения заказа, оплаты, отгрузки или доставки), период возврата, срок жизни бонусов, потолок начисления.
- Правила начисления: поправьте «Бонусы за покупки» или добавьте свои. Симуляция покажет, сколько программа стоила бы на ваших заказах за прошлый год.
- Настройки → Оплата бонусами: какую долю заказа можно оплатить и какими товарами.
- Настройки → Витрина: проверьте встраивание («Диагностика» → «Проверить страницы сайта»). Настройки → Документы: реквизиты и создание страниц программы, правил и согласия.
- Включите программу на вкладке Общие.
Совет Если покупатели уже копили баллы в другой системе, перенесите балансы до включения программы: страница Импорт, сначала пробный прогон.
#Обзор
Главная страница программы: долг магазина перед участниками (активные и ожидающие бонусы в рублях), число участников, сколько сгорит за 30 дней, а за выбранный период — сколько начислено, потрачено и сгорело, доля заказов с оплатой бонусами и график по дням. Ниже — начисления по источникам.
Если программ несколько (например, разные сайты), переключатель вверху страниц выбирает программу.
#Участники
Список бонусных счетов с поиском по имени, e-mail, телефону, номеру карты, коду друга или ID и фильтрами по уровню, балансу и статусу. Кнопки: выгрузка в CSV и добавление покупателя по телефону (например, для офлайн-магазина).
Карточка участника: баланс, ожидающие баллы и уровень с оборотом, данные участника, ручное начисление и списание с причиной, действующие начисления со сроками сгорания.
Ниже — журнал операций участника и сервисные действия: пересчитать баланс и уровень, удалить участника по заявлению (152-ФЗ) — счёт обезличивается, история операций остаётся для учёта.
Статусы участника: активен, заблокирован (баллы не начисляются и не списываются) и контрольная группа (см. «Эффект программы»). Уровень можно закрепить вручную.
Важно Ручные операции записываются в журнал действий. В настройках можно включить подтверждение вторым администратором для операций больше заданной суммы.
#Журнал операций и начисления
Журнал операций — все начисления, списания, возвраты, сгорания и отмены с фильтрами по типу, источнику, автору, номеру заказа и датам; итоги по выборке и выгрузка в CSV.
Начисления и сроки — партии бонусов: ожидающие активации, ждущие выполнения заказа, сгорающие в ближайшие дни и сгоревшие. Выбранные партии можно активировать досрочно, отменить или задать им дату сгорания.
Каждое начисление — отдельная партия со своим сроком жизни. Списание сначала расходует партии, которые сгорают раньше. При возврате списанные бонусы возвращаются в те же партии; если их срок уже прошёл, вернувшиеся бонусы живут ещё «грейс-период» из настроек.
#Правила начисления
Правила определяют, сколько бонусов покупатель получает за заказ. Правила проверяются по порядку сортировки; флажок «не проверять следующие правила» останавливает проверку; результаты можно складывать или брать максимум.
Что можно задать в правиле:
| Поле | Что делает |
|---|---|
| Сколько начислять | % от суммы; фиксированно за заказ; баллы за единицу товара; N баллов за каждые X рублей; значение из свойства товара (баллы или %); формула. Флажок «брать процент из уровня участника» |
| Ограничения | Не больше N % наценки товара (защищает прибыль: на товары с маленькой наценкой бонусов меньше); как поступать с товарами без закупочной цены; не больше баллов за заказ; база — цена со скидками или без |
| Условия | Условия заказа (сумма, число товаров, сайт, тип плательщика, оплата, доставка, купон, свойство заказа, внешний заказ, оплата бонусами), покупателя (группа, число заказов, первый или N-й заказ, каждый N-й, давность регистрации, уровень, приглашён другом, дни до дня рождения) |
| Какие товары | Бонусы считаются только с подходящих позиций: инфоблок, раздел (с подразделами), товар, цена, скидка, количество, сумма, наценка, название |
| Срок жизни | Свой срок для бонусов этого правила или дата сгорания; свой период возврата |
| Действует | Даты начала и окончания правила |
Под формой — «Проверить на заказе»: модуль покажет, сколько начислил бы по этому правилу на выбранном заказе и почему. «Прогнать на истории заказов» открывает симуляцию.
#Формулы
Формула — арифметическое выражение без кода PHP. Переменные: price, base_price, quantity, sum, purchase_price, margin, margin_pct, discount_pct (по позиции), order_sum, items_count, level_percent, user_orders, nth_order. Операции + - * / %, сравнения, and, or, not, функции min, max, round, floor, ceil, abs, if.
min(sum * 0.05, (price - purchase_price) * quantity * 0.3)
if(order_sum >= 10000, sum * 0.07, sum * 0.03)
#Общие ограничения
На вкладке «Начисление» настроек — потолок для всех правил: не больше N % от суммы заказа и не больше N баллов за заказ. Это защита от ошибки в правилах: никакая комбинация правил и акций не даст больше. Часть заказа, оплаченная бонусами, по умолчанию бонусов не приносит. Не начислять можно за заказы с маркетплейсов, определёнными способами оплаты и доставки, типами плательщика и свойствами заказа.
#Бонусы за действия
Кнопки над списком правил создают правила за действия покупателя:
| Действие | Когда начисляется |
|---|---|
| Регистрация | при регистрации на сайте (и при открытии счёта по телефону на кассе) |
| День рождения | за N дней до дня рождения, раз в год; дату покупатель указывает в профиле |
| Отзыв о товаре | за опубликованный (прошедший модерацию) отзыв: инфоблок отзывов, форум или блог компонента «Комментарии» (catalog_comments); минимальная длина, лимит в день и в месяц |
| Подписка на рассылку | за подтверждённую подписку модуля «Подписка, рассылки» |
| Заполненная анкета | когда заполнены все указанные поля профиля (например, имя, город, дата рождения) |
Старые отзывы и подписки бонусов не получают: модуль считает только те, что появились после создания правила.
#Акции по датам
Акция умножает бонусы выбранных правил на время: даты, дни недели, часы. Например, «Выходные ×2» или «Чёрная пятница ×3». Текст баннера показывается покупателям в блоке бонусов корзины и оформления.
#Уровни
Уровни включаются флажком. Уровень определяется по сумме или числу покупок за последние N дней (или за всё время); можно разрешить понижение, если оборот упал. Для каждого уровня — процент начисления (для правил с флажком «брать процент из уровня»), доля заказа, которую можно оплатить бонусами, группа пользователей (чтобы дать уровню свои цены и правила корзины) и цвет.
Покупатель видит свой уровень и сколько осталось до следующего в личном кабинете, корзине и оформлении заказа. Переход на новый уровень — повод для уведомления.
#Оплата бонусами
В корзине и при оформлении заказа модуль показывает блок: сколько будет начислено, сколько бонусов у покупателя, сколько можно списать — с ползунком, кнопками «Применить», «Максимум» и «Не списывать».
Списание работает как скидка правила корзины «Оплата бонусами (codebrain.loyalty)»: оно выполняется последним, после всех скидок магазина, и распределяет сумму по позициям. Чек и выгрузка в 1С видят обычную скидку.
Ограничения (вкладка «Оплата бонусами»):
- доля заказа, которую можно оплатить (с учётом уровня);
- минимальная сумма заказа и минимум баллов за раз;
- минимальная цена товара после бонусов (товар не становится бесплатным — для касс и маркировки);
- можно ли оплачивать доставку и товары со скидкой; только определённые товары (условия как в правилах);
- сразу предлагать максимум.
Режим «отдельная оплата»: вместо скидки модуль создаёт в заказе оплату платёжной системой «Бонусы» — для учётных систем, которые принимают бонусы как вид оплаты. Покупатель эту платёжную систему не видит.
При сохранении заказа модуль ещё раз проверяет баланс под блокировкой: потратить одни баллы дважды (две вкладки, два устройства) нельзя. Если бонусов уже не хватает, заказ не сохранится, а покупатель увидит причину.
Важно Правило корзины, которое прекращает применение следующих правил («Подарки в корзине» и т. п.), не даст сработать оплате бонусами. «Диагностика» показывает такие правила.
#Бонусы в заказе
В карточке заказа в админке — вкладка «Бонусы»: участник, сколько оплачено бонусами, сколько начислено и почему (по каким правилам), кнопки «Пересчитать» и изменение суммы списания менеджером.
Бонусы за заказ начисляются при наступлении события из настроек (статус «Выполнен», оплата, отгрузка, доставка) и становятся доступны после периода возврата. Отмена заказа или уменьшение суммы пересчитывают и начисление, и списание: списанные бонусы возвращаются покупателю.
#Витрина
Модуль сам встраивается в шаблоны на стандартных компонентах Битрикса: «+N баллов» в списке и карточке товара («от +N» для товаров с торговыми предложениями), блок бонусов в корзине и оформлении, «Купи ещё» — подсказка, сколько не хватает до бонуса или следующего уровня, и подборка товаров.
Для шаблона не на стандартных компонентах укажите на вкладке «Витрина» свои CSS-селекторы — по одному на строку: card= (карточка товара в списке), detail= (блок цены в карточке), cart= (итог корзины), checkout= (итог оформления). Проверка — «Диагностика» → «Проверить страницы сайта»: модуль откроет раздел каталога, корзину и оформление и покажет, нашлись ли места для блоков.
#Личный кабинет и страницы программы
Страница «Бонусный счёт» (/personal/bonus/ по умолчанию): доступные баллы, уровень и прогресс, карта с QR-кодом и штрихкодом для кассы, ссылка и код для друзей, история операций, уведомления и привязка мессенджеров.
Страница программы (/bonus/), правила программы и согласие на обработку персональных данных собираются из настроек: правила, уровни, сроки, ограничения. Реквизиты оператора — на вкладке «Документы»; там же флажок создания страниц.
Важно Тексты правил и согласия — шаблон. Проверьте их и дополните своими реквизитами; при необходимости покажите юристу.
#Реферальная программа
Каждый участник получает ссылку (?ref=КОД) и код друга. Пришедший по ссылке или указавший код покупатель становится приглашённым; после его заказа приглашающий получает награду: процент от покупок друга или баллы, за первый или за все заказы в течение N дней. Можно включить многоуровневую сеть (проценты для второй, третьей линии) и бонус другу: баллы после его первого заказа и группу пользователя — для скидки на первый заказ правилом корзины.
Защита от накруток: модуль сравнивает телефон, почту, устройство и адрес приглашённого и приглашающего, ограничивает число наград в день. Подозрительные приглашения ждут решения менеджера; циклы и самоприглашение не принимаются. Награда начисляется вместе с бонусами заказа друга — после выполнения и периода возврата, отмена заказа забирает её.
#Партнёры
Партнёры — блогеры, студии, агенты. У партнёра свой код (ссылка ?ref=КОД и промокод), вознаграждение деньгами (процент или фиксированно за заказ), контакты, UTM-метка. Модуль считает заказы и вознаграждения, принимает заявки на выплату и отмечает выплаченное; деньги перечисляет магазин сам. Проверка статуса самозанятого — по ИНН через сервис ФНС.
#Промокоды
Промокод начисляет бонусы: покупатель вводит его в личном кабинете. У кода — сумма, число активаций, даты действия, свой срок жизни бонусов и флажок «только для новых покупателей»; один покупатель активирует код один раз. «Сгенерировать пачку» создаёт одноразовые коды для листовок, рассылок и подарочных сертификатов и сразу скачивает их в CSV.
После 10 неверных кодов в час покупатель получает отказ — подбирать коды бессмысленно.
#Уведомления и боты
Каналы: e-mail (почтовое событие CODEBRAIN_LOYALTY, шаблон можно править в «Почтовых шаблонах»), SMS (через службу сообщений Битрикса), Telegram, MAX. События: начисление, бонусы стали доступны, списание, возврат, отмена начисления, сгорание, скорое сгорание (за 14 и 3 дня по умолчанию), новый уровень, друг присоединился, день рождения. Тихие часы: SMS и сообщения мессенджеров ночью не отправляются. Тексты каждого события можно изменить (с переменными #NAME#, #AMOUNT#, #BALANCE#, #ORDER#, #DATE#, #LEVEL#…) или попросить ИИ переписать их в нужном тоне.
Боты Telegram и MAX. Создайте бота (Telegram — у @BotFather; MAX — на business.max.ru от имени организации, токен — «Интеграция» → «Получить токен»), вставьте токен на вкладке «Уведомления» и нажмите «Подключить». Модуль проверит токен, зарегистрирует вебхук и сам отметит канал в уведомлениях. Покупатель подключает бота из личного кабинета: ссылка открывает бота уже привязанным к счёту. Бот отвечает балансом на любое сообщение, /stop отвязывает чат.
Примечание Один токен Telegram — один получатель обновлений. Не подключайте бота, которого уже использует другая система: она перестанет получать сообщения.
#Отчёты
Экономика: долг магазина перед участниками (для бухгалтерии), активные, ожидающие и сгорающие баллы; за период — начислено, отменено, потрачено, сгорело, выручка, стоимость программы в % выручки, доля заказов с оплатой бонусами, заказы участников, начисления по источникам.
Сегменты (RFM): покупатели по давности, частоте и сумме покупок — лучшие, постоянные, новые, уходящие, спящие, потерянные. Спящим и уходящим можно начислить бонусы в «Массовых операциях».
Эффект программы: сравнение участников с контрольной группой — покупатели, вступившие после включения контрольной группы, которые ничего не получают. Модуль показывает разницу в выручке и повторных покупках, проверку статистической значимости и стоимость программы на участника. Долю контрольной группы задают на вкладке «Общие» (обычно 5–10 %).
#Симуляция
Симуляция прогоняет правила по реальным выполненным заказам прошлого периода, ничего не начисляя. Видно, сколько бонусов получили бы покупатели, сколько стоила бы программа, какой долг накопился бы и сколько сгорело бы. Можно сравнить два варианта правил (например, текущие и «5 % всем») и задать, какая доля бонусов тратится.
#Массовые операции
Начислить подарок уровню, бонусы спящим покупателям, списать бонусы уволенных сотрудников, задать дату сгорания, сменить уровень или заблокировать участников. Сегмент: уровень, баланс, группа пользователей, сегмент RFM или список ID, телефонов, e-mail или номеров карт. Сначала «Посчитать участников», потом выполнить; повторный запуск того же задания ничего не удваивает.
#Импорт балансов
Перенос бонусов из прежней программы:
- Внутренний счёт Битрикса — деньги на внутренних счетах покупателей превращаются в бонусы по курсу программы; внутренний счёт можно обнулить.
- Файл CSV — выгрузка участников из старого модуля, 1С или таблицы: колонка покупателя (ID, e-mail, телефон, карта или логин), колонка баланса, при желании — дата сгорания.
Сначала пробный прогон: модуль покажет, сколько покупателей найдено, сколько бонусов будет перенесено и какие строки не сопоставились. Повторный импорт того же файла ничего не удваивает. Загруженный файл удаляется после переноса или через двое суток.
#Веб-касса
Касса для офлайн-магазина в браузере телефона или планшета: https://ваш-сайт/bitrix/tools/codebrain_loyalty_pos.php (добавьте на главный экран — работает как приложение). Кассир входит своей учётной записью сайта; доступ — группе с правом «Веб-касса».
Кассир находит покупателя по телефону, номеру карты или QR-коду из личного кабинета (или открывает счёт по телефону), вводит сумму чека и сколько бонусов списать — модуль сразу показывает доступный максимум, сумму к оплате и будущее начисление. Списание можно подтверждать кодом, который покупатель получает в Telegram, MAX, SMS или на почту. «Отменить последний чек» отменяет чек этого кассира за последние сутки.
#API
REST API для 1С, касс, CRM и других систем: POST https://ваш-сайт/bitrix/tools/codebrain_loyalty_api.php?method=<метод>, заголовок Authorization: Bearer <ключ> (или X-Api-Key: <ключ>), тело — JSON. Ответ — JSON {"ok": true, …} или {"ok": false, "error": "…"} с кодом HTTP.
Ключ создаётся на вкладке «API, касса, 1С» настроек и показывается один раз; модуль хранит только его хэш. У ключа — права, название точки продаж (попадает в комментарии операций) и адрес вебхука.
| Метод | Право | Что делает |
|---|---|---|
ping (GET) |
— | проверка связи: программа и курс балла |
balance (GET) |
чтение | баланс, доступно, ожидают, уровень, карта покупателя |
history (GET) |
чтение | операции покупателя (limit, offset) |
calc |
чтение | сколько будет начислено и сколько можно списать по чеку (purchase_sum или items) |
customer |
новые покупатели | найти или открыть счёт по телефону (phone, name, birthday) |
accrue |
начисление | начислить за чек по правилам программы (purchase_sum, items) или готовую сумму (amount) |
spend |
списание | списать сразу |
hold / confirm / cancel_hold |
списание | двухфазное списание: резерв на 15 минут → подтверждение после пробития чека или отмена |
refund |
возвраты | вернуть списанное по чеку (original_external_id, amount — часть) |
reverse |
возвраты | забрать начисленное по чеку |
order / order_spend |
заказы сайта | бонусы заказа сайта и изменение списания |
Покупатель (customer) — номер карты, телефон, e-mail, account:<ID> или user:<ID пользователя сайта>. Каждая запись принимает external_id (номер чека): повтор с тем же external_id того же ключа ничего не удваивает и возвращает прежний результат с "duplicate": true. Записи — только POST. Лимит — 300 запросов в минуту на ключ.
POST /bitrix/tools/codebrain_loyalty_api.php?method=accrue
Authorization: Bearer cbl_…
{"customer": "79991234567", "purchase_sum": 4500, "external_id": "ЧЕК-000123"}
→ {"ok": true, "operation_id": 381, "amount": 225, "duplicate": false, "customer": {"balance": 725, …}}
#Обработка для 1С
На вкладке «API, касса, 1С» — обработка-пример для 1С (УТ, Розница, КА): функции БалансКлиента, РассчитатьЧек, НачислитьПоЧеку, ЗарезервироватьБонусы, ПодтвердитьСписание, ОтменитьРезерв, ВернутьСписание, ОтменитьНачисление. Вставьте её код в модуль внешней обработки, укажите адрес сайта и ключ API и вызывайте функции из своего кода продажи на кассе или проведения документа. Готовое расширение конфигурации под вашу 1С делается под заказ.
#Вебхуки
Если у ключа указан адрес вебхука, модуль отправляет на него каждую операцию со счётом POST-запросом с JSON {"event": "operation", "data": {"op_id", "type", "amount", "source", "order_id", "external_id"}, "ts": …} — из очереди, через агента, а не в момент операции. Подпись — заголовок X-Codebrain-Signature: HMAC-SHA256 тела с секретом ключа. Только https.
#Интеграции
МойСклад (нужен модуль «Синхронизация с МойСклад»): выберите подключение на вкладке «API, касса, 1С». Операции сайта уходят в бонусную программу МоегоСклада, а списания на кассе МоегоСклада приходят на сайт — без двойного учёта.
Битрикс24: вставьте адрес входящего вебхука портала с правом crm. Модуль создаст в контактах поля «Бонусный баланс», «Уровень» и «Бонусная карта» и будет обновлять их у контактов, найденных по телефону или e-mail участника.
ИИ (нужен модуль «AI-генератор контента»): кнопка «✨ Совет ИИ по цифрам программы» в «Отчётах» → «Экономика» и «✨ Предложить текст (ИИ)» у текстов уведомлений. Без модуля на их месте — подсказка, как его установить или добавить ключ провайдера. Провайдеру уходят только сводные цифры и правила программы, без персональных данных.
#Диагностика
Страница проверяет: агенты работают и на cron, у программы есть действующие правила, правило корзины «Оплата бонусами» активно и его не блокируют другие правила корзины, балансы сходятся с журналом операций, задан адрес сайта, нет другого бонусного модуля, неотправленные уведомления. Кнопки: «Сверить балансы сейчас», «Создать недостающие правила корзины», «Проверить страницы сайта».
#Настройки
Вкладки настроек программы: Общие, Начисление, Оплата бонусами, Рефералы, Уведомления, Витрина, Права, API, касса, 1С, Документы.
Общие: название, сайты, курс балла, целые или дробные баллы и округление, название баллов (три формы), участвующие группы, вступление (автоматически или только с согласием на правила), контрольная группа.
Начисление: событие начисления (статус заказа, оплата, отгрузка, доставка), период возврата, срок жизни (дни, до конца месяца, до конца года), потолок, база начисления, исключения, грейс-период вернувшихся бонусов, подтверждение крупных ручных операций.
Права: группы с правами «Просмотр» (участники, журнал, отчёты), «Операции» (ручные начисления и списания, решения по приглашениям, импорт, массовые операции) и «Веб-касса». Настройки программы, правила и ключи API — только администраторы. По умолчанию просмотр есть у менеджеров с доступом к заказам.
Документы: реквизиты оператора персональных данных для правил программы и согласия, создание страниц программы и личного кабинета.
#Журнал действий
Кто из сотрудников что сделал: ручные операции, сохранение правил и настроек, решения по приглашениям, выплаты партнёрам, ключи API, импорт и массовые операции. Срок хранения — год (опция).
#Как это работает
- Счёт и журнал. У каждого участника счёт; каждая операция записывается в неизменяемый журнал. Баланс — сумма активных партий, «Диагностика» сверяет его с журналом.
- Блокировки и повторы. Все изменения счёта идут под блокировкой счёта. У операций есть ключ: повтор той же операции (обновление страницы, повтор запроса кассы, повторное сохранение заказа) ничего не удваивает.
- Заказы. При каждом сохранении заказа модуль сверяет, сколько должно быть списано и начислено, с тем, что уже записано, и исправляет разницу. Поэтому изменение, отмена и восстановление заказа обрабатываются одинаково.
- Агенты.
Agent::run— каждую минуту (активация бонусов, сгорание, уведомления, задания, интеграции),Agent::daily— раз в сутки (дни рождения, напоминания о сгорании, уровни, очистка, сверка балансов).
#Данные и конфиденциальность
Модуль хранит в базе данных сайта имя, телефон, e-mail, дату рождения участников, номера карт, привязку мессенджеров и историю операций, а для защиты реферальной программы — признаки устройства и адреса. Магазин — оператор этих данных; согласие на участие и обработку данных включается на вкладке «Общие», тексты — на вкладке «Документы».
Данные уходят только сервисам, которые вы подключили: почтовому серверу сайта, службе SMS, Telegram, MAX (имя, суммы и баланс в уведомлениях), вашему аккаунту МоегоСклада, порталу Битрикс24 и на адреса вебхуков ваших ключей API. На сервер Codebrain ничего не передаётся.
При удалении пользователя сайта его бонусный счёт обезличивается: имя, телефон, почта и мессенджеры стираются, бонусы списываются, история операций остаётся для учёта. То же делает кнопка «Удалить участника (152-ФЗ)» в карточке участника.
#Для разработчиков
#События
| Событие | Когда | Параметры |
|---|---|---|
OnBeforeAccrue |
перед начислением; можно изменить amount или отменить |
account, amount, params |
OnAfterAccrue |
после начисления | account, op_id, amount, params |
OnBeforeSpend |
перед списанием; можно отменить | account, amount, params |
OnAfterSpend |
после списания | account, op_id, amount, params |
OnAfterExpire |
бонусы сгорели | account, op_id, amount |
OnOrderCalculate |
расчёт начисления за заказ; можно изменить result |
order_id, result |
OnReferralLink |
приглашение; можно отменить | referral |
OnLevelChange |
смена уровня | account, old_level, new_level |
OnProgramSave |
сохранены настройки программы | id |
use Bitrix\Main\EventManager;
use Bitrix\Main\EventResult;
// не начислять сотрудникам
EventManager::getInstance()->addEventHandler('codebrain.loyalty', 'OnBeforeAccrue', function (\Bitrix\Main\Event $event) {
$account = $event->getParameter('account');
if ($account['USER_ID'] && in_array(5, \CUser::GetUserGroup($account['USER_ID']))) {
return new EventResult(EventResult::ERROR);
}
});
#Компоненты и вставки в шаблон
| Компонент | Назначение |
|---|---|
codebrain:loyalty.account |
личный кабинет участника (HISTORY_COUNT, SET_TITLE) |
codebrain:loyalty.page |
страница программы, правила или согласие (DOC) |
codebrain:loyalty.badge |
«+N баллов» для товара (PRODUCT_ID) — если автоматическое встраивание выключено |
codebrain:loyalty.checkout |
блок бонусов корзины и оформления в выбранном месте шаблона |
Баланс в шапке сайта: <span data-cbloy="balance"></span> — модуль подставит баланс авторизованного участника.
#Удаление модуля
При удалении модуль спрашивает, сохранить ли данные. С сохранением остаются счета, операции, правила и настройки, правило корзины выключается — при повторной установке всё продолжит работать. Без сохранения удаляются таблицы, настройки, правило корзины и почтовые шаблоны; платёжная система «Бонусы» удаляется, если по ней не было оплат (иначе выключается). Заказы сайта не меняются.
#Частые вопросы
Бонусы начислились, но покупатель не может ими оплатить. Бонусы за заказ становятся доступны после периода возврата (вкладка «Начисление»); до этого они «ожидают». В карточке участника видно, когда каждая партия станет активной.
Блок бонусов не появился в корзине или оформлении.
Откройте «Диагностика» → «Проверить страницы сайта». Если места для блока не нашлись, укажите свои селекторы на вкладке «Витрина» или вставьте компонент codebrain:loyalty.checkout в шаблон.
Списание бонусов не применяется к заказу. Проверьте в «Диагностике», что правило корзины «Оплата бонусами» активно и что раньше него нет правила, которое прекращает применение следующих правил. Ещё причины — ограничения вкладки «Оплата бонусами»: доля заказа, минимальная сумма, исключённые товары.
Свой шаблон оформления заказа не обновляет итог после списания.
Модуль применяет скидку на сервере и сразу обновляет свой блок («Списывается N баллов»). Если шаблон перерисовывает итог без стандартных событий sale.order.ajax, сумма в нём обновится при следующем пересчёте формы — на сохранение заказа это не влияет.
Сколько будет стоить программа? Запустите «Симуляцию» на заказах за прошлый год: она покажет начисления, долг и стоимость в % выручки. После запуска — «Отчёты» → «Экономика».
Как перенести бонусы из другого модуля? Если старый модуль хранил баллы на внутреннем счёте Битрикса — «Импорт» → «Внутренний счёт». Иначе выгрузите участников в CSV (покупатель и баланс) и загрузите на вкладке «Файл CSV». Сначала пробный прогон; старый модуль выключите до включения программы.
SMS не отправляются. SMS идут через службу сообщений Битрикса. У сервиса (SMS.ru, SMSC и др.) должно быть одобренное имя отправителя, выбранное в «Главный модуль» → «Отправка СМС». Кнопка «Отправить» на вкладке «Уведомления» показывает причину ошибки.
Работает ли модуль с кассой в магазине? Да: веб-касса на телефоне или планшете кассира, REST API для кассовых программ и обработка-пример для 1С. Покупатель показывает QR-код или штрихкод карты из личного кабинета.