API-архитектура SmmPanelUS: Полная спецификация интеграции v2

Мы не предоставляем «услуги продвижения» в маркетинговом смысле. Мы предоставляем транзакционный инструмент обмена. SmmPanelUS функционирует как Execution Layer (Уровень Исполнения), принимающий стандартизированные запросы и распределяющий их по узлам исполнения.

Интеграция требует строгого соблюдения Rate Limiting и валидации данных на вашей стороне. В отличие от веб-интерфейса, API не прощает синтаксических ошибок. Любое нарушение формата данных приведет к отказу (Request Denial) на уровне входного фильтра. Это инженерный инструмент: вы отправляете JSON-payload, система ставит его в очередь, провайдер исполняет.

Архитектурная суть: Это атомарные транзакции. Запрос либо принят и списан с баланса, либо отвергнут. Промежуточных состояний «наполовину создан» не существует.

1. Базовый протокол и аутентификация

Взаимодействие происходит через HTTP POST запросы к единой точке входа. Архитектура не является классическим RESTful сервисом, это RPC-over-HTTP. Все действия определяются параметром `action`.

• Endpoint: `https://smmpanelus.com/api/v2`
• Content-Type: `application/json`
• Auth: Параметр `key` (Ваш API Token) обязателен для каждого запроса.

2. Discovery: Получение списка услуг

Перед созданием заказа ваша система должна знать актуальные ID и параметры услуг. Метод `action=services` возвращает полный каталог. Мы рекомендуем кэшировать этот ответ (Redis/Memcached) с TTL минимум 24 часа, а не запрашивать его перед каждым заказом.

// Request
{
    "key": "YOUR_API_KEY",
    "action": "services"
}

// Response Example
[
    {
        "service": 1,
        "name": "Followers HQ",
        "type": "Default",
        "category": "Instagram",
        "rate": "0.90", // Стоимость за 1000
        "min": "50",
        "max": "10000",
        "refill": true, // Доступность авто-восстановления
        "cancel": true  // Возможность отмены
    }
]

Категоризация трафика (Routing Categories)

Параметр `type` определяет логику маршрутизации и необходимые поля:

3. Transaction: Создание заказа

Метод `add` инициирует списание средств и постановку задачи в очередь.

Спецификация параметров

Drip-feed Архитектура

Если требуется растянуть выполнение во времени, используйте параметры `runs` и `interval`. Общий объем заказа рассчитывается формулой:

$$ TotalQuantity = Quantity \times Runs $$

// Response (Success)
{
    "order": 23501 // Сохраните этот ID для отслеживания
}

4. Monitoring: Статусы и Жизненный Цикл

Самая ресурсоемкая операция — проверка статусов. Использование одиночного метода `status` в цикле — архитектурная ошибка, которая приведет к блокировке по WAF.

Определения статусов (Lifecycle States)

• Pending: Заказ в очереди на отправку провайдеру.
• In progress: Провайдер принял заказ, идет выполнение.
• Completed: Выполнено.
• Partial: Частичное выполнение. Деньги за недоставленный остаток (`remains`) возвращены на баланс.
• Canceled: Заказ отменен, полный возврат средств.
• Processing: Промежуточный статус обработки.

Multi-Status (Best Practice)

Используйте `action=multi_status`, передавая до 100 ID заказов через запятую. Это снижает нагрузку на сеть в 100 раз.

// Request
{
    "key": "API_KEY",
    "action": "multi_status",
    "orders": "1, 10, 100"
}

// Response
{
    "1": {
        "charge": "0.27819",
        "start_count": "3572", // Счетчик на момент старта
        "status": "Partial",   // Частичное выполнение
        "remains": "157",      // Остаток (деньги за него возвращены)
        "currency": "USD"
    },
    "10": {
        "error": "Incorrect order ID"
    }
}

5. Advanced Lifecycle: Refill и Cancel

Управление сложными состояниями (восстановление, отмена) также поддерживает массовые операции.

Multi-Refill

Создание задач на восстановление для списка заказов.

// Request
{
    "key": "API_KEY",
    "action": "multi_refill",
    "orders": "1, 2, 3"
}

// Response
[
    {
        "order": 1,
        "refill": 1 // ID задачи на восстановление
    },
    {
        "order": 2,
        "refill": { "error": "Incorrect order ID" }
    },
    {
        "order": 3,
        "refill": { "error": "Refill not available for this service" } 
    }
]

Multi-Cancel

Попытка массовой отмены. Важно: Успешный запрос не гарантирует отмену, он гарантирует попытку отмены.

// Request
{
    "key": "API_KEY",
    "action": "cancel",
    "orders": "1, 99"
}

// Response
[
    {
        "order": 1,
        "cancel": 1 // Успешно принят запрос на отмену
    },
    {
        "order": 99,
        "cancel": { "error": "Order is already completed" }
    }
]

6. Финансы: Проверка баланса

Для автоматизации биллинга используйте метод `balance`. Рекомендуется вызывать его не чаще раза в 5-10 минут или после серии крупных заказов.

// Request
{
    "key": "API_KEY",
    "action": "balance"
}

// Response
{
    "balance": "100.84292",
    "currency": "USD"
}

7. API Error Codes Reference (Troubleshooting Guide)

В распределенных системах ошибки — это норма. Ваш клиент должен обрабатывать их, не обрушивая весь пайплайн. Ответы сервера обычно имеют HTTP Status 200 OK, но содержат поле `error` в JSON теле.

Таблица кодов ошибок (API Error Codes)

Code Pattern: Python Wrapper

Пример надежной реализации запроса с обработкой таймаутов.

import requests
import json

class SmmPanelAPI:
    def __init__(self, api_key, base_url="https://smmpanelus.com/api/v2"):
        self.key = api_key
        self.url = base_url

    def _post(self, payload):
        payload['key'] = self.key
        try:
            # Жесткий таймаут: 5с на соединение, 30с на чтение
            response = requests.post(self.url, json=payload, timeout=(5, 30))
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            # Логирование ошибки сети
            print(f"Network Error: {e}")
            return None

    def add_order(self, service_id, link, quantity):
        return self._post({
            "action": "add",
            "service": service_id,
            "link": link,
            "quantity": quantity
        })

    def get_multi_status(self, order_ids):
        # order_ids -> list of integers
        ids_str = ",".join(map(str, order_ids))
        return self._post({
            "action": "multi_status",
            "orders": ids_str
        })

8. Разграничение ответственности

Мы предоставляем транспортный уровень. Мы гарантируем, что валидный запрос будет принят и передан в сеть исполнения. Однако:

• Мы не контролируем алгоритмы конечных платформ (Instagram, TikTok и др.).
• Мы не валидируем качество ваших ссылок (закрытые профили, гео-блокировки — ответственность клиента).
• Скорость выполнения зависит от текущей загрузки глобальных шлюзов.

9. FAQ: Часто задаваемые технические вопросы

Является ли API идемпотентным?
Нет. API не поддерживает идемпотентность по умолчанию. Если вы отправите запрос `add` дважды с одинаковыми параметрами, система создаст два разных заказа и спишет средства дважды. Реализуйте защиту от дублей на своей стороне (например, генерируя уникальные Transaction ID и проверяя их перед отправкой).

Какой Rate Limit установлен на шлюзе?
Мы не публикуем жесткие цифры во избежание эксплойтов, но WAF настроен на блокировку аномальной активности. Рекомендуемая частота поллинга статусов — 1 раз в 15-20 минут (используйте `multi_status`). Одиночные запросы чаще 1 раза в секунду могут привести к временному бану IP.

Это RESTful API?
Технически — нет. Это JSON-RPC архитектура, реализованная поверх HTTP. Мы используем один URL для всех операций, а тип действия определяется параметром `action` в теле запроса, а не HTTP-методом.

Можно ли безопасно делать Retry при ошибке сети?
Только если вы не получили ответ от сервера (timeout). Если получен любой ответ (даже 5xx или JSON с ошибкой), повторная отправка без проверки статуса заказа может привести к дублированию. Сначала проверьте последние заказы через `action=status`.

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