Telegram Mini App открывается внутри мессенджера, но её сервер не должен доверять любым данным, которые пришли из браузерной части. Если приложение принимает переданный user ID без проверки, посетитель сможет подставить другое значение. Для входа используется проверяемый набор данных запуска, а затем собственная серверная сессия приложения.
Главное различие проходит между данными интерфейса и подтверждённым контекстом. Поля, доступные JavaScript в клиенте, удобны для отображения, но не все они могут служить основанием доступа к заказам и личному кабинету. Ниже описан порядок проектирования входа без публикации токенов или готовых секретов.
Что получает приложение при запуске
Telegram предоставляет Mini App данные запуска через предусмотренный интерфейс. В документации различаются исходная строка initData и разобранное представление initDataUnsafe. Второе удобно для работы на клиенте, но его название не случайно: серверная авторизация не должна строиться на доверии к уже разобранному объекту из запроса посетителя.
Клиент передаёт серверу исходные данные способом, определённым вашим приложением. Сервер проверяет их по официальному алгоритму и только после успешной проверки использует подтверждённые поля. Если нужного поля нет для данного способа запуска, система должна обработать отсутствие, а не выдумывать значение из имени профиля.
Не смешивайте вход Mini App с обычной ссылкой на страницу в браузере. Приложение может открыться вне Telegram, и тогда ожидаемого контекста не будет. Для такого случая предусмотрите понятный экран: открыть приложение поддерживаемым способом либо использовать отдельный разрешённый метод входа, если он реализован.
Где должна выполняться проверка
Проверка, на которой строится доступ к данным, выполняется на доверенной серверной стороне. Токен бота не передают в JavaScript приложения, HTML или общедоступную конфигурацию сборки. Если секрет попал в браузерный код, его нельзя считать скрытым только потому, что файл сжат или название переменной неочевидно.
Используйте актуальный официальный алгоритм для выбранной модели проверки. Не копируйте случайный фрагмент из старой статьи без понимания, как формируется проверяемая строка и обрабатываются поля. У Telegram есть документированные варианты проверки для разных сценариев; их параметры нельзя произвольно смешивать между собой.
На уровне приложения проверяются также допустимая давность auth_date и правила повторного обмена. Конкретное окно времени выбирают с учётом процесса входа. Слишком короткое окно может ломать нормальный запуск, а бесконтрольное принятие старого набора данных затрудняет ограничение повторного использования.
Обмен на собственную сессию
После успешной проверки сервер связывает подтверждённого пользователя с внутренней учётной записью. Это ещё один отдельный шаг: Telegram-идентификатор не обязан совпадать с идентификатором клиента вашей системы. Для существующего кабинета может потребоваться предусмотренное подтверждение связи, особенно если там хранятся закрытые сведения.
Затем приложение выдаёт собственную сессию с согласованным сроком действия. Дальнейшие запросы используют эту сессию, а сервер проверяет права на конкретный ресурс. Сам факт входа не означает, что пользователь может читать любой заказ по подставленному номеру или изменять чужую запись.
Продумайте выход и отзыв доступа. Очистка одного значения в памяти браузера не обязательно прекращает серверную сессию. Если человек отвязал аккаунт или администратор изменил доступ, новые запросы должны учитывать это изменение. При использовании кэша разрешений определите, когда он обновляется и как сбрасывается.
Условный пример: запись клиента на консультацию
Предположим, Mini App показывает клиенту его записи и позволяет перенести время. После запуска клиентская часть передаёт initData серверу. Сервер проверяет данные, определяет внутреннего клиента и создаёт сессию. Список записей формируется по разрешённым этому клиенту данным, а не по номеру пользователя из адресной строки.
Человек выбирает новую дату. Сервер снова проверяет принадлежность записи и доступность времени перед сохранением. Если другой клиент уже занял слот, приложение сообщает об изменении и предлагает доступные варианты. Проверенный вход не отменяет проверку текущего состояния самой операции.
Позже пользователь открывает старую ссылку в обычном браузере. Вместо доступа к истории по сохранённому имени приложение показывает предусмотренный экран входа. Это условный пример архитектуры; он не означает, что Telegram самостоятельно создаёт клиентские кабинеты, бронирования и серверные сессии для каждой Mini App.
Проверка ошибок без утечки секретов
Разделите ошибки запуска на понятные категории: отсутствуют данные, проверка не прошла, данные слишком старые, внутренняя учётная запись не найдена или сервер временно недоступен. Пользователю не нужны технические подробности алгоритма. Ему нужен следующий шаг: открыть приложение заново, пройти привязку или повторить попытку позже.
В журнале разработчика сохраняют диагностический код и идентификатор запроса, но не полный набор секретов. Перед включением подробного логирования проверьте, какие поля окажутся в журнале, системе ошибок и стороннем мониторинге. Временная отладочная запись часто остаётся включённой дольше, чем предполагалось.
Не подменяйте ошибку проверки автоматическим входом в «гостевой аккаунт» с доступом к пользовательским данным. Гостевой режим может существовать, но у него должны быть отдельные возможности. Например, показать общий каталог допустимо, а выдать историю заказов по неподтверждённому идентификатору — уже другой процесс.
Набор тестов для разработчика
Начните с корректного запуска и убедитесь, что сервер создаёт ожидаемую сессию. Затем измените одно поле исходных данных в тестовом запросе: проверка должна перестать проходить. Испытайте отсутствие обязательного поля, неверный формат и устаревшее время. Эти проверки выполняют в собственной тестовой среде на вымышленных записях.
Отдельно проверьте права после входа. Два тестовых пользователя не должны получать данные друг друга при замене идентификатора записи. Такой тест выявляет ошибку авторизации, которую не обнаружит проверка одной лишь подписи запуска. Вход подтверждает контекст, а доступ к ресурсу определяется серверными правилами приложения.
Затем испытайте несколько устройств, выход, повторный запуск и отзыв связи с кабинетом. Определите ожидаемый результат для уже открытой вкладки. Если права изменились, интерфейс должен корректно пережить отказ следующего запроса и объяснить необходимость нового входа, а не бесконечно показывать старые данные.
Как принимать готовую реализацию
Попросите разработчика показать место серверной проверки, модель сессии и тесты доступа к чужой записи. Для приёмки не нужно публиковать секреты или показывать рабочие персональные данные. Достаточно понятной схемы и воспроизводимых тестов с отдельными тестовыми пользователями.
В рабочей документации зафиксируйте поддерживаемые способы запуска, срок сессии и владельца процедуры отзыва. После обновления SDK или процесса входа повторите проверочный набор. Доступность красивого экрана внутри Telegram подтверждает только загрузку интерфейса, но не правильность серверной авторизации и разделения пользовательских данных.
Почему проверка запуска не заменяет модель ролей
Сотрудник и обычный клиент могут открыть одну Mini App, но выполнять разные задачи. После подтверждения Telegram-пользователя сервер определяет его роль по собственным данным. Признак администратора не должен браться из параметра ссылки или переключателя интерфейса, который посетитель способен изменить самостоятельно.
Если сотрудник уволился или перешёл в другой отдел, недостаточно убрать кнопку из меню. Необходимо изменить доступ на сервере и проверить действующие сессии. Пользовательское приложение может сохранять старый экран до следующего запроса, поэтому отказ операции должен обрабатываться без потери введённого черновика и без обходного доступа через другой маршрут.
Для приёмки подготовьте отдельные тестовые роли: клиент, оператор и пользователь без связанного кабинета. Проверьте чтение и изменение одной и той же записи от каждой роли. Это помогает отделить корректность входа от корректности разрешений. Обе части нужны рабочему приложению, но исправление подписи запуска само по себе не устраняет ошибку выдачи лишних полномочий.
Источники
Структура данных и официальные способы проверки представлены в Telegram Mini Apps: Validating data received via the Mini App. Общая модель запуска описана в документации Telegram Mini Apps. Перед реализацией сверяйте алгоритм с текущей документацией, а правила своей сессии описывайте отдельно от возможностей Telegram.