API Smmplan: Подробное руководство для реселлеров

Программный интерфейс (API) Smmplan предоставляет B2B-клиентам и реселлерам мощные инструменты для автоматизации процессов заказа SMM-услуг. Интеграция по API позволяет вашей платформе, интернет-магазину или Telegram-боту напрямую взаимодействовать с нашим каталогом, отправлять задания в работу, получать актуальные статусы и контролировать баланс без ручного участия администратора.

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

1. Авторизация и безопасность

Все запросы к API Smmplan требуют аутентификации. Для получения доступа перейдите в раздел «Настройки API» в личном кабинете и сгенерируйте уникальный API-ключ.

Для выполнения запроса необходимо передавать два основных параметра в теле запроса (POST) или в качестве query-параметров (GET):

• `key`: ваш секретный API-ключ.
• `action`: название вызываемого метода (например, `services`, `add`, `status`, `balance`).

Требование безопасности: API-ключ жестко привязан к вашему аккаунту и финансовому балансу. Храните его исключительно в защищенном хранилище переменных окружения (например, `.env`) на стороне вашего бэкенд-сервера. Прямая передача ключа через фронтенд-приложения (React, Vue) или мобильные клиенты приведет к его немедленной компрометации и финансовым потерям.

2. Получение списка услуг и архитектура Shadow Catalog

Для синхронизации вашей витрины с ассортиментом Smmplan используйте метод получения каталога.

Запрос:

```http

POST /api/v1

Content-Type: application/json

{

"key": "ВАШ_API_КЛЮЧ",

"action": "services"

}

```

Ответ: Возвращает JSON-массив объектов. Каждый объект содержит `service` (внутренний идентификатор услуги в Smmplan), `name` (наименование), `type` (тип: Default, Custom Comments и т.д.), `rate` (цена за 1000 единиц), `min` и `max` (лимиты), `category` (категориальная принадлежность).

Рекомендуемая архитектура интеграции каталога

Крайне не рекомендуется реализовывать прямую запись всего объема получаемых услуг (Mass Sync) в вашу реляционную базу данных (например, PostgreSQL). Рекомендуется применять паттерн Shadow Catalog (Теневой буфер):

1. Буферизация: Сохраняйте ответ метода `services` во временное In-Memory хранилище (например, Redis по ключу `provider:smmplan:catalog`).

2. Cherry-Pick Импорт: Администратор вашей панели должен вручную выбирать нужные услуги из буфера и переносить их в боевую базу данных (Cherry-Pick).

3. Auto-Pricing Engine: Цены у провайдера могут меняться. Ваша система должна автоматически сопоставлять `rate` из буфера с текущими ценами и динамически обновлять розничные цены на вашей витрине для сохранения маржинальности (с учетом курсовых разниц, если вы работаете в другой валюте).

4. Zombie Eraser: Если услуга исчезла из ответа API, ваш ночной воркер обязан пометить связанную услугу в вашей БД как неактивную (`isActive = false`), предотвращая заказы в пустоту.

3. Оформление заказов: Одиночные и Mass Order

API поддерживает как одиночные транзакции, так и механизмы для обработки больших массивов данных.

Одиночный заказ (action: add)

Стандартный метод передачи одного целевого линка.

Параметры:

• `action`: `add`
• `service`: ID услуги из каталога.
• `link`: целевая ссылка. Тип ссылки жестко зависит от категории (`targetType`). Для подписчиков — ссылка на канал/профиль (`CHANNEL`), для лайков и просмотров — ссылка на конкретный пост (`POST`).
• `quantity`: требуемый объем. Должен строго входить в диапазон `min` и `max`.

Ответ при успехе:

```json

{

"order": 123456

}

```

Обязательно сохраняйте полученный идентификатор (`order`) в своей базе для дальнейшего трекинга.

Использование Mass Order (Массовый заказ)

Для снижения сетевой нагрузки при отправке сотен заказов в минуту, Smmplan предлагает функционал Mass Order. В рамках API это реализуется либо специализированным эндпоинтом для пакетной передачи данных (Batching), либо использованием параметра `runs` для Drip-feed заказов (постепенная накрутка). Всегда агрегируйте множественные однотипные задачи в минимальное количество сетевых вызовов, чтобы избежать блокировок по Rate Limit.

4. Синхронизация статусов заказов

Контроль за выполнением задач — критически важный процесс для обеспечения качественного клиентского сервиса.

Мульти-запрос статусов (Multi-Status):

• `action`: `status`
• `orders`: строка с ID заказов, разделенными запятыми (например, `12345,12346,12347`). Ограничение — до 100 ID в одном запросе.

Ответ: Возвращает JSON-объект, где ключами выступают ID заказов, а значениями — объекты с текущим статусом (`status`), стартовым счетчиком (`start_count`) и невыполненным остатком (`remains`).

Жизненный цикл статусов и бизнес-логика:

1. Pending (В ожидании): Заказ принят в систему Smmplan, поставлен в очередь воркеров (BullMQ).

2. Processing / In progress (В обработке / Выполняется): Задача запущена в работу провайдером.

3. Completed (Выполнен): Задача успешно и в полном объеме завершена.

4. Partial (Частично выполнен): Выполнена только часть заказа. Smmplan автоматически возвращает средства за невыполненный остаток (`remains`) на ваш API-баланс. Ваша биллинговая система обязана перехватить статус Partial и инициировать аналогичный частичный возврат средств на внутренний баланс вашего конечного пользователя.

5. Canceled (Отменен): Заказ отклонен (например, приватный аккаунт, ошибочный формат `targetType`, блокировка социальной сети). Производится полный возврат средств.

Паттерн поллинга: Строго запрещено опрашивать статусы отдельных заказов ежеминутно. Настройте фоновый процесс, который собирает все ваши заказы в статусах `Pending` и `Processing`, разбивает их на батчи по 100 штук и вызывает `Multi-Status` раз в 5–10 минут.

5. Контроль баланса

Чтобы избежать даунтайма продаж из-за нехватки средств на аккаунте поставщика, регулярно проверяйте баланс.

Запрос:

• `action`: `balance`

Интегрируйте логику алертинга: если баланс (ответ `balance`) опускается ниже заданного критического порога (например, 1000 RUB), система должна отправлять уведомление финансовому администратору или в выделенный Telegram-чат. Это позволит своевременно пополнять счет через доступные платежные шлюзы без прерывания обслуживания ваших клиентов.

6. Обработка ошибок и Rate Limits

При интеграции учитывайте стандартные коды ошибок:

• `Incorrect request` — неверный формат POST-запроса или пропущены обязательные поля.
• `Incorrect API key` — недействительный ключ доступа.
• `Not enough funds on balance` — недостаток средств. Воркер заказов должен перевести ваши локальные задачи в статус удержания (Hold) до пополнения баланса.
• `Service disabled` — услуга удалена или временно выключена. Срабатывает логика Zombie Eraser.
• `Invalid Link` — ошибка валидации `targetType` на стороне Smmplan.

Rate Limits:

API защищено алгоритмами ограничения запросов. При превышении лимита (обычно 60 запросов в минуту с одного IP) возвращается статус `429 Too Many Requests`. Ваша архитектура должна поддерживать механизм `Exponential Backoff`: при получении кода 429 процесс приостанавливается на 2 секунды, затем повторяет попытку; при повторной неудаче ожидание увеличивается до 4 секунд, затем до 8 и так далее.

Заключение

Интеграция по API Smmplan позволяет выстроить высокопроизводительную платформу для B2B-перепродажи услуг. Строго следуя рекомендациям по архитектуре Shadow Catalog, пакетной обработке статусов, обработке частичных возвратов (Partial) и соблюдению Rate Limits, вы обеспечите своим клиентам премиальный уровень сервиса и максимальную стабильность инфраструктуры.

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