API для рекламодателей
Управление заказами на покупку трафика: создание, настройка, остановка и статистика. Возможности соответствуют настройкам заказа в Telegram-боте.
https://tgrass.spaceТокен запросить у вашего менеджера @tgrassbot или в поддержке @tgrass_support_bot.
Авторизация
Во всех запросах передавайте токен в HTTP-заголовке Auth (как у продавцов):
Auth: <advertiser_api_token> Content-Type: application/json
Баланс
/advertiser/balance
curl -H "Auth: YOUR_TOKEN" https://tgrass.space/advertiser/balance
{
"user_id": 123456789,
"balance": 1500.50
}
Список и карточка заказа
/advertiser/orders
/advertiser/orders/{order_id}
В карточке заказа дополнительно возвращается expenses — сумма списаний.
Создание заказа
/advertiser/orders
Заказ уходит на модерацию
Обязательные поля
| Поле | Тип | Описание |
|---|---|---|
type | string | channel, bot, resource, folder, max_channel, max_bot |
link | string | Ссылка на ресурс (формат зависит от типа) |
max_subscribers | int | Минимум 50 |
Формат ссылок
- Telegram канал / бот / папка:
https://t.me/... - MAX канал / бот:
https://max.ru/... - Ресурс: любой валидный
https://...
Опциональные поля при создании и изменении
| Поле | Тип | Описание |
|---|---|---|
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
}'
Изменение настроек
/advertiser/orders/{order_id}
Можно менять те же параметры, что и в настройках заказа в боте. Чтобы сбросить поле в «без ограничения», передайте флаг:
reset_subscribers_per_day/reset_subscribers_per_hourreset_gender,reset_countries,reset_langs,reset_agereset_categories_excluded,reset_start_dttm,reset_schedule,reset_custom_check
Если после изменения фильтров текущая цена ниже минимума — цена поднимается автоматически.
Увеличение 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
}'
Старт, стоп и удаление
/advertiser/orders/{order_id}/stop
/advertiser/orders/{order_id}/start
/advertiser/orders/{order_id}
Запуск требует положительного баланса.
Статистика
/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}
]
}