WebApp «Магазин» (cat_shop)

cat_shop — готовое мини-приложение Квесчи для интернет-магазина прямо в Telegram/MAX. Подписчик открывает каталог в окне мессенджера, выбирает товары, кладёт в корзину, оформляет заказ — и возвращается в бот для оплаты.

В отличие от обычных блоков, где каталог из 30 товаров превращается в 30 экранов, cat_shop показывает всё на одном экране: фильтры, поиск, корзина, оформление.

Когда использовать

• Розничный магазин: одежда, косметика, электроника, мерч.
• Услуги-пакеты: «фотосессия 1 час / 2 часа / целый день».
• Цифровые товары: курсы, шаблоны, лицензии.
• Подарочные сертификаты.

Когда не использовать:

• 1-3 товара — проще обычные кнопки в блоках;
• сложные конфигураторы (выбор цвета → размера → опций по матрице) — нужен кастом;
• B2B с индивидуальными ценами — нужен индивидуальный механизм.

---

Часть 1. Настройка магазина

Шаг 1. Создайте приложение

Раздел Списки / WebApp → Добавить приложение каталога → выберите вкладку «Настройки» (cat_shop).

Заполните настройки приложения:

• Название — заголовок над настройками;
• Токен бота — для запуска не из кнопки под сообщением;
• Дизайн — выбор дизайна приложения;
• Элементы — тексты и цвета магазина;
• Поиск — настройка поиска и фильтров приложения;
• Рубрики — добавление рубрик;
• Размеры товаров — размеры для всего ассортимента каталога;
• Цвета — цвета для всего ассортимента каталога.

Скриншот 1. Настройка приложения.

Шаг 2. Добавьте товары в каталог

Списки / WebApp → Создайте каталог в настройках приложения на вкладке «Товары»:

Поле	Содержимое
title	Название товара
description	Полное описание
descrmin	Краткое описание (для карточки в списке)
price	Цена
oldprice	Старая цена (зачёркнутая)
size	Размеры (через запятую)
color	Цвета (через запятую)
code	Артикул
image	URL картинки
category	Категория для фильтра
stock	Остаток (опционально)

Скриншот 2. Каталог магазина.

Шаг 3. Подключите к Telegram (опционально)

Telegram Mini-App нужно зарегистрировать у @BotFather:

1. /mybots → выберите бот → Bot Settings → Menu Button.
2. Укажите URL вашего WebApp (показывается в Квесче после создания).
3. Опционально: настройте кнопку меню в углу окна.

---

Часть 2. Добавление кнопки WebApp в сценарий

В блоке, откуда хотите запускать магазин — создайте кнопку:

• Тип кнопки — Ссылка;
• Название — «🛒 Каталог», «Магазин»;
• Ссылка — скопируйте и вставьте ссылку из приложения.

Скриншот 3. Кнопка запуска cat_shop в блоке.

Альтернативы:

• Menu Button Telegram — кнопка постоянно в углу окна чата.

---

Часть 3. Обработка заказа в сценарии действий

После того как клиент оформил заказ в WebApp, он возвращается в бот. Текущий блок получает ответ webapp:catalog — по этому маркеру можно ветвить.

Шаг 1. Создайте блок-приёмник

Сразу после кнопки WebApp поставьте блок «Обработка заказа». В нём:

• Сценарий действий «До отправки» → действие «WebApp/MiniApp» → операция «Каталог: обработка заказа».

Шаг 2. Сохраните данные заказа в переменные

В операции укажите имена переменных, куда сохранять:

Переменная	Что попадает
Список заказа (orderlist)	Готовая строка со списком товаров для отправки клиенту
Сумма заказа (totalsum)	Общая сумма
ID заказа (orderId)	Сгенерированный уникальный ID
Наличие заказа (isorder)	1 — есть заказ, 0 — корзина пуста

Скриншот 4. Переменные после операции «Каталог: обработка заказа».

Шаг 3. Системные переменные

Дополнительно создаются автоматически:

• ItemsID — массив ID товаров. Передайте в платёжную ссылку под этим же именем, если хотите списания остатков.
• ItemsCount — количество разных позиций в заказе.

Шаг 4. Массивы для сохранения в список «Заказы»

Если нужно записать каждую позицию заказа отдельной строкой — используйте поля массивов:

Массив	Содержит
Наименования (title)	Названия каждого товара
Описания (description)	Полные описания
Краткие описания (descrmin)	Короткие описания
Цены (price)	Цена за единицу
Старые цены (oldprice)	Зачёркнутые цены
Размеры (size)	Выбранный размер
Цвета (color)	Выбранный цвет
Артикулы (code)	Артикул товара
Заказанное количество (count)	Сколько штук
Суммы заказа по каждому товару (sum)	Цена × количество

Все эти переменные — массивы. Для записи в список используйте перебор массива в «Операциях с данными».

---

Часть 4. Типовой сценарий

Полный цикл «открыть → заказать → оплатить»

Блок 1. Приветствие
   ↓ кнопка WebApp «🛒 Каталог»
   (открывается cat_shop)
   ↓ ответ webapp:catalog
Блок 2. Обработка заказа
   - Сценарий действий «До»:
     - Действие WebApp/MiniApp → cat_order
       → переменные: orderlist, totalsum, orderId, isorder
     - Условие: #{isorder} = 1 → продолжить, иначе блок «Корзина пуста»
     - Операция «Список» → «Заказы» → addrow:
       поля: ClientID, orderId, title (массив), count (массив), sum (массив), totalsum
     - Действие «Платежи» → getlink → переменная pay_link
   - Сообщение: «Ваш заказ:
       #{orderlist}
       
       Сумма к оплате: #{totalsum} ₽»
   - Кнопка-ссылка «Оплатить»: URL = #{pay_link}
   ↓ после оплаты
Блок 3. «Спасибо!» (запускается цепочкой приёма платежа)

---

Часть 5. Проверка ответа webapp:catalog

Если WebApp открывается не из кнопки текущего блока, а из:

• кнопки меню (Menu Button) Telegram;
• кнопки клавиатуры —

клиент может оказаться в любом блоке сценария. Чтобы ловить возврат из WebApp везде:

1. В каждом блоке-вопросе, где может прерваться диалог, настройте условие перехода на ответ webapp:catalog.
2. Условие истинно — направьте на блок «Обработка заказа».

Так клиент попадёт в обработку, на каком бы шаге ни был.

Скриншот 5. Условный переход по ответу webapp:catalog.

---

Часть 6. Продвинутые сценарии

Сценарий 1. Списания остатков

1. В товарах списка добавьте поле stock.
2. В действии «Платежи» в дополнительных данных передайте ItemsID = #{ItemsID} — Квесча знает, какие товары списать.
3. После успешной оплаты остатки автоматически уменьшаются.

Сценарий 2. Промокоды

1. Создайте глобальную переменную g_promo = WELCOME10, g_promo_percent = 10.
2. До генерации платёжной ссылки сделайте: переменная final_sum = {{ #{totalsum} * (1 - #{g_promo_percent} / 100) }}.
3. В блоке «Сумма со скидкой #{g_promo_percent}%: #{final_sum} ₽».

Сценарий 3. Уведомление менеджеру

1. В сценарии действий «После отправки» блока «Спасибо за заказ» добавьте действие HTTP или отправку в Telegram-канал.
2. Передайте: Новый заказ #{orderId} на #{totalsum} ₽ от [Name] ([ClientID]). Состав: #{orderlist}.

Сценарий 4. Брошенная корзина

1. После открытия WebApp ставьте тег был-в-каталоге.
2. После оформления заказа снимайте этот тег, ставьте купил.
3. Цепочка «Дожим» (триггер: тег был-в-каталоге, шаг через 1 день): «Не передумали? Ваша корзина ждёт».

---

Часть 7. Архитектура

Принцип 1. Один «Каталог» = один WebApp

Если у вас два магазина (например, мужской и женский) — сделайте два WebApp с разными настройками.

Принцип 2. История заказов в отдельном списке

Заведите список «Заказы» с полями ClientID, orderId, totalsum, status, created_at. По нему стройте «Мои заказы».

Принцип 3. ID товара важнее имени

При работе с остатками опирайтесь на ItemsID, а не на title. Имя клиент может видеть, но логика — по ID.

Принцип 4. Не передавайте чувствительные данные

В URL WebApp может попасть в логи. Не передавайте через URL пароли, паспорта, токены.

Принцип 5. Тестируйте на мобильном

WebApp оптимизирован под телефон. Смотрите в десктоп-Telegram — но финальные проверки на iOS/Android.

---

Частые ошибки

• Каталог открывается пустым — список товаров не выбран в настройках WebApp, или товары без поля title.
• Цены неверные — проверьте, что в поле price число без пробелов и валюты, валюта задаётся в настройках WebApp.
• #{orderlist} пустая — забыли указать имя переменной в действии «Каталог: обработка заказа».
• Платёжная ссылка генерируется, но не на ту сумму — totalsum не подставилось. Проверьте, что действие WebApp/MiniApp идёт до действия «Платежи» в том же сценарии.
• Списания остатков не происходит — не передан ItemsID в дополнительных данных платежа.
• Изображения товаров отсутствуют — загрузите изображения в каталог приложения (картинки заканчиваются на .jpg/.png/.webp).

---

Что дальше

• WebApp Кафе (cat_cafe) — каталог для общепита.
• WebApp Календарь (calendar) — запись на услуги.
• Платежи — приём оплат после WebApp.
• Списки — каталог и история заказов.
• Цепочки — дожим, оплата, доставка.