Пополнения и списания баланса
API для начисления и списания баланса пользователя бота, просмотра истории операций и заявок на вывод.
Базовый URL: https://api.bot-t.com
Все методы — POST, тело — JSON, заголовок Content-Type: application/json.
Два API
| API | Кто вызывает | Авторизация | Пользователь в запросе |
|---|---|---|---|
Методы бота /v1/bot/... | ваш сервер или личный кабинет | токен бота или секретный ключ бота | зависит от метода |
Методы модуля /v1/module/... | внешний веб-модуль | ключи модуля и при необходимости секрет пользователя | всегда Telegram ID |
Авторизация
Методы бота
| Параметр | Где передавать | Обязательный | Описание |
|---|---|---|---|
bot_id | тело | да | ID бота |
token или botToken | query или тело | да* | Токен бота |
secretKey | query | да* | Секретный ключ бота вместо токена |
* Достаточно либо токена, либо secretKey.
История выводов от имени пользователя дополнительно требует secret_user_key.
Методы модуля
| Доступ | Что передать |
|---|---|
| Сервер модуля | public_key и private_key |
| От имени пользователя | public_key, при необходимости private_key, плюс user_id (Telegram ID) и secret_key |
| Только публичный ключ | public_key — заявка на вывод и история выводов модуля |
Формат ответа
{ "result": true, "data": {} }
{ "result": false, "message": "текст ошибки" }
Используйте data, только если result равен true.
Некоторые методы возвращают в data строку: "1", "0" или число в виде строки (количество записей).
Лимит: 120 запросов в минуту с одного IP.
Суммы
В разных методах сумма передаётся в разных единицах.
| Где | Поле | Единица |
|---|---|---|
| Начисление и списание модуля | amount | минимальные единицы валюты (для рублей — копейки). 1000 = 10.00 |
| Заявка на вывод модуля | amount | минимальные единицы валюты |
| Начисление и списание бота | sum | основные единицы (для рублей — рубли). 10.5 = 10.50 |
Фильтры списка min_amount и max_amount | основные единицы (рубли) | |
Баланс в ответе, поле money | минимальные единицы валюты | |
Сумма операции в ответе, поле amount | минимальные единицы валюты |
Максимальная сумма одной операции — 1 000 000 в основной валюте. Большее значение будет уменьшено до этого предела.
Операция с балансом
Каждое начисление, списание, пополнение через платёжную систему или заявка на вывод — отдельная операция.
stateDiagram-v2
[*] --> Неоплачена: заявка на оплату
[*] --> Оплачена: начисление, списание, вывод, обнуление
Неоплачена --> Оплачена: подтверждение
Неоплачена --> [*]: удаление или истечение срока
Оплачена --> [*]: удаление
status | Значение |
|---|---|
0 | Не оплачена, баланс ещё не изменён |
1 | Оплачена, баланс уже изменён |
is_positive | Значение |
|---|---|
true | Начисление |
false | Списание |
Частые типы операции (balanceType.id):
| ID | Когда появляется |
|---|---|
5 | Действие администратора, в том числе обнуление баланса |
11 | Реферальное начисление |
15 | Заявка на вывод |
33 | Начисление или списание через API |
Объект операции
| Поле | Тип | Описание |
|---|---|---|
id | integer | ID операции |
bot_id | integer | ID бота |
user | object | Пользователь. user.id — ID в системе, user.telegram_id — Telegram ID |
is_positive | boolean | Начисление или списание |
status | integer | 0 — не оплачена, 1 — оплачена |
item_id | integer или null | Способ оплаты, если операция через платёжную систему |
itemData | string | Реквизиты или дополнительные данные способа оплаты |
payment_item_action | string или null | Код способа оплаты |
balanceType | object | Тип операции: id, title, image |
amount | integer | Сумма в минимальных единицах валюты |
created_at | integer | Время создания (Unix) |
created_time | string | Дата и время в часовом поясе бота |
comment | string | Комментарий |
Поле operation_id в ответе не возвращается. Оно нужно только при создании операции.
Объект пользователя бота
Возвращается после начисления, списания и обнуления баланса.
| Поле | Тип | Описание |
|---|---|---|
id | integer | ID пользователя в боте |
bot_id | integer | ID бота |
user | object | Данные из Telegram |
ref | object или null | Кто пригласил пользователя |
money | integer | Текущий баланс в минимальных единицах валюты |
status | object | Статус: id и title |
create_at, update_at | integer | Время создания и обновления (Unix) |
created_time, updated_time | string | Дата и время в часовом поясе бота |
expectation | string или null | Ожидаемое действие пользователя |
secret_user_key | string или null | Секрет пользователя. В запросах модуля передаётся как secret_key |
Повтор запроса: operation_id
operation_idНеобязательное поле в начислении и списании (и для бота, и для модуля).
- Строка до 64 символов.
- Уникальна в рамках одного бота.
- Повтор с тем же ключом не меняет баланс и возвращает актуальные данные пользователя.
- Если запрос оборвался по таймауту, повторите его с тем же
operation_id. - Без ключа повтор начислит или спишет сумму ещё раз.
- Если операция не прошла (например, не хватило средств), тот же ключ можно использовать снова.
{
"operation_id": "order-555-try-1"
}
Список методов
Изменение баланса
| Действие | URL |
|---|---|
| Начислить (модуль) | POST /v1/module/user/add-balance |
| Списать (модуль) | POST /v1/module/user/subtract-balance |
| Начислить (бот) | POST /v1/bot/user/add-balance |
| Списать (бот) | POST /v1/bot/user/subtract-balance |
| Обнулить баланс | POST /v1/bot/user/zero-balance |
| Создать заявку на вывод | POST /v1/module/replenishment/create-conclusion |
| Подтвердить оплату | POST /v1/bot/replenishment/user/success |
История и управление
| Действие | URL |
|---|---|
| Список операций | POST /v1/bot/replenishment/user/index |
| Количество операций | POST /v1/bot/replenishment/user/count |
| Удалить операцию | POST /v1/bot/replenishment/user/delete |
| Статистика | POST /v1/bot/replenishment/user/statistics |
| Действия для одной операции | POST /v1/bot/replenishment/user/method |
| Массовые действия | POST /v1/bot/replenishment/user/mass-method |
| Заявки на вывод (пользователь бота) | POST /v1/bot/user/referral/conclusion-withdrawals |
| История выводов (пользователь бота) | POST /v1/bot/user/referral/withdrawal-history |
| История выводов (модуль) | POST /v1/module/referral/withdrawal-history |
Начисление и списание: модуль
Комментарий обязателен. Пустая строка не принимается.
POST /v1/module/user/add-balance
Начисляет сумму на баланс. Операция сразу считается оплаченной. В ответе — пользователь бота с новым балансом.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
public_key | string | да | Публичный ключ модуля |
private_key | string | да | Приватный ключ модуля |
user_id | integer | да | Telegram ID |
secret_key | string | да | Секрет пользователя |
amount | integer | да | Сумма в минимальных единицах валюты, больше 0 |
comment | string | да | Комментарий к операции |
operation_id | string | нет | Ключ для безопасного повтора, до 64 символов |
{
"public_key": "...",
"private_key": "...",
"user_id": 123456789,
"secret_key": "...",
"amount": 1500,
"comment": "Возврат за заказ 555",
"operation_id": "refund-555"
}
{
"result": true,
"data": {
"id": 88,
"bot_id": 12,
"money": 6500,
"secret_user_key": "...",
"user": {
"id": 50,
"telegram_id": 123456789
}
}
}
POST /v1/module/user/subtract-balance
Списывает сумму с баланса. Если средств меньше, чем amount, баланс не меняется и возвращается ошибка.
Набор полей такой же, как у начисления.
{
"public_key": "...",
"private_key": "...",
"user_id": 123456789,
"secret_key": "...",
"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 | Не передана сумма |
comment not found | Не передан комментарий |
secret key not valid | Секрет не подходит этому пользователю |
У Вас закончился баланс в боте. Пополните его! | Недостаточно средств |
operation_id is too long | Ключ длиннее 64 символов |
Начисление и списание: бот
Здесь user_id — это ID пользователя в боте (поле id объекта пользователя бота), не Telegram ID.
POST /v1/bot/user/add-balance
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
user_id | integer | да | ID пользователя в боте |
sum | number | да | Сумма в основных единицах валюты, больше 0. Например, 10.5 |
comment | string | нет | По умолчанию: «Пополнение баланса через API» |
isNotice | boolean | нет | Отправить уведомления. По умолчанию true |
isSendComment | boolean | нет | Отправить текст комментария пользователю в бот. По умолчанию true |
operation_id | string | нет | Ключ для безопасного повтора |
{
"bot_id": 12,
"user_id": 88,
"sum": 15,
"comment": "Бонус",
"isNotice": false,
"isSendComment": false,
"operation_id": "bonus-88-20260904"
}
В ответе — объект пользователя бота. Поле money — баланс после операции, в минимальных единицах валюты.
POST /v1/bot/user/subtract-balance
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
user_id | integer | да | ID пользователя в боте |
sum | number | да | Сумма в основных единицах валюты, больше 0 |
comment | string | нет | К тексту автоматически добавляется пометка «(API)» |
operation_id | string | нет | Ключ для безопасного повтора |
У списания нет полей isNotice и isSendComment.
{
"bot_id": 12,
"user_id": 88,
"sum": 10.5,
"comment": "Оплата услуги",
"operation_id": "svc-100"
}
POST /v1/bot/user/zero-balance
Списывает весь текущий баланс. Поле operation_id не поддерживается.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
id | integer или массив | да | Один ID пользователя в боте или несколько |
- Один ID — в ответе объект пользователя бота.
- Массив — в ответе
"1". - Если баланс уже равен нулю, операция не создаётся.
{ "bot_id": 12, "id": 88 }
{ "bot_id": 12, "id": [88, 89, 90] }
Список, подтверждение и удаление
В фильтрах списка и подсчёта user_id — это ID пользователя в системе (поле user.id в объекте операции), не ID в боте и не Telegram ID.
POST /v1/bot/replenishment/user/index
Список операций. По умолчанию до 50 записей, не больше 100, сдвиг 0. Новые записи сверху.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
user_id | integer | нет | ID пользователя в системе |
limit | integer | нет | Число записей, от 1 до 100 |
offset | integer | нет | Сдвиг для постраничной загрузки |
is_positive | boolean | нет | Только начисления или только списания |
min_amount | number | нет | Минимальная сумма в основных единицах валюты |
max_amount | number | нет | Максимальная сумма в основных единицах валюты |
balance_id | integer или массив | нет | Тип операции |
balance_not_in | boolean | нет | Если true, указанные типы исключаются |
status | integer | нет | 0 или 1 |
id | integer | нет | Одна конкретная операция |
time_start | string | нет | Начало периода в часовом поясе бота |
time_end | string | нет | Конец периода в часовом поясе бота |
data_1 | string | нет | Поиск по данным способа оплаты, до 500 символов |
sort_amount | ASC или DESC | нет | Сортировка по сумме |
sort_created_at | ASC или DESC | нет | Сортировка по дате. Если указана, имеет приоритет над сортировкой по сумме |
В ответе — массив операций.
{
"bot_id": 12,
"user_id": 50,
"is_positive": false,
"status": 1,
"limit": 50,
"offset": 0,
"time_start": "2026-09-01 00:00:00",
"time_end": "2026-09-04 23:59:59"
}
POST /v1/bot/replenishment/user/count
Те же фильтры, что у списка, без limit, offset и сортировки.
{ "result": true, "data": "42" }
POST /v1/bot/replenishment/user/success
Подтверждает неоплаченную операцию и изменяет баланс. Повтор для уже оплаченной операции вернёт ошибку.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
id | integer | да | ID операции |
{ "bot_id": 12, "id": 1001 }
{ "result": true, "data": "1" }
POST /v1/bot/replenishment/user/delete
Удаляет операцию. Если баланс уже был изменён, деньги автоматически не возвращаются.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
id | integer или массив | да | Один ID операции или несколько |
{ "bot_id": 12, "id": [1001, 1002] }
POST /v1/bot/replenishment/user/statistics
Статистика начислений в часовом поясе бота.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
start_date | string | нет | Дата начала YYYY-MM-DD. По умолчанию сегодня |
end_date | string | нет | Дата конца YYYY-MM-DD |
{
"result": true,
"data": {
"today": { "count": 3, "total": 150000 },
"yesterday": { "count": 1, "total": 5000 },
"week": { "count": 10, "total": 400000 },
"lastWeek": { "count": 8, "total": 210000 },
"month": { "count": 40, "total": 1200000 },
"lastMonth": { "count": 35, "total": 980000 },
"period": {
"start": "2026-09-01",
"end": "2026-09-04",
"data": {
"2026-09-01": { "count": 2, "total": 3000 }
},
"total": { "count": 2, "total": 3000 }
}
}
}
Поле total — сумма в минимальных единицах валюты. count — число операций.
POST /v1/bot/replenishment/user/method
Список доступных действий для одной операции.
| Поле | Обяз. |
|---|---|
bot_id | да |
id | да |
POST /v1/bot/replenishment/user/mass-method
Список массовых действий. В теле запроса достаточно bot_id.
Вывод баланса
В боте должна быть включена система выводов. Для создания заявки через модуль также нужна форма обратной связи для вывода.
Если в настройках бота задан процент комиссии, с баланса списывается больше, чем сумма заявки. При нехватке средств заявка не создаётся.
POST /v1/module/replenishment/create-conclusion
Нужны public_key, Telegram ID и секрет пользователя. Приватный ключ не требуется.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
public_key | string | да | Публичный ключ модуля |
user_id | integer | да | Telegram ID |
secret_key | string | да | Секрет пользователя |
amount | integer | да | Сумма заявки в минимальных единицах валюты, больше 0 |
После создания заявки пользователю в личные сообщения уходит форма обратной связи.
{
"result": true,
"data": {
"replenishment_user": {
"id": 2001,
"amount": 1100,
"is_positive": false,
"status": 1
},
"bot_user": {
"id": 88,
"money": 4000
}
}
}
replenishment_user.amount — сколько списано с баланса, включая комиссию.
POST /v1/module/referral/withdrawal-history
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
public_key | string | да | Публичный ключ модуля |
user_id | integer | да | Telegram ID |
secret_key | string | да | Секрет пользователя |
limit | integer | нет | По умолчанию 20, максимум 100 |
offset | integer | нет | Сдвиг |
{
"result": true,
"data": {
"total": 3,
"limit": 20,
"offset": 0,
"items": [
{
"id": 2001,
"amount": 1100,
"withdrawal_amount": 1000,
"feedback": null
}
]
}
}
| Поле | Описание |
|---|---|
amount | Списано с баланса, включая комиссию |
withdrawal_amount | Сумма заявки без комиссии |
feedback | Статус и ответы формы вывода или null |
POST /v1/bot/user/referral/withdrawal-history
История выводов текущего пользователя. Форма обратной связи не обязательна.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
bot_id | integer | да | ID бота |
user_id | integer | да | ID пользователя в боте |
secret_user_key | string | да | Секрет пользователя |
limit | integer | нет | По умолчанию 20, максимум 100 |
offset | integer | нет | Сдвиг |
В ответе: total, limit, offset, items — список операций.
POST /v1/bot/user/referral/conclusion-withdrawals
Те же операции, но:
- в боте должна быть включена форма обратной связи для вывода;
- в ответе сразу массив операций, без поля
total; - по умолчанию до 500 записей, максимум 500.
Какой идентификатор пользователя передавать
| Методы | Что передать |
|---|---|
| Начисление, списание, вывод и история выводов модуля | Telegram ID |
| Начисление и списание бота | ID пользователя в боте |
| Обнуление баланса | поле id — ID пользователя в боте |
| Список и количество операций | ID пользователя в системе (user.id из объекта операции) |
| Подтверждение, удаление, действия | ID операции |
| История выводов бота | ID пользователя в боте и secret_user_key |
Примеры
Списать баланс через модуль и безопасно повторить запрос
POST /v1/module/user/subtract-balance HTTP/1.1
Host: api.bot-t.com
Content-Type: application/json
{
"public_key": "PUB",
"private_key": "PRIV",
"user_id": 123456789,
"secret_key": "USERSECRET",
"amount": 19900,
"comment": "Заказ 777",
"operation_id": "order-777"
}
Если запрос оборвался по таймауту, отправьте тот же запрос. Повтор не спишет 199.00 ещё раз.
Начислить 10 рублей без уведомлений
POST /v1/bot/user/add-balance?token=BOT_TOKEN HTTP/1.1
Host: api.bot-t.com
Content-Type: application/json
{
"bot_id": 12,
"user_id": 88,
"sum": 10,
"comment": "Компенсация",
"isNotice": false,
"isSendComment": false,
"operation_id": "comp-88-1"
}
Последние списания пользователя
В фильтре списка нужен ID пользователя в системе — поле user.id из объекта пользователя бота, не поле id самого пользователя бота.
POST /v1/bot/replenishment/user/index?token=BOT_TOKEN HTTP/1.1
Host: api.bot-t.com
Content-Type: application/json
{
"bot_id": 12,
"user_id": 50,
"is_positive": false,
"limit": 20
}
Типичные ошибки
| Сообщение | Что проверить |
|---|---|
user_id not found / id not found | Поле не передано или указан не тот идентификатор |
user not found / access | Пользователь или операция принадлежит другому боту |
secret key not valid | Неверный секрет пользователя |
sum should have been more 0 / amount must been more 0 | Сумма должна быть больше нуля |
У Вас закончился баланс в боте. Пополните его! | Сумма списания больше остатка |
Изменение баланса уже было произведено | Операция уже подтверждена |
Администратор бота не создал раздел пополнения | В боте не включён раздел пополнения |
Система выводов баланса выключена | В боте не настроен вывод |
operation_id is too long | Ключ длиннее 64 символов |
Рекомендации
- Для начисления и списания всегда передавайте
operation_id— уникальный ключ вашей операции. - После таймаута повторяйте запрос с тем же ключом, не создавайте новый.
- В методах бота сумма в поле
sum— в рублях. В методах модуля и в ответах сумма — в копейках. - Не путайте Telegram ID, ID пользователя в боте и ID пользователя в системе.
- Удаление уже оплаченной операции не возвращает деньги на баланс.
- Приватный ключ модуля и секрет пользователя передавайте только с сервера по HTTPS.