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

Материал из Касса
Перейти к навигации Перейти к поиску

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

Оглавление

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

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

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

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

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

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

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

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

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

Note.svg Обратите внимание
Бот работает с программами лояльности только типов 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).

Note.svg Секреты
В коде бота и в репозитории не должно быть секретов. Все пароли, токены и 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 (обязателен).

Note.svg Уникальность токена
Значение 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).

Note.svg Включение 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-канал работать не будет.

Note.svg Зависимость от библиотеки 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-код со значением номера карты лояльности, который покупатель предъявляет продавцу.
  • Меню бота — набор кнопок: «Карта покупателя», «Баланс», «Покупки», «НАЧАТЬ РАБОТУ».
Источник — http://kassa.bifit.com/wiki/index.php?title=Боты_программы_лояльности&oldid=57971