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

Обзор

Toplistbot предоставляет два HTTP API. Оба используют JSON поверх HTTPS и списывают средства с одного и того же баланса токенов — выберите тот, который подходит вашему способу интеграции.

API SMM-панели

Один эндпоинт, совместимый с Perfect Panel. Если ваша панель уже говорит на стандартном протоколе SMM, направьте её сюда — и всё заработает без изменений в коде.

API платформы

REST API, на котором работает личный кабинет: просматривайте каталог сайтов, входите в аккаунт, создавайте кампании и управляйте ими из собственного приложения.

Базовый URL

Base URL

https://backend.toplistbot.com/api

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

От нового аккаунта до работающей кампании за пять шагов. Всё ниже использует эндпоинт SMM — самый быстрый путь; API платформы работает так же, как только вы получите JWT.

Создайте аккаунт
Зарегистрируйтесь и подтвердите почту. Подтверждение начисляет 100 бесплатных токенов — этого хватит на настоящую кампанию, прежде чем вы что-то потратите.
Скопируйте ключ API
Откройте личный кабинет и создайте ключ API. Относитесь к нему как к паролю — он тратит ваш баланс токенов. Ключ можно перевыпустить в любой момент, старый сразу перестаёт работать.
3
Найдите нужный сервис
Получите список всех сайтов, на которых можно оформить заказ. У каждой записи есть числовой id сервиса и тариф в токенах за 1 000 действий. Запишите id сайта, на котором хотите продвигаться.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=services"
```
4
Оформите первый заказ
Отправьте id сервиса, URL, на котором будет работать кампания, и количество действий. Стоимость списывается сразу, а в ответе приходит id заказа.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000"
```
5
Отслеживайте выполнение
Запрашивайте статус по id заказа, чтобы видеть, сколько уже выполнено. Когда схема вас устроит, встройте те же вызовы в свою панель или скрипты.
cURL
```
curl -X POST https://backend.toplistbot.com/api/v2 -d "key=YOUR_API_KEY" -d "action=status" -d "orders=184223"
```

Подключение Perfect Panel

Если вы используете Perfect Panel или совместимое ПО для SMM-панелей, писать код не нужно — добавьте Toplistbot как провайдера с этими настройками и импортируйте список сервисов.

URL API: https://backend.toplistbot.com/api/v2
Ключ API: YOUR_API_KEY
HTTP-метод: POST

Начните с небольшого объёма на одном сайте, чтобы убедиться, что формат ссылки принимается, и только потом масштабируйтесь. Неверная ссылка тоже расходует токены.

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

Два API аутентифицируются по-разному. Эндпоинт SMM использует долгоживущий ключ API, а API платформы — JWT, который вы получаете при входе.

Ключ API (эндпоинт SMM)

Передавайте ключ в поле `key` в каждом запросе — как поле формы, параметр строки запроса или заголовок `Authorization: Bearer`. Создать и перевыпустить его можно в личном кабинете. GET-запрос к тому же эндпоинту возвращает статус ok — это дешёвый способ проверить, что ключ действителен.

Health check

curl https://backend.toplistbot.com/api/v2?key=YOUR_API_KEY

JWT (API платформы)

Войдите в аккаунт, чтобы получить токен, и передавайте его как bearer-токен в защищённых маршрутах. Токены истекают — вызовите /auth/refresh, чтобы получить новый.

curl -X POST https://backend.toplistbot.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

Authenticated request

curl https://backend.toplistbot.com/api/orders/getAll \
  -H "Authorization: Bearer YOUR_JWT"

Ключ API тратит реальный баланс токенов. Держите его на сервере: всё, что попало в браузер или в репозиторий, следует считать скомпрометированным и перевыпустить в личном кабинете.

Токены и цены

Кампании оплачиваются токенами, купленными заранее. У каждого сайта есть тариф — сколько токенов стоит 1 000 действий кампании на нём — он возвращается в поле `rate` действия services.

Cost formula

cost_in_tokens = (rate * quantity) / 1000

Сайт с тарифом 13 стоит 13 токенов за 1 000 действий, значит заказ на 500 обойдётся в 6,5 токена. Стоимость списывается при принятии заказа, а отмена возвращает неизрасходованный остаток.

Ответы balance и status указывают валюту USD ради совместимости с Perfect Panel, но значение — это баланс токенов, а не доллары. Считайте это число токенами.

API SMM-панели

Всё выполняет один эндпоинт. Передавайте поле `action` в каждом POST-запросе, чтобы выбрать операцию; каждый запрос также содержит ваш `key`.

POSThttps://backend.toplistbot.com/api/v2

Действие	Параметры
`services`	—
`add`	service, link, quantity, interval?
`status`	orders
`balance`	—
`cancel`	orders

`action=services`

Возвращает все сайты, на которых можно оформить заказ, с текущим тарифом и ограничениями. Используйте id `service` в вызовах add.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"

Response

[
  {
    "service": 9,
    "name": "arena-top100.com 1000 upvotes",
    "type": "Default",
    "category": "Votes",
    "rate": 15,
    "min": 1,
    "max": 50000,
    "refill": false,
    "cancel": true
  }
]

`rate` указан в токенах за 1 000 действий. Для всех сервисов `min` равен 1, `max` — 50000.

`action=add`

Создаёт кампанию и сразу списывает её стоимость с баланса.

Параметр	Тип	Описание
`key`обязательный	string	Ваш ключ API.
`action`обязательный	string	Должно быть `add`.
`service`обязательный	integer	Id сервиса из действия services.
`link`обязательный	url	URL, на котором работает кампания. Должен быть корректным URL.
`quantity`обязательный	integer	Количество действий, от 1 до 50000.
`interval`	integer	Действий в час. По умолчанию 15, максимум 4000, и не может превышать собственный лимит сайта.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000" \
  -d "interval=60"

Response

{
  "order_id": 184223
}

`action=status`

Возвращает прогресс по одному или нескольким заказам. Передайте один id, чтобы получить простой объект, или список через запятую.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"

Response — single order

{
  "charge": 13.5,
  "start_count": 0,
  "status": "Completed",
  "remains": 1000,
  "currency": "USD"
}

При нескольких id ответ индексируется по id заказа, а неизвестные или чужие заказы возвращают запись об ошибке, не обрушивая весь запрос.

Response — multiple orders

{
  "184223": { "charge": 13.5, "start_count": 0, "status": "Completed", "remains": 1000, "currency": "USD" },
  "184224": { "error": "Incorrect order ID" }
}

`action=balance`

Возвращает остаток вашего баланса токенов.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"

Response

{
  "balance": 528.41,
  "currency": "USD"
}

`action=cancel`

Останавливает заказ и возвращает неизрасходованный остаток на баланс. Завершённые заказы отменить нельзя.

cURL

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"

Response

[
  { "order": "184223", "cancel": 1, "refund": 4.5 },
  { "order": "184224", "cancel": { "error": "Incorrect order ID" } }
]

API платформы

Тот же REST API, который использует личный кабинет. Эндпоинты каталога открыты, всё остальное требует JWT.

Каталог

Публичные, без аутентификации. Удобно для сборки собственного каталога или страницы с ценами.

GET/orders/getAllWebsitesВсе сайты каталога с тарифами и метаданными
POST/orders/getWebsiteDetailsByNameОдин сайт по точному названию
GET/orders/getAllBasicWebsitesDetails20 случайных названий сайтов
POST/products/getSuggestionsПохожие сайты для набора id
GET/products/tokensДоступные пакеты токенов
POST/products/suggestПредложить сайт для добавления
GET/news/timelineИстория изменений продукта

cURL

curl https://backend.toplistbot.com/api/orders/getAllWebsites

Аккаунт

Регистрация, сессии и история счетов.

POST/auth/registerСоздать аккаунт
POST/auth/loginОбменять учётные данные на JWT
POST/auth/refreshВыпустить новый JWT JWT
POST/auth/logoutАннулировать текущий JWT JWT
GET/auth/user-profileПрофиль текущего пользователя JWT
POST/auth/reset-api-keyПеревыпустить ключ API JWT
GET/invoices/getИстория счетов JWT

Кампании

Создавайте кампании, управляйте ими и читайте журналы выполнения.

GET/orders/getAllВаши кампании, новые сверху
POST/orders/checkoutСоздать одну или несколько кампаний
POST/orders/updateИзменить кампанию
POST/orders/pauseПриостановить активную кампанию
POST/orders/unpauseВозобновить приостановленную кампанию
POST/orders/archiveАрхивировать кампанию
PATCH/orders/updateLimitИзменить дневной лимит
GET/orders/logs/{id}Журнал выполнения кампании
GET/orders/graph/{id}Временной ряд для графиков

Ошибки

Ошибки возвращаются с соответствующим HTTP-статусом. При ошибках валидации приходит объект `errors`, где ключи — имена полей.

400Недопустимое действие, некорректные параметры или несуществующий id сервиса.
401Учётные данные отсутствуют или недействительны.
403Аутентификация пройдена, но баланса токенов не хватает на заказ.
422Запрос понят, но не прошёл валидацию.

Validation error

{
  "errors": {
    "quantity": ["The quantity must be at least 1."]
  }
}

Ограничения и примечания

Количество в заказе должно быть от 1 до 50000 действий.
Интервал по умолчанию — 15 в час, максимум 4000. Запрос выше собственного лимита сайта отклоняется с ошибкой 400, в которой указан лимит.
Действия `refill` и `refill_status` не реализованы — вместо этого создайте новый заказ.
Поле `status` пока не отражает прогресс в реальном времени; для отслеживания используйте `remains` и `start_count`.
Сайты-каталоги устанавливают собственные правила и со временем их меняют. Вы сами отвечаете за то, чтобы использование сервиса соответствовало правилам любого сайта, на котором вы продвигаетесь. Мы не обещаем какую-либо позицию или место в рейтинге.

Спросите нас в Discord

Обзор

API SMM-панели

API платформы

Базовый URL

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

Создайте аккаунт

Скопируйте ключ API

Найдите нужный сервис

Оформите первый заказ

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

Подключение Perfect Panel

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

Ключ API (эндпоинт SMM)

JWT (API платформы)

Токены и цены

API SMM-панели

action=services

action=add

action=status

action=balance

action=cancel

API платформы

Каталог

Аккаунт

Кампании

Ошибки

Ограничения и примечания

Начните продвижение прямо сейчас!

`action=services`

`action=add`

`action=status`

`action=balance`

`action=cancel`