javascript

Как перенести Telegram-бота в MAX: каталог, заказ и очередь обновлений

  • вторник, 17 ноября 2026 г. в 00:00:13
https://habr.com/ru/articles/1108462/

В каталоге собственного магазина керамогранита была ветка Telegram. Для MAX понадобилось сохранить путь покупателя: открыть каталог, выбрать товар и упаковки, оформить заказ, передать контакт и получить заказ у менеджера. Главная трудность оказалась не в переносе кнопок. Между страницей магазина и ботом нужен был другой способ передачи данных: в просмотренном MAX Bridge я не нашёл аналога Telegram sendData.

Я сохранил один HTML-интерфейс для двух сред запуска, но разделил способы общения с мессенджером. Дальше расскажу, как устроен этот путь в действующем коде, что удалось проверить в работе и какие ограничения остались. Это собственный проект: бюджета заказчика, прироста продаж и результатов нагрузочного теста у него в этом разборе нет.

Сначала проверка доступа к API

Для бота использованы Python 3.11 и requests. В рабочем окружении запрос GET /me к platform-api.max.ru вернул HTTP 200 и подтвердил, что учётная запись является ботом. Запрос к platform-api2.max.ru до этого не проходил TLS: возникала проблема с цепочкой сертификата Минцифры. Рабочий хост позволил продолжить проверку без отключения проверки сертификатов.

Это наблюдение об окружении, а не заявление, что альтернативный адрес недоступен у всех. verify=False я не использовал, системное хранилище сертификатов не менял. Для переноса такая проверка полезнее предположения, что ошибка TLS означает неправильную бизнес-логику. Пока GET /me не проходит, разбирать сценарий заказа рано: сначала надо отделить доступ к API от ошибок обработчика.

Приветствие отправляется в ответ на bot_started или /start. В клавиатуре используется inline_keyboard, строки кнопок лежат в payload.buttons. Для открытия каталога в рабочем боте выбрана кнопка link. Она содержит адрес страницы магазина. Это отличается от open_app: у него привязанное приложение и собственная схема, поэтому нельзя автоматически переносить туда произвольное поле url из другой платформы.

Общая страница, разные способы возврата

Telegram-ветка использует tg.sendData. Для MAX я не стал имитировать этот вызов другим названием. Внутри MAX страница проверяет наличие window.WebApp, initData и метода openMaxLink. Когда эти признаки есть, оформление передаёт управление боту через openMaxLink и параметр start.

Отдельно потребовалась ветка обычного браузера. При проверке в веб-версии MAX каталог открывался обычной вкладкой, а не средой с доступным Bridge. Наличие загруженного SDK само по себе не означало, что страница находится внутри приложения. В браузерной ветке переход выполняется через location.href. Поэтому интерфейс каталога общий, а решение о способе перехода принимается по доступной среде.

Смысл этого разделения — не заставлять браузер вызывать отсутствующий метод. Открытие каталога и возврат к боту являются разными переходами, и каждый надо проверить именно в том окружении, где им пользуется покупатель. Успешное открытие страницы ещё не подтверждает, что заказ попал в обработчик.

Вместо полного заказа — компактный payload

В параметр start я передаю не весь JSON заказа. Ограничение в этой реализации — 128 знаков. Полные названия, цены, имя и контакт в такую строку не нужны. В ней остаются способ получения и пары идентификатора товара с количеством упаковок. Для чисел используется система счисления 36.

Формат начинается с o1, затем идёт признак получения p или d и разделитель подчёркивания. Внутри пары идентификатор отделён от количества точкой, пары разделены дефисами. Корзина перед сериализацией сортируется по идентификаторам. Если строка оказывается длиннее лимита, интерфейс предлагает разделить заказ, а не обрезает его молча.

Внутри обхода корзины используются эти операции из кода каталога:

if (!product(id) || !Number.isInteger(q) || q < 1 || q > 100000)
  throw new Error('Проверьте количество упаковок.');
return id.toString(36) + '.' + q.toString(36);

Это фрагмент сериализации, а не самостоятельная функция оформления. Проверка на странице помогает показать понятную ошибку, но доверять только ей нельзя: входящую строку пользователь может изменить. Контакт при таком устройстве не оказывается в адресе перехода. Его бот запросит позже, уже после разбора заказа.

Цену определяет бот

Обработчик получает payload из bot_started либо разбирает его после /start в событии message_created. Затем проверяет тип и длину строки, её формат, известность товаров, отсутствие повторяющихся идентификаторов и допустимое количество упаковок. Входной payload — описание выбора, а не подтверждённая стоимость.

После разбора цена берётся из локального каталога. Бот заново считает сумму по товару, упаковке и количеству. Денежный расчёт идёт целыми копейками. Так сумма не зависит от значения, которое покупатель мог бы подставить в ссылку. Участок парсера выглядит так:

product_id, quantity = (int(x, 36) for x in pair.split('.'))
if product_id not in catalog or product_id in used or not 1 <= quantity <= 100000:
    raise ValueError('Проверьте товары и количество упаковок в каталоге.')
used.add(product_id)
p = catalog[product_id]
amount = p['price'] * p['pack'] * quantity

Этот код находится внутри разбора пар и использует подготовленные catalog и used. Полный обработчик также проверяет оболочку payload. Важно сохранить оба уровня: ограничение длины и синтаксиса строки не заменяет проверку идентификаторов и количества. Иначе компактная запись останется удобной для передачи, но перестанет быть надёжным входом для расчёта.

Контакт и передача менеджеру

После разбора бот показывает покупателю сводку и просит поделиться контактом. Кнопка имеет тип request_contact и подпись «Поделиться телефоном». Она размещена в строке inline_keyboard. Поэтому данные для связи не надо заранее включать в deep link или переносить из браузерной формы в адрес.

Пока бот ожидает контакт, заказ хранится в self.pending. Когда контакт получен, заказ передаётся зарегистрированному менеджеру, а клиент получает подтверждение. В действующем коде ожидание ограничено 1800 секундами. Это часть текущей реализации, а не обещание хранить корзину бессрочно.

Здесь остаётся ограничение: self.pending находится в памяти процесса. После перезапуска незавершённый заказ не восстановится. Проверенный путь работает, когда процесс остаётся запущенным; постоянное хранение ожидающих заказов в этой работе не реализовано. Эту границу нельзя прятать за успешной проверкой получения контакта.

Что происходило с событиями при перезапуске

Во время работы сообщения терялись между остановкой и новым запуском опроса. Начальное получение очереди использовалось для установки marker, но свежие события из этой пачки тоже могли требовать ответа. Исправление сохраняет их в carry и добавляет к следующей пачке обработки. Берутся события не старше 5 минут, старые пропускаются.

Дальше marker из ответа передаётся в следующий GET /updates. Для защиты от повторной обработки используется seen: ключ включает тип события, адресата и mid либо timestamp. Ключ записывается до попытки отправить ответ. После неясного сетевого исхода POST /messages автоматически не повторяется, чтобы не создавать дубли.

У этого решения есть цена. Отказ от автоматического повтора не доказывает доставку: при сбое сообщение может быть пропущено. Marker и seen тоже находятся в памяти. Обработка свежей начальной пачки исправляет конкретную потерю на старте, но не превращает процесс в устойчивую дисковую очередь. Гарантию доставки на основании такого механизма заявлять нельзя.

По документации, которую я читал во время работы, Long Polling предназначен для разработки, а для эксплуатации предусмотрен Webhook через POST /subscriptions. Переход на внешний backend и проверка Webhook в эту реализацию не входили. Текущий опрос полезен для проверки сценария, но его ограничения надо учитывать до постоянного запуска.

Что проверено вживую

13.11.2026 прошёл весь путь: каталог → «Оформить» → сводка → получение контакта → заказ менеджеру. Такой проход подтвердил связь страницы, payload, обработчика и доставки заказа. Он не заменяет нагрузочную проверку, восстановление состояния после сбоя или проверку всех возможных комбинаций корзины.

Из небольших граблей запомнилось имя бота: длинное тире в нём не принималось. Логотип в этой работе загружал владелец. Это наблюдения о конкретном процессе настройки, а не вывод о том, что API во всех случаях запрещает загружать изображение другим способом.

В результате перенос потребовал сохранить сценарий и разделить границы: каталог собирает компактный выбор, бот проверяет его и считает сумму, контакт запрашивается в чате, менеджер получает заказ после этого шага. Общая страница с разными ветками среды оказалась удобнее попытки перенести Telegram-вызовы без изменений. Следующая работа здесь — устойчивое хранение состояния и проверка эксплуатации, а не новые обещания поверх успешно пройденного пути.