API для рекламодателей

Управление заказами на покупку трафика: создание, настройка, остановка и статистика. Возможности соответствуют настройкам заказа в Telegram-боте.

Базовый URL: https://tgrass.space
Токен запросить у вашего менеджера @tgrassbot или в поддержке @tgrass_support_bot.

Авторизация

Во всех запросах передавайте токен в HTTP-заголовке Auth (как у продавцов):

Auth: <advertiser_api_token>
Content-Type: application/json

Баланс

GET /advertiser/balance
curl -H "Auth: YOUR_TOKEN" https://tgrass.space/advertiser/balance
{
  "user_id": 123456789,
  "balance": 1500.50
}

Список и карточка заказа

GET /advertiser/orders
GET /advertiser/orders/{order_id}

В карточке заказа дополнительно возвращается expenses — сумма списаний.

Создание заказа

POST /advertiser/orders

Заказ уходит на модерацию

Обязательные поля

ПолеТипОписание
typestringchannel, bot, resource, folder, max_channel, max_bot
linkstringСсылка на ресурс (формат зависит от типа)
max_subscribersintМинимум 50

Формат ссылок

Опциональные поля при создании и изменении

ПолеТипОписание
name string Название заказа (для удобства в кабинете / боте)
bot_token string Токен Telegram-бота покупателя. Нужен для точной проверки подписки на бота
price float Цена за подписчика. Не ниже минимума по фильтрам, не выше 15
tg_channel_id string Числовой ID Telegram-канала (например -100...) для проверки подписки
join_request bool Канал с заявками на вступление (join request). Актуально для закрытых каналов
folder_channels_count int Количество каналов в папке. Для заказов типа folder
subscribers_per_day int (≥50) Лимит новых подписчиков в сутки. Без поля — без суточного лимита
subscribers_per_hour int (≥1) Лимит новых подписчиков в час. Без поля — без часового лимита
count_unsubscriptions bool Если true — отписки учитываются и освобождают слот в лимите заказа
only_filled_profiles bool Только пользователи с заполненным профилем (имя / username и т.п.)
only_profiles_with_photo bool Только пользователи с аватаркой
gender string Фильтр по полу: male или female
countries string[] Список стран (коды/значения как в боте), например ["RU", "KZ"]
langs string[] Языки интерфейса пользователя, например ["ru", "en"]
cities string[] Игнорируется. Фильтр по городам больше не используется
age string[] Возрастные группы: under 18, 18 - 24, 25 - 34, 35+
only_premium bool Только пользователи с Telegram Premium
adult bool 18+ / adult-заказ (меняет модерацию и минимальную цену)
categories_excluded string[] Категории источников трафика, которые нужно исключить
start_dttm datetime Отложенный старт заказа (ISO datetime). До этого времени трафик не выдаётся
schedule_days string[] Дни недели приёма трафика: mon … sun
schedule_from time Начало окна приёма трафика (время GMT), например 09:00:00
schedule_to time Конец окна приёма трафика (время GMT), например 21:00:00
resource_from_telegram bool Для ресурсов: принимать трафик из Telegram
resource_from_max bool Для ресурсов: принимать трафик из MAX
custom_check_url string URL своей проверки подписки (custom check)
custom_check_api_key string API-ключ для custom check URL
custom_check_bot_token string Токен своего checker-бота для проверки участника канала

Цены по умолчанию: канал 1.5, бот/ресурс 2, папка 3, MAX 3.5. Минимальная цена пересчитывается по фильтрам (как в боте), максимум — 15.

curl -X POST https://tgrass.space/advertiser/orders \
  -H "Auth: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "channel",
    "link": "https://t.me/example_channel",
    "max_subscribers": 1000,
    "gender": "male",
    "langs": ["ru"],
    "price": 1.8
  }'

Изменение настроек

PATCH /advertiser/orders/{order_id}

Можно менять те же параметры, что и в настройках заказа в боте. Чтобы сбросить поле в «без ограничения», передайте флаг:

Если после изменения фильтров текущая цена ниже минимума — цена поднимается автоматически. Увеличение max_subscribers автоматически запускает заказ (как в боте).

curl -X PATCH https://tgrass.space/advertiser/orders/12345 \
  -H "Auth: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers_per_day": 200,
    "only_premium": true,
    "price": 4
  }'

Сброс суточного лимита (убрать ограничение subscribers_per_day):

curl -X PATCH https://tgrass.space/advertiser/orders/12345 \
  -H "Auth: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reset_subscribers_per_day": true
  }'

Старт, стоп и удаление

POST /advertiser/orders/{order_id}/stop
POST /advertiser/orders/{order_id}/start
DELETE /advertiser/orders/{order_id}

Запуск требует положительного баланса.

Статистика

GET /advertiser/orders/{order_id}/stats?from=YYYY-MM-DD&to=YYYY-MM-DD

Период не больше 30 дней. По умолчанию — последние 30 дней.

{
  "order_id": 12345,
  "from_date": "2026-07-28",
  "to_date": "2026-08-27",
  "total_spend": 420.5,
  "total_subs": 210,
  "total_unsubs": 15,
  "active_subscribers_count": 195,
  "daily": [
    {"date": "2026-08-27", "spend": 12.0, "subs": 6, "unsubs": 1}
  ]
}