Resellers के लिए Balance API: यह कैसे काम करता है

संक्षिप्त उत्तर

Balance API आपको programmatically supplier के साथ अपने reseller account credit balance की जाँच करने देता है। आपका account prepaid model पर चलता है: आप funds load करते हैं, और हर order wholesale cost deduct करता है। Balance शून्य होने पर सभी orders fail होते हैं। Balance API इसे रोकता है आपकी system को real-time में available funds की visibility देकर, ताकि आप low balance पर alert कर सकें, insufficient balance पर order creation block कर सकें, और top-up workflows automate कर सकें।

परिभाषा: Balance API एक endpoint है जो digital goods supplier के साथ reseller के account का current credit balance return करता है। इसका उपयोग available funds monitor करने, insufficient balance से failed orders रोकने, और balance replenishment workflows trigger करने के लिए होता है।

मुख्य निष्कर्ष: शनिवार की रात 2 बजे zero balance का मतलब है failed orders, नाराज customers और जब तक कोई manually top up न करे तब तक lost revenue। Automated alerts के साथ Balance API monitoring इसे पूरी तरह रोकता है।

यह Guide किसके लिए है

• Developers जो digital goods supplier API integrate कर रहे हैं
• Store operators जिन्होंने empty balance से failed orders experience किए हैं
• Production-grade digital goods reseller system build करने वाले

Prepaid Balance Model कैसे काम करता है

ज्यादातर digital goods suppliers prepaid (credit) model पर चलते हैं:

1. आप reseller account में funds deposit करते हैं (bank transfer, crypto, आदि)
2. हर order creation balance से wholesale cost deduct करता है
3. Balance शून्य पर पहुँचने पर, order creation calls error return करती हैं
4. आप balance restore करने के लिए top up करते हैं

यह net-30 model से अलग है (जहाँ आप बाद में pay करते हैं)। Prepaid model का मतलब है orders process होने से पहले आपके पास हमेशा sufficient balance होनी चाहिए।

Balance कैसे Monitor करें

FoxReload में dedicated GET /balance endpoint नहीं है। Balance monitor करने के दो तरीके हैं:

1. GET /api/access/me — account info:

GET /api/access/me
X-API-Key: YOUR_API_KEY

Response (example):
{
  "balance": 284.50,
  "currency": "USD"
}

2. BalanceNotEnough error detect करें:

जब balance कम हो, POST /api/orders/ call BalanceNotEnough error return करती है। Production में इस error को catch करके ops team को immediately alert करें।

Balance top up करना:

POST /api/topups/crypto/
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "chain": "TRC20",
  "asset": "USDT",
  "balanceCurrency": "USD",
  "quoteAmount": 500
}

Balance API को Effectively कैसे Use करें

1. Pre-Order Balance Check

Order create करने से पहले, check करें कि balance wholesale cost cover करने के लिए sufficient है:

# GET /api/access/me से balance check करें
resp = requests.get(f"{BASE}/api/access/me", headers=HEADERS)
balance_usd = resp.json().get("balance", 0)

order_cost = get_wholesale_price(item_id, quantity)

if balance_usd < order_cost:
    # Order creation call न करें
    # Customer को "temporarily unavailable" दिखाएं
    # Ops team को balance alert trigger करें
    raise InsufficientBalanceError()

यह frustrating UX रोकता है जहाँ customer ने pay किया लेकिन आपके account balance के कारण order fail हो गया।

2. Low-Balance Alert

Alert threshold set करें — minimum balance जिसके नीचे आप notification चाहते हैं:

ALERT_THRESHOLD = 100.00  # Balance < $100 होने पर alert

def check_balance_alert():
    resp = requests.get(f"{BASE}/api/access/me", headers=HEADERS)
    balance_usd = resp.json().get("balance", 0)
    if balance_usd < ALERT_THRESHOLD:
        send_alert(f"FoxReload balance low: ${balance_usd:.2f}")

इसे scheduled job के रूप में run करें (business hours में हर 15–30 minutes; रात में हर hour)।

3. Daily Balance Monitoring

हर trading day की शुरुआत और अंत में balance log करें। यह देता है:

• Daily spend rate (cash flow planning के लिए useful)
• Alert अगर balance expected से faster drop हो (possible duplicate orders या system issue)
• Current balance कितने समय तक चलेगा project करने का data

daily_spend = opening_balance - closing_balance
days_remaining = closing_balance / daily_spend  # Estimate

Balance vs. Order Volume Planning

Balance top-ups plan करने के लिए daily spend rate use करें:

Expected spend के 3–5 days से कम cover होने पर top up करें। High-volume stores के लिए top-up trigger automate करने पर विचार करें।

Automated Balance Top-Up

High-volume operators के लिए top-up process automate करें:

MIN_BALANCE_DAYS = 3  # हमेशा 3 days का runway maintain करें

def check_and_top_up():
    balance = get_balance()
    daily_spend = calculate_daily_spend()  # Order history से
    days_remaining = balance.amount / daily_spend
    
    if days_remaining < MIN_BALANCE_DAYS:
        top_up_amount = daily_spend * 7  # 7 days तक top up करें
        trigger_top_up(top_up_amount)
        send_notification(f"Balance top-up triggered: ${top_up_amount:.2f}")

इसके लिए आपका top-up method automation support करना चाहिए (कुछ suppliers bank transfer या crypto के through automated top-up support करते हैं)।

Balance API Rate Limits

हर order पर balance endpoint poll न करें। यह API rate limits waste करता है और order flow में latency add करता है। इसके बजाय:

• Balance cache करें: हर 60–300 seconds में update करें
• Order creation पर: expected cost को cached balance value से subtract करें
• Cached balance को actual API response से हर 5–10 minutes में reconcile करें

Checklist

• GET /api/access/me से balance fetch test किया (X-API-Key header)
• Pre-order balance check implement (insufficient होने पर order block)
• BalanceNotEnough error catch और ops alert implement किया
• Low-balance alert threshold set (जैसे $100 या 24-hour spend equivalent)
• Alert Slack, Telegram, email या SMS के through ops team को भेजा
• Balance monitoring scheduled job हर 15–30 minutes चलता है
• Spend tracking के लिए daily balance log
• Per-order API calls से बचने के लिए balance caching
• (Optional) POST /api/topups/crypto/ से automated top-up logic