Zimmer Samarqand — QR-акция с Telegram-ботом

Мы запустили QR-акцию с Telegram-ботом для бренда из Самарканда: покупатель сканирует стикер, запускает бота и попадает в базу и в розыгрыш. Сотрудникам сделали панель с партиями до 150 000 кодов, печатью стикеров, выгрузкой в Excel и розыгрышами.

Клиент
Zimmer Samarqand
Тип проекта
Веб-приложение
Открыть приложение
Zimmer Samarqand — QR-акция с Telegram-ботом

Задача

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

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

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

Партии исчисляются десятками тысяч наклеек, а печатают их по-разному: на листах A4 или рулонами этикеток на термопринтере. Каждый принтер немного сдвигает изображение, а QR-код на маленьком стикере всё равно должен уверенно читаться камерой телефона. С панелью управления работают сотрудники бренда, а не программисты, — на узбекском или русском, и не только с компьютера. Сервер общий с другими проектами, поэтому акция не должна отнимать у соседей процессор и память. Наконец, имена и телефоны участников — персональные данные, а ключ доступа к боту даёт полный контроль над ним: ни то ни другое не должно попасть в чужие руки.

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

Решение

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

Серверную часть мы написали на C++ с фреймворком Drogon и дали ей жёсткие рамки: на общем сервере она получает одно ядро процессора и 512 МБ памяти, чтобы соседние сайты не страдали. Telegram передаёт ей каждое сообщение, а она за один шаг регистрирует код и участника и отвечает в том же обмене, поэтому ключ от бота ей не нужен вовсе — он используется только при выкладке обновлений. Бот говорит только по-узбекски, все 8 его сообщений сотрудники правят в панели, и правка действует с первого же ответа. Телефон бот просит кнопкой, но не требует, а сообщения из групп и от других ботов не замечает.

Панель управления мы собрали на React Admin — готовой основе для таблиц, фильтров и форм. В ней шесть разделов: партии QR-кодов, участники, розыгрыши, коды, тексты бота и пользователи. Панель работает на узбекском, русском и английском, в светлой и тёмной теме, а на телефоне таблицы превращаются в карточки. PDF со стикерами собирается прямо в браузере, поэтому печать не нагружает сервер, пока бот отвечает покупателям. Сотрудники входят по логину и паролю, открытой регистрации нет. Приложение упаковано в Docker: каждая версия хранится целиком, и прошлую можно вернуть сразу, а GitHub Actions выкладывает новую только после всех проверок.

  1. Каждый код срабатывает один раз

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

  2. Партии до 150 000 кодов

    Партия от 1 до 150 000 кодов создаётся за один шаг и появляется целиком или не появляется вовсе; самая большая на рабочем сервере занимает около 16 секунд. Каждый код — 16 случайных букв и цифр, поэтому угадать чужой подбором практически невозможно. Ссылка короткая, QR-код получается компактным и читается даже со стикера 20 мм. Партию с использованными кодами удалить нельзя.

  3. Печать стикеров в браузере

    PDF для печати собирается прямо в браузере сотрудника, в фоне, и страница при этом не зависает: листы A4 по 54 стикера размером 30 мм или по одному стикеру на этикетку термопринтера. Размер от 20 до 50 мм, поля, зазоры и сдвиг подгоняются под конкретный принтер, пробный лист с линейкой 50 мм проверяет настройку, а нужный диапазон номеров можно допечатать. Раскладку, при которой код выходит за край листа, панель в печать не пустит.

  4. База участников и выгрузка

    Каждый, кто зарегистрировал код, попадает в базу: имя, ник в Telegram, язык, телефон, если человек им поделился, и число кодов. Список ищется и фильтруется по датам, а выгружается в Excel до 300 000 строк или в CSV без ограничений; файл собирается частями по 20 000 строк, чтобы не перегружать сервер. Формула, вписанная в имя в Telegram, в выгрузке не сработает, а в карточке участника видны все его коды.

  5. Честный розыгрыш призов

    Розыгрыш за один шаг выбирает от 1 до 1000 разных людей из одной партии. Каждый зарегистрированный код — отдельный шанс, коды других партий не считаются, а сама база данных не даёт человеку выиграть в партии дважды, даже если два розыгрыша запустили одновременно. Партию можно разыграть снова без прежних победителей, а итоги сохраняются, даже если партию потом удалят.

  6. Безопасные обновления и копии базы

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

Результаты

Главные итоги проекта в цифрах.

  • 150kКодов в одной партии

    Самая большая партия — 150 000 кодов — появляется на рабочем сервере примерно за 16 секунд, целиком или не появляется вовсе.

  • 1Нажатие для участия

    Покупателю достаточно отсканировать стикер и нажать одну кнопку в Telegram — без регистрации, анкет и отдельного приложения.

  • 1000Победителей за розыгрыш

    Один розыгрыш выбирает до 1000 разных участников партии, и выиграть в ней один человек может только раз.

  • 54Стикера на листе A4

    По умолчанию на лист A4 помещается 54 стикера по 30 мм, а размер, поля и сдвиг подгоняются под принтер.

Технологии в проекте

Стек, на котором мы строили решение под задачи клиента.

  • C++
  • Drogon
  • PostgreSQL
  • Docker
  • Nginx
  • GitHub Actions
  • TypeScript
  • React
  • Vite
  • MUI
  • React Admin
  • Telegram Bot API

Готовы стать следующим кейсом?

Расскажите о задаче — менеджер соберёт команду, посчитает смету и пришлёт коммерческое предложение в первый час после заявки. Без обязательств и без рассылок.