Как устроена заявка Web/Admin: от формы до Telegram

Бизнес-сценарий: клиенту нужно передать задачу

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

В Web/Admin для уведомления используется Telegram. Это удобная точка получения небольшого потока обращений: сообщение содержит контакт, описание задачи и контекст заявки. Но сам выбор мессенджера ещё не делает систему надёжной — решающее значение имеет обработка ответа и ошибок.

Что происходит после нажатия кнопки

Клиентская форма собирает поля и отправляет JSON в /api/lead. Сервер проверяет необходимые значения и длину полей, формирует полезную нагрузку и передаёт её модулю Telegram. Служебные метки рекламного перехода позволяют сохранить контекст обращения, если они пришли вместе с формой.

Перед отправкой пользовательский текст экранируется для HTML-разметки сообщения. Символы из описания задачи не должны превращаться в произвольные теги. Токен бота и идентификатор получателя читаются сервером из переменных окружения: посетителю не требуется знать секреты интеграции.

1. Браузер → серверный маршрут /api/lead.
2. Проверка полей → формирование сообщения.
3. Запрос sendMessage → проверка HTTP-ответа и поля ok.
4. Подтверждение интерфейсу или понятный код ошибки.

Почему успешного HTTP-запроса недостаточно

Отправка в Telegram реализована через Bot API. Модуль проверяет и HTTP-статус, и поле ok в JSON-ответе API. При отказе возвращается ошибка доставки; при выключенной интеграции в production — ошибка недоступности. Клиентская форма может показать ошибку и оставить человеку альтернативный контакт.

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

Что защищает форму и где заканчивается защита

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

Также предусмотрено особое поведение локальной разработки: без настроенного Telegram сервер может вернуть тестовый успех. Это удобно для вёрстки, но такую проверку нельзя выдавать за проверку реальной доставки. Production-сценарий и локальный сценарий требуют отдельных критериев приёмки.

Ограничения и следующий уровень надёжности

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

Для бизнеса с дорогим трафиком я бы отдельно оценивал сохранение заявки до уведомления, уникальный идентификатор и повторные попытки с ограничением. Это возможное развитие архитектуры, а не заявленная функция текущего решения. Нужный уровень зависит от цены потери обращения и объёма заявок.

Как принимать такую доработку в своём проекте

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

Мой вывод из разбора: проверять нужно весь путь обращения. Если у вас форма показывает успех, но заявок нет, начать можно с одной диагностики — проверить браузерный запрос, серверную обработку и ответ почты, CRM или мессенджера. Переписывание всего сайта для этого не является исходным требованием.