Боты программы лояльности

Инструкция по настройке бота лояльности

Оглавление

• 1. Общие сведения
• 2. Что нужно подготовить перед стартом
• 3. Общие шаги настройки (для всех каналов)
• 4. Настройка Telegram-бота
• 5. Настройка MAX-бота
• 6. Запуск бота
• 7. Проверка работы бота
• 8. Типовые проблемы и их решение
• 9. Глоссарий

1. Общие сведения

Бот программы лояльности обслуживает покупателей вашего магазина (организации). Покупатель в мессенджере:

• делится с ботом своей контактной карточкой (ФИО и номер телефона);
• автоматически привязывается к активной программе лояльности (например, «10% скидка» или «Накопление баллов»);
• получает персональный идентификационный QR-код с номером карты;
• может смотреть баланс накопительной программы и историю покупок.

Продавец считывает QR-код покупателя кассовым ПО (сканером/камерой мобильной кассы). Взаимодействие продавца с ботом через интерфейс мессенджера не требуется.

Один и тот же магазин может обслуживаться одновременно двумя ботами: в Telegram и в MAX. Оба бота могут одновременно работать с одной организацией.

 Важно
Учётная запись, от имени которой бот работает с API БИФИТ Касса, должна иметь максимальное количество прав — право создавать, редактировать и удалять документы и справочники, а также карты лояльности и клиентов.

2. Что нужно подготовить перед стартом

Перед запуском бота у вас должны быть:

• Учётная запись БИФИТ Касса с логином (номер телефона в формате 7xxxxxxxxxx) и паролем, привязанная к вашей организации.
• ID организации (Organization ID).
• Активная программа лояльности в организации (типы, с которыми работает бот: DISCOUNT — скидка, SCORING — баллы).
• Учётные данные Telegram-бота и/или MAX-бота (см. разделы 4 и 5).
• Доступ к базе данных PostgreSQL, в которой хранится конфигурация ботов (таблица bifit_loyalty_bots).

 Обратите внимание
Бот работает с программами лояльности только типов DISCOUNT и SCORING. Программы типов COUPON и GIFT ботом игнорируются.

3. Общие шаги настройки (для всех каналов)

Независимо от того, какой канал вы настраиваете (Telegram или MAX), конфигурация бота хранится в таблице bifit_loyalty_bots базы данных PostgreSQL. Одна строка таблицы = один магазин = один экземпляр бота.

Параметры бэкенда (доступ к API БИФИТ Касса) — общие для обоих каналов одной организации. Различаются только токены мессенджеров и адрес Bot API.

Строка настраивается через следующие ключевые поля:

Основные поля строки bifit_loyalty_bots

Поле	Назначение
id	Служебный идентификатор строки. Используется для имени файлов хранилища (например data/customers_1.json).
enabled	Флаг «включён». Бот запускает только строки с enabled = TRUE.
name	Название магазина (отображается в логах).
organization_id	ID организации (магазина) в БИФИТ Касса.
api_base_url	Базовый адрес API БИФИТ Касса (по умолчанию http://kassa.bifit.com/cashdesk-api/v1).
auth_username	Логин учётной записи (номер телефона). Бот сам нормализует его до формата 7xxxxxxxxxx.
auth_password	Пароль учётной записи в открытом виде. Бот сам зашифрует его: SHA-256 → Base64 urlencoded.
auth_refresh_token	Альтернатива паролю — refresh-токен (для продления сессии без пароля).
http_timeout_ms	Таймаут запросов к API (по умолчанию 10000).
retry_attempts	Количество повторов при ошибках API (по умолчанию 3).

 Секреты
В коде бота и в репозитории не должно быть секретов. Все пароли, токены и ID организации хранятся только в базе данных. В окружении сервера находятся лишь параметры подключения к базе: PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD.

Порядок действий администратора:

1. Создать строку в таблице bifit_loyalty_bots для своего магазина.
2. Заполнить общие поля (раздел 3) и поля конкретного канала (раздел 4 и/или 5).
3. Установить флаг enabled = TRUE.
4. Запустить бота (раздел 6).

4. Настройка Telegram-бота

4.1 Создание бота в Telegram

1. Откройте мессенджер Telegram.
2. Найдите бота @BotFather и откройте с ним чат.
3. Отправьте команду /newbot.
4. Следуйте подсказкам BotFather: введите имя бота и его уникальный username (адрес, заканчивающийся на bot, например my_shop_loyalty_bot).
5. После создания BotFather выдаст токен вида 123456:ABC-DEF123.... Скопируйте и сохраните его.
6. (Необязательно) задайте боту аватар, описание и команды.

Полученный токен является единственным Telegram-специфичным параметром; остальные поля строки — общие (раздел 3).

4.2 QR-ссылка на Telegram-бота

• Прямая ссылка на бота имеет вид https://t.me/имя_бота.
• Эту ссылку нужно закодировать в QR-код и разместить в зоне видимости покупателя.
• При сканировании QR-кода телефон открывает чат с ботом, и покупатель нажимает «НАЧАТЬ РАБОТУ».

4.3 Поля таблицы для Telegram

Telegram-специфичные поля строки bifit_loyalty_bots

Поле	Значение
telegram_token	Токен, выданный @BotFather (обязателен).

 Уникальность токена
Значение telegram_token в таблице должно быть уникальным. Один токен не может использоваться двумя запущенными экземплярами бота одновременно.

Telegram-канал запускается, если в строке заполнен telegram_token.

5. Настройка MAX-бота

5.1 Создание бота в MAX

1. Войдите на портал MAX (или API-платформу MAX) под учётной записью организации.
2. Зарегистрируйте нового бота в соответствии с правилами платформы MAX.
3. Получите токен MAX-бота (используется как max_token) и, при необходимости, session-ключ и код подтверждения.
4. Сохраните параметры доступа: логин, пароль, session-ключ, код подтверждения.

MAX-бот работает через библиотеку maxapi и требует сетевого доступа сервера к хостам платформы MAX (см. раздел 5.4).

5.2 QR-ссылка на MAX-бота

• Для MAX используется прямая ссылка на бота платформы MAX.
• Ссылку кодируют в QR-код и размещают в зоне видимости покупателя.

5.3 Поля таблицы для MAX

MAX-специфичные поля строки bifit_loyalty_bots

Поле	Назначение
max_token	Токен MAX-бота. Именно его наличие включает MAX-канал, а не флаг max_enabled.
max_enabled	Флаг (справочный). На запуск MAX-бота влияет наличие max_token.
max_login	Логин для входа в MAX.
max_password	Пароль для входа в MAX.
max_session_key	Session-ключ MAX (при необходимости).
max_confirmation_code	Код подтверждения (при необходимости).
max_api_base_url	Адрес Bot API MAX (по умолчанию https://api.max.ru; рабочий хост — platform-api2.max.ru).

 Включение MAX-канала
MAX-бот запускается по наличию токена max_token, а не по флагу max_enabled. Если в строке заполнен max_token — MAX-канал будет запущен.

5.4 Сетевые хосты MAX

Для работы MAX-бота сервер должен иметь доступ (в том числе исходящий по TCP 443) к следующим хостам:

• Bot API: platform-api2.max.ru (или адрес из max_api_base_url);
• Загрузка медиа: iu.oneme.ru;
• Скачивание медиа: i.oneme.ru.

Если сервер не может обратиться к этим хостам, MAX-канал работать не будет.

 Зависимость от библиотеки maxapi
MAX-канал подключается лениво. Если библиотека maxapi не установлена на сервере — MAX-канал пропускается с сообщением об ошибке в лог, а Telegram-бот продолжает работать.

6. Запуск бота

1. Убедитесь, что на сервере установлены зависимости (Python 3, библиотеки проекта, а для MAX — maxapi).
2. Задайте параметры подключения к базе PostgreSQL в окружении (PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD).
3. Запустите приложение-лаунчер ботов.
4. Бот на старте выполняет авторизацию OAuth2 и проверяет привязку учётной записи к вашей организации:
   • если привязка есть — бот запускает каналы (Telegram и/или MAX);
   • если привязки нет — бот выводит ошибку в лог и останавливается.

По умолчанию развёртывание происходит в режиме polling (и для Telegram, и для MAX) — отдельные webhook-серверы не требуются.

7. Проверка работы бота

Для каждого настроенного канала выполните проверку:

1. Откройте чат с ботом по QR-ссылке магазина.
2. Нажмите кнопку «НАЧАТЬ РАБОТУ».
3. Нажмите кнопку «Поделиться контактом» и разрешите передачу контакта.
4. Убедитесь, что бот:
   • сохранил данные и считал вас авторизованным;
   • привязал вас к активной программе лояльности;
   • показал идентификационный QR-код;
   • показывает меню с кнопками «Карта покупателя», «Баланс», «Покупки».
5. Проверьте повторный вход: дубли клиента и карт создаваться не должны.
6. (SCORING) Проверьте отображение баланса в отдельной ячейке с названием программы.
7. Проверьте отображение истории покупок.

Ключевые проверки по каналам

Канал	Что проверить
Telegram	Кнопка «Поделиться контактом» (request_contact), отправка фото с QR, меню с кнопками.
MAX	Кнопка «Поделиться контактом» (vCard), инлайн-меню, отправка QR без длительной паузы, меню после регистрации показывается сразу.

}}}

8. Типовые проблемы и их решение

Диагностика

Симптом	Причина / решение
Бот не запускается, в логе ошибка авторизации	Учётная запись не привязана к введённому organization_id. Проверьте права и привязку учётной записи к организации.
Ошибка «требуется двухфакторная авторизация» (mfa_required)	MFA в БИФИТ Касса не поддерживается. Отключите MFA у учётной записи или используйте grant refresh_token / bearer.
MAX-канал не запускается	Библиотека maxapi не установлена, либо нет сетевого доступа к хостам MAX (см. раздел 5.4). Telegram продолжает работать.
QR-карта в MAX отправляется с задержкой ~2 секунды	Убедитесь, что отправка изображения использует after_input_media_delay = 0.05 (библиотека не принимает нулевое значение).
Покупатель «не найден»	Проверьте, что покупатель прошёл регистрацию (поделился контактом) в этом канале. Иначе бот просит «пройти регистрацию».
«Нет активной программы лояльности»	Проверьте, что в организации есть активная ПЛ типов DISCOUNT или SCORING.

9. Глоссарий

• Покупатель — конечный участник программы лояльности; работает в боте продавца.
• Продавец — владелец бота, сотрудник организации; настраивает бота, но не работает в его интерфейсе.
• Организация (магазин) — точка обслуживания, владеющая программами лояльности.
• Программа лояльности (ПЛ) — сущность API LoyaltyV2 (типы: DISCOUNT, COUPON, SCORING, GIFT). Бот работает только с DISCOUNT и SCORING.
• Идентификационный QR — QR-код со значением номера карты лояльности, который покупатель предъявляет продавцу.
• Меню бота — набор кнопок: «Карта покупателя», «Баланс», «Покупки», «НАЧАТЬ РАБОТУ».