Когда панель реселлера подключена к поставщику по API, клиент видит заказ глазами вашей системы. Всё, что он знает о прогрессе, вы берёте из ответа на запрос status. Разберём каждое поле этого ответа в API SMMPanel.ru, покажем, как превратить его в понятный клиенту прогресс, и как опрашивать сотни заказов без лишней нагрузки.

Запрос и ответ

Запрос status отправляется так же, как остальные запросы API: методом POST на адрес из документации, ответ приходит в JSON. Параметры:

Пример ответа из документации:

{
  "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, а не от текущего счётчика.

Ответ status и прогресс заказа для клиента

Как показать прогресс клиенту

Из ответа легко собрать понятную карточку заказа. Формулы:

  1. Выполнено = заказанный объём − remains.
  2. Процент выполнения = выполнено / заказанный объём × 100%.
  3. Ожидаемый итог на странице = start_count + заказанный объём.
  4. Возврат клиенту при частичном выполнении = remains × ваша цена за 1000 / 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: вместо объекта пришла строка с ошибкой. Код должен обрабатывать оба варианта — объект и строку — и не падать на одном неверном номере.

Как построить опрос

  1. Выбирайте из базы только активные заказы — те, что не завершены и не отменены.
  2. Делите их на пачки. Максимальный размер пачки в документации не указан, поэтому начните с умеренного и не увеличивайте его без проверки.
  3. Отправляйте пачку запросом status с параметром orders.
  4. Для каждого ключа в ответе проверьте тип: объект — обновите заказ, строка — запишите ошибку.
  5. Завершённые заказы исключайте из следующего цикла.
  6. Повторяйте раз в несколько минут фоновой задачей.

Частые ошибки при работе со status

Логи и сверка

Сохраняйте ответы status в журнал хотя бы на время жизни заказа. Когда клиент напишет в поддержку, вы сразу увидите, как менялся заказ: когда стартовал, с какого значения, сколько оставалось на каждой проверке. Раз в неделю сверяйте сумму charge по завершённым заказам с изменением баланса у поставщика. Расхождение — повод проверить, не задвоился ли какой-то заказ в вашей системе.

Что попробовать