Каталог и корзина в Telegram Mini App: от витрины до настоящего заказа

MAATRIX · 17 октября 2026 · 8 мин чтения

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

Магазин в Telegram становится полезным не тогда, когда научился показывать товары, а когда договорился со складом, оплатой и сотрудниками о том, что считать заказом. Разберём такую систему на примере небольшого магазина физических товаров. Здесь не требуется сразу строить торговую империю. Достаточно, чтобы покупатель получал обещанное, а менеджер не расшифровывал сообщения «мне вот эти две, только другого цвета».

Начните с десяти товаров, которые действительно можно купить

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

У карточки должны быть собственный идентификатор, название, варианты, цена, валюта, доступность и изображения. Удобный адрес картинки не заменяет идентификатор товара. Когда дизайнер переименует файл, заказ не должен потерять связь с каталогом.

Сразу определите, откуда приходят цены и остатки. Если магазин уже работает в учётной системе, именно она обычно остаётся главным источником. Mini App получает опубликованную версию каталога и сообщает время обновления. Не создавайте вторую таблицу, которую сотрудники будут вручную сверять с первой по вечерам.

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

Что Telegram даёт магазину, а что нужно написать

Mini App — интерфейс, открывающийся внутри Telegram. Каталог, расчёт заказа, работа со складом и административная часть остаются вашим приложением. На VPS размещаются API, база данных и фоновые обработчики; изображения можно хранить отдельно, если их объём заметно растёт.

Создайте бота, подготовьте HTTPS-адрес и настройте запуск приложения через меню. Способы запуска и проверка данных пользователя описаны в документации Mini Apps. На сервер передавайте исходные данные запуска и проверяйте их подлинность; идентификатор покупателя из обычного поля формы доверенным не становится.

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

Не требуйте адрес доставки до того, как человек выбрал товар. Лишняя анкета на входе отлично защищает магазин от заказов, но обычно такую защиту никто не заказывал.

Корзина хранит намерение, заказ фиксирует обязательство

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

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

В заказ копируйте название, артикул, цену и условия на момент покупки. Ссылка на текущую карточку тоже полезна, но исторический заказ должен оставаться понятным после переименования товара. Иначе через месяц в накладной внезапно появится новая коллекция вместо той, которую действительно отправили.

Денежные суммы храните в выбранном точном представлении: например, в целых минимальных единицах валюты. Не рассчитывайте итоговую стоимость обычной двоичной дробью без правил округления. Валюта является частью суммы, а не декоративным символом в интерфейсе.

Как последняя вещь достанется одному покупателю

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

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

UPDATE inventory
SET reserved = reserved + :quantity
WHERE variant_id = :variant_id
  AND :quantity > 0
  AND available - reserved >= :quantity
RETURNING variant_id, reserved;

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

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

Освобождение просроченного резерва также делайте однократным. Два фоновых обработчика не должны вернуть одну футболку на склад дважды. Проверяйте текущее состояние резерва и переводите его в новое состояние вместе с корректировкой остатка.

Оплата — отдельный разговор

Для физических товаров Telegram предлагает интеграцию с платёжными провайдерами; доступность конкретного провайдера и способы оплаты нужно проверять для вашего бизнеса. Общая схема приведена в документации Bot Payments. Выбор VPS сам по себе не подключает магазин к эквайрингу.

Не переносите эту схему автоматически на цифровые товары и услуги: внутри Telegram для них действуют правила платежей в Stars. Тип товара нужно определить до проектирования оплаты, а не после готовой интеграции.

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

Продумайте поздний платёж: деньги пришли, когда резерв уже истёк. Не ставьте автоматически отметку «готов к отправке». Сначала проверьте возможность исполнения, затем примените заранее объявленный порядок: новый резерв, согласование замены или возврат.

Повторное нажатие не означает второй заказ

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

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

На экране после подтверждения показывайте номер заказа и состояние, полученное из базы. При восстановлении связи приложение должно уметь запросить этот заказ. Не оставляйте человека один на один с бесконечной анимацией и догадкой, стоит ли уже звонить в магазин.

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

Возвраты и отмены проверяют зрелость магазина

Пилот часто тестируют только по счастливому маршруту: выбрали, оплатили, получили. Но первая отмена быстро обнаруживает, где в системе вместо правил была надежда.

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

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

Репетиция перед первым покупателем

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

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

Сделайте восстановление базы на отдельном сервере. После него должны сохраниться не только товары, но и связи заказов, резервов, платежей и событий. Копия фотографий полезна, однако сама по себе не восстановит магазин.

Какой VPS выбрать для такого каталога

Для небольшого пилота с API, PostgreSQL и умеренным каталогом разумно проверить Uab Start: 2 vCPU, 4 ГБ памяти и 80 ГБ диска. Если одновременно работают импорт, обработка изображений и дополнительные интеграции, начальной точкой испытаний может стать Heka Standard с 4 vCPU и 8 ГБ памяти.

На VPS MAATRIX магазин разворачивается как самостоятельное приложение. Выберите поддерживаемую вашей сборкой ОС, например Ubuntu 24.04, закройте базу от публичного доступа и настройте отдельные резервные копии. Диск рассчитывайте с учётом изображений, журналов и временных файлов импорта.

Расширять сервер лучше по измерениям: время оформления, задержка синхронизации остатков, нагрузка базы и длина очереди. Самая дорогая ошибка маленького магазина обычно не недостаток процессорных ядер, а уверенно проданная вещь, которой уже нет.