Перейти к содержимому

Параметры, поля ответов и тексты ошибок

Это справочник, в который удобно заглядывать во время работы. Если вы подключаете API впервые, начните с обзора или откройте примеры кода. Действий всего пять; любое другое значение action, в том числе запрос восстановления отписок, получит ошибку о неверном действии.

Последнее обновление

POSThttps://smmvia.com/api/v2

Названия полей и тексты ошибок ниже приведены по-английски, как их возвращает сервер: если ваш скрипт сравнивает строки, сравнивайте их дословно.

Общие правила для всех запросов

Что Как устроено
Адрес smmvia.com/api/v2, только по https.
Метод HTTP Рекомендуем POST; GET тоже работает. На другие методы сервер отвечает кодом 405.
Формат запроса Поля формы или тело JSON с теми же именами. Ответы всегда в JSON.
Обязательные поля key (ключ из настроек аккаунта) и action (строчными буквами).
Ошибки Объект с полем error и кодом HTTP 200. Другие коды: 429 — превышен лимит, 405 — неверный метод, 404 — неверный путь.
Числа Суммы передаются строками: у rate 4 знака после точки, у balance и charge — от 4 до 8. Номера и количества — целые числа.

action=balance

Дополнительных полей нет. Ответ показывает, сколько денег можно потратить: balance — доступная сумма, currency — валюта всех сумм в API (сейчас USD).

action=services

Дополнительных полей нет. В ответе по одной записи на каждую услугу, которую можно заказать. Цены персональные: если у аккаунта есть индивидуальные цены или скидки, они уже учтены, поэтому у разных аккаунтов значения могут отличаться.

Назначение каждого поля указано в комментариях к примеру. Главное правило: выбирайте услугу по номеру service, а не по названию — названия могут меняться.

Node.jsПример одной записи с пояснениями (значения выдуманы)
[
  {
    "service": 205,                  // номер, который передаётся в add
    "name": "Sample catalogue name", // название из каталога, может меняться
    "type": "Default",               // тип; сейчас у всех услуг одинаковый
    "category": "Sample category",   // группа каталога
    "rate": "0.1000",                // ваша цена за 1000 единиц, строкой
    "min": 10,                       // минимальное количество в одном заказе
    "max": 3000,                     // максимальное количество в одном заказе
    "dripfeed": false,               // поле совместимости; у части услуг true, но add не принимает параметров постепенной подачи
    "refill": false,                 // поле совместимости, у всех текущих услуг false
    "cancel": true                   // true, если заказы этой услуги можно отменять
  }
]

action=add

Создаёт один заказ и сразу списывает его стоимость с баланса. Успешный ответ выглядит так: {"order": 80412} (номер выдуман).

Параметр Тип Правило
service целое число Обязательный. Номер услуги из ответа services.
link строка Обязательный. Ссылка на канал, группу или пост, не длиннее 2048 символов.
quantity целое число Обязательный. Целое число в пределах min и max этой услуги.

action=status

Передайте order с одним номером или orders — до 100 номеров через запятую. Если указаны оба поля, используется orders. Номера сверх первой сотни отбрасываются.

Поле Тип Что содержит
charge строка Стоимость за вычетом возвратов: 0.0000 при полном возврате, доля выполненного при Partial.
start_count целое число Значение счётчика до начала выполнения, передаётся как есть; может быть 0.
status строка Один из статусов из таблицы ниже.
remains целое число Сколько единиц не выполнено; 0 при Completed.
currency строка Валюта поля charge.

С полем order приходит один объект или ошибка о неверном номере, если заказ не найден или принадлежит другому аккаунту. С полем orders приходит объект, где ключи — номера заказов; чужие и несуществующие номера пропускаются, а если не подошёл ни один, возвращается пустой список.

JSONПример ответа для orders=80412,80413 (значения выдуманы)
{
  "80412": {"charge": "0.0500", "start_count": 2140, "status": "In progress", "remains": 180, "currency": "USD"},
  "80413": {"charge": "0.0000", "start_count": 0, "status": "Canceled", "remains": 500, "currency": "USD"}
}

action=cancel

Передайте orders — до 100 номеров через запятую — или один order. В ответе по строке на каждый номер, в том же порядке. Значение 1 в поле cancel означает, что заказ остановлен, а невыполненная часть уже на балансе; заказ завершается как Canceled (ничего не выполнено) или Partial. Для одиночного order приходит объект с полями order и cancel или ошибка.

JSONПример ответа для orders=80412,80413,99999 (значения выдуманы)
[
  {"order": 80412, "cancel": 1},
  {"order": 80413, "cancel": {"error": "Cancel is not available for this order"}},
  {"order": 99999, "cancel": {"error": "Incorrect order ID"}}
]
  • Отменить можно только заказ в статусе Pending, Processing или In progress и только у услуги, где поле cancel разрешает отмену.
  • Отмена проходит, только когда её подтвердит система выполнения. Если подтвердить сейчас не удалось, ничего не меняется — просто повторите запрос позже.
  • Уже отменённый заказ снова вернёт 1, поэтому повтор после обрыва связи ничего не сломает.
  • Если окажется, что заказ уже выполнен, он станет Completed без возврата, а в строке ответа будет ошибка.
  • На один запрос отводится не больше 20 секунд; номера, до которых очередь не дошла, вернутся с просьбой повторить.
Пример расчётаПример расчёта при отмене (числа выдуманы)
Заказано
500
Оплачено
0.0500
Не выполнено по данным о выполнении
180
Вернётся на баланс
0.0500 × 180 / 500 = 0.0180
Заказ после отмены
Partial, charge 0.0320, remains 180

Доля возврата считается от невыполненного остатка — так же, как для заказов с сайта. Полные правила — на странице о возврате.

Статусы заказа

Статус в API В кабинете Финальный? Что это значит для скрипта
Pending «Ожидает» нет Оплачен, но ещё не передан в работу. Если передать не удалось, примерно через 15 минут заказ отменяется с полным возвратом.
Processing «В обработке» нет Заказ передан в работу, выполненных единиц пока нет.
In progress «Выполняется» нет Единицы поступают, remains уменьшается.
Completed «Выполнен» да Всё количество выполнено, remains = 0.
Partial «Частично выполнен» да Выполнена часть, остаток возвращён на баланс.
Canceled «Отменён» да, когда charge = 0.0000 Ничего не выполнено, деньги возвращены. Заказ, который ждёт повторной передачи в работу, тоже показывается как Canceled, но с полной суммой в charge.
Refunded «Возвращён» да Вся сумма возвращена без запроса на отмену, например автоматической проверкой.

Тексты ошибок

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

Node.jsКлюч, действие и параметры заказа
"Invalid API key"                       // ключ не передан, неверный, заменён или аккаунт приостановлен
"Invalid action"                        // action пустой, с опечаткой или не из пяти допустимых
"The service field is required."        // в add нет service; для link и quantity фраза та же
"The selected service is invalid."      // услуги с таким номером нет
"This service is currently unavailable."// услуга выключена: обновите список services
"The quantity field must be an integer."// не целое число; меньше 1 — "must be at least 1"
"Quantity must be between N and M."     // количество вне min и max услуги
"The link field must not be greater than 2048 characters." // сократите ссылку
"Your balance is not enough. Please top up your account."  // не хватает баланса, ничего не списано
Node.jsСтатус, отмена и сбои
"Incorrect order ID"                    // status или cancel: номер не передан, не найден или не ваш
"Too many orders: send at most 100 IDs per request" // разбейте список отмены на пачки по 100
"Cancel is not available for this order" // у услуги нет отмены или заказ завершён: не повторяйте
"The order is still being sent for processing, please retry in a few seconds" // заказ передаётся в работу, повторите чуть позже
"The order cannot be canceled right now, please retry shortly"               // отмена не подтвердилась, повторите
"Request took too long, please retry this order" // 20 секунд истекли до этого номера, отправьте его снова
"Server error"                          // сбой на нашей стороне; для add сначала проверьте раздел заказов

Лимит запросов

Один ключ может делать 300 запросов в минуту — любые действия, включая неудачные. В обычных ответах есть заголовки с лимитом и остатком запросов. После превышения приходит HTTP 429 с телом, показанным ниже, без заголовка с временем ожидания: просто подождите до следующей минуты. Отклонённый запрос ничего не меняет.

JSONТело ответа HTTP 429
{"error": "Rate limit exceeded — too many requests, please slow down."}

Данные проверены: