Когда панель реселлера подключена к поставщику по API, клиент видит заказ глазами вашей системы. Всё, что он знает о прогрессе, вы берёте из ответа на запрос status. Разберём каждое поле этого ответа в API SMMPanel.ru, покажем, как превратить его в понятный клиенту прогресс, и как опрашивать сотни заказов без лишней нагрузки.
Запрос и ответ
Запрос status отправляется так же, как остальные запросы API: методом POST на адрес из документации, ответ приходит в JSON. Параметры:
key— ваш API-ключ;action—status;order— номер заказа, который вернул запросadd.
Пример ответа из документации:
{
"order": "32",
"status": "pending",
"charge": "0.0360",
"start_count": "0",
"remains": "0"
}
Обратите внимание: все значения приходят строками, включая числа. Перед расчётами приводите их к числу. Сумму charge храните как десятичное число с фиксированной точностью, а не как число с плавающей точкой — иначе на больших объёмах накопятся ошибки округления.
Что значит каждое поле
| Поле | Что это | Как использовать |
|---|---|---|
order |
Номер заказа у поставщика | Ключ для связи с заказом в вашей базе |
status |
Текущее состояние заказа | Переводить в понятный клиенту статус |
charge |
Сумма, списанная с вашего баланса за заказ, в долларах | Сверять с закупкой и считать маржу |
start_count |
Значение счётчика на момент старта | Показывать клиенту точку отсчёта |
remains |
Сколько единиц ещё не выполнено | Считать прогресс и возврат |
status
В примерах документации встречаются значения pending и processing. По мере выполнения заказ переходит в другие состояния: выполнен, выполнен частично, отменён. Логику возврата для двух последних SMMPanel.ru описывает в FAQ: деньги за отменённый заказ возвращаются на баланс, при частичной отмене — пропорционально невыполненной части.
Практическое правило: не жёстко зашивайте список статусов. Сравнивайте значения без учёта регистра, а любое неизвестное значение записывайте в лог и показывайте клиенту как «в работе». Так новая строка в ответе не сломает панель.
start_count
Это значение счётчика на момент начала выполнения: сколько подписчиков, просмотров или реакций было до заказа. Пока заказ не стартовал, поле может быть нулевым, как в примере выше.
Зачем показывать его клиенту: он видит, с какой цифры шёл отсчёт. Это снимает часть вопросов «а точно ли выполнили», если до заказа на странице уже была активность.
remains
Остаток — число единиц, которые ещё не выполнены. Именно по нему считается прогресс и сумма возврата при частичном выполнении.
Прогресс заказа — это не «сколько стало на странице», а «сколько из заказанного выполнено». Считайте его от remains, а не от текущего счётчика.
Как показать прогресс клиенту
Из ответа легко собрать понятную карточку заказа. Формулы:
- Выполнено = заказанный объём −
remains. - Процент выполнения = выполнено / заказанный объём × 100%.
- Ожидаемый итог на странице =
start_count+ заказанный объём. - Возврат клиенту при частичном выполнении =
remains× ваша цена за 1000 / 1000.
Что выводить в интерфейсе:
- статус человеческим языком: «в очереди», «выполняется», «выполнен», «выполнен частично», «отменён»;
- строку прогресса: «750 из 1000»;
- стартовое значение, если оно больше нуля;
- сумму возврата, если заказ завершён частично.
Технические поля вроде charge клиенту не показывайте: это ваша закупочная цена.
Пакетный запрос: много заказов за один раз
Опрашивать заказы по одному медленно. Вместо order передайте параметр orders — номера заказов через запятую. Ответ придёт объектом, где ключ — номер заказа:
{
"12": { "order": "12", "status": "processing", "charge": "1.2600", "start_count": "0", "remains": "0" },
"2": "Incorrect order ID",
"13": { "order": "13", "status": "pending", "charge": "0.6300", "start_count": "0", "remains": "0" }
}
Обратите внимание на заказ 2: вместо объекта пришла строка с ошибкой. Код должен обрабатывать оба варианта — объект и строку — и не падать на одном неверном номере.
Как построить опрос
- Выбирайте из базы только активные заказы — те, что не завершены и не отменены.
- Делите их на пачки. Максимальный размер пачки в документации не указан, поэтому начните с умеренного и не увеличивайте его без проверки.
- Отправляйте пачку запросом
statusс параметромorders. - Для каждого ключа в ответе проверьте тип: объект — обновите заказ, строка — запишите ошибку.
- Завершённые заказы исключайте из следующего цикла.
- Повторяйте раз в несколько минут фоновой задачей.
Частые ошибки при работе со status
- Прогресс от текущего счётчика. Счётчик на странице меняется и без вашего заказа. Используйте
remains. - Числа как строки. Сравнение
"10" > "9"в строковом виде даст неверный результат. - Падение на ошибке в пачке. Одна строка вместо объекта не должна останавливать обработку остальных.
- Нет сверки
charge. Если закупка выросла, а цена клиента осталась прежней, вы теряете маржу. Как выстроить наценку, мы разбирали в статье «Своя SMM-панель на API SMMPanel.ru». - Нет баланса. Запрос
balanceвозвращает остаток и валюту. Проверяйте его по расписанию, чтобы новые заказы не отклонялись.
Логи и сверка
Сохраняйте ответы status в журнал хотя бы на время жизни заказа. Когда клиент напишет в поддержку, вы сразу увидите, как менялся заказ: когда стартовал, с какого значения, сколько оставалось на каждой проверке. Раз в неделю сверяйте сумму charge по завершённым заказам с изменением баланса у поставщика. Расхождение — повод проверить, не задвоился ли какой-то заказ в вашей системе.
Что попробовать
- Откройте документацию API и отправьте
statusпо одному из своих заказов. - Соберите пакетный опрос активных заказов с обработкой строк-ошибок.
- Готовые формулировки ответов клиентам по статусам возьмите из статьи «Поддержка клиентов реселлера: 10 шаблонов ответов».