Документация для внешних разработчиков

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

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

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

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

Admin URL и host страницы модуля — разные адреса:

Назначение	Откуда берётся	Пример
Admin URL	URL типа модуля в каталоге BOT-T	`https://module.example.com/api/` — сюда идут `ping`, `create`, …
Host страницы	`default_host` типа / поле host экземпляра	`https://module.example.com/app` — сюда открывают пользователя

Admin URL должен заканчиваться на /: BOT-T склеивает путь без вставки слэша ({url}ping → https://module.example.com/api/ping).

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

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

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

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

private_key, secret_key, токен бота и Telegram ID в ссылку не передаются.

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`

Типичный flow Web App

sequenceDiagram
    participant User as Пользователь Telegram
    participant Page as Страница модуля
    participant ModBE as Backend модуля
    participant BOT as BOT-T API

    User->>Page: Открыл Web App / ссылку
    Note over Page: URL: host?bot_id=&public_key=
    Page->>Page: Telegram.WebApp.initData
    Page->>BOT: POST /v1/module/bot/check-hash
    BOT-->>Page: BotUserDto + secret_user_key
    Page->>ModBE: Запрос действия пользователя
    ModBE->>BOT: POST /v1/module/... с public_key + private_key + secret_key
    BOT-->>ModBE: result + data

Пользователь открывает {host}?bot_id={bot_id}&public_key={public_key}.
Фронтенд модуля читает Telegram.WebApp.initData.
POST /v1/module/bot/check-hash с bot_id и сырой строкой userData → пользователь и secret_user_key.
Дальнейшие операции с балансом, заказами и т.п. выполняет backend модуля: public_key + private_key + при необходимости user_id + secret_key.
private_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, data=true
    BOT->>BOT: Удалить запись модуля

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

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

Базовый URL — Admin 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-запросы BOT-T требует поле data. Без него подключение/удаление/синхронизация упадут с ошибкой. Для delete и rotatePrivateKey достаточно любого JSON-значения в data (например true).

Таймаут со стороны BOT-T: connect ~5 с, total ~20 с. Редиректы запрещены.

GET ping

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

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

Успешный ответ: в поле data должна быть строка OK (именно так, без пробелов и лишних символов). Сравнение строгое (!= '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 — пары «ключ → значение» настроек. В теле нет id, version, bot_id, public_key, private_key (BOT-T их не отправляет). Булевы значения приходят как 0 / 1.

Ответ: полный актуальный объект настроек в data (снова с обязательными полями, как у create).

GET delete

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

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

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

Ответ (рекомендуемый):

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

Поле data обязательно — иначе BOT-T отклонит успешный ответ.

GET rotatePrivateKey

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

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

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

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

Ответ (рекомендуемый):

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

Рекомендуется всегда возвращать data, чтобы формат ответов был единообразным.

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

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

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

Заголовки:

Content-Type: application/json

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

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

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

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

Лимит: 120 запросов в минуту с одного IP (при превышении — HTTP 429).

CSRF не требуется.

Сводная таблица 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`, опционально `currency`	Начисление баланса
`POST /v1/module/user/subtract-balance`	ключи + `user_id`, `secret_key`, `amount`, `comment`, опционально `currency`	Списание баланса
`POST /v1/module/user/send-request`	ключи + `user_tg_id`, `method`, `params`	Вызов метода Telegram Bot API (`sendMessage`)
`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 для чата заказа (`sendMessage`)
`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/payment/history-create`	`public_key`, `private_key`	Создать запись истории оплаты сообщения
`POST /v1/module/payment/history-success`	`public_key`, `private_key`	Засчитать оплату
`POST /v1/module/payment/history-fail`	`public_key`, `private_key`	Отменить оплату
`POST /v1/module/payment/history-delete`	`public_key`, `private_key`	Удалить запись истории

Бот

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`), например содержимое `Telegram.WebApp.initData`
`bot_clone_id`	integer	нет	ID клона бота, если Web App открыт у клона

Ответ: объект пользователя бота (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	да	Комментарий к операции (пустая строка не принимается)
`currency`	string	нет	ISO-код валюты `amount` (`USD`, `RUB`…). Если отличается от валюты бота — конвертация перед операцией
`operation_id`	string	нет	Идемпотентный ключ (до 64 символов). Повтор с тем же ключом не меняет баланс. При timeout повторять только с тем же `operation_id`.

Ответ: обновлённый 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	да	Сейчас разрешён только `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	да	Сейчас разрешён только `sendMessage`
`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	нет	Пагинация

Оплаты сообщений (кратко)

Методы /v1/module/payment/* управляют историей оплаты сообщения-оплаты (MessagePaymentHistory).

URL	Назначение
`history-create`	Создать запись со статусом `pending`
`history-success`	Засчитать оплату
`history-fail`	Отменить оплату
`history-delete`	Удалить запись

Нюансы:

во всех методах нужны public_key + private_key;
в history-create поле id — это MessagePayment; в success/fail/delete — ID истории из ответа create;
amount в payment передаётся в основных единицах валюты (рубли/доллары), BOT-T умножает на 100; это отличается от баланса/вывода, где amount уже в копейках.

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

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

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

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

Ситуация	Что проверить
Модуль не подключается	`ping` возвращает `data: "OK"`; Admin URL со слэшем на конце и доступен с серверов BOT-T
«public_key not found» / «private_key not found»	Поля переданы в теле POST (JSON)
«secret key not valid»	`secret_key` соответствует Telegram ID и боту; пользователь есть в боте
«comment not found»	В add/subtract-balance передан непустой `comment`
create отклонён	В ответе `data` совпадают `bot_id`, `public_key`, `private_key` с query; есть `id` и `version`
delete / get падает при `result: true`	В успешном JSON есть поле `data`
send-request отклонён	`method` равен ровно `sendMessage`
429 / лимит	Не более 120 запросов/мин к `/v1/module/*` с одного IP

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

Связанные материалы

Управление заказами: https://bott.readme.io/reference/%D1%83%D0%BF%D1%80%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B7%D0%B0%D0%BA%D0%B0%D0%B7%D0%B0%D0%BC%D0%B8
Процесс API-модуля товара: https://bott.readme.io/reference/%D0%BF%D1%80%D0%BE%D1%86%D0%B5%D1%81%D1%81-%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F-api-%D0%BC%D0%BE%D0%B4%D1%83%D0%BB%D1%8F

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

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

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

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

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

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

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

Типичный flow Web App

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

Часть 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)

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

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

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

Связанные материалы