API Reference

Методы без токена бота

API от имени пользователя

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

Токен бота здесь не нужен. Ключ пользователя действует только на одного человека в одном боте.

Все методы — POST с телом JSON.

Content-Type: application/json

https://api.bot-t.com

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

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

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

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

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

Секретный ключ пользователя

В ответах API пользователя поле называется secret_user_key.
В запросах модулей то же значение передаётся как secret_key.

Это один и тот же ключ. Он привязан к паре «пользователь + бот».

Как получитьГде взять ключ
POST /v1/bot/user/view, view-by-telegram-id и другие методы просмотра пользователяПоле secret_user_key в объекте пользователя
POST /v1/module/bot/check-hashПоле secret_user_key после проверки Telegram Web App
POST /v1/module/user/check-secretПроверяет уже известный ключ и возвращает пользователя

Ключ не логируйте и не отдавайте в публичный фронтенд вместе с private_key модуля. Для Web App достаточно bot_id, user_id и secret_user_key.

Два способа авторизации

Для когоПоляuser_idСумма баланса
Модуль на своём сервереpublic_key, private_key, secret_keyTelegram IDamount в копейках
Web App / клиент пользователяbot_id, secret_user_keyID пользователя в боте (id из объекта пользователя)методы ниже баланс не меняют

private_key модуля храните только на сервере модуля.

Как получить ключ: POST /v1/module/bot/check-hash

Проверяет данные Telegram Web App или Login Widget и возвращает пользователя вместе с secret_user_key.

ПолеТипОбяз.Описание
bot_idintegerдаID бота
userDatastringдаСырая строка Telegram.WebApp.initData (с hash)
bot_clone_idintegerнетID клона, если Web App открыт у клона
{
  "bot_id": 12,
  "userData": "query_id=AAH...&user=%7B%22id%22%3A182352323552%7D&auth_date=1716288000&hash=..."
}

В data — объект пользователя. Дальше используйте data.id (ID в боте) и data.secret_user_key.

Методы модуля

Нужны ключи экземпляра модуля. user_id и id здесь — Telegram ID.

МетодURLНазначение
check-secretPOST /v1/module/user/check-secretПроверить ключ и получить пользователя
add-balancePOST /v1/module/user/add-balanceНачислить баланс
subtract-balancePOST /v1/module/user/subtract-balanceСписать баланс
create-conclusionPOST /v1/module/replenishment/create-conclusionЗаявка на вывод
withdrawal-historyPOST /v1/module/referral/withdrawal-historyИстория заявок на вывод

Комментарий у начисления и списания обязателен. Пустая строка не принимается.

amount — целое число в минимальных единицах валюты. 1500 = 15.00. Это не то же самое, что sum в API бота.

Повтор с тем же operation_id не меняет баланс второй раз. Максимум 64 символа.

POST /v1/module/user/check-secret

Проверяет, что secret_key принадлежит пользователю с этим Telegram ID в боте модуля.

ПолеТипОбяз.Описание
public_keystringдаПубличный ключ модуля
private_keystringдаПриватный ключ модуля
idintegerдаTelegram ID
secret_keystringдаСекрет пользователя
{
  "public_key": "...",
  "private_key": "...",
  "id": 182352323552,
  "secret_key": "k7f3a9b2c1d4e5f6"
}

В ответе — объект пользователя, в том числе id (ID в боте), money и secret_user_key.

СообщениеПричина
Неверный или отсутствует id / Неверный формат idНет или неверный Telegram ID
Неверный или отсутствует public_key / private_key / secret_keyНет или неверный формат ключа
secret key not valid 2Ключ не подходит этому Telegram ID и боту
WebModuleBot not found.Модуль с такими ключами не найден

POST /v1/module/user/add-balance

Начисляет сумму. Операция сразу считается выполненной. Пишется в историю.

ПолеТипОбяз.Описание
public_keystringдаПубличный ключ модуля
private_keystringдаПриватный ключ модуля
user_idintegerдаTelegram ID
secret_keystringдаСекрет пользователя
amountintegerдаСумма в копейках, больше 0
commentstringдаКомментарий. Пустая строка не принимается
operation_idstringнетКлюч идемпотентности, до 64 символов
{
  "public_key": "...",
  "private_key": "...",
  "user_id": 182352323552,
  "secret_key": "k7f3a9b2c1d4e5f6",
  "amount": 1500,
  "comment": "Возврат за заказ 555",
  "operation_id": "refund-555"
}

{
  "result": true,
  "data": {
    "id": 88,
    "bot_id": 12,
    "money": 6500,
    "secret_user_key": "k7f3a9b2c1d4e5f6",
    "user": {
      "id": 50,
      "telegram_id": 182352323552
    }
  }
}

money в ответе — баланс после операции, в копейках.

Штатные уведомления о пополнении уходят, если они настроены в боте. Отдельного флага «не уведомлять» у модульного API нет.

POST /v1/module/user/subtract-balance

Списывает сумму. Если средств меньше, чем amount, баланс не меняется.

Набор полей такой же, как у начисления.

{
  "public_key": "...",
  "private_key": "...",
  "user_id": 182352323552,
  "secret_key": "k7f3a9b2c1d4e5f6",
  "amount": 1500,
  "comment": "Оплата заказа 555",
  "operation_id": "order-555-pay"
}
СообщениеПричина
public_key not found / private_key not foundНе переданы ключи модуля
user_id not found / secret_key not foundНе переданы данные пользователя
amount not foundНе передана сумма
amount must be greater than 0Сумма ≤ 0
comment not foundНет комментария или пустая строка
secret key not validКлюч не подходит этому пользователю
У Вас закончился баланс в боте. Пополните его!Недостаточно средств
operation_id is too longКлюч длиннее 64 символов

POST /v1/module/replenishment/create-conclusion

Создаёт заявку на вывод и отправляет пользователю в бот цепочку вопросов.
Нужен только public_key (без private_key). В боте должна быть включена система выводов с формой обратной связи.

ПолеТипОбяз.Описание
public_keystringдаПубличный ключ модуля
user_idintegerдаTelegram ID
secret_keystringдаСекрет пользователя
amountintegerдаСумма вывода в копейках, больше 0

Если в боте задан процент за вывод, с баланса списывается сумма плюс комиссия. При нехватке средств заявка не создаётся.

{
  "public_key": "...",
  "user_id": 182352323552,
  "secret_key": "k7f3a9b2c1d4e5f6",
  "amount": 50000
}

В data:

  • replenishment_user — созданная заявка;
  • bot_user — пользователь с балансом после списания.

POST /v1/module/referral/withdrawal-history

История заявок на вывод текущего пользователя.

ПолеТипОбяз.Описание
public_keystringдаПубличный ключ модуля
user_idintegerдаTelegram ID
secret_keystringдаСекрет пользователя
limitintegerнетПо умолчанию 20, максимум 100
offsetintegerнетСдвиг, по умолчанию 0
{
  "public_key": "...",
  "user_id": 182352323552,
  "secret_key": "k7f3a9b2c1d4e5f6",
  "limit": 20,
  "offset": 0
}

{
  "result": true,
  "data": {
    "total": 3,
    "limit": 20,
    "offset": 0,
    "items": []
  }
}

Методы Web App

Токен бота и ключи модуля не нужны. user_id — ID пользователя в боте.

МетодURLНазначение
indexPOST /v1/bot/user/referral/indexСписок рефералов
countPOST /v1/bot/user/referral/countКоличество рефералов
referrerPOST /v1/bot/user/referral/referrerКто пригласил
personal-percentPOST /v1/bot/user/referral/personal-percentПерсональный реферальный процент
statisticsPOST /v1/bot/user/referral/statisticsСтатистика по приглашённым
balance-referralPOST /v1/bot/user/referral/balance-referralРеферальные начисления на баланс
referrals-balancePOST /v1/bot/user/referral/referrals-balanceПополнения баланса рефералов
replenishment-statisticsPOST /v1/bot/user/referral/replenishment-statisticsПополнения рефералов по типам
conclusion-withdrawalsPOST /v1/bot/user/referral/conclusion-withdrawalsЗаявки на вывод
withdrawal-historyPOST /v1/bot/user/referral/withdrawal-historyИстория выводов с пагинацией

Общие поля всех этих методов:

ПолеТипОбяз.Описание
bot_idintegerдаID бота
user_idintegerдаID пользователя в боте
secret_user_keystringдаСекрет пользователя

В ответах secret_user_key не возвращается.

POST /v1/bot/user/referral/index

ПолеТипПо умолчаниюОписание
limitinteger5Записей на страницу, максимум 50
offsetinteger0Сдвиг
{
  "bot_id": 12,
  "user_id": 88,
  "secret_user_key": "k7f3a9b2c1d4e5f6",
  "limit": 50,
  "offset": 0
}

В ответе — массив рефералов. Новые сверху.

POST /v1/bot/user/referral/count

{
  "bot_id": 12,
  "user_id": 88,
  "secret_user_key": "k7f3a9b2c1d4e5f6"
}

data — строка с числом.

POST /v1/bot/user/referral/referrer

{
  "result": true,
  "data": {
    "referrer": {
      "id": 10,
      "telegram_id": 111111111,
      "username": "inviter"
    }
  }
}

Если пригласившего нет, referrer равен null.

POST /v1/bot/user/referral/personal-percent

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

Если процент не задан — HTTP 404 и сообщение Персональный реферальный процент не задан.

POST /v1/bot/user/referral/statistics

Статистика по числу приглашённых. Дополнительных полей нет.

POST /v1/bot/user/referral/balance-referral

Сумма и количество реферальных начислений на баланс текущего пользователя.

POST /v1/bot/user/referral/referrals-balance

Пополнения баланса у приглашённых, без системных типов операций.

POST /v1/bot/user/referral/replenishment-statistics

ПолеТипОбяз.Описание
balance_idinteger[]даТипы операций, непустой массив
balance_not_idinteger[]нетТипы, которые нужно исключить
is_positivebooleanнетТолько начисления. По умолчанию true
{
  "bot_id": 12,
  "user_id": 88,
  "secret_user_key": "k7f3a9b2c1d4e5f6",
  "balance_id": [1, 2],
  "is_positive": true
}

POST /v1/bot/user/referral/conclusion-withdrawals

Заявки на вывод. В боте должна быть включена система выводов с формой обратной связи.

ПолеТипПо умолчаниюОписание
limitinteger500Максимум 500
offsetinteger0Сдвиг

В ответе — массив заявок.

POST /v1/bot/user/referral/withdrawal-history

Та же история выводов, но без требования включённой формы. Ответ с пагинацией.

ПолеТипПо умолчаниюОписание
limitinteger20Максимум 100
offsetinteger0Сдвиг
{
  "result": true,
  "data": {
    "total": 3,
    "limit": 20,
    "offset": 0,
    "items": []
  }
}

Другие API с тем же ключом

Тот же secret_user_key принимают публичные методы магазина, корзины и цифровых заказов.

Создание заказа из модуля: POST /v1/module/shop/order-create — те же public_key, private_key, Telegram ID и secret_key.

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

СообщениеПричина
bot_id not foundНе передан bot_id (Web App)
not found user_idНе передан user_id (Web App)
Используйте официальный клиент телеграм и убедитесь, что у вас последняя версия.Нет secret_user_key
public_key not found / private_key not foundНет ключей модуля
secret_key not foundНет секрета пользователя в модульном API
secret key not validКлюч не подходит этому пользователю и боту
amount not found / amount must be greater than 0Нет суммы или она ≤ 0
comment not foundНет комментария у начисления или списания
У Вас закончился баланс в боте. Пополните его!Недостаточно средств
operation_id is too longКлюч длиннее 64 символов

Примеры кода

Модуль: списать баланс (PHP)

<?php

const API_BASE = 'https://api.bot-t.com';
const PUBLIC_KEY = '...';
const PRIVATE_KEY = '...';

function moduleUserRequest(string $action, array $body): array
{
    $url = API_BASE . '/v1/module/user/' . $action;

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(array_merge([
            'public_key' => PUBLIC_KEY,
            'private_key' => PRIVATE_KEY,
        ], $body)),
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);
    if (!is_array($data) || ($data['result'] ?? false) !== true) {
        throw new RuntimeException($data['message'] ?? 'API error');
    }

    return $data['data'];
}

$checked = moduleUserRequest('check-secret', [
    'id' => 182352323552,
    'secret_key' => 'k7f3a9b2c1d4e5f6',
]);

moduleUserRequest('subtract-balance', [
    'user_id' => 182352323552,
    'secret_key' => 'k7f3a9b2c1d4e5f6',
    'amount' => 1500,
    'comment' => 'Оплата заказа 555',
    'operation_id' => 'order-555-pay',
]);

Web App: список рефералов (JavaScript)

const API_BASE = 'https://api.bot-t.com';

async function referralRequest(action, body) {
  const response = await fetch(`${API_BASE}/v1/bot/user/referral/${action}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  const json = await response.json();
  if (!json.result) {
    throw new Error(json.message || 'API error');
  }
  return json.data;
}

const referrals = await referralRequest('index', {
  bot_id: 12,
  user_id: 88,
  secret_user_key: 'k7f3a9b2c1d4e5f6',
  limit: 50,
  offset: 0,
});

private_key модуля не вызывайте из браузера. Для Web App используйте только bot_id, user_id и secret_user_key.

Updated 43 minutes ago

Did this page help you?

Updated 43 minutes ago

Did this page help you?