Управление балансом для реселлеров: как это работает

Краткий ответ

В FoxReload нет отдельного GET-эндпоинта баланса. Аккаунт работает по предоплатной модели: вы пополняете криптовалютой через POST /api/topups/crypto/, каждый заказ списывает средства. Если баланс недостаточен — создание заказа возвращает ошибку BalanceNotEnough. Для управления балансом отслеживайте ошибки BalanceNotEnough, поддерживайте внутренний счётчик расходов через историю заказов и заблаговременно пополняйте через крипто API.

Определение: Предоплатной баланс FoxReload — средства на аккаунте реселлера, из которых списывается стоимость каждого заказа. Пополнение — только криптовалютой через /api/topups/crypto/. Отдельного GET-эндпоинта баланса нет; нехватка средств сигнализируется ошибкой BalanceNotEnough при создании заказа.

Главный вывод: Нулевой баланс в 2 часа ночи в субботу означает ошибки BalanceNotEnough на всех заказах, недовольных клиентов и потерянную выручку до пополнения. Мониторинг ошибок BalanceNotEnough и превентивное пополнение через /api/topups/crypto/ полностью исключают эту ситуацию.

Для кого это руководство

• Разработчики, интегрирующие API поставщика цифровых товаров
• Операторы магазинов, столкнувшиеся с неудачными заказами из-за пустого баланса
• Все, кто строит production-grade систему реселлера цифровых товаров

Как работает модель предоплатного баланса

Большинство поставщиков цифровых товаров работают по предоплатной (кредитной) модели:

1. Вы депонируете средства на реселлерский аккаунт (банковский перевод, криптовалюта и т.д.)
2. Каждое создание заказа вычитает оптовую стоимость из баланса
3. Когда баланс достигает нуля, вызовы создания заказов возвращают ошибку
4. Вы пополняете баланс для восстановления

Это отличается от модели net-30 (где вы платите постфактум). Предоплатная модель означает, что перед обработкой заказов у вас всегда должен быть достаточный баланс.

Как работает баланс в FoxReload

FoxReload не предоставляет GET-эндпоинт баланса. Вместо этого:

• Пополнение — POST /api/topups/crypto/ с параметрами chain, asset, сумма
• Список цепочек — GET /api/topups/crypto/chains/
• Статус пополнения — GET /api/topups/crypto/{topup_id}
• Нехватка средств — ошибка BalanceNotEnough при POST /api/orders/

Для отслеживания расходов используйте историю заказов GET /api/orders/ и суммируйте стоимости.

Как эффективно управлять балансом

1. Обработка ошибки BalanceNotEnough

При получении ошибки нехватки баланса:

try:
    response = create_foxreload_order(items)
except FoxReloadAPIError as e:
    if e.error_code == 'BalanceNotEnough':
        # Не списывать с покупателя
        # Показать "временно недоступно"
        # Запустить алерт для команды операторов
        raise InsufficientBalanceError()

Это предотвращает ситуацию, когда клиент оплатил, но заказ завершился ошибкой из-за баланса аккаунта.

2. Алерт при ошибке BalanceNotEnough

Отслеживайте ошибки BalanceNotEnough как сигнал для немедленного пополнения:

BALANCE_ALERT_TRIGGERED = False

def handle_order_error(error_code):
    if error_code == 'BalanceNotEnough' and not BALANCE_ALERT_TRIGGERED:
        send_alert("Баланс FoxReload недостаточен — пополнение через /api/topups/crypto/")
        # Запустить автоматическое пополнение или уведомить команду

Дополнительно: рассчитывайте дневной расход из GET /api/orders/ и запускайте превентивный алерт, если расчётный остаток покрывает менее 2 дней.

3. Ежедневный мониторинг расходов

Рассчитывайте дневной расход из истории заказов, чтобы планировать пополнения:

# Получить заказы за последние 7 дней
orders = foxreload_get('/api/orders/?limit=1000')
daily_spend = sum_completed_order_costs(orders) / 7  # Средний расход
# Оценка: при текущем темпе баланс кончится через N дней
# days_remaining = known_balance / daily_spend

Это даёт данные для прогнозирования и алертов при аномально высоком расходе (возможные дублирующиеся заказы).

Планирование баланса в зависимости от объёма заказов

Используйте дневной темп расходов для планирования пополнений баланса:

Пополняйте, когда баланс покрывает менее 3–5 дней ожидаемых расходов. Для магазинов с высоким объёмом рассмотрите автоматизацию триггера пополнения.

Автоматическое пополнение баланса через FoxReload API

FoxReload поддерживает пополнение криптовалютой через API, что позволяет автоматизировать процесс:

def trigger_crypto_topup(amount_usd: float):
    # Получить доступные сети
    chains = foxreload_get('/api/topups/crypto/chains/')
    # Создать топап (например, USDT TRC-20)
    topup = foxreload_post('/api/topups/crypto/', {
        'chain': 'tron',
        'asset': 'USDT',
        'balanceCurrency': 'USD',
        'quoteAmount': str(amount_usd),
    })
    # topup содержит адрес для отправки криптовалюты
    send_notification(f"Пополнение инициировано: ${amount_usd:.2f}")
    return topup['id']

Статус пополнения проверяется через GET /api/topups/crypto/{topup_id}.

Чек-лист

• Авторизация X-API-Key настроена для всех запросов к FoxReload
• Обработка ошибки BalanceNotEnough реализована (показывать «временно недоступно», не списывать с клиента)
• Алерт на BalanceNotEnough отправляется команде операторов через Slack, Telegram, email или SMS
• Ежедневный расчёт расходов из GET /api/orders/ для прогнозирования остатка
• Доступные крипто-цепочки получены через GET /api/topups/crypto/chains/
• Пополнение через POST /api/topups/crypto/ протестировано
• (Опционально) Логика автоматического пополнения при приближении к нулевому балансу