Описание

Передайте integration token в заголовке Authorization: Bearer <token>. Канонический список находится в data.sponsors_info. Legacy TgBomber-ответ может дополнительно повторить тот же список в верхнеуровневом sponsors_info.

type=external означает произвольный внешний HTTPS-ресурс. Это не признак Яндекс Директа и не гарантия наличия ERID. Ссылка может вести на лендинг, короткую ссылку или канал, где бот AllStats не может проверить подписку. Клик и подписка на внешнем ресурсе напрямую не проверяются.

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

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

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

Поля элемента ответа

У external всегда action=open и verification_mode=selection_dependencies: статус зависит от невнешних спонсоров той же подборки. Даже status=subscribed не доказывает переход по внешней ссылке.

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

{
    "error": false,
    "message": "Resources returned.",
    "data": {
        "sponsors_info": [
            {
                "id": 33,
                "link": "https://telegram.me/channel1",
                "type": "channel",
                "status": "unsubscribed",
                "action": "subscribe",
                "verification_mode": "telegram_membership"
            },
            {
                "id": 34,
                "link": "https://example.com/offer",
                "type": "external",
                "status": "unsubscribed",
                "action": "open",
                "verification_mode": "selection_dependencies"
            }
        ]
    }
}

Коды ответов

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

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

{
    "platform": "telegram",
    "user_id": 123456789,
    "chat_id": 987654321,
    "sponsor_ids": [33, 34]
}

sponsor_ids можно не передавать — тогда проверяется последняя исторически выданная подборка. Неизвестные или не выдававшиеся этому пользователю ID возвращаются в unknown_ids.

Семантика ответа

Элементы содержат те же action и verification_mode, что и get-channels. Дополнительный статус unavailable означает, что ранее выданный заказ больше нельзя проверить. Для external повторно проверяются только невнешние зависимости исторической подборки; сама внешняя ссылка не проверяется.

Описание

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

Пример ответа (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 - Успешно получен пример вебхука

Описание

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

Код класса

from aiohttp import ClientSession, ClientTimeout
from typing import Optional

class AllStatsAPI:
    def __init__(self, base_url: str, api_key: str, timeout: int = 10):
        """
        Инициализация клиента AllStatsAPI.
        
        :param base_url: Базовый URL API AllStats.
        :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 check_sponsor_subscriptions(
        self,
        platform: str,
        user_id: int,
        chat_id: int,
        sponsor_ids: Optional[list[int]] = None,
    ):
        """Свежая проверка ранее выданных спонсоров без новой раздачи."""
        session: ClientSession = await self._get_session()
        url = f"{self.base_url}/api/check-sponsor-subscriptions"
        payload = {
            "platform": platform,
            "user_id": user_id,
            "chat_id": chat_id,
        }
        if sponsor_ids is not None:
            payload["sponsor_ids"] = sponsor_ids

        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 = AllStatsAPI(
        base_url="https://api.all-stats.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