كيفية إعداد التعبئة التلقائية للرصيد في لوحة SMM عبر API

ما يجب تحضيره قبل إعداد التعبئة التلقائية

تربط التعبئة التلقائية رصيد لوحة SMM بخدمة دفع أو نظام فوترة داخلي. تتحقق الخدمة من الرصيد المتبقي، وتنشئ دفعة عند بلوغ الحد المحدد، وتضيف الأموال فقط بعد تأكيد الدفع. للعمل تحتاج إلى وثائق API الخاصة باللوحة، والوصول إلى API الدفع، ومفاتيح منفصلة لبيئة الاختبار وبيئة العمل، بالإضافة إلى سجل لجميع العمليات.

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

افصل التحقق من الرصيد عن قرار الدفع

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

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

اختر الحد ومنطق مبلغ التعبئة

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

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

اضبط القيود المالية بشكل منفصل عن الحد

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

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

أنشئ مفاتيح منفصلة واحمِ الوصول

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

تُخزن المفاتيح في متغيرات البيئة أو في مخزن أسرار محمي. لا تمررها في كود المتصفح أو السجلات أو المستودعات العامة أو رسائل الأخطاء. يجب أن يكون لكل مفتاح مالك وإجراء استبدال واضح. عيب التدوير المتكرر للمفاتيح هو أن التعبئة ستتوقف إذا لم يُحدَّث السر الجديد في جميع عمليات العمل.

أنشئ دفعة بمعرّف فريد

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

فيما يلي مثال عام للطلب. استبدل أسماء الحقول والعناوين بالقيم من وثائق المزوّد المحدد. في المتغير PAYMENT_ID يُخزن معرّف فريد أُنشئ مسبقًا، وCALLBACK_URL يشير إلى معالج خطافات الويب.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

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

تحقق من الرصيد واحفظ حالة العملية

يجب تنفيذ طلب الرصيد قبل قرار التعبئة الجديدة وبعد الإضافة الناجحة. قد يبدو الطلب العام هكذا: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". في الاستجابة احفظ ليس المبلغ فقط، بل ووقت التحقق أيضًا، حتى لا تتخذ قرارًا بناءً على بيانات قديمة.

لكل عملية احتفظ بسجل يحتوي على المعرّف الداخلي، ومعرّف الدفعة لدى المزوّد، والمبلغ، والعملة، ووقت الإنشاء، والحالة، واستجابات API، وسبب الخطأ. سلسلة الحالات المناسبة: «منشأة»، «بانتظار الدفع»، «مدفوعة»، «قيد الإضافة»، «مضافة»، «ملغاة»، «تتطلب تحققًا».

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

استقبل خطاف الويب وتحقق من حالة الدفعة

صفحة الدفع الناجح وإعادة توجيه المستخدم لا تؤكدان وصول الأموال. التأكيد هو خطاف ويب من خدمة الدفع أو إعادة التحقق من الحالة عبر API الخاصة بها. عند استقبال خطاف الويب تحقق من التوقيع، ووقت الإرسال، ومعرّف الدفعة، والمعرّف الخارجي، والمبلغ، والعملة. بعد ذلك فقط حوّل العملية إلى حالة الدفع المؤكد.

بعد التحقق من خطاف الويب من المفيد طلب الحالة الفعلية للدفعة من المزوّد. على سبيل المثال: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". طابق الحالة مع بيانات السجل، ثم أرسل طلب الإضافة إلى لوحة SMM بالمعرّف الداخلي نفسه.

يجب ألا ينشئ خطاف الويب المتكرر إضافة ثانية. يجد المعالج العملية بالمعرّف الخارجي، ويرى الحالة «مضافة»، ويعيد استجابة ناجحة دون إجراءات جديدة. عيب خطافات الويب هو أنها قد تتأخر أو لا تصل إذا كان المعالج غير متاح.

عالج المهلات وإعادة المحاولات والدفعات المعلقة

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

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

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

أضف الدفعة المؤكدة إلى لوحة SMM

قبل الإضافة يتحقق المعالج مرة أخرى: المبلغ لا يتجاوز الحد، والعملة متطابقة، والعملية لم تُلغَ، وحالتها ليست «مضافة» بعد. يُمرر في الطلب المبلغ والمعرّف الخارجي للدفعة. إذا كان API اللوحة يدعم مفتاح التماثل، فاستخدم المعرّف الداخلي نفسه للعملية.

الشكل العام للطلب: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

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

أضف الإشعارات ومفتاح الإيقاف والتحقق من التشغيل

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

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

قائمة التحقق قبل تشغيل التعبئة التلقائية

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