Як налаштувати автоматичне поповнення балансу в 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.