واجهة API الرصيد للموزّعين — كيف تعمل

إجابة موجزة

تتيح لك واجهة API الرصيد التحقّق برمجياً من رصيد حساب الموزّع لديك مع المورّد. يعمل حسابك بنموذج مدفوع مسبقاً — تشحن الأموال، ويخصم كل طلب تكلفة الجملة. وإذا بلغ الرصيد الصفر، تفشل جميع الطلبات. تمنع واجهة API الرصيد ذلك بمنح نظامك رؤية فورية للأموال المتاحة، بحيث يمكنك التنبيه عند انخفاض الرصيد، وحظر إنشاء الطلبات عند عدم كفايته، وأتمتة مسارات الشحن.

التعريف: واجهة API الرصيد هي نقطة نهاية تعيد الرصيد الائتماني الحالي لحساب موزّع لدى مورّد سلع رقمية. وتُستخدم لمراقبة الأموال المتاحة، ومنع الطلبات الفاشلة بسبب عدم كفاية الرصيد، وإطلاق مسارات تجديد الرصيد.

الخلاصة الرئيسية: رصيد صفر في الثانية صباحاً ليلة سبت يعني طلبات فاشلة وعملاء غاضبين وإيرادات ضائعة حتى يشحن أحدهم يدوياً. مراقبة API الرصيد مع تنبيهات آلية تمنع ذلك كلياً.

لمن هذا الدليل

• المطوّرون الذين يدمجون API مورّد سلع رقمية
• مشغّلو المتاجر الذين واجهوا طلبات فاشلة بسبب رصيد فارغ
• كل من يبني نظام موزّع سلع رقمية بمستوى إنتاجي

كيف يعمل نموذج الرصيد المدفوع مسبقاً

يعمل معظم مورّدي السلع الرقمية بنموذج مدفوع مسبقاً (ائتماني):

1. تودع الأموال في حساب الموزّع لديك (حوالة بنكية، عملات مشفّرة، إلخ)
2. يخصم كل إنشاء طلب تكلفة الجملة من رصيدك
3. عند بلوغ الرصيد الصفر، تعيد استدعاءات إنشاء الطلبات خطأً
4. تشحن لاستعادة الرصيد

يختلف هذا عن نموذج net-30 (حيث تدفع لاحقاً). فالنموذج المدفوع مسبقاً يعني أنّه يجب أن يكون لديك دائماً رصيد كافٍ قبل أن تتمكّن الطلبات من المعالجة.

كيف يعرض FoxReload الرصيد

لا يملك FoxReload نقطة نهاية GET /balance في واجهة API العامة. ويُفرض الرصيد وقت الطلب — تُدفع الطلبات من رصيدك المدفوع مسبقاً، وإذا كان منخفضاً جداً، يفشل POST /api/orders/ بخطأ BalanceNotEnough. وتشحن الرصيد بالعملات المشفّرة:

POST https://public-api.foxreload.com/api/topups/crypto/
X-API-Key: {api_key}
Content-Type: application/json

{
  "chain": "tron",
  "asset": "USDT",
  "balanceCurrency": "RUB",
  "quoteAmount": 5000
}

لذا فالنمط العملي هو — تتبّع إنفاقك الخاص من سجلّ الطلبات (GET /api/orders/)، وعالج خطأ BalanceNotEnough دفاعياً، واشحن قبل أن ينفد رصيدك.

كيفية استخدام API الرصيد بفعالية

1. فحص الرصيد قبل الطلب

قبل إنشاء طلب، تحقّق من أنّ رصيدك كافٍ لتغطية تكلفة الجملة:

balance = get_balance()
order_cost = get_wholesale_price(sku, quantity)

if balance.amount < order_cost:
    # لا تستدعِ إنشاء الطلب
    # اعرض "غير متاح مؤقتاً" للعميل
    # أطلق تنبيه الرصيد لفريق العمليات
    raise InsufficientBalanceError()

يمنع هذا تجربة مستخدم محبطة يكون فيها العميل قد دفع لكنّ الطلب يفشل بسبب رصيد حسابك.

2. تنبيه انخفاض الرصيد

اضبط عتبة تنبيه — الحدّ الأدنى للرصيد الذي ترغب في تلقّي إشعار دونه:

ALERT_THRESHOLD = 100.00  # نبّه عندما يكون الرصيد < $100

def check_balance_alert():
    balance = get_balance()
    if balance.amount < ALERT_THRESHOLD:
        send_alert(f"Supplier balance low: ${balance.amount:.2f}")

شغّل هذا الفحص كمهمّة مجدولة (كل 15–30 دقيقة خلال ساعات العمل؛ وكل ساعة ليلاً).

3. مراقبة الرصيد اليومية

سجّل رصيدك في بداية كل يوم تداول ونهايته. يمنحك ذلك:

• معدّل الإنفاق اليومي (مفيد لتخطيط التدفّق النقدي)
• تنبيهاً إذا انخفض الرصيد أسرع من المتوقّع (احتمال طلبات مكرّرة أو مشكلة في النظام)
• بيانات لتوقّع مدى استمرار الرصيد الحالي

daily_spend = opening_balance - closing_balance
days_remaining = closing_balance / daily_spend  # تقدير

تخطيط الرصيد مقابل حجم الطلبات

استخدم معدّل إنفاقك اليومي لتخطيط عمليات شحن الرصيد:

اشحن عندما يغطّي الرصيد أقل من 3–5 أيام من الإنفاق المتوقّع. وللمتاجر عالية الحجم، فكّر في أتمتة مُطلق الشحن.

الشحن التلقائي للرصيد

للمشغّلين عالي الحجم، أتمت عملية الشحن:

MIN_BALANCE_DAYS = 3  # حافظ دائماً على احتياطي 3 أيام

def check_and_top_up():
    balance = get_balance()
    daily_spend = calculate_daily_spend()  # من سجلّ طلباتك
    days_remaining = balance.amount / daily_spend
    
    if days_remaining < MIN_BALANCE_DAYS:
        top_up_amount = daily_spend * 7  # اشحن لتغطية 7 أيام
        trigger_top_up(top_up_amount)
        send_notification(f"Balance top-up triggered: ${top_up_amount:.2f}")

يتطلّب هذا أن تدعم طريقة الشحن لديك الأتمتة (بعض المورّدين يدعمون الشحن التلقائي عبر الحوالة البنكية أو العملات المشفّرة).

حدود معدّل API الرصيد

لا تستطلع نقطة نهاية الرصيد عند كل طلب. فهذا يهدر حدود معدّل API ويضيف زمن استجابة إلى مسار طلبك. بدلاً من ذلك:

• خزّن الرصيد مؤقتاً — حدّث كل 60–300 ثانية
• عند إنشاء الطلب — اطرح التكلفة المتوقّعة من قيمة رصيدك المخزّن مؤقتاً
• وفّق الرصيد المخزّن مؤقتاً مع استجابة API الفعلية كل 5–10 دقائق

قائمة التحقّق

• تحديد نقطة نهاية API الرصيد واختبارها
• تطبيق فحص الرصيد قبل الطلب (احظر الطلب إذا كان غير كافٍ)
• ضبط عتبة تنبيه انخفاض الرصيد (مثل $100 أو ما يعادل إنفاق 24 ساعة)
• إرسال التنبيه لفريق العمليات عبر Slack أو Telegram أو البريد أو SMS
• مهمّة مراقبة الرصيد المجدولة تعمل كل 15–30 دقيقة
• سجلّ رصيد يومي لتتبّع الإنفاق
• تخزين الرصيد مؤقتاً لتجنّب استدعاءات API لكل طلب
• (اختياري) منطق شحن تلقائي للعمليات عالية الحجم