Аутентификация

Все методы требуют передачи в запросе GET (Один из видов токена)

botToken — токен бота
secretKey — секретный ключ

Базовый путь: /v1/bot/user/

API пользователей бота

Авторизация

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

Параметр	Где	Обязательность	Описание
`bot_id`	тело	да	ID бота в системе BOT-T (таблица `bots_bot`)
`token` или `botToken`	query или тело	да*	Токен бота (Bot API token)
`secretKey`	query	да*	Секретный ключ бота (альтернатива токену)

* Достаточно либо token/botToken, либо secretKey.

Заголовки:

Content-Type: application/json

Базовый URL

https://api.bot-t.com

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

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

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

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

Лимит запросов: 120 запросов в минуту с одного IP. (Cloudflare может ограничить быстрее)

Основные методы для получения пользователей

Метод	URL	Назначение
`index`	`POST /v1/bot/user/index`	Список пользователей (с пагинацией и фильтрами)
`count`	`POST /v1/bot/user/count`	Количество пользователей по тем же фильтрам
`view`	`POST /v1/bot/user/view`	Один пользователь по `user_id` (id из `bots_bot_user`)
`view-by-telegram-id`	`POST /v1/bot/user/view-by-telegram-id`	Один пользователь по Telegram ID
`view-by-user-id`	`POST /v1/bot/user/view-by-user-id`	Один пользователь по системному `user_id` (таблица `users`)
`referrals`	`POST /v1/bot/user/referrals`	Список рефералов пользователя

POST /v1/bot/user/index — список пользователей

Параметры тела

Поле	Тип	По умолчанию	Описание
`bot_id`	integer	—	ID бота (обязательно)
`limit`	integer	`25`	Записей на страницу, максимум 500
`offset`	integer	`0`	Сколько записей пропустить (пагинация)
`status`	integer[]	—	Фильтр по статусам (см. таблицу ниже)
`sort_id`	string	`DESC`	Сортировка по id: `ASC` или `DESC`
`sort_telegram_id`	string	—	Сортировка по Telegram ID
`sort_created_time`	string	—	Сортировка по дате создания
`sort_updated_time`	string	—	Сортировка по дате обновления
`sort_balance`	string	—	Сортировка по балансу
`id`	integer	—	ID записи пользователя бота (`bots_bot_user.id`)
`ref_id`	integer	—	ID реферера
`created_time_start`	string	—	Начало периода создания (часовой пояс бота)
`created_time_end`	string	—	Конец периода создания
`updated_time_start`	string	—	Начало периода обновления
`updated_time_end`	string	—	Конец периода обновления
`min_balance`	number	—	Минимальный баланс (в рублях/единицах, не в копейках)
`max_balance`	number	—	Максимальный баланс
`user_id`	integer	—	Системный ID пользователя (`users.id`)
`type`	integer	—	Тип пользователя Telegram
`telegram_id`	integer	—	Telegram ID

Если указано несколько sort_*, применяется последний переданный параметр сортировки.
По умолчанию сортировка: id DESC.

Статусы пользователя (`status`)

ID	Константа	Описание
`1`	SYSTEM_ACTIVE	Активный
`2`	SYSTEM_NOT_ACTIVE	Неактивный
`3`	SYSTEM_BAN	Заблокирован
`4`	SYSTEM_MANAGER	Менеджер
`5`	SYSTEM_NOT_VERIFIED	Не верифицирован
`6`	SYSTEM_FIDUCIARY	Доверенный

Пример фильтра только активных:

{
  "bot_id": 1,
  "status": [1],
  "limit": 100,
  "offset": 0
}

Структура элемента ответа (`BotUserDto`)

{
  "id": 123,
  "bot_id": 1,
  "user": {
    "id": 100500,
    "telegram_id": 182352323552,
    "username": "username",
    "first_name": "Иван",
    "last_name": "Иванов",
    "link": "<a href='tg://user?id=182352323552'>Иван</a>",
    "type": "private"
  },
  "ref": null,
  "money": 15000,
  "status": {
    "id": 1,
    "title": "Активный"
  },
  "create_at": 1716288000,
  "created_time": "2024-05-21 12:00:00",
  "update_at": 1716374400,
  "updated_time": "2024-05-22 12:00:00",
  "expectation": null,
  "secret_user_key": "k7f3a9b2c1d4e5f6"
}

Поле	Описание
`id`	ID пользователя в контексте бота (`bots_bot_user.id`) — используйте в `view`, `add-balance` и т.д.
`user.id`	Системный ID (`users.id`)
`user.telegram_id`	Telegram ID
`money`	Баланс в минимальных единицах (копейки). Для отображения: `money / 100`
`ref`	Данные реферера (`UserDto`) или `null`

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

{
  "result": true,
  "data": [
    { "id": 123, "bot_id": 1, "user": { "...": "..." }, "money": 0, "status": { "id": 1, "title": "Активный" } }
  ]
}

POST /v1/bot/user/count — количество

Те же фильтры, что у index, но без limit, offset и сортировки.

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

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

Алгоритм: выгрузить всех пользователей

Вызвать count с нужными фильтрами → получить общее число.
В цикле вызывать index с limit=500 (максимум) и увеличивать offset на limit.
Останавливаться, когда data пустой или offset >= count.

Примеры кода

Замените константы на свои значения:

API_BASE   = https://api.example.com
BOT_ID     = 1
BOT_TOKEN  = 123456789:ABCdefGHI...

PHP

<?php

const API_BASE = 'https://api.example.com';
const BOT_ID = 1;
const BOT_TOKEN = '123456789:ABCdefGHI...';

/**
 * POST-запрос к API пользователей бота.
 */
function botUserRequest(string $action, array $body): array
{
    $url = API_BASE . '/v1/bot/user/' . $action . '?token=' . urlencode(BOT_TOKEN);

    $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(['bot_id' => BOT_ID], $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'];
}

/** Получить одну страницу пользователей */
function fetchUsersPage(int $limit = 500, int $offset = 0, array $filters = []): array
{
    return botUserRequest('index', array_merge($filters, [
        'limit' => $limit,
        'offset' => $offset,
    ]));
}

/** Выгрузить всех пользователей с пагинацией */
function fetchAllUsers(array $filters = []): array
{
    $limit = 500;
    $offset = 0;
    $all = [];

    do {
        $page = fetchUsersPage($limit, $offset, $filters);
        if (empty($page)) {
            break;
        }
        $all = array_merge($all, $page);
        $offset += $limit;
    } while (count($page) === $limit);

    return $all;
}

// --- Использование ---

// Одна страница (25 пользователей по умолчанию)
$users = fetchUsersPage(25, 0, ['status' => [1]]);

// Все активные пользователи
$allActive = fetchAllUsers(['status' => [1]]);

foreach ($allActive as $botUser) {
    $tgId = $botUser['user']['telegram_id'] ?? null;
    $balance = ($botUser['money'] ?? 0) / 100;
    echo "BotUser #{$botUser['id']}, TG: {$tgId}, balance: {$balance}\n";
}

// Количество
$count = (int) botUserRequest('count', ['status' => [1]]);
echo "Active users: {$count}\n";

// Один пользователь по Telegram ID
$one = botUserRequest('view-by-telegram-id', ['telegram_id' => 182352323552]);

JavaScript (Node.js, fetch)

const API_BASE = 'https://api.example.com';
const BOT_ID = 1;
const BOT_TOKEN = '123456789:ABCdefGHI...';

async function botUserRequest(action, body = {}) {
  const url = `${API_BASE}/v1/bot/user/${action}?token=${encodeURIComponent(BOT_TOKEN)}`;

  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ bot_id: BOT_ID, ...body }),
  });

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

async function fetchUsersPage(limit = 500, offset = 0, filters = {}) {
  return botUserRequest('index', { limit, offset, ...filters });
}

async function fetchAllUsers(filters = {}) {
  const limit = 500;
  let offset = 0;
  const all = [];

  while (true) {
    const page = await fetchUsersPage(limit, offset, filters);
    if (!page.length) break;

    all.push(...page);
    offset += limit;

    if (page.length < limit) break;
  }

  return all;
}

// --- Использование ---

(async () => {
  // Одна страница
  const page = await fetchUsersPage(100, 0, { status: [1] });
  console.log(`Loaded ${page.length} users`);

  // Все активные
  const users = await fetchAllUsers({ status: [1] });
  for (const u of users) {
    const tgId = u.user?.telegram_id;
    const balance = (u.money ?? 0) / 100;
    console.log(`#${u.id} TG:${tgId} balance:${balance}`);
  }

  // Количество
  const count = parseInt(await botUserRequest('count', { status: [1] }), 10);
  console.log('Total active:', count);
})();

Python 3

import requests

API_BASE = 'https://api.example.com'
BOT_ID = 1
BOT_TOKEN = '123456789:ABCdefGHI...'


def bot_user_request(action: str, body: dict = None) -> dict:
    url = f'{API_BASE}/v1/bot/user/{action}'
    params = {'token': BOT_TOKEN}
    payload = {'bot_id': BOT_ID, **(body or {})}

    response = requests.post(
        url,
        params=params,
        json=payload,
        headers={'Content-Type': 'application/json'},
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()

    if not data.get('result'):
        raise RuntimeError(data.get('message', 'API error'))

    return data['data']


def fetch_users_page(limit: int = 500, offset: int = 0, **filters) -> list:
    return bot_user_request('index', {'limit': limit, 'offset': offset, **filters})


def fetch_all_users(**filters) -> list:
    limit = 500
    offset = 0
    all_users = []

    while True:
        page = fetch_users_page(limit=limit, offset=offset, **filters)
        if not page:
            break
        all_users.extend(page)
        offset += limit
        if len(page) < limit:
            break

    return all_users


if __name__ == '__main__':
    # Одна страница
    page = fetch_users_page(limit=100, offset=0, status=[1])
    print(f'Loaded {len(page)} users')

    # Все активные пользователи
    users = fetch_all_users(status=[1])
    for u in users:
        tg_id = (u.get('user') or {}).get('telegram_id')
        balance = (u.get('money') or 0) / 100
        print(f"#{u['id']} TG:{tg_id} balance:{balance}")

    # Количество
    count = int(bot_user_request('count', {'status': [1]}))
    print('Total active:', count)

    # По Telegram ID
    one = bot_user_request('view-by-telegram-id', {'telegram_id': 182352323552})
    print(one)

Примеры фильтрации

Пользователи с балансом от 100 до 1000 руб.

{
  "bot_id": 1,
  "min_balance": 100,
  "max_balance": 1000,
  "limit": 500,
  "offset": 0
}

Зарегистрированные за период

{
  "bot_id": 1,
  "created_time_start": "2024-01-01 00:00:00",
  "created_time_end": "2024-12-31 23:59:59",
  "sort_created_time": "ASC"
}

Конкретный Telegram ID

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

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

Сообщение	Причина
`bot_id not found`	Не передан `bot_id` в теле
`token not found`	Нет `token`/`botToken` и нет `secretKey`
`token is not valid`	Неверный токен
`secretKey is not valid`	Неверный secretKey
`tariff have been premium`	Для бота нужен премиум-тариф
`sortAmount should be ASC or DESC`	Неверное значение параметра сортировки

Дополнительные методы (кратко)

Метод	Описание
`add-balance`	Начислить баланс (`user_id`, `sum`, `comment`)
`subtract-balance`	Списать баланс
`ban`	Забанить / разбанить
`delete`	Удалить пользователя
`set-ref`	Назначить реферера (`id`, `ref_id`)
`zero-balance`	Обнулить баланс
`zero-ref`	Сбросить реферера
`chats-channels-list`	Список чатов и каналов бота

Полная спецификация OpenAPI: /docs/swagger.yaml или Swagger UI на вашем API-хосте.

Важные замечания

user_id в разных методах означает разное:
- в index (фильтр) — системный ID (users.id);
- в view, add-balance, referrals — ID записи бота (bots_bot_user.id).
Баланс: в фильтрах min_balance/max_balance передаётся в рублях (дробное число), в ответе money — в копейках.
Даты фильтров интерпретируются в часовом поясе бота.
Пагинация: при выгрузке больших баз используйте limit=500 и не превышайте лимит 120 req/min.
Авторизация через secretKey: передайте ключ в query вместо токена:
POST /v1/bot/user/index?secretKey=YOUR_SECRET_KEY

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

Успех: { "result": true, "data": <данные> }
Ошибка: { "result": false, "message": "<текст ошибки>" } (или аналог через ApiHelper::errorNew())