Описание

Данный endpoint принимает информацию о пользователе и возвращает список рекомендуемых спонсорских каналов, которые соответствуют его демографии и интересам.

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

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

{
    "user_id": 123456789,
    "first_name": "Иван",
    "country": "Russia",
    "language_code": "ru",
    "age": 25,
    "gender": "m"
}

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

{
    "sponsors_info": [
        {
            "channel_name": "Канал 1",
            "channel_link": "https://t.me/channel1",
            "subscribers_count": 50000
        },
        {
            "channel_name": "Канал 2",
            "channel_link": "https://t.me/channel2",
            "subscribers_count": 120000
        }
    ]
}

Коды ответов

• 200 - Успешно получен список каналов
• 400 - Некорректные входные данные
• 401 - Ошибка аутентификации (неверный token)
• 404 - Подходящие каналы не найдены

Описание

Возвращает отсортированный список всех регионов, для которых доступны данные о городах.

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

{
    "regions": [
        "Altai",
        "Altai_Krai",
        "Amur_Oblast",
        "Arkhangelskaya",
        "Moscow",
        "Moscow_Oblast",
        "St.-Petersburg"
    ]
}

Коды ответов

• 200 - Успешно получен список регионов

Описание

Возвращает отсортированный список всех городов из всех регионов.

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

{
    "cities": [
        "Abakan",
        "Aksay",
        "Altaysk",
        "Anadyr",
        "Arkhangelsk",
        "Astrakhan",
        "Azov"
    ]
}

Коды ответов

• 200 - Успешно получен список городов

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

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

{
    "region": "Moscow"
}

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

{
    "cities": [
        "Altufyevskiy",
        "Begovoy",
        "Bibirevo",
        "Butyrskiy",
        "Dorogomilovo",
        "Krasnopresnenskiy",
        "Moscow",
        "Vorobyovy Gory",
        "Zyablikovo",
        "Zyuzino"
    ]
}

Коды ответов

• 200 - Успешно получен список городов (может быть пустым)

Описание

Используйте этот эндпоинт для тестирования и разработки обработчика вебхуков. Он возвращает пример структуры данных, которые система будет отправлять на ваш URL при подписке/отписке пользователя от спонсора.

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

{
    "event_type": "subscription",
    "user_id": 123456789,
    "channel_id": 987654321,
    "timestamp": "2025-02-02T10:30:00Z",
    "status": "subscribed"
}

Коды ответов

• 200 - Успешно получен пример вебхука

Описание

Класс TgBombersAPI предоставляет удобный асинхронный интерфейс для работы с Integration API. Он автоматически управляет сессиями, аутентификацией и обработкой запросов.

Код класса

from aiohttp import ClientSession, ClientTimeout
from typing import Optional

class TgBombersAPI:
    def __init__(self, base_url: str, api_key: str, timeout: int = 10):
        """
        Инициализация клиента TgBombersAPI.
        
        :param base_url: Базовый URL API TgBombers.
        :param api_key: API ключ для аутентификации.
        :param timeout: Таймаут для запросов.
        """
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.session: Optional[ClientSession] = None
        self.timeout = ClientTimeout(total=timeout)
        
    async def _get_session(self) -> ClientSession:
        """Получение или создание сессии aiohttp."""
        if self.session is None:
            headers = {
                "Content-Type": "application/json",
            }
            
            if self.api_key:
                headers["Authorization"] = f"Bearer {self.api_key}"
            
            self.session = ClientSession(
                headers=headers,
                timeout=self.timeout
            )
            
        return self.session

    async def _close_session(self):
        """Закрытие сессии aiohttp."""
        if self.session:
            await self.session.close()
            
            self.session = None

    async def __aenter__(self):
        """Вход в контекстный менеджер."""
        await self._get_session()
        return self

    async def __aexit__(self, exc_type, exc, tb):
        """Выход из контекстного менеджера."""
        await self._close_session()

    async def get_channels(self, user_id: int, chat_id: int):
        """
        Получение каналов для указанного пользователя и чата.
        
        :param user_id: ID пользователя.
        :param chat_id: ID чата.
        :return: Ответ API в формате JSON.
        """
        session: ClientSession = await self._get_session()
        
        url = f"{self.base_url}/api/get-channels"
        
        payload = {
            "user_id": user_id,
            "chat_id": chat_id
        }
        
        async with session.post(url, json=payload) as response:
            return await response.json()
        
    async def get_cities(self):
        """
        Получение списка городов.
        
        :return: Ответ API в формате JSON.
        """
        session: ClientSession = await self._get_session()
        
        url = f"{self.base_url}/api/cities"
    
        async with session.get(url) as response:
            return await response.json()
    
    async def get_regions(self):
        """
        Получение списка всех поддерживаемых регионов.
        
        :return: Ответ API в формате JSON.
        """
        session: ClientSession = await self._get_session()
        
        url = f"{self.base_url}/api/regions"
        
        async with session.get(url) as response:
            return await response.json()
    
    async def get_cities_by_region(self, region: str):
        """
        Получение списка городов в указанном регионе.
        
        :param region: Название региона.
        :return: Ответ API в формате JSON.
        """
        session: ClientSession = await self._get_session()
        
        url = f"{self.base_url}/api/cities-by-region"
        
        payload = {
            "region": region
        }
        
        async with session.post(url, json=payload) as response:
            return await response.json()

Пример использования

import asyncio

async def main():
    api = TgBombersAPI(
        base_url="https://api.tgbombers.ru",
        api_key="your_api_key"
    )
    
    async with api:
        # Получить каналы
        channels = await api.get_channels(user_id=123456789, chat_id=987654321)
        print(channels)
        
        # Получить регионы
        regions = await api.get_regions()
        print(regions)
        
        # Получить города
        cities = await api.get_cities()
        print(cities)
        
        # Получить города в регионе
        moscow_cities = await api.get_cities_by_region("Moscow")
        print(moscow_cities)

asyncio.run(main())

Требуемые зависимости

pip install aiohttp