Авторизация

Получение секретного ключа пользователя через API

Инструкция для интеграторов: как получить секрет пользователя бота и использовать его в последующих запросах.

Что это за ключ

Имя в ответе API	Имя в запросах (API модулей)	Имя в запросах (корзина, заказы пользователя)
secret_user_key	secret_key	secret_user_key

Идентифицирует конкретного пользователя в контексте конкретного бота.
Нужен для операций от имени пользователя: корзина, оформление заказа, баланс, вывод и т.п.
Не путать с secretKey в query — это секрет бота (для API владельца), а не пользователя.

Где в ответе искать ключ

При успешном ответе (result: true) объект пользователя содержит поле secret_user_key:

{
  "result": true,
  "data": {
    "id": 123,
    "bot_id": 1,
    "user": {
      "telegram_id": 182352323552,
      "username": "username",
      "first_name": "Иван"
    },
    "secret_user_key": "k7f3a9b2c1d4e5f6"
  }
}

Поле	Описание
data.id	ID пользователя в контексте бота — используйте как user_id в API корзины и публичных заказов
data.user.telegram_id	Telegram ID — используйте как user_id в API модулей при передаче secret_key
data.secret_user_key	Секрет пользователя — сохраните для следующих запросов

Перед использованием данных всегда проверяйте result === true.

Формат ошибки:

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

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

Способы получить ключ

1. API владельца бота (сервер с токеном бота)

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

Метод: POST
Заголовок: Content-Type: application/json

Параметр	Где	Обяз.	Описание
bot_id	тело	да	ID бота в BOT-T
token или botToken	query или тело	да*	Токен Bot API
secretKey	query	да*	Секрет бота (вместо токена)

Достаточно либо токена, либо secretKey бота.

Базовый URL (подставьте свой хост):

https://api.bot-t.com

POST /v1/bot/user/view-by-telegram-id

Один пользователь по Telegram ID.

Поле	Тип	Обяз.	Описание
bot_id	integer	да
telegram_id	integer	да	Telegram ID

Тело запроса:

{
  "bot_id": 1,
  "telegram_id": 182352323552
}

Пример с токеном в query:

POST https://api.bot-t.com/v1/bot/user/view-by-telegram-id?token=123456789:ABCdefGHI...

Ответ: data.secret_user_key, data.id.

POST /v1/bot/user/view

По ID записи пользователя в боте.

Поле	Тип	Обяз.	Описание
bot_id	integer	да
user_id	integer	да	ID пользователя в контексте бота (поле id из ответа выше)

Тело:

{
  "bot_id": 1,
  "user_id": 123
}

POST /v1/bot/user/view-by-user-id

По системному ID пользователя в BOT-T (не Telegram ID).

Поле	Тип	Обяз.	Описание
bot_id	integer	да
user_id	integer	да	Системный ID пользователя

POST /v1/bot/user/index

Список пользователей; в каждом элементе массива data есть secret_user_key.

Поле	Тип	По умолчанию	Описание
bot_id	integer	—	обязательно
limit	integer	25	записей на страницу, максимум 500
offset	integer	0	пагинация
telegram_id	integer	—	фильтр по Telegram ID

Тело (пример):

{
  "bot_id": 1,
  "telegram_id": 182352323552,
  "limit": 1,
  "offset": 0
}

2. API веб-модуля (сервер с ключами модуля)

Когда: backend модуля хранит public_key и private_key экземпляра модуля; нужен ключ пользователя по Telegram ID.

Метод: POST
Заголовок: Content-Type: application/json
Базовый URL:

https://api.bot-t.com

POST /v1/module/user/get

Поле	Тип	Обяз.	Описание
id	integer	да	Telegram ID пользователя
public_key	string	да	Публичный ключ экземпляра модуля
private_key	string	да	Приватный ключ модуля (только на backend)

Тело:

{
  "id": 182352323552,
  "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "private_key": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
}

Ответ: объект пользователя с secret_user_key.
В дальнейших запросах модуля от имени пользователя передавайте:

user_id — Telegram ID;
secret_key — значение из secret_user_key.

3. Авторизация Telegram Web App / Login Widget

Когда: пользователь открыл Web App или прошёл Login Widget; на клиенте есть данные от Telegram с полем hash (initData, query-строка).

Токен бота и ключи модуля не нужны.

POST /v1/module/bot/check-hash

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

Тело (JSON):

{
  "bot_id": 1,
  "userData": "query_id=AAHdF6IQ...&user=%7B%22id%22%3A182352323552...&hash=abc123..."
}

Допускается также application/x-www-form-urlencoded.

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

Рекомендация: передавайте userData на свой backend, который вызовет check-hash; не вызывайте этот метод напрямую из публичного JS с долгоживущими секретами модуля.

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

Сценарий	URL	Авторизация	Что передать	Поле в ответе
Backend владельца бота	POST /v1/bot/user/view-by-telegram-id	токен или secretKey бота	telegram_id	secret_user_key
Backend владельца бота	POST /v1/bot/user/view	то же	user_id (ID в боте)	secret_user_key
Backend модуля	POST /v1/module/user/get	public_key + private_key	id (Telegram ID)	secret_user_key
Web App / Login	POST /v1/module/bot/check-hash	не требуется	userData от Telegram	secret_user_key

Методы, которые не выдают новый ключ

URL	Назначение
POST /v1/module/user/check-secret	Проверка уже известного secret_key
POST /v1/bot/auth/view-by-key	Данные пользователя по уже известному secret_user_key

Как использовать после получения

Тип API	user_id в запросе	Секрет в запросе
Корзина, публичные заказы	ID пользователя в боте (data.id)	secret_user_key
API модуля (баланс, заказ, вывод)	Telegram ID	secret_key

Пример авторизации для корзины (каждый запрос):

{
  "bot_id": 1,
  "user_id": 123,
  "secret_user_key": "k7f3a9b2c1d4e5f6"
}

Безопасность

Не передавайте токен бота и private_key модуля в браузер, мобильное приложение и публичный JavaScript.
Для Web App: userData → ваш backend → check-hash → сохранить secret_user_key в сессии.
Методы владельца бота (view-by-telegram-id, index) — только с доверенного сервера.
Считайте secret_user_key паролем сессии пользователя; при утечке возможны запросы от его имени.

Типовой сценарий (Web App + корзина)

Пользователь открывает Web App → клиент получает initData / query от Telegram.
Backend вызывает POST /v1/module/bot/check-hash с bot_id и userData.
Из ответа сохраняете data.id → user_id, data.secret_user_key.
Все запросы корзины и заказов отправляете с этими тремя полями в JSON.