Обзор системы
Панель управления LUXEMBURG предназначена для администрирования магазина мгновенных продаж. Система работает в трёх режимах одновременно: Telegram-боты для покупателей, веб-витрины (сайты), и инструменты для курьеров по загрузке адресов.
Основные компоненты
| Компонент | Назначение |
|---|---|
| Telegram-бот | Основной канал продаж. Покупатель проходит через бота: капча, выбор языка, города, товара, оплата, получение адреса. |
| Веб-витрина | Сайт для покупок. Доступен по адресу /s/slug. Работает независимо от бота с собственными настройками валюты и темы. |
| Курьерский бот | Отдельный бот (или команда /worker в основном боте) через который курьер загружает адреса кладок. |
| Панель управления | Текущий интерфейс. Доступ по роли: администратор видит всё, менеджер — без финансовых настроек, курьер — только адреса. |
Жизненный цикл заказа
Быстрый старт: с нуля до первой продажи
Боты
Боты — основной канал продаж. Один магазин может работать через несколько ботов одновременно. Каждый бот может быть настроен под отдельную страну с собственной валютой и языком.
Типы ботов
| Тип | Назначение |
|---|---|
| Продавец | Основной бот для покупателей. Полный цикл: каталог, оплата, получение адреса. |
| Распределитель | Технический бот. Отправляет покупателей на один из активных ботов-продавцов, чтобы не "светить" один токен. При блокировке основного бота — уведомляет о замене. |
Настройки бота
- Токен — получается в @BotFather. Можно вставить несколько токенов (по одному на строку) для массового добавления.
- Валюта бота — определяет в какой валюте отображается баланс покупателя и производятся расчёты пополнения. Должна совпадать с валютой товаров для данного бота.
- Язык по умолчанию — язык интерфейса для новых пользователей, у которых Telegram-клиент не определил поддерживаемый язык.
- Приветственное сообщение — текст при входе. Поддерживается HTML-форматирование: жирный, курсив, подчёркнутый.
- Капча — защита от спам-регистраций. При отключении бот пропускает проверку.
Кнопки главного меню
В разделе "Ссылки в кнопках главного меню" задаются URL для трёх кнопок, которые видит покупатель: Оператор (ссылка на чат поддержки), Сайт (ссылка на веб-витрину), Работа (ссылка для рекрутинга курьеров).
TG-аккаунты: автоматическое создание ботов
Раздел TG-аккаунты позволяет создавать Telegram-ботов без BotFather — через загрузку сессии реального Telegram-аккаунта. Система автоматически зарегистрирует бота от имени этого аккаунта.
Что такое TData-сессия
TData — это папка с файлами авторизации Telegram Desktop. Когда вы входите в Telegram Desktop на своём компьютере, создаётся папка tdata. Загрузив её в систему, вы позволяете серверу действовать от имени этого аккаунта и автоматически создать бота через @BotFather.
Создание бота через TG-аккаунт
Альтернатива: StringSession
Если нет доступа к папке tdata (например, используется Telegram на телефоне) — можно экспортировать строку сессии из Telegram через сторонние инструменты (например Pyrogram или Telethon) и загрузить её в виде текстового файла.
Безопасность
- Загруженная сессия хранится на сервере в зашифрованном виде. Ключ шифрования задаётся в переменной среды CRYPTO_ENCRYPTION_KEY.
- После создания бота рекомендуется завершить сессию аккаунта через Telegram (Настройки — Устройства — Завершить сеанс) чтобы файл сессии больше не давал доступ к аккаунту.
- Никогда не загружайте сессию основного личного аккаунта. Используйте отдельный аккаунт специально для создания ботов.
Распределитель ботов
После создания нескольких ботов-продавцов можно создать бот-распределитель. Покупатель пишет в бот-распределитель и получает ссылку на один из активных ботов-продавцов — это позволяет скрыть основной канал и снизить риск блокировки. При блокировке одного из ботов-продавцов распределитель автоматически перестаёт его предлагать.
Веб-витрины
Витрина — это отдельный сайт-магазин. Покупатель открывает его в браузере, регистрируется, выбирает товар и платит криптовалютой. Каждая витрина доступна по адресу вашего_домена/s/slug.
Создание витрины
Настройки внешнего вида
- Акцент-цвет 1 и 2 — цвета кнопок и акцентов. Можно задать градиент из двух цветов с углом.
- Цвет фона — фоновый цвет страницы. Превью показывает результат до сохранения.
- Тема — тёмная или светлая. Влияет на цвет текста, карточек и фонов по умолчанию.
- Баннеры — слайдер на главной странице. Можно добавить несколько изображений с заголовками.
- Объявление — полоса уведомления вверху страницы (акции, важные сообщения).
Режимы работы витрины
| Режим | Поведение |
|---|---|
| Активна | Витрина работает в штатном режиме. |
| Тех. работы | Покупатель видит сообщение о техническом обслуживании. Новые заказы не принимаются. |
Товары и фасовки
Товары организованы в группы. Каждый товар имеет одну или несколько фасовок (вариантов) — это конкретное предложение с весом, количеством и ценой.
Структура каталога
Группа товаров (например: Шишки) — Товар (например: Amnesia Haze) — Фасовка (например: 1 г. за 2000 ₽, 3 г. за 5000 ₽).
Создание товара
- Название — отображается покупателю в боте и на сайте.
- Вес/количество и единица измерения — граммы, штуки или миллилитры. Эта информация образует название фасовки (например: "1 г.").
- Цена и валюта — валюта фасовки определяет в чём выражена цена и по какому курсу конвертируется в крипту при оплате.
- Фотография — загружается файлом, показывается в боте и на витрине.
Предзаказ
Если для фасовки нет адресов на складе, но спрос есть — можно включить предзаказ. Покупатель платит сейчас, адрес получает позже когда товар поступит. При включении предзаказа для товара в карточке появляется отдельный вариант с пометкой "Предзаказ".
Цены по городам
Можно задать разную цену для конкретного города. Например, товар стоит 2000 ₽ по умолчанию, но для Тбилиси — 50 ₾. Покупатель в Тбилиси увидит цену в лари, покупатель в Москве — в рублях.
Склад и адреса
Адреса — это физические точки (кладки, тайники), которые продаются покупателям после оплаты. Каждый адрес привязан к конкретному товару-фасовке и географическому району.
Структура склада
Адрес всегда привязан к: Фасовка + Район (который входит в Город, который входит в Регион). Покупатель при выборе города и товара видит только те товары и города, для которых есть свободные адреса.
Статусы адресов
| Статус | Значение |
|---|---|
| Свободен | Адрес готов к продаже. Доступен покупателям. |
| Зарезервирован | Ожидание оплаты. Покупатель выбрал товар и оплачивает. Другие покупатели этот адрес не видят. |
| Продан | Передан покупателю. Учитывается в статистике. |
| Не найден | Адрес оказался недействительным (помечается курьером или по жалобе покупателя). |
Добавление адресов через панель управления
Раздел Склад — Адреса — нажать "Добавить адрес". Выбрать город, район (список фильтруется по городу), товар, тип кладки и ввести текст адреса. Фотографию можно добавить опционально.
Курьеры
Курьер — сотрудник, который физически размещает адреса и загружает их в систему. У каждого курьера есть логин/пароль для входа в панель управления и в курьерский бот.
Создание курьера
- Раздел Сотрудники — Курьеры — кнопка "Добавить".
- Задать имя, логин, пароль. Пароль можно сгенерировать автоматически.
- Выбрать разрешённые города и разрешённые товары через чекбоксы. Если ничего не выбрано — курьер видит всё. Если выбраны конкретные города — он работает только с ними.
Ставки ЗП
Для каждого курьера можно настроить ставку вознаграждения за один проданный адрес. Ставку можно задать как универсальную (для всех товаров/городов), так и специфическую для конкретного товара и/или города. При приоритете выбирается наиболее конкретная ставка.
Загрузка адресов через курьерский бот
Покупки и заказы
Раздел Покупки отображает все завершённые и активные заказы. Каждый заказ содержит: клиент, товар, сумма, статус, адрес (если назначен), дата.
Статусы заказов
| Статус | Значение |
|---|---|
| Pending | Ожидание оплаты. Заказ создан, но оплата ещё не поступила. |
| Paid | Оплачен. Адрес передан покупателю. |
| Delivered | Доставлен (для предзаказов — адрес назначен после поступления товара). |
| Disputed | Открыт диспут. Средства заморожены до решения. |
| Cancelled | Отменён. Средства возвращены на баланс клиента. |
Методы оплаты
Система поддерживает два типа оплаты: криптовалюта и банковский перевод (фиат). Методы включаются/отключаются в разделе Настройки.
Криптовалюта
Для каждого криптоплатежа система генерирует уникальную сумму (с незначительным солевым отклонением), чтобы идентифицировать транзакцию среди других. Покупатель получает адрес кошелька и точную сумму для перевода.
| Сеть | Авто-детект | Особенности |
|---|---|---|
| BTC (Bitcoin) | Автоматически | Проверяется через Blockchair API. Точность — 8 знаков после запятой. Транзакция обнаруживается при появлении в мемпуле, без ожидания блока. |
| USDT TRC-20 | Автоматически | Проверяется через TronGrid API. Сумма округлена до 2 знаков с уникальным "центом" (например 12.08 USDT). Биржи иногда округляют иначе — если авто не сработало, попросите клиента нажать "Проверить оплату". |
| XMR (Monero) | Только вручную | Monero — полностью анонимная сеть. Публичный блокчейн-эксплорер не позволяет проверить суммы без приватного view key. Система не может автоматически подтвердить XMR-платёж. |
Авто-детект платежей (BTC, USDT)
Система проверяет блокчейн каждые 20 секунд. Если транзакция найдена с точным совпадением суммы — оплата подтверждается автоматически. Если авто-детект не сработал (задержка блокчейна, округление биржи) — покупатель может нажать кнопку "Проверить оплату" вручную.
Банковские переводы
Реквизиты добавляются в разделе Кошельки — вкладка "Банки". Для каждого реквизита выбирается тип (карта или перевод по телефону) и валюта. Покупателю автоматически показываются реквизиты, соответствующие валюте его товара.
Кошельки
Раздел содержит два типа: криптовалютные адреса для приёма платежей и банковские реквизиты для фиатных переводов.
Крипто-кошельки
Каждый добавленный адрес — это адрес в блокчейне куда поступают средства от покупателей. В боковой панели отображается суммарный объём всех подтверждённых поступлений за всё время (в $).
Банки и реквизиты
В разделе "Банки" добавляются реквизиты для фиатных платежей. При каждом банке указывается: название банка, тип (карта или перевод), номер карты или телефон, имя держателя, валюта. Покупатель видит реквизиты только для своей валюты.
Пополнения
Раздел Пополнения показывает все попытки пополнения баланса: от клиентов через бота и от сайта. Включает как криптоплатежи, так и фиатные переводы (ожидающие подтверждения).
Статусы пополнений
| Статус | Значение |
|---|---|
| Ожидание | Счёт выставлен, платёж не получен. Действует 30 минут. |
| В сети | Транзакция найдена, ожидание подтверждений сети. |
| Подтверждён | Платёж получен, баланс клиента пополнен. |
| Истёк | Клиент не успел оплатить за 30 минут. |
Ручное пополнение
Администратор может вручную добавить средства на баланс клиента. В разделе Клиенты открыть клиента и нажать "Добавить баланс". Сумма вводится в валюте магазина.
Работа с валютами
В системе несколько уровней валюты, которые работают независимо друг от друга.
Уровни валюты
| Уровень | Где задаётся | На что влияет |
|---|---|---|
| Валюта бота | Боты — настройки бота | Отображение баланса и пополнений в боте. Курс конвертации при пополнении. |
| Валюта витрины | Витрины — настройки витрины | Отображение цен и итогов на сайте. Резервный символ если у товара нет price_currency. |
| Валюта фасовки | Товары — цена фасовки | Фактическая цена товара. Определяет курс CoinGecko для расчёта крипты. |
| Валюта банковских реквизитов | Кошельки — Банки | Фильтрация реквизитов для покупателя. Показываются только реквизиты в валюте товара. |
Сотрудники и роли
Система поддерживает несколько уровней доступа. Каждый сотрудник видит только те разделы, которые разрешены его ролью.
Роли
| Роль | Доступ |
|---|---|
| Администратор | Полный доступ ко всем разделам панели управления. |
| Менеджер | Покупки, товары, клиенты, аналитика, рассылки. Без доступа к финансовым настройкам, кошелькам, ботам. |
| Оператор | Покупки, клиенты, диспуты, техподдержка, промокоды. |
| Курьер | Только раздел Адреса и Диспуты. При входе автоматически перенаправляется на страницу адресов. |
Создание сотрудника
Диспуты
Покупатель открывает диспут когда недоволен заказом: адрес не найден, товар не соответствует описанию. Диспут замораживает заказ до решения администратора.
Работа с диспутами
Действия с диспутом
| Действие | Результат |
|---|---|
| Отправить сообщение | Сохраняет ответ и переводит статус в "На рассмотрении". Покупатель получает уведомление в Telegram. Диспут остаётся открытым. |
| Решить в пользу покупателя | Диспут закрывается как решённый. Покупатель уведомлён. |
| Отклонить | Диспут закрывается как отклонённый. Покупатель уведомлён. |
| Вернуть средства | Сумма заказа автоматически возвращается на баланс покупателя. Диспут закрывается. Покупатель уведомлён. |
Промокоды и маркетинг
Промокоды
Промокоды позволяют предоставить скидку на заказ. Покупатель вводит код при оформлении.
| Тип скидки | Пример |
|---|---|
| Процент | Код SALE10 — скидка 10% от суммы заказа. |
| Фиксированная сумма | Код BONUS500 — скидка 500 единиц в валюте товара. |
- Максимальное число использований — сколько раз код можно применить. После исчерпания лимита код перестаёт работать.
- Дата окончания — код автоматически перестаёт работать после указанной даты.
Рассылки
Раздел Рассылки позволяет отправить сообщение всем пользователям бота или сегменту. Поддерживается HTML-форматирование.
Настройки магазина
Основные параметры
- Название магазина — отображается в боте и в заголовке панели.
- Валюта магазина — глобальная валюта по умолчанию. Используется как резервная если у бота или витрины нет собственной валюты.
- Статус магазина — три режима: Активный (работает), На обслуживании (показывается сообщение, заказы не принимаются), Неактивный (доступ полностью закрыт).
Методы оплаты
Переключатели включают/отключают доступность конкретных методов для всех ботов и витрин. Отдельно настраивается: BTC, XMR, USDT TRC-20, банковская карта, перевод по телефону.
Реферальная программа
При включении реферальной программы покупатели могут делиться ссылками. Процент бонуса за привлечённого покупателя задаётся в настройках.
Языки бота
Задаёт список языков для ручного выбора. Если список пустой — покупатель видит все доступные языки. Если задан — только выбранные (например: только русский и грузинский).
Аналитика
Главная страница (Дашборд)
Показывает ключевые метрики: заказы и выручка за сегодня/неделю/месяц в долларовом эквиваленте, новые клиенты, открытые диспуты, ожидающие пополнения.
Графики покупки
Раздел Статистика — Графики покупки. Показывает разбивку по городам: количество заказов, выручку и остаток склада (свободно/в резерве/продано). Можно фильтровать по периоду (1/7/30 дней) и по конкретному городу. Также отображается топ продаваемых товаров.
История действий
Раздел История фиксирует все действия администраторов и сотрудников: создание/изменение/удаление товаров, адресов, ботов, витрин, закрытие диспутов, изменение настроек. Каждая запись содержит: имя сотрудника, тип действия, IP-адрес и время.