ВАЖНО:

Данный раздел только если вы создали веб модуль в рамках БОТТ

99% случаев вам не подойдет этот раздел и используйте документацию с публичными ключами

Веб-модули BOT-T — инструкция для разработчиков

Документация для авторов внешних веб-модулей: как подключить модуль к платформе, какие endpoint'ы реализовать на своём сервере и какие запросы отправлять в API BOT-T.

Два раздела интеграции

Раздел	Кто инициатор	Базовый URL	Назначение
Административные запросы	BOT-T → ваш сервер	URL типа модуля (`web_module_type.url`)	Подключение, настройки, удаление, смена ключа
Запросы из API	ваш модуль → BOT-T	`https://api.bot-t.com`	Данные бота, пользователей, баланс, магазин, рефералы

Ключи и авторизация

public_key (публичный ключ)

Идентификатор конкретного экземпляра модуля, привязанного к боту.
Генерируется BOT-T при подключении модуля (хеш от bot_id и type_id типа модуля).
Не секрет — можно передавать в URL страницы модуля и в публичных API-методах.
В ссылке на веб-страницу модуля передаётся в query вместе с bot_id:

https://ваш-хост-модуля/?bot_id=1&public_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

private_key (приватный ключ)

Секрет сервера модуля. Генерируется BOT-T (хеш от bot_id, type_id и токена бота).
Храните только на backend модуля. Не передавайте в браузер, мобильное приложение и публичный JS.
Обязателен вместе с public_key для:
- административных запросов get, update, delete, rotatePrivateKey;
- приватных методов API BOT-T (баланс, пользователи, Bot API, заказы и т.д.).
При компрометации — перевыпуск через rotatePrivateKey (см. ниже).

secret_key (секрет пользователя бота)

Отдельный от ключей модуля. Идентифицирует конкретного пользователя бота в контексте модуля.
Выдаётся в ответах API пользователя (secret_user_key в объекте пользователя) или формируется после авторизации через Telegram Web App (check-hash).
Нужен для операций от имени пользователя: списание/начисление баланса, создание заказа, вывод средств и т.п.
Передаётся в теле запроса вместе с user_id (Telegram ID пользователя).

Сводка по методам API BOT-T

Уровень доступа	Поля в запросе
Публичный (только модуль)	`public_key` (+ иногда `type_id`)
Приватный (сервер модуля)	`public_key` + `private_key`
От имени пользователя	`public_key` (+ `private_key` где требуется) + `user_id` (Telegram ID) + `secret_key`

Жизненный цикл модуля

sequenceDiagram
    participant LK as ЛК владельца бота
    participant BOT as BOT-T
    participant MOD as Сервер модуля

    LK->>BOT: Подключить модуль к боту
    BOT->>MOD: GET ping
    MOD-->>BOT: result=true, data=OK
    BOT->>MOD: GET create (bot_id, public_key, private_key)
    MOD-->>BOT: result=true, data=настройки
    BOT->>BOT: Сохранить ключи и настройки

    Note over LK,MOD: Эксплуатация
    MOD->>BOT: POST /v1/module/... (API)
    LK->>BOT: Изменить настройки
    BOT->>MOD: POST update
    MOD-->>BOT: result=true, data=настройки

    LK->>BOT: Удалить модуль
    BOT->>MOD: GET delete (public_key, private_key)
    MOD-->>BOT: result=true
    BOT->>BOT: Удалить запись модуля

Часть 1. Административные запросы (ваш сервер)

Реализуйте на сервере модуля. BOT-T обращается к ним автоматически.

Базовый URL — значение поля URL типа модуля в каталоге BOT-T (без изменений со стороны разработчика модуля при регистрации типа). К URL добавляется имя действия:

Действие	Метод	Пример полного URL
ping	GET	`{url}ping`
create	GET	`{url}create?bot_id=...&public_key=...&private_key=...`
get	GET	`{url}get?public_key=...&private_key=...`
update	POST	`{url}update?public_key=...&private_key=...`
delete	GET	`{url}delete?public_key=...&private_key=...`
rotatePrivateKey	GET	`{url}rotatePrivateKey?public_key=...&private_key=...&new_private_key=...`

Общие требования к ответам

HTTP-код 200.
Заголовок Content-Type: application/json.
Тело — JSON:

{ "result": true, "data": ... }

{ "result": false, "message": "текст ошибки" }

При result: false BOT-T считает операцию неуспешной и показывает message пользователю.

GET ping

Когда вызывается: перед созданием экземпляра модуля (проверка, что сервер доступен).

Параметры: нет.

Успешный ответ: в поле data должна быть строка OK (именно так, без пробелов и лишних символов).

{ "result": true, "data": "OK" }

GET create

Когда вызывается: один раз при подключении модуля к боту.

Query-параметры:

Параметр	Описание
`bot_id`	ID бота в BOT-T
`public_key`	Публичный ключ, сгенерированный BOT-T
`private_key`	Приватный ключ, сгенерированный BOT-T

Задача модуля: создать запись экземпляра (привязка bot_id + ключи) и вернуть начальные настройки в data.

Обязательные поля в data:

Поле	Описание
`id`	ID экземпляра на стороне модуля
`version`	Версия схемы настроек (целое число)
`bot_id`	Должен совпадать с переданным
`public_key`	Должен совпадать с переданным
`private_key`	Должен совпадать с переданным

Дополнительно можно вернуть произвольные поля конфигурации (например balance, category_id). BOT-T сохранит их без bot_id, public_key, private_key.

Пример успешного ответа:

{
  "result": true,
  "data": {
    "id": 1,
    "version": 1,
    "bot_id": 42,
    "public_key": "a1b2c3...",
    "private_key": "f0e1d2...",
    "balance": 0
  }
}

GET get

Когда вызывается: синхронизация настроек из ЛК («получить с сервера»).

Query-параметры: public_key, private_key.

Ответ: объект настроек в том же формате, что при create (с обязательными полями id, version, bot_id, public_key, private_key).

POST update

Когда вызывается: сохранение настроек из ЛК.

Query-параметры: public_key, private_key.

Тело: application/x-www-form-urlencoded — пары «ключ → значение» настроек (без bot_id, public_key, private_key в теле).

Ответ: полный актуальный объект настроек в data.

GET delete

Когда вызывается: удаление модуля из бота в ЛК.

Query-параметры: public_key, private_key.

Задача модуля: удалить данные экземпляра на своей стороне.

Ответ: достаточно { "result": true }. Поле data необязательно.

GET rotatePrivateKey

Когда вызывается: перевыпуск приватного ключа из админки BOT-T.

Query-параметры:

Параметр	Описание
`public_key`	Текущий публичный ключ
`private_key`	Текущий приватный ключ
`new_private_key`	Новый ключ (сгенерирован BOT-T)

Задача модуля: атомарно заменить private_key в своей БД.

Ответ:

{ "result": true }

Часть 2. Запросы из API (BOT-T)

Базовый URL: https://api.bot-t.com

Метод: все перечисленные endpoint'ы — POST.

Заголовки:

Content-Type: application/json

Допускается также application/x-www-form-urlencoded для части методов (см. Swagger).

Формат ответа:

{ "result": true, "data": ... }

{ "result": false, "message": "текст ошибки" }

Лимит: 120 запросов в минуту с одного IP.

Сводная таблица endpoint'ов

URL	Авторизация	Назначение
`POST /v1/module/bot/get-by-public-key`	`type_id`, `public_key`	Данные бота по публичному ключу модуля
`POST /v1/module/bot/check-hash`	`bot_id`, `userData`	Проверка Telegram Web App / Login и получение пользователя
`POST /v1/module/user/check-secret`	ключи модуля + `id` (tg), `secret_key`	Проверка secret_key пользователя
`POST /v1/module/user/get`	ключи модуля + `id` (telegram_id)	Пользователь бота по Telegram ID
`POST /v1/module/user/get-creator`	`public_key`, `private_key`	Пользователь-создатель бота
`POST /v1/module/user/add-balance`	ключи + `user_id`, `secret_key`, `amount`, `comment`	Начисление баланса
`POST /v1/module/user/subtract-balance`	ключи + `user_id`, `secret_key`, `amount`, `comment`	Списание баланса
`POST /v1/module/user/send-request`	ключи + `user_tg_id`, `method`, `params`	Вызов метода Telegram Bot API
`POST /v1/module/shop/order-create`	ключи + `user_id`, `secret_key`, `amount`, `count`, `category_id`, `product`	Создание заказа магазина
`POST /v1/module/shop/send-request`	ключи + `order_id`, `method`, `params`	Bot API для чата заказа
`POST /v1/module/replenishment/create-conclusion`	`public_key` + `user_id`, `secret_key`, `amount`	Заявка на вывод баланса
`POST /v1/module/referral/get-by-public-key`	`type_id`, `public_key`	Настройки реферальной системы
`POST /v1/module/referral/withdrawal-history`	`public_key` + `user_id`, `secret_key`, `limit`, `offset`	История заявок на вывод

Бот

POST /v1/module/bot/get-by-public-key

Получить информацию о боте, к которому привязан модуль.

Поле	Тип	Обяз.	Описание
`type_id`	integer	да	ID типа модуля в каталоге BOT-T
`public_key`	string	да	Публичный ключ экземпляра

POST /v1/module/bot/check-hash

Авторизация пользователя через данные Telegram (Web App, Login Widget).

Поле	Тип	Обяз.	Описание
`bot_id`	integer	да	ID бота
`userData`	string	да	Строка query-параметров от Telegram (с `hash`)
`bot_clone_id`	integer	нет	ID клона бота, если используется

Ответ: объект пользователя бота (BotUserDto), включая secret_user_key для последующих запросов.

Пользователи

POST /v1/module/user/get

Поле	Тип	Обяз.	Описание
`id`	integer	да	Telegram ID пользователя
`public_key`	string	да
`private_key`	string	да

POST /v1/module/user/check-secret

Проверка, что переданный secret_key соответствует пользователю.

Поле	Тип	Обяз.	Описание
`id`	integer	да	Telegram ID
`secret_key`	string	да
`public_key`	string	да
`private_key`	string	да

POST /v1/module/user/get-creator

Данные владельца/создателя бота. Только ключи модуля.

POST /v1/module/user/add-balance / subtract-balance

Поле	Тип	Обяз.	Описание
`public_key`	string	да
`private_key`	string	да
`user_id`	integer	да	Telegram ID
`secret_key`	string	да
`amount`	number	да	Сумма в минимальных единицах (копейки)
`comment`	string	нет	Комментарий к операции

Ответ: обновлённый BotUserDto (поле money — в копейках).

POST /v1/module/user/send-request

Прокси к Telegram Bot API от имени бота модуля.

Поле	Тип	Обяз.	Описание
`public_key`	string	да
`private_key`	string	да
`user_tg_id`	integer	да	Telegram ID получателя
`method`	string	да	Имя метода Bot API (например `sendMessage`)
`params`	object	да	Параметры метода; `chat_id` подставится автоматически

Ответ: { "response": { ... } } — ответ Telegram.

Магазин

POST /v1/module/shop/order-create

Поле	Тип	Обяз.	Описание
`public_key`	string	да
`private_key`	string	да
`user_id`	integer	да	Telegram ID
`secret_key`	string	да
`amount`	number	да	Сумма заказа
`count`	integer	да	Количество
`category_id`	integer	да	ID категории/товара
`product`	string	да	Название/описание товара

POST /v1/module/shop/send-request

Поле	Тип	Обяз.	Описание
`public_key`	string	да
`private_key`	string	да
`order_id`	integer	да	ID заказа
`method`	string	да	Метод Bot API
`params`	object	да	Параметры метода

Вывод средств и рефералы

POST /v1/module/replenishment/create-conclusion

Создание заявки на вывод. Только public_key (без private_key).

Поле	Тип	Обяз.	Описание
`public_key`	string	да
`user_id`	integer	да	Telegram ID
`secret_key`	string	да
`amount`	integer	да	Сумма списания в копейках

Требуется включённая в боте система выводов с обратной связью (feedback).

POST /v1/module/referral/get-by-public-key

Поле	Тип	Обяз.	Описание
`type_id`	integer	да
`public_key`	string	да

Ответ: referral_id, is_active, bonus_source, levels[] с процентами.

POST /v1/module/referral/withdrawal-history

Поле	Тип	Обяз.	Описание
`public_key`	string	да
`user_id`	integer	да	Telegram ID
`secret_key`	string	да
`limit`	integer	нет	По умолчанию 20, макс. 100
`offset`	integer	нет	Пагинация

Объект пользователя бота (BotUserDto)

Ключевые поля для интеграции:

Поле	Описание
`id`	ID пользователя в контексте бота
`user.telegram_id`	Telegram ID
`money`	Баланс в копейках (делить на 100 для отображения)
`secret_user_key`	Секрет для запросов от имени пользователя (`secret_key` в API)
`status`	Статус пользователя (активен, бан и т.д.)

Типичные ошибки

Ситуация	Что проверить
Модуль не подключается	`ping` возвращает `data: "OK"`, URL типа модуля доступен с серверов BOT-T
«public_key not found» / «private_key not found»	Поля переданы в теле POST (JSON)
«secret key not valid»	`secret_key` соответствует Telegram ID и боту; пользователь есть в боте
create отклонён	В ответе `data` совпадают `bot_id`, `public_key`, `private_key` с query
429 / лимит	Не более 120 запросов/мин к `/v1/module/*` с одного IP

Чек-лист перед публикацией типа модуля

Реализованы ping, create, get, update, delete, rotatePrivateKey
Все административные ответы — JSON, HTTP 200, поле result
create возвращает обязательные поля настроек
Ключи модуля хранятся на backend, не утекают в клиент
Авторизация пользователя через check-hash или check-secret
Запросы к API BOT-T идут с сервера по HTTPS
Обработаны ошибки result: false и показ сообщений пользователю

WEB модули

Веб-модули BOT-T — инструкция для разработчиков

Два раздела интеграции

Ключи и авторизация

public_key (публичный ключ)

private_key (приватный ключ)

secret_key (секрет пользователя бота)

Сводка по методам API BOT-T

Жизненный цикл модуля

Часть 1. Административные запросы (ваш сервер)

Общие требования к ответам

GET ping

GET create

GET get

POST update

GET delete

GET rotatePrivateKey

Часть 2. Запросы из API (BOT-T)

Сводная таблица endpoint'ов

Бот

POST /v1/module/bot/get-by-public-key

POST /v1/module/bot/check-hash

Пользователи

POST /v1/module/user/get

POST /v1/module/user/check-secret

POST /v1/module/user/get-creator

POST /v1/module/user/add-balance / subtract-balance

POST /v1/module/user/send-request

Магазин

POST /v1/module/shop/order-create

POST /v1/module/shop/send-request

Вывод средств и рефералы

POST /v1/module/replenishment/create-conclusion

POST /v1/module/referral/get-by-public-key

POST /v1/module/referral/withdrawal-history

Объект пользователя бота (BotUserDto)

Рекомендации по безопасности

Типичные ошибки

Чек-лист перед публикацией типа модуля