|
|
| Строка 1: |
Строка 1: |
| Инструкция по настройке бота лояльности | | Инструкция по подключению бота лояльности |
| == Оглавление == | | == Оглавление == |
|
| |
|
| * [[#1 Общие сведения|1. Общие сведения]] | | * [[#1 Что нужно от вас|1. Что нужно от вас]] |
| * [[#2 Что нужно подготовить перед стартом|2. Что нужно подготовить перед стартом]]
| | * [[#2 Получение токена Telegram-бота|2. Получение токена Telegram-бота]] |
| * [[#3 Общие шаги настройки (для всех каналов)|3. Общие шаги настройки (для всех каналов)]] | | * [[#3 Получение токена MAX-бота (необязательно)|3. Получение токена MAX-бота (необязательно)]] |
| * [[#4 Настройка Telegram-бота|4. Настройка Telegram-бота]]
| | * [[#4 Что дальше|4. Что дальше]] |
| * [[#5 Настройка MAX-бота|5. Настройка MAX-бота]] | | * [[#5 Глоссарий|5. Глоссарий]] |
| * [[#6 Запуск бота|6. Запуск бота]] | |
| * [[#7 Проверка работы бота|7. Проверка работы бота]] | |
| * [[#8 Типовые проблемы и их решение|8. Типовые проблемы и их решение]]
| |
| * [[#9 Глоссарий|9. Глоссарий]]
| |
|
| |
|
| == 1. Общие сведения == | | == 1. Что нужно от вас == |
|
| |
|
| Бот программы лояльности обслуживает '''покупателей''' вашего магазина (организации). Покупатель в мессенджере:
| | Для подключения бота лояльности вам достаточно подготовить два (или три) значения: |
|
| |
|
| * делится с ботом своей контактной карточкой ('''ФИО''' и '''номер телефона''');
| | # '''ИНН организации''' — по нему мы самостоятельно найдём <code>organization_id</code>. |
| * автоматически привязывается к активной программе лояльности (например, «10% скидка» или «Накопление баллов»);
| | # '''Токен Telegram-бота''' — как получить, см. раздел 2. |
| * получает персональный '''идентификационный QR-код''' с номером карты;
| | # '''Токен MAX-бота''' — необязательно; как получить, см. раздел 3. |
| * может смотреть '''баланс''' накопительной программы и '''историю покупок'''.
| |
|
| |
|
| Продавец считывает QR-код покупателя кассовым ПО (сканером/камерой мобильной кассы). Взаимодействие продавца с ботом через интерфейс мессенджера '''не требуется'''.
| | Больше от вас ничего не требуется: настройка, запуск и обслуживание выполняются на нашей стороне. |
| | |
| Один и тот же магазин может обслуживаться '''одновременно двумя ботами''': в Telegram и в MAX. Оба бота могут одновременно работать с одной организацией.
| |
|
| |
|
| {{Note|'''Важно'''<br> | | {{Note|'''Важно'''<br> |
| Учётная запись, от имени которой бот работает с API БИФИТ Касса, должна иметь '''максимальное количество прав''' — право создавать, редактировать и удалять документы и справочники, а также карты лояльности и клиентов.| | | Учётная запись БИФИТ Касса, от имени которой будет работать бот, должна иметь максимальное количество прав — право создавать, редактировать и удалять документы, справочники, клиентов и карты лояльности.| |
| 700}}
| |
| | |
| == 2. Что нужно подготовить перед стартом ==
| |
| | |
| Перед запуском бота у вас должны быть:
| |
| | |
| * '''Учётная запись''' БИФИТ Касса с логином (номер телефона в формате <code>7xxxxxxxxxx</code>) и паролем, привязанная к вашей организации.
| |
| * '''ID организации''' (Organization ID). Если Вы не знаете organization_id Вы можете запросить ее в службе технической поддержки через Личный кабинет
| |
| * '''Активная программа лояльности''' в организации (типы, с которыми работает бот: '''DISCOUNT''' — скидка, '''SCORING''' — баллы).
| |
| * '''Учётные данные Telegram-бота''' и/или '''MAX-бота''' (см. разделы 4 и 5).
| |
| * Доступ к '''базе данных PostgreSQL''', в которой хранится конфигурация ботов (таблица <code>bifit_loyalty_bots</code>).
| |
| | |
| {{Note|'''Обратите внимание'''<br>
| |
| Бот работает с программами лояльности только типов '''DISCOUNT''' и '''SCORING'''. Программы типов COUPON и GIFT ботом игнорируются.|
| |
| 700}}
| |
| | |
| == 3. Общие шаги настройки (для всех каналов) ==
| |
| | |
| Независимо от того, какой канал вы настраиваете (Telegram или MAX), конфигурация бота хранится в таблице <code>bifit_loyalty_bots</code> базы данных PostgreSQL. '''Одна строка таблицы = один магазин = один экземпляр бота'''.
| |
| | |
| Параметры бэкенда (доступ к API БИФИТ Касса) — '''общие''' для обоих каналов одной организации. Различаются только токены мессенджеров и адрес Bot API.
| |
| | |
| Строка настраивается через следующие ключевые поля:
| |
| | |
| {| class="wikitable"
| |
| |+ Основные поля строки <code>bifit_loyalty_bots</code>
| |
| ! Поле
| |
| ! Назначение
| |
| |-
| |
| | <code>id</code>
| |
| | Служебный идентификатор строки. Используется для имени файлов хранилища (например <code>data/customers_1.json</code>).
| |
| |-
| |
| | <code>enabled</code>
| |
| | Флаг «включён». Бот запускает только строки с <code>enabled = TRUE</code>.
| |
| |-
| |
| | <code>name</code>
| |
| | Название магазина (отображается в логах).
| |
| |-
| |
| | <code>organization_id</code>
| |
| | ID организации (магазина) в БИФИТ Касса.
| |
| |-
| |
| | <code>api_base_url</code>
| |
| | Базовый адрес API БИФИТ Касса (по умолчанию <code>http://kassa.bifit.com/cashdesk-api/v1</code>).
| |
| |-
| |
| | <code>auth_username</code>
| |
| | Логин учётной записи (номер телефона). Бот сам нормализует его до формата <code>7xxxxxxxxxx</code>.
| |
| |-
| |
| | <code>auth_password</code>
| |
| | Пароль учётной записи в открытом виде. Бот сам зашифрует его: <code>SHA-256 → Base64 urlencoded</code>.
| |
| |-
| |
| | <code>auth_refresh_token</code>
| |
| | Альтернатива паролю — refresh-токен (для продления сессии без пароля).
| |
| |-
| |
| | <code>http_timeout_ms</code>
| |
| | Таймаут запросов к API (по умолчанию <code>10000</code>).
| |
| |-
| |
| | <code>retry_attempts</code>
| |
| | Количество повторов при ошибках API (по умолчанию <code>3</code>).
| |
| |}
| |
| | |
| {{Note|'''Секреты'''<br>
| |
| В коде бота и в репозитории не должно быть секретов. Все пароли, токены и ID организации хранятся только в базе данных. В окружении сервера находятся лишь параметры подключения к базе: <code>PGHOST</code>, <code>PGPORT</code>, <code>PGDATABASE</code>, <code>PGUSER</code>, <code>PGPASSWORD</code>.|
| |
| 700}} | | 700}} |
|
| |
|
| Порядок действий администратора:
| | == 2. Получение токена Telegram-бота == |
| | |
| # Создать строку в таблице <code>bifit_loyalty_bots</code> для своего магазина.
| |
| # Заполнить общие поля (раздел 3) и поля конкретного канала (раздел 4 и/или 5).
| |
| # Установить флаг <code>enabled = TRUE</code>.
| |
| # Запустить бота (раздел 6).
| |
| | |
| == 4. Настройка Telegram-бота == | |
| | |
| === 4.1 Создание бота в Telegram ===
| |
|
| |
|
| # Откройте мессенджер '''Telegram'''. | | # Откройте мессенджер '''Telegram'''. |
| # Найдите бота '''@BotFather''' и откройте с ним чат. | | # Найдите бота '''@BotFather''' и откройте с ним чат. |
| # Отправьте команду <code>/newbot</code>. | | # Отправьте команду <code>/newbot</code>. |
| # Следуйте подсказкам BotFather: введите имя бота и его уникальный username (адрес, заканчивающийся на <code>bot</code>, например <code>my_shop_loyalty_bot</code>). | | # Следуйте подсказкам BotFather: введите имя бота и его уникальный адрес (username), который заканчивается на <code>bot</code>, например <code>my_shop_loyalty_bot</code>. |
| # После создания BotFather выдаст '''токен''' вида <code>123456:ABC-DEF123...</code>. Скопируйте и сохраните его. | | # После создания BotFather выдаст '''токен''' вида <code>123456:ABC-DEF123...</code>. |
| # (Необязательно) задайте боту аватар, описание и команды.
| |
|
| |
|
| Полученный токен является единственным Telegram-специфичным параметром; остальные поля строки — общие (раздел 3).
| | Скопируйте этот токен и передайте его нам. Это единственное, что нужно сделать в Telegram. |
|
| |
|
| === 4.2 QR-ссылка на Telegram-бота ===
| | {{Note|'''Обратите внимание'''<br> |
| | | Токен выдаётся '''только один раз''' при создании бота. Сохраните его в надёжном месте — это ключ доступа к вашему боту.| |
| * Прямая ссылка на бота имеет вид <code>https://t.me/имя_бота</code>.
| |
| * Эту ссылку нужно закодировать в QR-код и разместить в зоне видимости покупателя.
| |
| * При сканировании QR-кода телефон открывает чат с ботом, и покупатель нажимает '''«НАЧАТЬ РАБОТУ»'''.
| |
| | |
| === 4.3 Поля таблицы для Telegram ===
| |
| | |
| {| class="wikitable"
| |
| |+ Telegram-специфичные поля строки <code>bifit_loyalty_bots</code>
| |
| ! Поле
| |
| ! Значение
| |
| |-
| |
| | <code>telegram_token</code>
| |
| | Токен, выданный '''@BotFather''' (обязателен).
| |
| |}
| |
| | |
| {{Note|'''Уникальность токена'''<br> | |
| Значение <code>telegram_token</code> в таблице должно быть '''уникальным'''. Один токен не может использоваться двумя запущенными экземплярами бота одновременно.|
| |
| 700}} | | 700}} |
|
| |
|
| Telegram-канал запускается, если в строке заполнен <code>telegram_token</code>.
| | Дополнительно вы получите прямую ссылку на бота вида <code>https://t.me/имя_бота</code>. Её нужно будет разместить в зоне видимости покупателя в виде QR-кода (мы поможем это настроить). |
|
| |
|
| == 5. Настройка MAX-бота == | | == 3. Получение токена MAX-бота (необязательно) == |
|
| |
|
| === 5.1 Создание бота в MAX ===
| | Этот шаг нужен только если вы хотите, чтобы магазин обслуживался ещё и ботом в MAX. Если нет — пропустите раздел. |
|
| |
|
| # Войдите на '''портал MAX''' (или API-платформу MAX) под учётной записью организации. | | # Войдите на '''портал MAX''' (или API-платформу MAX) под учётной записью организации. |
| # Зарегистрируйте нового бота в соответствии с правилами платформы MAX. | | # Зарегистрируйте нового бота в соответствии с правилами платформы MAX. |
| # Получите '''токен MAX-бота''' (используется как <code>max_token</code>) и, при необходимости, '''session-ключ''' и '''код подтверждения'''. | | # Получите '''токен MAX-бота''' и, при необходимости, логин, пароль и другие параметры доступа, которые запросит платформа. |
| # Сохраните параметры доступа: логин, пароль, session-ключ, код подтверждения.
| |
| | |
| MAX-бот работает через библиотеку <code>maxapi</code> и требует сетевого доступа сервера к хостам платформы MAX (см. раздел 5.4).
| |
| | |
| === 5.2 QR-ссылка на MAX-бота ===
| |
| | |
| * Для MAX используется '''прямая ссылка на бота''' платформы MAX.
| |
| * Ссылку кодируют в QR-код и размещают в зоне видимости покупателя.
| |
| | |
| === 5.3 Поля таблицы для MAX ===
| |
| | |
| {| class="wikitable"
| |
| |+ MAX-специфичные поля строки <code>bifit_loyalty_bots</code>
| |
| ! Поле
| |
| ! Назначение
| |
| |-
| |
| | <code>max_token</code>
| |
| | Токен MAX-бота. '''Именно его наличие включает MAX-канал''', а не флаг <code>max_enabled</code>.
| |
| |-
| |
| | <code>max_enabled</code>
| |
| | Флаг (справочный). На запуск MAX-бота влияет наличие <code>max_token</code>.
| |
| |-
| |
| | <code>max_login</code>
| |
| | Логин для входа в MAX.
| |
| |-
| |
| | <code>max_password</code>
| |
| | Пароль для входа в MAX.
| |
| |-
| |
| | <code>max_session_key</code>
| |
| | Session-ключ MAX (при необходимости).
| |
| |-
| |
| | <code>max_confirmation_code</code>
| |
| | Код подтверждения (при необходимости).
| |
| |-
| |
| | <code>max_api_base_url</code>
| |
| | Адрес Bot API MAX (по умолчанию <code>https://api.max.ru</code>; рабочий хост — <code>platform-api2.max.ru</code>).
| |
| |}
| |
| | |
| {{Note|'''Включение MAX-канала'''<br>
| |
| MAX-бот запускается '''по наличию токена <code>max_token</code>''', а не по флагу <code>max_enabled</code>. Если в строке заполнен <code>max_token</code> — MAX-канал будет запущен.|
| |
| 700}}
| |
|
| |
|
| === 5.4 Сетевые хосты MAX ===
| | Скопируйте полученный токен и передайте его нам. |
|
| |
|
| Для работы MAX-бота сервер должен иметь доступ (в том числе исходящий по TCP 443) к следующим хостам:
| | {{Note|'''Примечание'''<br> |
| | | Если токен MAX-бота не передан — магазин будет обслуживаться только ботом в Telegram. MAX-канал подключается только при наличии токена.| |
| * '''Bot API:''' <code>platform-api2.max.ru</code> (или адрес из <code>max_api_base_url</code>);
| |
| * '''Загрузка медиа:''' <code>iu.oneme.ru</code>;
| |
| * '''Скачивание медиа:''' <code>i.oneme.ru</code>.
| |
| | |
| Если сервер не может обратиться к этим хостам, MAX-канал работать не будет.
| |
| | |
| {{Note|'''Зависимость от библиотеки <code>maxapi</code>'''<br> | |
| MAX-канал подключается лениво. Если библиотека <code>maxapi</code> не установлена на сервере — MAX-канал пропускается с сообщением об ошибке в лог, а Telegram-бот продолжает работать.| | |
| 700}} | | 700}} |
|
| |
|
| == 6. Запуск бота ==
| | Также вы получите прямую ссылку на MAX-бота — её разместят в зоне видимости покупателя в виде QR-кода. |
| | |
| # Убедитесь, что на сервере установлены зависимости (Python 3, библиотеки проекта, а для MAX — <code>maxapi</code>).
| |
| # Задайте параметры подключения к базе PostgreSQL в окружении (<code>PGHOST</code>, <code>PGPORT</code>, <code>PGDATABASE</code>, <code>PGUSER</code>, <code>PGPASSWORD</code>).
| |
| # Запустите приложение-лаунчер ботов.
| |
| # Бот на старте выполняет авторизацию OAuth2 и проверяет привязку учётной записи к вашей организации:
| |
| #* если привязка есть — бот запускает каналы (Telegram и/или MAX);
| |
| #* если привязки нет — бот выводит ошибку в лог и останавливается.
| |
| | |
| По умолчанию развёртывание происходит в режиме '''polling''' (и для Telegram, и для MAX) — отдельные webhook-серверы не требуются.
| |
| | |
| == 7. Проверка работы бота ==
| |
| | |
| Для каждого настроенного канала выполните проверку:
| |
|
| |
|
| # Откройте чат с ботом по QR-ссылке магазина.
| | == 4. Что дальше == |
| # Нажмите кнопку '''«НАЧАТЬ РАБОТУ»'''.
| |
| # Нажмите кнопку '''«Поделиться контактом»''' и разрешите передачу контакта.
| |
| # Убедитесь, что бот:
| |
| #* сохранил данные и считал вас авторизованным;
| |
| #* привязал вас к активной программе лояльности;
| |
| #* показал идентификационный '''QR-код''';
| |
| #* показывает '''меню''' с кнопками «Карта покупателя», «Баланс», «Покупки».
| |
| # Проверьте повторный вход: дубли клиента и карт создаваться '''не должны'''.
| |
| # (SCORING) Проверьте отображение баланса в отдельной ячейке с названием программы.
| |
| # Проверьте отображение истории покупок.
| |
|
| |
|
| {{{!}} class="wikitable"
| | После того как вы передали нам '''ИНН организации''' и токены ботов: |
| {{!}}+ Ключевые проверки по каналам
| |
| {{!}} Канал
| |
| {{!}} Что проверить
| |
| {{!}}-
| |
| {{!}} Telegram
| |
| {{!}} Кнопка «Поделиться контактом» (<code>request_contact</code>), отправка фото с QR, меню с кнопками.
| |
| {{!}}-
| |
| {{!}} MAX
| |
| {{!}} Кнопка «Поделиться контактом» (vCard), инлайн-меню, отправка QR без длительной паузы, меню после регистрации показывается сразу.
| |
| {{!}}}
| |
| }}}
| |
|
| |
|
| == 8. Типовые проблемы и их решение ==
| | * мы найдём <code>organization_id</code> по ИНН; |
| | * настроим и запустим бота; |
| | * пришлём вам QR-коды для размещения в зоне продажи. |
|
| |
|
| {| class="wikitable"
| | Ваши покупатели смогут делиться контактом, получить идентификационный QR-код, смотреть баланс и историю покупок. |
| |+ Диагностика
| |
| ! Симптом
| |
| ! Причина / решение
| |
| |-
| |
| | Бот не запускается, в логе ошибка авторизации
| |
| | Учётная запись не привязана к введённому <code>organization_id</code>. Проверьте права и привязку учётной записи к организации.
| |
| |-
| |
| | Ошибка «требуется двухфакторная авторизация» (<code>mfa_required</code>)
| |
| | MFA в БИФИТ Касса '''не поддерживается'''. Отключите MFA у учётной записи или используйте grant <code>refresh_token</code> / <code>bearer</code>.
| |
| |-
| |
| | MAX-канал не запускается
| |
| | Библиотека <code>maxapi</code> не установлена, либо нет сетевого доступа к хостам MAX (см. раздел 5.4). Telegram продолжает работать.
| |
| |-
| |
| | QR-карта в MAX отправляется с задержкой ~2 секунды
| |
| | Убедитесь, что отправка изображения использует <code>after_input_media_delay = 0.05</code> (библиотека не принимает нулевое значение).
| |
| |-
| |
| | Покупатель «не найден»
| |
| | Проверьте, что покупатель прошёл регистрацию (поделился контактом) в этом канале. Иначе бот просит «пройти регистрацию».
| |
| |-
| |
| | «Нет активной программы лояльности»
| |
| | Проверьте, что в организации есть активная ПЛ типов DISCOUNT или SCORING.
| |
| |}
| |
|
| |
|
| == 9. Глоссарий == | | == 5. Глоссарий == |
|
| |
|
| * '''Покупатель''' — конечный участник программы лояльности; работает в боте продавца. | | * '''Покупатель''' — конечный участник программы лояльности; работает в боте. |
| * '''Продавец''' — владелец бота, сотрудник организации; настраивает бота, но не работает в его интерфейсе.
| | * '''Программа лояльности (ПЛ)''' — сущность API БИФИТ Касса (типы: DISCOUNT — скидка, SCORING — баллы). Бот работает с типами DISCOUNT и SCORING. |
| * '''Организация (магазин)''' — точка обслуживания, владеющая программами лояльности.
| |
| * '''Программа лояльности (ПЛ)''' — сущность API <code>LoyaltyV2</code> (типы: DISCOUNT, COUPON, SCORING, GIFT). Бот работает только с <code>DISCOUNT</code> и <code>SCORING</code>. | |
| * '''Идентификационный QR''' — QR-код со значением номера карты лояльности, который покупатель предъявляет продавцу. | | * '''Идентификационный QR''' — QR-код со значением номера карты лояльности, который покупатель предъявляет продавцу. |
| * '''Меню бота''' — набор кнопок: «Карта покупателя», «Баланс», «Покупки», «НАЧАТЬ РАБОТУ». | | * '''Токен бота''' — ключ доступа, который подтверждает право управлять ботом. |
Важно