Как настроить автоматическое пополнение баланса в SMM-панели через API

Что подготовить до настройки автопополнения

Автопополнение связывает баланс SMM-панели с платёжным сервисом или внутренним биллингом. Сервис проверяет остаток, создаёт платёж при достижении заданного порога и зачисляет средства только после подтверждения оплаты. Для работы нужны документация API панели, доступ к платёжному API, отдельные ключи для тестовой и рабочей среды, а также журнал всех операций.

До разработки проверьте, умеет ли API панели возвращать баланс, принимать запрос на зачисление, показывать историю пополнений и принимать внешний идентификатор операции. Если панель не поддерживает зачисление через API, автоматизация сможет только создать заявку или отправить уведомление оператору. Недостаток такого варианта — деньги всё равно придётся вносить вручную.

Разделите проверку баланса и решение о платеже

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

Перед новым платежом обработчик должен проверить, нет ли операции со статусом «создана», «ожидает оплаты» или «подтверждается». Если такая запись есть, новая попытка не запускается до завершения сверки. Недостаток последовательной обработки — при долгом ответе внешнего API пополнение может начаться позже, чем при нескольких параллельных запросах.

Выберите порог и логику суммы пополнения

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

Сумма пополнения может быть фиксированной или рассчитываться от расхода за выбранный период. Фиксированная сумма проще для контроля и сверки. Её недостаток — в спокойный период на балансе могут лежать лишние средства, а при резком росте заказов одного пополнения может не хватить. Расчётная сумма гибче, но требует очистки статистики от аномальных списаний и возвратов.

Настройте финансовые ограничения отдельно от порога

Порог отвечает только на вопрос, когда системе разрешено начать процесс пополнения. Ограничения отвечают на другой вопрос: сколько средств она вправе списать. Задайте максимальную сумму одной операции, общий лимит на период и допустимый остаток после зачисления. Эти правила проверяются перед созданием платежа, а не после его оплаты.

Автопополнение не должно списывать средства без лимита на операцию и период. Если расчётная сумма выше разрешённой, операцию лучше перевести в ручную проверку и отправить уведомление. Недостаток жёстких лимитов — при быстром росте расходов баланс может закончиться до того, как ответственный сотрудник подтвердит увеличение лимита.

Создайте отдельные ключи и защитите доступ

Для скрипта автопополнения используйте отдельные API-ключи с минимальными правами: чтение баланса, создание платежа, проверка статуса и зачисление подтверждённой операции. Доступ к пользователям, настройкам услуг, заказам и выводу средств такому ключу не нужен. Если сервис поддерживает ограничение по IP-адресам, разрешите обращения только с сервера интеграции.

Ключи хранят в переменных окружения или защищённом хранилище секретов. Не передавайте их в браузерный код, логи, публичные репозитории и сообщения об ошибках. У каждого ключа должен быть владелец и понятный порядок замены. Недостаток частой ротации ключей — пополнение остановится, если новый секрет не обновить во всех рабочих процессах.

Создайте платёж с уникальным идентификатором

Каждому пополнению присваивают внутренний идентификатор до обращения к платёжному API. Его сохраняют в журнале и передают как ключ идемпотентности или внешний номер операции. При сетевом тайм-ауте тот же запрос можно повторить с тем же идентификатором: платёжный сервис должен вернуть уже созданную операцию, а не списать деньги повторно.

Ниже — общий пример запроса. Названия полей и адреса замените на значения из документации конкретного провайдера. В переменной PAYMENT_ID хранится заранее созданный уникальный ID, а CALLBACK_URL ведёт на обработчик вебхуков.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Не определяйте уникальность платежа только по сумме и времени создания. Два одинаковых пополнения могут быть легитимными, а повторный запрос после сбоя — нет. Недостаток внешнего ID в собственной базе — его нужно надёжно хранить и не переиспользовать после отмены операции.

Проверяйте баланс и сохраняйте состояние операции

Запрос баланса должен выполняться до решения о новом пополнении и после успешного зачисления. Общий запрос может выглядеть так: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". В ответе сохраняйте не только сумму, но и время проверки, чтобы не принимать решение по устаревшим данным.

Для каждой операции ведите запись с внутренним ID, ID платежа у провайдера, суммой, валютой, временем создания, статусом, ответами API и причиной ошибки. Подходящая цепочка состояний: «создана», «ожидает оплаты», «оплачена», «зачисляется», «зачислена», «отменена», «требует проверки».

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

Принимайте вебхук и сверяйте статус платежа

Страница успешной оплаты и редирект пользователя не подтверждают поступление денег. Подтверждением служит вебхук от платёжного сервиса или повторная проверка статуса через его API. При получении вебхука проверьте подпись, время отправки, ID платежа, внешний ID, сумму и валюту. Только после этого переводите операцию в состояние подтверждённой оплаты.

После проверки вебхука полезно запросить актуальный статус платежа у провайдера. Например: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Сверьте статус с данными журнала, затем отправьте запрос на зачисление в SMM-панель с тем же внутренним ID.

Повторный вебхук не должен создавать второе зачисление. Обработчик находит операцию по внешнему ID, видит статус «зачислена» и возвращает успешный ответ без новых действий. Недостаток вебхуков — они могут задержаться или не дойти, если обработчик был недоступен.

Обработайте тайм-ауты, ретраи и зависшие платежи

При тайм-ауте после создания платежа не отправляйте новый запрос с другим ID. Сначала найдите операцию по внутреннему идентификатору или повторите запрос с тем же ключом идемпотентности. Если провайдер принял исходный запрос, он вернёт существующий платёж. Это защищает от двойного списания при обрыве соединения.

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

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

Зачислите подтверждённый платёж в SMM-панель

Перед зачислением обработчик ещё раз проверяет: сумма не превышает лимит, валюта совпадает, операция не была отменена и её статус ещё не «зачислена». В запрос передают сумму и внешний идентификатор платежа. Если API панели поддерживает ключ идемпотентности, используйте тот же внутренний ID операции.

Общий вид запроса: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

После ответа панели запросите баланс повторно и сохраните результат в журнале. Если деньги списаны у платёжного сервиса, но API панели вернул ошибку, не создавайте новый платёж. Операция остаётся в статусе «требует проверки» до повторной попытки зачисления или ручной сверки. Недостаток такой осторожной схемы — баланс может временно не пополниться автоматически.

Добавьте уведомления, выключатель и проверку запуска

Уведомления нужны для отклонений: баланс опустился ниже критического уровня, платёж отклонён, вебхук не получен, превышен лимит, API недоступно или операция требует ручной проверки. В сообщении достаточно указать внутренний ID, статус и причину. Не включайте в него API-ключи, подписи вебхуков и платёжные реквизиты.

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

Чек-лист перед включением автопополнения

• Проверка баланса не создаёт платёж, пока есть незавершённая операция.
• Для каждого платежа создаётся уникальный внутренний ID и ключ идемпотентности.
• Настроены лимиты на одну операцию и выбранный период.
• Вебхуки проверяются по подписи, сумме, валюте и идентификатору.
• При отсутствии вебхука запускается повторная сверка статуса через API.
• Тайм-аут не приводит к созданию второго платежа до проверки первого.
• Зачисление в панель выполняется один раз и фиксируется в журнале.
• Тестовый режим проверен на успехе, отказе, дубле вебхука и недоступности API.