Проверка баланса через 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 с фактическим ответом. Так можно заметить, когда сервис резервирует сумму, а когда списывает её окончательно.

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