Параметры, поля ответов и тексты ошибок
Это справочник, в который удобно заглядывать во время работы. Если вы подключаете 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, а не по названию — названия могут меняться.
[
{
"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 приходит объект, где ключи — номера заказов; чужие и несуществующие номера пропускаются, а если не подошёл ни один, возвращается пустой список.
{
"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 или ошибка.
[
{"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 содержит одну из строк ниже, слово в слово. Проверка параметров сообщает только о первой найденной проблеме. Пояснения даны в комментариях.
"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." // не хватает баланса, ничего не списано
"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 с телом, показанным ниже, без заголовка с временем ожидания: просто подождите до следующей минуты. Отклонённый запрос ничего не меняет.
{"error": "Rate limit exceeded — too many requests, please slow down."}
Данные проверены: