SubLite API

Документация по API SubLite

Всё необходимое для интеграции ваших сервисов с нашей платформой.

Начало работы

API SubLite предоставляет программный доступ к функциям нашей платформы. Вы можете управлять ботами, заказами на рекламу, получать статистику и многое другое.

Все запросы к API следует отправлять на базовый URL:

https://api.sublite.org

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

Для взаимодействия с API требуется ключ аутентификации. Каждый запрос должен содержать HTTP-заголовок Auth с вашим ключом.

Существует три основных типа ключей, каждый для своих задач:

  • Ключ-доступа (Secret Key): 🔐 Ваш главный и секретный ключ для выполнения управляющих действий: создание и обновление заказов (/orders), добавление и настройка ботов (/bots).
    Как получить: в приложении @id744819489509_bot перейдите в Профиль → API → Secret Key. Никогда и никому не передавайте этот ключ!
  • Токен (API Token): 📈 Этот токен предназначен только для получения данных, таких как баланс (/get-balance) и статистика (/statistic).
    Как получить: в приложении @id744819489509_bot перейдите в Профиль → API Token.
  • Ключ бота (API Key): 🤖 Генерируется для каждого добавленного бота. Используется для запросов от имени конкретного бота: получение спонсоров (/get-sponsors) и проверка подписок (/get-user-subscriptions).
    Как получить: в приложении @id744819489509_bot перейдите в Боты → Выбираете свой бот → Интеграция.

Пример заголовка

Auth: ВАШ_СЕКРЕТНЫЙ_КЛЮЧ_ДОСТУПА

Структура ответов

Все ответы от API приходят в формате JSON. Успешные ответы и ошибки имеют стандартизированную структуру для предсказуемой обработки.

Пример успешного ответа (HTTP 200 OK)

{
                      "status": "ok",
                      "code": 200,
                      "message": "Операция прошла успешно" 
                    }

Пример ответа с ошибкой (HTTP 4xx/5xx)

{
                      "status": "error",
                      "code": 401,
                      "message": "Невалидный API токен"
                    }

Publisher API

Методы для владельцев ботов для монетизации трафика.

Получение спонсоров

POST /get-sponsors

Основной метод для запроса блока обязательной подписки. Сервис анализирует пользователя и подбирает для него наиболее релевантный список спонсоров. Аутентификация происходит по API-ключу бота в заголовке Auth.

Параметры запроса (Body, JSON)

ПараметрТипОбязательныйОписание
chat_idIntegerДаID чата, откуда идет запрос.
user_idIntegerДаID пользователя Telegram.
message_idStringДаID сообщения пользователя в Max (обязательно для извлечения данных). Как получить?
actionStringНет Тип действия:
  • subscribe (по умолчанию): Список спонсоров закрепляется за пользователем на N кол-во времени, указанное в настройках бота в сервисе.
    Проверка подписки может выполняться повторным запросом с тем же user_id
  • newtask: Список не закрепляется. При каждом новом запросе сервис будет пересобирать список спонсоров.
    Проверка подписки выполняется через метод "Проверка подписок"
max_sponsorsIntegerНетПринудительное ограничение на максимальное количество спонсоров в одном запросе (от 1 до 10).
get_linksIntegerНетЕсли 1, сервис вернет массив ссылок в поле links. По умолчанию 0.
exclude_ads_idsArray[Integer]НетID заказов из этого массива не будут выданы.
exclude_resource_idsArray[Integer]НетID ресурсво из этого массива не будут выданы.

Примеры запросов

# Пример тела запроса в формате JSON (cURL)
curl -X POST https://api.sublite.org/get-sponsors \
-H "Auth: ВАШ_API_КЛЮЧ_БОТА" \
-H "Content-Type: application/json" \
-d '{
      "user_id": 123456789,
      "chat_id": 123456789,
      "message_id": "mid.0000000003dec690019e28ac41280172"
    }'
Важно: При использовании режима get_links=0 (когда сервис сам отправляет блок обязательной подписки) к сообщению автоматически прикрепляется кнопка проверки подписки с callback-данными sublite-op. Убедитесь, что ваш бот корректно перехватывает этот callback и инициирует повторный запрос к API для подтверждения подписки (референсная реализация доступна в примерах кода ниже).

В этом режиме SubLite самостоятельно отправляет пользователю блок с обязательной подпиской, если это необходимо. Ваша задача — просто вызвать API и проверить статус. Если статус блокирующий (warning), больше ничего делать не нужно — сервис все сделает сам.


# --- Файл: utils/sublite_api.py ---
import aiohttp
import logging

API_KEY = "ВАШ_API_КЛЮЧ_БОТА"
URL = "https://api.sublite.org/get-sponsors"

async def get_sublite_sponsors(user_id: int, chat_id: int, message_id: str, **kwargs) -> dict | None:
    """Универсальная функция для запроса спонсоров."""
    headers = { "Auth": API_KEY }
    payload = { "user_id": user_id, "chat_id": chat_id, "message_id": message_id }
    payload.update(kwargs)
    
    async with aiohttp.ClientSession() as session:
        try:
            async with session.post(URL, headers=headers, json=payload, timeout=5) as response:
                result = await response.json()
                if result["status"] == 'error':
                    logging.error(f"Ошибка запроса к SubLite API: {str(result['message'])}")
                else:
                    logging.info(f"Ответ SubLite API: {str(result['message'])}")

                return result
        except Exception as e:
            logging.error(f"Ошибка запроса к SubLite API: {e}")
            return None

# --- Файл: handlers/start.py (пример обработчика) ---
from utils.sublite_api import get_sublite_sponsors
from maxapi import Bot, Dispatcher, F
from maxapi.types import BotStarted, Command, MessageCreated

BOT_TOKEN = 'TOKEN'

bot = Bot(token=BOT_TOKEN)

dp = Dispatcher()

@dp.message_created()
async def main_message_handler(event: MessageCreated):
    # Игнорируем сообщения от самого бота:
    if getattr(event.message.sender, 'bot', False): return

    user_id = event.message.sender.user_id
    chat_id = event.message.recipient.chat_id
    
    message_id = getattr(event.message.body, 'mid', None) if hasattr(event.message, 'body') else getattr(event.message, 'message_id', None)

    # Вызываем функцию для проверки подписки
    response = await get_sublite_sponsors(
        user_id=user_id,
        chat_id=chat_id,
        message_id=message_id
    )

    if response:
        status = response.get("status")
       
        if status and status == 'warning':
            # Сервис сам отправит сообщение с просьбой подписаться
            return

    await bot.send_message(chat_id=chat_id, text="✅ Доступ предоставлен!")
                
    # ... ваш код для выдачи контента ...


@dp.message_callback()
async def global_callback_handler(event: MessageCreated):
    cb_data = getattr(event.callback, 'callback_data', None) or getattr(event.callback, 'payload', None)
    
    if not cb_data:
        return

    user_id = event.callback.user.user_id
    chat_id = event.message.recipient.chat_id
    message_id = getattr(event.message.body, 'mid', None) if hasattr(event.message, 'body') else getattr(event.message, 'message_id', None)

    if cb_data == "sublite-op":
        response = await get_sublite_sponsors(
        user_id=user_id,
        chat_id=chat_id,
        message_id=message_id
        )

        if response:
            status = response.get("status")
           
            if status and status == 'warning':
                # Сервис сам отправит сообщение с просьбой подписаться
                return

        await bot.send_message(chat_id=chat_id, text="✅ Доступ предоставлен!")


        # ... ваш код для выдачи контента ...
            

// --- Файл: subliteApi.js ---
const axios = require('axios');

const API_KEY = 'ВАШ_API_КЛЮЧ_БОТА';
const URL = 'https://api.sublite.org/get-sponsors';

async function getSubliteSponsors(userId, chatId, messageId, options = {}) {
  const headers = { 
      'Auth': API_KEY,
      'Content-Type': 'application/json'
  };
  const payload = { user_id: userId, chat_id: chatId, message_id: messageId, ...options };
  
  try {
    const response = await axios.post(URL, payload, { headers, timeout: 5000 });
    const result = response.data;
    if (result.status === 'error') {
        console.error('Ошибка запроса к SubLite API:', result.message);
    } else {
        console.info('Ответ SubLite API:', result.message);
    }
    return result;
  } catch (error) {
    console.error('Ошибка запроса к SubLite API:', error.message);
    return null;
  }
}
module.exports = { getSubliteSponsors };


// --- Файл: bot.js (пример обработчика сообщений) ---
// ... инициализация бота ...
// const { getSubliteSponsors } = require('./subliteApi');

bot.on('message', async (msg) => {
    // Игнорируем сообщения от самого бота
    if (msg.from?.is_bot) return;

    const messageId = msg.message_id || msg.mid;

    // Вызываем функцию для проверки подписки
    const response = await getSubliteSponsors(msg.from.id, msg.chat.id, messageId);

    if (response) {
        const status = response.status;
        
        if (status && status === 'warning') {
            // Сервис сам отправит сообщение с просьбой подписаться
            return;
        }
    }

    await bot.sendMessage(msg.chat.id, "✅ Доступ предоставлен!");
    // ... ваш код для выдачи контента ...
});

bot.on('callback_query', async (callbackQuery) => {
    const cbData = callbackQuery.data || callbackQuery.payload;
    if (cbData === 'sublite-op') {
        const userId = callbackQuery.from.id;
        const chatId = callbackQuery.message.chat.id;
        const messageId = callbackQuery.message.message_id || callbackQuery.message.mid;

        // Отправляем повторный запрос
        const response = await getSubliteSponsors(userId, chatId, messageId);
        
        if (response) {
            const status = response.status;
            
            if (status && status === 'warning') {
                // Сервис сам отправит сообщение с просьбой подписаться
                return;
            }
        }

        await bot.sendMessage(chatId, "✅ Доступ предоставлен!");
        // ... ваш код для выдачи контента ...
    }
});
                        

<?php
// --- Файл: sublite_api.php ---
const API_KEY = "ВАШ_API_КЛЮЧ_БОТА";
const URL = "https://api.sublite.org/get-sponsors";

function getSubliteSponsors($userId, $chatId, $messageId, $options = []) {
    $payload = ['user_id' => $userId, 'chat_id' => $chatId, 'message_id' => $messageId];
    $payload = array_merge($payload, $options);
    
    $headers = [
        'Auth: ' . API_KEY,
        'Content-Type: application/json'
    ];
    
    $ch = curl_init(URL);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
    
    $response_body = curl_exec($ch);
    curl_close($ch);
    
    if ($response_body === false) {
        error_log("Ошибка запроса к SubLite API: cURL error");
        return null;
    }
    
    $result = json_decode($response_body, true);
    if ($result && isset($result['status']) && $result['status'] === 'error') {
        error_log("Ошибка запроса к SubLite API: " . ($result['message'] ?? 'Unknown error'));
    } elseif ($result) {
        error_log("Ответ SubLite API: " . ($result['message'] ?? 'ok'));
    }
    
    return $result;
}

// --- Файл: bot.php (пример обработчика вебхука) ---
// ... инициализация и функции отправки сообщений ...

$update = json_decode(file_get_contents('php://input'), true);

if (isset($update['message'])) {
    if (!empty($update['message']['from']['is_bot'])) {
        exit();
    }
    $userId = $update['message']['from']['id'];
    $chatId = $update['message']['chat']['id'];
    $messageId = $update['message']['message_id'] ?? $update['message']['mid'] ?? null;

    // Вызываем функцию для проверки подписки
    $response = getSubliteSponsors($userId, $chatId, $messageId);

    if ($response) {
        $status = $response['status'] ?? null;
        
        if ($status && $status === 'warning') {
            // Сервис сам отправит сообщение с просьбой подписаться
            exit(); 
        }
    }
    
    sendMessage($chatId, "✅ Доступ предоставлен!");
    // ... ваш код для выдачи контента ...

} elseif (isset($update['callback_query'])) {
    $callback = $update['callback_query'];
    $cbData = $callback['data'] ?? $callback['payload'] ?? null;
    
    if ($cbData === 'sublite-op') {
        $userId = $callback['from']['id'];
        $chatId = $callback['message']['chat']['id'];
        $messageId = $callback['message']['message_id'] ?? $callback['message']['mid'] ?? null;

        // Отправляем повторный запрос
        $response = getSubliteSponsors($userId, $chatId, $messageId);
        
        if ($response) {
            $status = $response['status'] ?? null;
            
            if ($status && $status === 'warning') {
                exit();
            }
        }

        sendMessage($chatId, "✅ Доступ предоставлен!");
        // ... ваш код для выдачи контента ...
    }
}
?>

В этом режиме сервис в ответ на ваш запрос отдает JSON с данными, на основе которых вы должны самостоятельно сформировать и отправить пользователю сообщение с кнопками. Этот подход требует самостоятельно выводить блок обязательной подписки


# --- Файл: utils/sublite_api.py ---
import aiohttp
import logging

API_KEY = "ВАШ_API_КЛЮЧ_БОТА"
URL = "https://api.sublite.org/get-sponsors"

async def get_sublite_sponsors(user_id: int, chat_id: int, message_id: str, **kwargs) -> dict | None:
    """Универсальная функция для запроса спонсоров."""
    headers = { "Auth": API_KEY }
    payload = { "user_id": user_id, "chat_id": chat_id, "message_id": message_id }
    payload.update(kwargs)
    
    async with aiohttp.ClientSession() as session:
        try:
            async with session.post(URL, headers=headers, json=payload, timeout=5) as response:
                result = await response.json()
                if result["status"] == 'error':
                    logging.error(f"Ошибка запроса к SubLite API: {str(result['message'])}")
                else:
                    logging.info(f"Ответ SubLite API: {str(result['message'])}")

                return result
        except Exception as e:
            logging.error(f"Ошибка запроса к SubLite API: {e}")
            return None

# --- Файл: handlers/sublite.py ---
import logging
from utils.sublite_api import get_sublite_sponsors
from maxapi import Bot, Dispatcher, F
from maxapi.types import BotStarted, Command, MessageCreated
from maxapi.types.attachments.upload import AttachmentUpload

BOT_TOKEN = 'TOKEN'

bot = Bot(token=BOT_TOKEN)

dp = Dispatcher()

async def process_sublite_check(user_id: int, chat_id: int, message_id: str):
    """Основная функция для обработки всех статусов от SubLite."""

    # На всякий случай явно указываем, что хотим получить ссылки в ответе API
    api_kwargs = {
        "get_links": 1
    }
    
    response = await get_sublite_sponsors(user_id=user_id, chat_id=chat_id, message_id = message_id, **api_kwargs)

    if response and response.get("status") and response.get("status") == "warning" and response.get("links"):

        buttons = []

        for link in response['links']:
            button = {
                "type": "link", 
                "text": "Подписаться", 
                "url": str(link)
            }

            buttons.append([button])

        done_button = {
            "type": "callback", 
            "text": "✅ Я выполнил", 
            "payload": "sublite-op"
        }

        buttons.append([done_button])
            

        keyboard = AttachmentUpload.model_construct(
            type="inline_keyboard",
            payload={
                "buttons": buttons
            }
        )


        text = "Пожалуйста, выполните задания ниже:"
        
        # Для универсальности примера вернем данные для отправки:
        return False, text, keyboard
                
    else: # ошибка запроса -> пускаем
        return True, None, None


@dp.message_created()
async def main_message_handler(event: MessageCreated):
    # Игнорируем сообщения от самого бота:
    if getattr(event.message.sender, 'bot', False): return

    user_id = event.message.sender.user_id
    chat_id = event.message.recipient.chat_id

    message_id = getattr(event.message.body, 'mid', None) if hasattr(event.message, 'body') else getattr(event.message, 'message_id', None)

    is_allowed, text, keyboard = await process_sublite_check(user_id, chat_id, message_id)

    if not is_allowed:
        await bot.send_message(chat_id=chat_id, text=text, reply_markup=keyboard)
        return

    # Даем доступ
    await bot.send_message(chat_id=chat_id, text="✅ Доступ предоставлен!")
    # ... ваш код ...

@dp.message_callback()
async def global_callback_handler(event: MessageCreated):
    cb_data = getattr(event.callback, 'callback_data', None) or getattr(event.callback, 'payload', None)
    
    if cb_data == "sublite-op":
        user_id = event.callback.user.user_id
        chat_id = event.message.recipient.chat_id
        message_id = getattr(event.message.body, 'mid', None) if hasattr(event.message, 'body') else getattr(event.message, 'message_id', None)

        is_allowed, text, keyboard = await process_sublite_check(user_id, chat_id, message_id)

        if not is_allowed:
            await bot.send_message(chat_id=chat_id, text=text, reply_markup=keyboard)
            return

        # Даем доступ
        await bot.send_message(chat_id=chat_id, text="✅ Доступ предоставлен!")
                        

// --- Файл: subliteApi.js ---
const axios = require('axios');

const API_KEY = 'ВАШ_API_КЛЮЧ_БОТА';
const URL = 'https://api.sublite.org/get-sponsors';

async function getSubliteSponsors(userId, chatId, messageId, options = {}) {
  const headers = { 
      'Auth': API_KEY,
      'Content-Type': 'application/json'
  };
  const payload = { user_id: userId, chat_id: chatId, message_id: messageId, ...options };
  
  try {
    const response = await axios.post(URL, payload, { headers, timeout: 5000 });
    const result = response.data;
    if (result.status === 'error') {
        console.error('Ошибка запроса к SubLite API:', result.message);
    } else {
        console.info('Ответ SubLite API:', result.message);
    }
    return result;
  } catch (error) {
    console.error('Ошибка запроса к SubLite API:', error.message);
    return null;
  }
}

// --- Файл: bot.js ---
// ... инициализация бота ...

async function processSubliteCheck(userId, chatId, messageId) {
    const apiOptions = { get_links: 1 };
    const response = await getSubliteSponsors(userId, chatId, messageId, apiOptions);

    if (response && response.status === "warning" && response.links && response.links.length > 0) {
        const text = "Пожалуйста, выполните задания ниже:";
        
        const inline_keyboard = response.links.map(link => [
            { text: "Подписаться", url: link }
        ]);
        
        inline_keyboard.push([
            { text: "✅ Я выполнил", callback_data: "sublite-op" }
        ]);

        return { allowed: false, text, reply_markup: { inline_keyboard } };
    }
    
    return { allowed: true };
}

bot.on('message', async (msg) => {
    if (msg.from?.is_bot) return;

    const messageId = msg.message_id || msg.mid;
    const result = await processSubliteCheck(msg.from.id, msg.chat.id, messageId);

    if (!result.allowed) {
        await bot.sendMessage(msg.chat.id, result.text, { reply_markup: result.reply_markup });
        return;
    }

    await bot.sendMessage(msg.chat.id, "✅ Доступ предоставлен!");
});

bot.on('callback_query', async (callbackQuery) => {
    const cbData = callbackQuery.data || callbackQuery.payload;
    if (cbData === 'sublite-op') {
        const userId = callbackQuery.from.id;
        const chatId = callbackQuery.message.chat.id;
        const messageId = callbackQuery.message.message_id || callbackQuery.message.mid;

        const result = await processSubliteCheck(userId, chatId, messageId);

        if (!result.allowed) {
            await bot.sendMessage(chatId, result.text, { reply_markup: result.reply_markup });
            return;
        }

        await bot.sendMessage(chatId, "✅ Доступ предоставлен!");
    }
});
                        

<?php
// --- Файл: sublite_api.php ---
const API_KEY = "ВАШ_API_КЛЮЧ_БОТА";
const URL = "https://api.sublite.org/get-sponsors";

function getSubliteSponsors($userId, $chatId, $messageId, $options = []) {
    $payload = ['user_id' => $userId, 'chat_id' => $chatId, 'message_id' => $messageId];
    $payload = array_merge($payload, $options);
    
    $headers = [
        'Auth: ' . API_KEY,
        'Content-Type: application/json'
    ];
    
    $ch = curl_init(URL);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
    
    $response_body = curl_exec($ch);
    curl_close($ch);
    
    if ($response_body === false) {
        error_log("Ошибка запроса к SubLite API: cURL error");
        return null;
    }
    
    $result = json_decode($response_body, true);
    if ($result && isset($result['status']) && $result['status'] === 'error') {
        error_log("Ошибка запроса к SubLite API: " . ($result['message'] ?? 'Unknown error'));
    } elseif ($result) {
        error_log("Ответ SubLite API: " . ($result['message'] ?? 'ok'));
    }
    
    return $result;
}


// --- Файл: bot.php ---
// ... функции sendMessage ...

function processSubliteCheck($userId, $chatId, $messageId) {
    $apiOptions = [
        "get_links" => 1
    ];
    
    $response = getSubliteSponsors($userId, $chatId, $messageId, $apiOptions);

    if ($response && ($response['status'] ?? null) === "warning" && !empty($response['links'])) {
        $text = "Пожалуйста, выполните задания ниже:";
        $keyboard = [];

        foreach ($response['links'] as $link) {
            $keyboard[] = [['text' => "Подписаться", 'url' => $link]];
        }
        $keyboard[] = [['text' => "✅ Я выполнил", 'callback_data' => "sublite-op"]];
        
        // Возвращаем результат
        return ['allowed' => false, 'text' => $text, 'keyboard' => $keyboard];
    }
    
    // error, ok или null -> пускаем
    return ['allowed' => true];
}


$update = json_decode(file_get_contents('php://input'), true);

if (isset($update['message'])) {
    if (!empty($update['message']['from']['is_bot'])) {
        exit();
    }
    $userId = $update['message']['from']['id'];
    $chatId = $update['message']['chat']['id'];
    $messageId = $update['message']['message_id'] ?? $update['message']['mid'] ?? null;

    $result = processSubliteCheck($userId, $chatId, $messageId);

    if (!$result['allowed']) {
        sendMessage($chatId, $result['text'], json_encode(['inline_keyboard' => $result['keyboard']]));
        exit();
    }

    // Даем доступ
    sendMessage($chatId, "✅ Доступ предоставлен!");
    // ... ваш код ...

} elseif (isset($update['callback_query'])) {
    $callback = $update['callback_query'];
    $cbData = $callback['data'] ?? $callback['payload'] ?? null;
    
    if ($cbData === 'sublite-op') {
        $userId = $callback['from']['id'];
        $chatId = $callback['message']['chat']['id'];
        $messageId = $callback['message']['message_id'] ?? $callback['message']['mid'] ?? null;

        $result = processSubliteCheck($userId, $chatId, $messageId);

        if (!$result['allowed']) {
            sendMessage($chatId, $result['text'], json_encode(['inline_keyboard' => $result['keyboard']]));
            exit();
        }

        // Даем доступ
        sendMessage($chatId, "✅ Доступ предоставлен!");
        // ... ваш код ...
    }
}
?>

Описание ответа

Сервер обрабатывает ваш запрос и возвращает JSON, на основе которого вы должны строить логику в боте. Возможны следующие варианты:

Статус ответаHTTP КодЧто делать
ok200 / 404Можно пропускать пользователя. Это означает, что он либо уже подписан на все ресурсы (код 200), либо для него не нашлось подходящих спонсоров (код 404).
warning200Не пропускать. Пользователю нужно выполнить действие (например, подписаться на канал).
error4xx/5xxПроизошла ошибка (неверный API-ключ, ошибка сервера и т.д.). Сообщение будет в поле message.

Пример ответа со статусом ok (доступ разрешен)

{
  "status": "ok",
  "code": 404,
  "message": "Нет подходящих рекламодателей для данного пользователя"
}

Пример ответа со статусом warning (get_links: 0)

Сервис самостоятельно отправил блок обязательной подписки пользователю. Вам просто нужно запретить ему доступ к конечному контенту.

{
  "status": "warning",
  "code": 200,
  "message": "Пользователь не подписан на один или несколько ресурсов",
  "total_links": 2
}

Пример ответа со статусом warning (get_links: 1)

Вам необходимо самостоятельно сформировать блок обязательной подписки, используя данные из массивов links или additional.sponsors.

{
  "status": "warning",
  "code": 200,
  "message": "Пользователь не подписан на один или несколько ресурсов",
  "links": [
    "https://max.ru/somechannel",
    "https://max.ru/someanotherchannel"
  ],
  "total_links": 2,
  "additional": {
    "sponsors": [
      {
        "ads_id": "123",
        "link": "https://max.ru/somechannel",
        "resource_id": "-70123456789",
        "type": "channel",
        "status": "unsubscribed",
        "available_now": true,
        "button_text": "Подписаться",
        "resource_logo": "",
        "resource_name": ""
      },
      {
        "ads_id": "124",
        "link": "https://max.ru/someanotherchannel",
        "resource_id": "-60987654321",
        "type": "resource",
        "status": "unsubscribed",
        "available_now": true,
        "button_text": "Запустить бота",
        "resource_logo": "",
        "resource_name": ""
      }
    ]
  }
}

Управление ботами

POST /bots

Эндпоинт для работы с ботами в кабинете. Возможные значения параметра action: list, info, add, update, change_api_key.

Action: add — Добавление нового бота

ПараметрТипОбязательныйОписание
actionStringДаВсегда "add".
bot_tokenStringДаТокен бота от @masterbot.
Пример запроса (add)
{
                      "action": "add",
                      "bot_token": "f9LHodD..."
                    }
Пример ответа (add)
{
                      "status": "ok",
                      "response": { 
                          "bot_id": 123,
                          "api_key": "bba3ea94-7e8c-4437-9755-aab70c18776f"
                      }
                    }

Action: update — Обновление бота

Изменяет настройки существующего бота.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "update".
bot_idIntegerДаID бота, настройки которого нужно изменить.
is_onIntegerНетВключить (1) или выключить (0) бота в системе SubLite.
in_archiveIntegerНетАрхивировать (1) или разархивировать (0) бота.
bot_tokenStringНетНовый токен бота для обновления.
statusStringНетУстановите "moderation" для повторной отправки бота после отклонения.
time_purgeIntegerНетВремя (в минутах, от 5 до 4320), на которое закеширован список спонсоров.
max_sponsorsIntegerНетКол-во спонсоров, выдаваемое пользователю (1-10).
get_linksIntegerНетПолучать только ссылки (1) или позволить отправлять блок ОП (0).
text_opStringНетКастомный текст блока ОП. null для стандартного.
image_opStringНетURL изображения для ОП. null для удаления картинки.
forbidden_themesArray[String]НетКоды запрещенных тематик (из /filters).
Пример запроса (update)
{
                      "action": "update",
                      "bot_id": 123456789,
                      "is_on": 0,
                      "bot_token": "f9LHodD...",
                      "time_purge": 60
                    }

Action: info — Получение информации

Возвращает полную информацию и настройки по указанному боту.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "info".
bot_idIntegerДаID бота, информацию о котором нужно получить.
Пример ответа (info)
{
                        "status": "ok",
                        "response": {
                            "bot_id": 123456789,
                            "bot_name": "Мой Супер Бот",
                            "bot_nickname": "MySuperBot",
                            "status": "active",
                            "note": null,
                            "is_on": 1,
                            "profit": 12345.67,
                            "profit_own_orders": 123.45,
                            "api_key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
                            "time_purge": 180,
                            "max_sponsors": 4,
                            "get_links": 0,
                            "text_op": "Для доступа к эксклюзиву, подпишись:",
                            "image_op": "https://example.com/image.jpg",
                            "forbidden_themes": ["crypto", "games"]
                        }
                    }

Action: list — Список ваших ботов

Возвращает массив добавленных ботов с возможностью пагинации.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "list".
offsetIntegerНетСмещение (по умолчанию 0).
limitIntegerНетКоличество возвращаемых записей (по умолчанию 15, максимум 20).
in_archiveIntegerНетВернуть активных (0) или удаленных/архивированных (1) ботов.
Пример ответа (list)
{
                        "status": "ok",
                        "response": {
                            "bots": [ ... массив объектов ботов аналогичных info ... ]
                        }
                    }

Action: change_api_key — Перегенерация API ключа

Создает новый API ключ для бота и возвращает его.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "change_api_key".
bot_idIntegerДаID бота.
Пример ответа (change_api_key)
{
                        "status": "ok",
                        "response": { "new_api_key": "новый-уникальный-ключ" }
                    }

Action: toggle_exclude — Исключение/Возврат спонсора

Исключает спонсора из выдачи для конкретного бота, или возвращает, если он уже исключен.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "toggle_exclude".
bot_idIntegerДаID бота.
link_idStringДаID ссылки (заказа) спонсора, которого нужно исключить.
Пример ответа (toggle_exclude)
{
                        "status": "ok",
                        "message": "Спонсор исключен"
                    }

Проверка подписок

POST /get-user-subscriptions

Позволяет проверить статус подписки конкретного пользователя на один или несколько ресурсов. Аутентификация по API-ключу бота.

Параметры запроса (Body, JSON)

ПараметрТипОбязательныйОписание
user_idIntegerДаID пользователя Telegram, чьи подписки нужно проверить.
ads_idsArray[Integer]НетМассив ID рекламных кампаний для проверки.
linksArray[String]НетМассив ссылок для проверки (как альтернатива ads_ids).
start_dateStringНетНачальная дата для выборки в формате YYYY-MM-DD.
end_dateStringНетКонечная дата для выборки в формате YYYY-MM-DD.
Примечание: Если не передать links, ads_ids и/или start_date/end_date, метод вернет все подписки пользователя за последние 30 дней.

Пример запроса

{
                      "user_id": 123456789,
                      "links": [
                        "https://max.ru/somechannel",
                        "https://max.ru/someanotherchannel"
                      ]
                    }

Пример успешного ответа (HTTP 200)

{
                      "status": "ok",
                      "code": 200,
                      "message": "Информация о подписках получена",
                      "additional": {
                        "sponsors": [
                          {
                            "ads_id": "123",
                            "link": "https://max.ru/somechannel",
                            "resource_id": "-70123456789",
                            "type": "channel",
                            "status": "subscribed",
                            "available_now": true,
                            "button_text": "Подписаться",
                            "resource_logo": "",
                            "resource_name": ""
                          },
                          {
                            "ads_id": "124",
                            "link": "https://max.ru/someanotherchannel",
                            "resource_id": "-60987654321",
                            "type": "resource",
                            "status": "unsubscribed",
                            "available_now": true,
                            "button_text": "Запустить бота",
                            "resource_logo": "",
                            "resource_name": ""
                          }
                        ]
                      }
                    }

Advertiser API

Методы для рекламодателей для управления кампаниями.

Управление заказами

POST /orders

Единый эндпоинт для создания, обновления и получения информации о ваших заказах (рекламных кампаниях). Аутентификация происходит по вашему ключу-доступа (Secret Key), переданному в заголовке Auth.
В теле запроса обязательно должно быть поле action, которое определяет действие.

Action: create — Создание заказа

Создает новую рекламную кампанию и отправляет ее на модерацию.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "create".
linkStringДаПолная ссылка на ресурс (https://max.ru/...).
ads_typeStringДаТип заказа: channel или resource.
channel - чат/канал в макс где добавлен бот в администраторы, т.е. есть проверка на проверку/отписку.
resource - любая ссылка, где нет проверки на подписку и не требуется добавлять бота в администраторы.
nameStringНетНазвание заказа. По умолч.: "Новый заказ".
is_onIntegerНетЗапустить ли заказ сразу после модерации (1) или оставить на паузе (0). По умолч.: 1.
quantity_allIntegerДаОбщее желаемое количество подписчиков (10-10,000,000).
quantity_dayIntegerНетДневной лимит подписчиков. По умолч. равен quantity_all.
priceFloatНетБазовая цена за обычного подписчика (до применения коэффициентов). Если не указана, будет установлена стандартная.
track_unsubscriptionsIntegerНетОтслеживать отписки (1) или нет (0). Применимо только для ads_type = channel. По умолч.: 1.
is_liteIntegerНетАктивировать плавное распределение вступлений в течение дня (1) или получать подписчиков максимально быстро (0). По умолч.: 0.
sub_speedIntegerНетСкорость вступлений в час. Имеет смысл только если is_lite: 1.
fixationIntegerНетЧастота фиксаций подписчиков. Имеет смысл только если track_unsubscriptions: 1 и ads_type: channel
  • 1 - 1 раз в неделю (вск-пн) (х1.4 к цене)
  • 2 - 2 раза в неделю (ср-чт, вск-пн) (х1.2 к цене)
  • 3 - 3 раза в неделю (вт-ср, чт-пт, вск-пн) (без наценки)
  • 4 - 7 раз в неделю (ежедневно) (х0.8 к цене)
По умолч.: 3.
placesIntegerНетМеста показов заказа.
  • 0 - В своих ботах
  • 1 - В чужих ботах
  • 2 - В своих и чужих ботах
По умолч.: 2.
user_parametersObjectНетОбъект с параметрами таргетинга. Описание полей см. в таблице ниже. Дополнительную информацию о коэффициентах и зависимостях параметров можно получить из эндпоинта /parameters.
forbidden_themesArray[String]НетМассив кодов категорий ботов для исключения. Коды можно получить из /filters.
start_showStringНетОтложенный запуск. Дата и время в формате "YYYY-MM-DD HH:MM:SS".
start_timeStringНетВремя начала показов ежедневно. Формат "HH:MM".
end_timeStringНетВремя окончания показов ежедневно. Формат "HH:MM".
to_sheduleIntegerНетИспользовать расписание (1) или нет (0).
schedule_daysArray[Integer]НетМассив дней недели ДЛЯ ПОКАЗОВ (где 1=Понедельник, ..., 7=Воскресенье). Если передано, в остальные дни показов не будет.
Структура объекта user_parameters
ПараметрТипОписание и Коэффициенты
genderStringПол: male, female, all. По умолч.: "all".
has_first_nameIntegerТребовать наличие имени (1 - да, 0 - не важно). Коэффициент к цене: x1.1
has_ru_nameIntegerТребовать наличие ру имени (1 - да, 0 - не важно). Коэффициент к цене: x1.1
has_rus_nameIntegerТребовать наличие русского имени (1 - да, 0 - не важно). Коэффициент к цене: x1.1
has_only_cyrillicIntegerТребовать наличие только кириллице в имени (1 - да, 0 - не важно). Коэффициент к цене: x1.1

Action: update — Обновление заказа

Изменяет параметры существующего заказа.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "update".
order_idIntegerДаID заказа, который вы хотите обновить.
...все параметры, доступные при create (кроме ads_type, link, quantity_all), можно передать для обновления...

Action: info — Получение информации о заказе

Возвращает текущие данные заказа.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "info".
order_idIntegerДаID заказа.

Action: list — Список ваших заказов

Возвращает список ваших последних добавленных заказов по их статусу.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "list".
offsetIntegerНетКоличество заказов для пропуска (для пагинации). По умолчанию: 0.
limitIntegerНетКоличество заказов для возврата. По умолчанию: 15.
in_archiveIntegerНетИскать ли в архиве. 1 — в архиве, 0 — активные. По умолчанию: 0.

Action: duplicate — Создание копии заказа

Копирует существующий заказ в новый с теми же настройками.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "duplicate".
order_idIntegerДаID заказа для дублирования.

Action: resubmit — Переотправить отклоненный заказ на модерацию

Возвращает статус "Moderation" для заказа со статусом "Rejected".

ПараметрТипОбязательныйОписание
actionStringДаВсегда "resubmit".
order_idIntegerДаID отклоненного заказа.

Action: not_working — Диагностика, почему заказ не работает

Возвращает массив причин (reasons), если у активного заказа медленно идут подписчики или он простаивает.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "not_working".
order_idIntegerДаID заказа, который проверяем.

Action: report — Заказать генерацию отчета по заказу

Запускает асинхронную генерацию отчета. Возвращает task_id, который можно проверять.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "report".
order_idIntegerДаID заказа для отчета.
time_rangeStringНетВременной промежуток. Допустимые значения: 'today', '3days', '7days', 'all'. По умолч.: 'all'
include_priceBooleanНетВключает столбец с финансовыми данными, если true. По умолч.: false

Action: check_report — Проверить статус генерации отчета

Проверяет состояние задачи отчета, запущенной через метод report.

ПараметрТипОбязательныйОписание
actionStringДаВсегда "check_report".
task_idStringДаУникальный ID задачи, полученный из предыдущего запроса report.

Примеры и Ответы

Пример запроса на создание (create)
{
                      "action": "create",
                      "link": "https://max.ru/somechannel",
                      "ads_type": "channel",
                      "name": "Тестовый заказ через API",
                      "quantity_all": 1000,
                      "price": 12,
                      "user_parameters": {
                        "gender": "male",
                        "has_first_name": 1
                      },
                      "to_shedule": 1,
                      "start_time": "09:00",
                      "end_time": "22:00",
                      "schedule_days": [1, 2, 3, 4, 5]
                    }
Пример ответа на создание (create)
{
                      "status": "ok",
                      "code": 200,
                      "message": "Заказ успешно создан и отправлен на модерацию",
                      "response": {
                        "order_id": 12345
                      }
                    }
Пример ответа на получение информации (info)

Ответ включает все параметры заказа, текущий прогресс, а также итоговые цены и примененные коэффициенты.

ПолеТипОписание
order_idIntegerID заказа.
statusString Текущий статус заказа:
  • Moderation — На модерации.
  • Processing — Активен и выполняется.
  • Stopped — Остановлен вручную.
  • Finished — Заказ выполнен (достигнут лимит quantity_all).
  • Rejected — Отклонен модератором.
  • Archived — Перемещен в архив (удален).
reasonStringПричина отклонения (только для статуса Rejected).
link, name, ......Все остальные параметры, переданные при создании/обновлении.
followersIntegerТекущее количество выполненных подписок всего.
followers_todayIntegerТекущее количество выполненных подписок за сегодня.
offered_priceFloatБазовая цена за подписчика, указанная вами (до применения коэффициентов).
real_priceFloatИтоговая реальная цена за подписчика после применения всех коэффициентов.
user_parametersObjectОбъект с примененными настройками таргетинга.
coefficientsObjectОбъект, в котором перечислены все примененные коэффициенты и их значения. Содержит ключ total с итоговым множителем.
 
{
                        "status": "ok",
                        "response": {
                            "id": 12345,
                            "user_id": 999,
                            "link": "https://max.ru/somechannel",
                            "name": "Тестовый заказ через API",
                            "ads_type": "channel",
                            "old_price": 12.0,
                            "price": 13.2,
                            "quantity_day": 1000,
                            "quantity_all": 1000,
                            "places": 2,
                            "is_lite": 0,
                            "sub_speed": null,
                            "track_unsubscriptions": true,
                            "fixation": 3,
                            "status": "moderation",
                            "is_on": 1,
                            "followers": 150,
                            "followers_today": 150,
                            "in_archive": 0,
                            "start_show": null,
                            "start_time": "09:00:00",
                            "end_time": "22:00:00",
                            "to_schedule": 1,
                            "schedule_days": [1, 2, 3, 4, 5],
                            "user_parameters": {
                                "gender": "male",
                                "has_first_name": 1,
                                "has_ru_name": 0,
                                "has_rus_name": 0,
                                "has_only_cyrillic": 0
                            },
                            "forbidden_themes": []
                        }
                    }

Возможные ошибки

HTTP КодКод ошибки (error_code)Описание
400price_too_lowУказанная price ниже минимально допустимой.
400invalid_parameterПередан неверный параметр, например, track_unsubscriptions для заказа типа resource.
403forbidden_or_not_foundЗаказ не найден или вы не являетесь его владельцем (при update или info).
409update_forbiddenПопытка изменить поле, которое нельзя менять (например, ссылку в заказе, где уже есть подписчики).
409rejected, exist, moderationКонфликт при создании: ссылка уже отклонена, существует или на модерации.
422-Ошибка валидации данных. В поле message будет подробное описание.

Общие методы API

Эндпоинты, доступные разным типам пользователей.

Получение баланса

POST /get-balance

Возвращает текущий баланс аккаунта и краткую сводку по всем подключенным ботам. Аутентификация по токену пользователя.

Этот метод не требует параметров в теле запроса.

Пример успешного ответа (HTTP 200)

{
                      "status": "ok",
                      "code": 200,
                      "message": "Баланс и информация о ботах успешно получена",
                      "balance": 219.21,
                      "bots_info": [
                        {
                          "bot_id": 12345678,
                          "bot_username": "my_super_bot",
                          "total_followers": 60667,
                          "revenue": 120542.45
                        }
                      ]
                    }

Получение фильтров

GET /filters

Возвращает полный список всех доступных значений для настройки таргетинга в заказах (Advertiser API) и для исключения тематик в настройках ботов (Publisher API).

Примечание: Этот эндпоинт является публичным и не требует аутентификации.

Параметры запроса

Этот метод не требует параметров в теле запроса или в URL.

Пример запроса (cURL)

curl -X GET https://api.sublite.org/filters

Пример ответа (HTTP 200)

{
                      "filters": {
                        "ads": {
                          "countries": [
                            { "id": 1, "name": "Россия", "percentage": 75.4 },
                            { "id": 2, "name": "Украина", "percentage": 8.1 }
                          ],
                          "languages": [
                            { "id": 1, "name": "Русский", "percentage": 89.2 },
                            { "id": 2, "name": "Украинский", "percentage": 5.5 }
                          ],
                          "cities": [
                            { "id": 101, "name": "Москва", "percentage": 25.0 },
                            { "id": 102, "name": "Санкт-Петербург", "percentage": 12.3 }
                          ],
                          "ages": [
                            { "id": 5, "name": "18 - 24", "percentage": 40.5 },
                            { "id": 6, "name": "25 и старше", "percentage": 30.1 }
                          ],
                          "devicestype": [
                            { "id": "mobile", "name": "Смартфон/Планшет", "percentage": 92.3 },
                            { "id": "desktop", "name": "Компьютер/Ноутбук", "percentage": 7.7 }
                          ],
                          "devicesos": [
                            { "id": 1, "name": "Android", "percentage": 65.4 },
                            { "id": 2, "name": "iOS", "percentage": 25.1 }
                          ],
                          "forbidden_themes": [
                            { "id": "stars", "name": "Старсы/NFT", "percentage": 15.8 },
                            { "id": "adult", "name": "18+", "percentage": 10.2 }
                          ]
                        },
                        "bots": {
                          "forbidden_themes": [
                            { "id": "news", "name": "Новости", "percentage": 5.3 },
                            { "id": "useful", "name": "Полезное", "percentage": 12.1 }
                          ]
                        }
                      }
                    }

Описание полей ответа

ПолеТипОписание
filtersObjectКорневой объект, содержащий все фильтры.
filters.adsObjectОбъект с фильтрами, применимыми к заказам (Advertiser API).
filters.ads.*Array[Object]Массивы объектов для каждого типа фильтра (countries, languages, ages и т.д.).
filters.botsObjectОбъект с фильтрами, применимыми к настройкам ботов (Publisher API).
filters.bots.forbidden_themesArray[Object]Массив тематик рекламы, которые можно запретить к показу в ваших ботах.
Структура объекта в массивах
idInteger/StringУникальный идентификатор значения (например, ID страны или код категории), который нужно использовать при создании/обновлении заказов и ботов.
nameStringЧеловекочитаемое название значения (например, "Россия" или "Криптовалюта").
percentageFloatПримерная доля этого параметра среди всех пользователей в системе SubLite. Помогает оценить, насколько сильно фильтр сузит аудиторию.

Получение дополнительных параметров

GET /parameters

Возвращает информацию о дополнительных параметрах (наличие фото, возраст аккаунта и т.д.), их коэффициентах к цене и автоматически включаемых параметрах.

Примечание: Этот эндпоинт является публичным и не требует аутентификации.

Параметры запроса

Этот метод не требует параметров в теле запроса или в URL.

Пример запроса (cURL)

curl -X GET https://api.sublite.org/parameters

Пример ответа (HTTP 200)

{
  "parameters": [
    {
      "id": "has_photo",
      "name": "Наличие фото",
      "type": "boolean",
      "price_multiplier": 1.1,
      "enables_automatically": []
    },
    {
      "id": "old_account",
      "name": "Возраст аккаунта",
      "type": "enum",
      "values": [
        {
          "value": 1,
          "label": ">= 2 лет",
          "price_multiplier": 1.1
        }
      ]
    }
  ]
}

Описание полей ответа

ПолеТипОписание
parametersArray[Object]Массив объектов с информацией о параметрах.
idStringУникальный идентификатор параметра.
nameStringЧеловекочитаемое название параметра.
typeStringТип параметра (boolean, enum, array).
price_multiplierFloat/NullКоэффициент, на который умножается цена при активации параметра.
enables_automaticallyArray[String]Массив ID параметров, которые автоматически включаются при активации текущего.
valuesArray[Object](Только для enum или array) Возможные значения параметра и их коэффициенты.

Получение статистики

GET /statistic

Универсальный эндпоинт для получения статистики как по доходам (для владельцев ботов), так и по расходам (для рекламодателей). Аутентификация происходит по токену пользователя, переданному в query-параметре api_token.

Параметры запроса (Query)

ПараметрТипОбязательныйОписание
api_tokenStringДаВаш основной токен пользователя.
actionStringДа Тип запрашиваемой статистики:
  • Для рекламодателей: allads, ads, source.
  • Для владельцев ботов: allbots, bots, sponsor.
ads_idIntegerНетID заказа (обязателен для action=ads и action=source).
bot_idIntegerНетID бота (обязателен для action=bots и action=sponsor для одного бота).
start_dateStringНетНачальная дата (YYYY-MM-DD). По умолч.: 9 дней назад.
end_dateStringНетКонечная дата (YYYY-MM-DD). По умолч.: сегодня.
output_formatStringНетФормат ответа: html (для веб-страницы) или json (для API).

Пример URL запроса

https://api.sublite.org/statistic?api_token=ВАШ_ТОКЕН&action=allads&output_format=json

Описание полей ответа (для output_format=json)

Ответ содержит объект data, структура которого зависит от параметра action.

ПолеТипОписание
Общие поля (для action=ads/allads/bots/allbots)
data.labelsArray[String]Массив меток (дат) для оси X на графике.
data.subscribers_dataArray[Integer]Массив данных о количестве подписок для каждой даты.
data.value_dataArray[Float]Массив данных о расходах/доходах для каждой даты.
data.avg_price_dataArray[Float]Массив данных о средней цене подписчика для каждой даты.
data.total_subscribersIntegerИтоговое количество подписок за период.
data.total_valueFloatИтоговые расходы/доходы за период.
Поля для action=source / sponsor
data.table_dataArray[Object]Массив объектов для построения таблицы. Структура зависит от action:
• Для source: bot_id, bot_nickname, subscribers, value, is_excluded.
• Для sponsor: link, ads_id, subscribers, is_excluded.
Дополнительные поля для action=bots/allbots
data.show_extended_tableBooleantrue, если у бота были подписки со "своих" заказов, что активирует расширенную таблицу.
data.table_dataArray[Object]Содержит массив данных для таблицы. Включает date, total_sub_count_formatted (кол-во всех людей подавших заявку), total_unsub_count_formatted (кол-во отписавшихся/заблокировавших). Если show_extended_table равно true, объекты также будут содержать детальную разбивку: service_subs, service_value, own_subs, own_value и т.д.
data.requests_statsObjectОбъект со статистикой по API-запросам к вашему боту. Включает total_requests, successful_requests и др.
Дополнительные поля для action=ads
data.language_statsArray[Object]Массив объектов со статистикой по языкам привлеченных пользователей. Пример: {"lang": "ru", "percentage": "85.4%"}.

Управление исключениями

POST /toggle-exclusion

Универсальный эндпоинт для управления "черными списками". Позволяет как рекламодателям исключать нежелательные источники трафика (ботов), так и владельцам ботов исключать нежелательных спонсоров.

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

Этот метод использует аутентификацию по токену пользователя, который необходимо передать как query-параметр. 

POST /toggle-exclusion?api_token=ВАШ_ОСНОВНОЙ_API_ТОКЕН

Параметры запроса (Body, JSON)

ПараметрТипОбязательныйОписание
actionStringДаДействие, которое нужно выполнить:
  • exclude: Добавить в черный список.
  • activate: Убрать из черного списка.
contextStringДа Определяет логику работы. Ключевой параметр:
  • advertiser: Режим для рекламодателя. Вы исключаете бота из показа для своего заказа.
  • publisher: Режим для владельца бота. Вы исключаете спонсора из показа в ваших ботах.
ads_idIntegerДаID заказа. В зависимости от контекста это либо ваш заказ, который вы настраиваете, либо заказ спонсора, которого вы блокируете.
bot_idIntegerУсловно*ID бота. *Обязателен, если context равен advertiser. Для publisher он опционален (см. примеры).

Сценарии использования и примеры

Пример 1: Рекламодатель исключает бот из своей кампании

Вы (рекламодатель) хотите, чтобы ваш заказ с ID 12345 больше никогда не показывался в боте с ID 98765.

{
                      "action": "exclude",
                      "context": "advertiser",
                      "ads_id": 12345,
                      "bot_id": 98765
                    }
Пример 2: Владелец бота исключает спонсора (локально)

Вы (владелец бота) хотите, чтобы спонсор с ID заказа 54321 больше не показывался в конкретно вашем боте с ID 888777.

{
                      "action": "exclude",
                      "context": "publisher",
                      "ads_id": 54321,
                      "bot_id": 888777
                    }
Пример 3: Владелец бота исключает спонсора (глобально)

Вы (владелец бота) хотите, чтобы спонсор с ID заказа 54321 больше не показывался ни в одном из ваших ботов.

Для глобального исключения просто не передавайте параметр bot_id.
{
                      "action": "exclude",
                      "context": "publisher",
                      "ads_id": 54321
                    }

Ответы

Пример успешного ответа (HTTP 200)
{
                      "status": "ok",
                      "message": "Ресурс успешно исключен."
                    }

В случае успеха вы получите простое подтверждение. В случае ошибок (неверный токен, отсутствие прав на управление ресурсом) будет возвращен стандартный ответ с ошибкой и соответствующим HTTP-кодом (401, 403, 404).