Перевірка балансу через API перед масовим запуском замовлень

Навіщо запитувати баланс перед запуском черги

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

Для запуску важливий не загальний обсяг поповнень і не бухгалтерський залишок в особистому кабінеті. Потрібна сума, яку сервіс дозволяє списати в момент створення нового замовлення. Кошти під активні заявки можуть уже перебувати в резерві, хоча остаточне списання ще не відображено в історії операцій.

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

Як виглядає відповідь методу балансу

Назви полів визначає документація конкретної платформи, але зручний контракт методу балансу зазвичай повертає total, available, reserved, currency та updated_at. Нижче наведено приклад структури, яку можна використовувати як орієнтир під час інтеграції. Це не універсальна відповідь для кожного сервісу, а приклад зрозумілої схеми даних.

Запит може виглядати так:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Відповідь:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

У цьому прикладі total — усі кошти акаунта, available — гроші для нових замовлень, reserved — сума під раніше створені операції. Перевірка сходиться: 125.80 мінус 41.30 дорівнює 84.50. Поле currency задає одиницю розрахунку, а updated_at допомагає зрозуміти, наскільки свіжі дані.

Як розбирати available і reserved

Поле available використовують для рішення про запуск. Якщо черга коштує 80.00, а available дорівнює 84.50, коштів достатньо лише за умови, що API не додасть окрему комісію і не перерахує ціну в момент створення заявки. Поле reserved не додають до доступного залишку: ця сума вже зайнята.

reserved може включати вартість замовлень зі статусами processing, pending або review — точний набір залежить від правил платформи. Іноді резерв звільняється після скасування, часткового виконання або ручної перевірки. Тому розраховувати його самостійно за списком замовлень можна лише як додаткову звірку.

• total підходить для звірки з історією поповнень і списань;
• available підходить для допуску нової черги до запуску;
• reserved показує, скільки коштів уже заблоковано під активні операції;
• currency не можна ігнорувати навіть під час роботи лише з одним акаунтом;
• updated_at корисний для журналу та діагностики застарілої відповіді.

Відповідь лише з полем balance простіше обробити, але в неї є недолік: не можна зрозуміти, чи ці гроші доступні негайно, чи частину суми вже утримано під інші замовлення.

Перевіряйте формат сум у документації API

У прикладі суми передані рядками: "84.50", а не числом 84.5. Такий формат зберігає точне значення, яке повернув сервіс. Якщо API використовує рядки з десятковою точкою, не варто одразу переводити їх у числа з плаваючою точкою і виконувати порівняння через float.

Наприклад, ваш розрахунок може дати 84.499999 замість очікуваних 84.50. На межі бюджету це здатне помилково пропустити чергу або, навпаки, зупинити її. Для операцій з рядковими десятковими значеннями використовуйте десятковий тип даних, який підтримує точність фіксованої дробової частини.

Інший поширений контракт — цілі мінімальні одиниці. Тоді відповідь може містити "available_minor": 8450 і "currency": "USD", а ціна замовлення — "price_minor": 1250. Усередині такого API 8450 означає 84.50, якщо правила валюти передбачають дві дробові позиції. Ділити значення на 100 можна лише коли це прямо зазначено в документації.

Не змішуйте валюти та формати цін

Перед розрахунком черги порівняйте currency з балансу з валютою цінового методу або відповіді під час створення замовлення. Якщо баланс повертає одну валюту, а каталог послуг — іншу, не можна підставляти цифри напряму. Потрібен або розрахунок, який надає сама платформа, або окремий підтверджений метод конвертації.

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

Якщо метод ціни відповідає "price": "12.345", а баланс зберігає значення з двома знаками, уточніть правило округлення. Не округлюйте автоматично вниз: фактичне списання може виявитися вищим. Для допуску черги використовуйте саме суму, яку API називає підсумковою вартістю замовлення.

Рахуйте бюджет черги до першого запиту

До запуску зберіть усі заявки та розрахуйте їхню вартість з урахуванням обсягу, обраної послуги, регіону, додаткових опцій і комісії, якщо вона передається окремо. Не порівнюйте available з базовою ціною з інтерфейсу: в API підсумок може залежати від параметрів конкретного замовлення.

Припустімо, у черзі три замовлення. API розрахунку ціни повернув для них 18.40, 27.15 і 31.60 у тій самій валюті, що зазначена в balance.currency. Бюджет дорівнює 77.15. Якщо balance.available дорівнює 84.50, після планового запуску залишається 7.35. Якщо available дорівнює 76.90, запускати всю чергу не можна.

1. Отримайте ціни за фактичними параметрами кожного замовлення.
2. Додайте підсумкові вартості, не змінюючи їхній формат і валюту.
3. Порівняйте бюджет з available зі свіжої відповіді балансу.
4. За достатнього залишку зафіксуйте суму як локальний резерв запуску.
5. Після створення кожної заявки зменшуйте локальний резерв на підтверджену вартість.

Запас знижує ризик відмови при додатковому списанні, але в нього є недолік: частина доступних коштів залишиться невикористаною, хоча черга могла б пройти повністю.

Робіть другу перевірку безпосередньо перед надсиланням

Баланс, отриманий під час підготовки кампанії, швидко втрачає актуальність. За час між розрахунком і запуском інший оператор, автоматизація або активне замовлення можуть змінити available і reserved. Повторний запит потрібен після формування черги і безпосередньо перед першою заявкою.

Робоча схема складається з двох етапів: спочатку отримати ціни й оцінити бюджет, потім запросити balance ще раз. Якщо значення available зменшилося і стало нижчим за розрахункову суму, чергу не надсилають цілком. Між фінальною перевіркою і запуском не варто виконувати інші списання з того самого акаунта.

Один запит на весь запуск зменшує навантаження на API, але його недолік у тому, що доступний залишок може змінитися, поки довга черга ще обробляється.

Як запускати чергу за нестачі коштів

Якщо available менше за бюджет, не надсилайте всі запити в надії, що частина пройде. Розділіть чергу на пакети, вартість яких укладається в доступний ліміт. У прикладі із залишком 76.90 можна надіслати перші два замовлення за 45.55, потім зупинитися: третє за 31.60 потребує повторної перевірки.

Порядок заявок під час батчингу задавайте явно. Можна надсилати спочатку пріоритетні замовлення або формувати пакети з близькою вартістю. У кожного варіанта є недолік: пріоритетний порядок відкладе менш важливі позиції, а сортування за ціною може порушити початковий план кампанії.

• Сформуйте пакет із сумою не вище поточного available.
• Створіть замовлення з пакета і збережіть їхні ідентифікатори.
• Дочекайтеся відповідей або перевірте статуси операцій після тайм-аутів.
• Зробіть паузу, якщо цього вимагають ліміти API або правила сервісу.
• Повторно запросіть balance перед наступним пакетом.

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

Захистіть бюджет під час паралельного надсилання

За послідовної обробки достатньо зменшувати локальний ліміт після підтвердження замовлення. За паралельної моделі два воркери здатні одночасно побачити available 84.50 і кожен запланувати витрату на 60.00. Обидва рішення виглядають допустимими окремо, але разом перевищують доступний залишок.

Для захисту потрібен спільний лічильник локального резерву або черга, доступ до якої виконується атомарно. Перед надсиланням воркер намагається зайняти суму замовлення в цьому лічильнику. Якщо вільного ліміту не вистачає, заявка залишається в очікуванні повторної перевірки балансу.

• Послідовна черга простіше контролюється, але запускається повільніше.
• Паралельне надсилання скорочує час запуску, але потребує блокування спільного бюджету.
• Локальне резервування знижує конфлікти, але може зависнути після збою воркера.
• Резервування на стороні API надійніше, але доступне не в кожної платформи.

Якщо процес завершився до отримання відповіді, локальний резерв не можна одразу вважати витраченим або вільним. Спершу перевірте, чи створилося замовлення, за його зовнішнім ідентифікатором або методом пошуку операцій.

Використовуйте резерв API, якщо він передбачений

Деякі API дозволяють створити резерв під набір операцій або провести замовлення у два кроки: розрахунок, блокування суми, підтвердження. У такій схемі між перевіркою і списанням менше вікно, у якому інший процес може витратити кошти акаунта.

За наявності такого методу зберігайте ідентифікатор резерву, його суму, валюту, термін дії та статус. Потім передавайте цей ідентифікатор під час створення замовлень, якщо цього вимагає контракт API. Після завершення черги звіряйте невикористану частину і факт зняття блокування.

Резерв API не вирішує всіх проблем: він може мати короткий термін дії, не покривати комісії або звільнятися після помилки підтвердження. Локальний резерв простіше впровадити, але його недолік у тому, що він не захищає від витрат, створених поза вашим застосунком.

Відокремлюйте помилку балансу від нульового залишку

Відповідь з кодом помилки, тайм-аут або обмеження частоти запитів не означають, що available дорівнює нулю. Не підставляйте останнє відоме значення автоматично, якщо від нього залежить великий запуск. За неможливості отримати свіжий баланс чергу потрібно поставити на паузу.

Окремо обробляйте відмову під час створення замовлення. Вона може бути пов'язана з нестачею коштів, але також із неправильним ідентифікатором послуги, неприпустимим обсягом, обмеженням на канал або повтором однієї операції. Код і текст помилки зберігайте разом із зовнішнім ідентифікатором заявки.

• У разі помилки авторизації оновіть доступ і лише потім повторюйте запит.
• У разі ліміту запитів витримайте паузу за правилами API.
• У разі тайм-ауту створення спершу перевірте, чи з'явилася операція фактично.
• У разі помилки нестачі коштів зупиніть пакет і запросіть balance заново.

Не створюйте дублі після тайм-ауту

Тайм-аут означає, що ваш клієнт не отримав відповідь, а не те, що сервер не обробив запит. Повторне надсилання без перевірки може створити друге замовлення і повторно зайняти гроші. Особливо небезпечно це в черзі, де автоматичний повтор налаштований на кілька спроб.

Передавайте унікальний зовнішній ідентифікатор замовлення, якщо API підтримує поле client_order_id, external_id або idempotency_key. Зберігайте його до надсилання запиту. Після тайм-ауту знайдіть операцію за цим значенням або запросіть статус за ідентифікатором, отриманим раніше.

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

Що зберігати в журналі запуску

Журнал допомагає відновити хід масової операції та пояснити, чому конкретний пакет зупинився. Для кожного запуску збережіть час двох перевірок, total, available, reserved, currency, розрахований бюджет, розмір локального резерву та список зовнішніх ідентифікаторів заявок.

Для кожної спроби створення фіксуйте вартість, код відповіді, технічний ідентифікатор операції та підсумковий статус. Секрети до журналу не потрапляють: токени авторизації, ключі API, повні заголовки запитів і персональні дані потрібно маскувати або виключати до запису.

Повне логування зручне під час налагодження, але в нього є недолік: без фільтрації у сховище можуть потрапити дані доступу та відомості про клієнтів.

Перевірте схему на невеликій черзі

Перед великим запуском проведіть короткий сценарій: отримайте balance, запросіть підсумкові ціни, створіть обмежений пакет, знову запросіть balance і порівняйте очікувану зміну available і reserved з фактичною відповіддю. Так можна помітити, коли сервіс резервує суму, а коли списує її остаточно.

Тестовий пакет не гарантує однакової поведінки під великим навантаженням: можуть спрацювати ліміти, паралельні процеси або обмеження конкретної послуги. Тому в масовій черзі продовжуйте ділити запуск на пакети, перевіряти доступний залишок між ними і розбирати кожну відмову окремо.