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

action=services

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

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

[
  {
    "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

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

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"

{
  "order_id": 184223
}

action=status

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

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

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

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

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

`status` и `cancel` принимают не более 100 идентификаторов заказов за вызов. Группируйте вместо перебора: один вызов со 100 идентификаторами намного дешевле для обеих сторон, чем 100 вызовов.

action=balance

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

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

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

action=cancel

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

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

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

Каталог и поиск#

Открытый доступ, ключ не нужен. Начинать стоит с getAllWebsites: он отдаёт идентификатор, цену, часовой потолок и процент принятия — всё, что нужно, чтобы посчитать стоимость и задать параметры заказа.

• GET/orders/getAllWebsitesОткрытыйПолный каталог: каждый сайт с тарифами, лимитами и метаданными
• GET/orders/getAllBasicWebsitesDetailsОткрытый20 случайных названий сайтов — для виджетов и автодополнения
• POST/orders/getWebsiteDetailsByNameОткрытыйОдин сайт по точному названию
• POST/products/getSuggestionsОткрытыйСайты, связанные с набором идентификаторов
• GET/products/demand?days=30ОткрытыйСколько заказов было на каждый сайт в последнее время
• GET/products/tokensОткрытыйПакеты токенов, доступные к покупке
• POST/products/suggestAPI-ключПопросить добавить новый сайт
• GET/api/news/timelineОткрытыйИстория изменений продукта

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

Просите меньше

Полный каталог занимает около 665 КБ на 396 сайтов, и половину этого веса дают два поля, с которыми вы никогда не оформите заказ: JSON-блок популярности и маркетинговое описание. Оставьте только поля, которыми заказываете, отбросьте неактивные сайты — и останется около 40 КБ.

# The whole catalog is ~665 KB across 396 sites.
# Projected to what you actually order with: ~40 KB.
curl -s "https://backend.toplistbot.com/orders/getAllWebsites" \
  | jq '[.[]
      | select(.active == 1)
      | {id, name, price_per_1000, max_per_hour, accept_rate, subscribeable}]'

Аккаунт и сессии#

Регистрация требует браузера: её защищает проверка Cloudflare. Зарегистрируйтесь один раз на app.toplistbot.com, а всё дальнейшее автоматизируйте.

• POST/api/auth/registerОткрытыйСоздать аккаунт — только из браузера, защищено капчей
• POST/api/auth/loginОткрытыйОбменять учётные данные на JWT
• POST/api/auth/refreshJWTВыдать новый JWT взамен истекающего
• POST/api/auth/logoutJWTАннулировать текущий JWT
• GET/api/auth/user-profileJWTТекущий аккаунт с балансом и API-ключом
• GET/api/userJWTТот же объект пользователя по более короткому пути
• GET/api/api_tokenAPI-ключОпределить владельца API-ключа — так проверяют ключ
• POST/api/auth/reset-api-keyJWTСменить API-ключ; старый умирает сразу
• POST/api/auth/fingerprintJWTЗаписать отпечаток браузера в аккаунт
• POST/api/auth/ipJWTЗаписать текущий IP аккаунта
• POST/api/auth/forgot-passwordОткрытыйОтправить ссылку на сброс пароля, действует 60 минут
• POST/api/auth/reset-passwordОткрытыйЗадать новый пароль по присланному токену

Двухфакторная защита и вход#

Двухфакторная защита прикрывает вход по паролю. На API-ключи она не распространяется — поэтому для работы без присмотра ключ подходит лучше.

• POST/api/2fa/enableJWTНачать привязку: вернёт секрет, ссылку на QR и коды восстановления
• POST/api/2fa/verifyJWTПодтвердить шестизначный код и включить двухфакторную защиту
• POST/api/2fa/disableJWTВыключить двухфакторную защиту
• POST/api/account/verification/requestJWTОтправить письмо с подтверждением на адрес аккаунта
• GET/api/account/verification/confirm?token=ОткрытыйПоказать страницу подтверждения — ничего не записывает
• POST/api/account/verification/confirmОткрытыйЗавершить подтверждение
• GET/api/auth/googleОткрытыйНачать вход через Google
• GET/api/auth/google/callbackОткрытыйВозврат после входа через Google
• GET/api/auth/discordОткрытыйНачать вход через Discord
• GET/api/auth/discord/callbackОткрытыйВозврат после входа через Discord

Настройки и оповещения#

Переключатели писем и уведомлений, а также лента оповещений аккаунта.

• GET/api/user/email-preferencesJWTСостояние подписки на маркетинговые письма
• POST/api/user/email-preferencesJWTИзменить его
• GET/api/user/notification-preferencesJWTНастройка всплывающих уведомлений о голосах
• POST/api/user/notification-preferencesJWTИзменить её: нужен настоящий булев тип JSON
• GET/api/user/alerts?limit=20JWTОповещения аккаунта, свежие первыми, с постраничностью по ?before
• POST/api/user/alerts/readJWTПометить оповещение прочитанным
• POST/api/user/alerts/dismissJWTСкрыть оповещение
• GET/api/email/unsubscribe?token=ОткрытыйОтписка в один клик по присланному токену

Кампании#

Создавайте кампании, управляйте ими на ходу и завершайте их. Это ядро API платформы.

• GET/orders/getAllAPI-ключВаши кампании, свежие первыми, вместе с их сайтами
• GET/orders/get/{id}API-ключОдна кампания
• POST/orders/checkoutAPI-ключСоздать кампании и списать с баланса
• POST/orders/updateAPI-ключИзменить кампанию
• POST/orders/pauseAPI-ключПриостановить активную кампанию
• POST/orders/unpauseAPI-ключВозобновить приостановленную кампанию
• POST/orders/archiveAPI-ключАрхивировать кампанию
• POST/orders/unarchiveAPI-ключВернуть кампанию из архива
• PATCH/orders/updateLimitAPI-ключЗадать или снять дневной потолок голосов

POST /orders/checkout

Тело запроса — это JSON-массив строк корзины на верхнем уровне, а не объект. Каждая строка — отдельная кампания. Вся корзина проверяется до любого списания, а списание и вставки идут одной транзакцией: заказ либо проходит целиком, либо не проходит вовсе.

Строка с фиксированным количеством

Обычный случай: доставить заданное число голосов на один адрес.

curl -X POST "https://backend.toplistbot.com/orders/checkout?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": 9,
      "amount": 1000,
      "ownName": "https://arena-top100.com/index.php?a=in&u=yourserver",
      "custom_max_per_hour": 60
    }
  ]'

200 OK
Successfully purchased with token balance

Строка подписки

Для сайтов, у которых признак `subscribeable` равен 1. Цена считается как subscription_price_1d сайта, умноженная на число дней и на скидку уровня: Weekly — 0,90, Monthly — 0,80, всё остальное — 1,00. Доставляемое количество выводится на сервере из собственного subscription_speed сайта, поэтому ничем из запроса его не изменить.

[
  {
    "type": "subscription",
    "website": { "id": 9 },
    "subscription_days": 30,
    "tier": { "name": "Monthly" },
    "url": "https://arena-top100.com/index.php?a=in&u=yourserver"
  }
]

Ответы

• 200Все строки созданы, с баланса списано. Тело ответа — обычный текст.
• 400Тело запроса не является корректным JSON.
• 402Не хватает токенов. В сообщении указана нужная сумма, списания не было.
• 422Одна или несколько строк некорректны. Списания не было.
• 429Та же корзина отправлялась в последние 60 секунд. Повторите после указанной паузы.

Ответ 422 указывает на проблемную строку: ошибки нумеруются как items.[index].[field], поэтому корзина с тремя плохими строками чинится за один заход, а не за три.

{
  "errors": {
    "items.2.amount": ["Enter 0 or more votes; a negative amount is not allowed."]
  }
}

POST /orders/update

`id` обязателен; отправляйте только те поля, которые меняете. Заказы-подписки изменить нельзя.

curl -X POST "https://backend.toplistbot.com/orders/update?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"amount_to_do":2000,"custom_name":"EU launch"}'

Дневной потолок

`type: "delete"` снимает потолок. Валидатор всё равно требует `max_votes_per_day` — отправьте любое целое число.

curl -X PATCH "https://backend.toplistbot.com/orders/updateLimit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"max_votes_per_day":500,"type":"set"}'

Логи и аналитика#

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

• GET/orders/logs/{id}API-ключЛог доставки кампании по каждому голосу
• GET/orders/graph/{id}API-ключВременной ряд одной кампании, готовый к отрисовке
• GET/api/orders/graph/summaryJWTОдин ряд по всем вашим кампаниям
• GET/orders/grouped/usernames/{id}API-ключДоставки, сгруппированные по голосовавшему имени
• POST/orders/averageAPI-ключСредняя доставка по нескольким кампаниям
• GET/api/logs/{id}/filtered-graphJWTОтфильтрованный временной ряд

Профили голосов и прокси#

Профиль голосов — это именованный список имён, от которых голосует кампания. Профиль прокси — именованный список разрешённых стран для используемых IP. Привяжите любой из них к кампании через username_profile_id или proxy_profile_id в /orders/update.

• GET/advanced/profile/getAPI-ключВаши профили голосов
• GET/advanced/profile/get/{id}API-ключОдин профиль голосов
• POST/advanced/profile/createAPI-ключСоздать профиль голосов или перезаписать по идентификатору
• DELETE/advanced/profile/delete/{id}API-ключУдалить профиль голосов
• GET/advanced/profile/proxy/getAPI-ключВаши профили прокси
• GET/advanced/profile/proxy/get/{id}API-ключОдин профиль прокси
• POST/advanced/profile/proxy/createAPI-ключСоздать профиль прокси или перезаписать по идентификатору
• DELETE/advanced/profile/proxy/delete/{id}API-ключУдалить профиль прокси

Токены Discord#

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

• GET/api/discord-tokensJWTВаши токены Discord
• POST/api/discord-tokensJWTДобавить токен
• GET/api/discord-tokens/statsJWTСтатистика использования ваших токенов
• GET/api/discord-tokens/{id}JWTОдин токен
• PATCH/api/discord-tokens/{id}JWTИзменить токен или его активность
• DELETE/api/discord-tokens/{id}JWTУдалить токен
• PUT/api/discord-tokens/{id}/toggleJWTПереключить токен между включённым и выключенным

Счета и платежи#

Покупка токенов всегда заканчивается на размещённой у провайдера странице оплаты, поэтому пополнение нельзя сделать полностью автоматическим. Всё, что после пополнения, — можно.

• GET/invoices/getAPI-ключИстория счетов
• GET/api/subscriptions/subscriptionsJWTАктивные подписки
• GET/products/tokensByUserAPI-ключПакеты токенов по ценам вашего аккаунта
• POST/company/getAPI-ключВаш платёжный адрес
• POST/company/createAPI-ключЗадать его: country, region, city, address, postalCode
• GET/api/stripe/checkout?product_id=JWTСсылка Stripe Checkout для пакета токенов
• GET/api/stripe/subscription?plan=JWTСсылка Stripe Checkout для тарифа
• GET/api/stripe/portalJWTСсылка на платёжный портал Stripe
• GET/api/stripe/documentsJWTСчета и квитанции Stripe
• GET/coinpayments/checkoutAPI-ключСсылка на оплату криптовалютой

Сохранённая корзина#

Корзина панели, которая хранится на сервере и переживает смену устройства. Для оформления заказов она не нужна: /orders/checkout принимает корзину прямо в запросе.

• GET/api/cartJWTСохранённая корзина
• PUT/api/cartJWTЗаменить её
• POST/api/cartJWTЗаменить её — то же, что PUT
• DELETE/api/cartJWTОчистить её

Внутренние эндпоинты#

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

• POST/api/stripe/webhookСобытия оплаты Stripe, проверяются по подписи
• POST/api/jobs/tickЗапускает подошедшие задачи, доступ по общему секрету
• POST/api/pow/challengeПроверка proof-of-work при регистрации
• POST/api/logs/updateУчёт активности в письмах
• POST/api/order/{email}Создаёт заказ на другом аккаунте — только для списка администраторов
• GET/reset-password/{token}Старая серверная страница сброса пароля, оставлена ради уже отправленных ссылок
• GET/ОткрытыйПроверка доступности

Объект сайта#

Возвращают /orders/getAllWebsites и /orders/getWebsiteDetailsByName; он же вложен в каждую кампанию под ключом `website`.

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

Объект кампании#

Возвращают /orders/getAll и /orders/get/. Обратите внимание на то, чего нет: поля статуса не существует.

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

Работает ли она? Закончилась ли?#

У кампании нет поля статуса, поэтому состояние выводится из четырёх колонок. Проверяйте условия по порядку и берите первое совпадение.

Прогресс и возвраты#

amount_to_do считает принятые голоса, amount_done — отправленные. Принимается лишь accept_rate процентов отправленных, поэтому величины в разных единицах и вычитать одну из другой напрямую неверно.

// accept_rate arrives as a STRING, and it is per-site, not global.
const rate = Number(order.website.accept_rate)

// amount_done counts SUBMISSIONS; amount_to_do counts ACCEPTED votes.
// Convert before comparing them.
const delivered = order.amount_done * rate / 100
const remaining = Math.max(order.amount_to_do - delivered, 0)
const percent   = 100 * delivered / order.amount_to_do

// What cancelling right now would put back on your balance:
const refund    = (remaining / 1000) * order.website.price_per_1000

Та же арифметика оценивает отмену: возвращается неизрасходованный остаток по прайсовой цене сайта, так что вы можете узнать, чего стоит остановка кампании, ещё до решения.