التحقق من الرصيد عبر 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 مع الاستجابة الفعلية. بهذه الطريقة يمكن ملاحظة متى تحجز الخدمة المبلغ ومتى تخصمه نهائياً.

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