شرح تدفّق الطلبات في FoxReload — Active وPaid وProcessing وCompleted وFailed

إذا كنت تُكامل FoxReload على نطاق واسع، فعليك نمذجة حالة الطلب بعناية في نظامك — إذ يعتمد كل من دعم العملاء والتسوية على فهم معنى كل حالة وموعد حدوث الانتقالات. يستعرض هذا المقال تدفّق طلبات FoxReload الكامل كما يعمل فعليًا في بيئة الإنتاج.

الحالات الست

ينتقل كل طلب عبر ما يصل إلى ست حالات. تكتمل معظم الطلبات في المسار المثالي خلال أقل من 60 ثانية.

آلة الحالات تتقدّم في اتجاه واحد فقط بشكل صارم. لا يمكن للطلب completed أن يتراجع. تحمل الطلبات الملغاة قيمة cancelReason — وهي payment_failure أو payment_expiration أو user_request أو null.

1. إنشاء طلب

استدعِ POST /api/orders بجسم JSON يسرد العناصر عبر itemId (وهو معرّف المنتج id من الكتالوج) والكمية، واختياريًا totalPrice وكائن note للمنتجات التي تتطلب بيانات إضافية مثل معرّف اللاعب.

curl -X POST "https://public-api.foxreload.com/api/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "product_01krgfgww8eth9xvvysd6y7r4j",
        "quantity": 1,
        "note": {"player_id": "123456"}
      }
    ],
    "isMock": false
  }'

يعيد الاستدعاء الناجح الرمز HTTP 201 مع كائن الطلب والحالة status: "active". تُخصم الطلبات من رصيد حسابك؛ وإذا كان الرصيد منخفضًا جدًا فستتلقى خطأ BalanceNotEnough. لا توجد بيئة اختبار منفصلة — استخدم "isMock": true لتلقّي أكواد وهمية للاختبار دون إنفاق رصيد فعلي.

2. دفع الطلب

بمجرد أن يصبح الطلب active، استدعِ POST /api/orders/{order_id}/pay لإنشاء عملية دفع خارجية له. يقبل جسم الطلب قيمة اختيارية لـ paymentProvider (pally أو yookassa أو tbank؛ الافتراضي pally)، وpaymentMethodType (مثل bank_card أو sbp؛ الافتراضي sbp)، وpaymentReturnUrl. تتضمن الاستجابة رابط confirmationUrl لإعادة توجيه العميل.

عند تأكيد الدفع ينتقل الطلب إلى paid، ثم على الفور تقريبًا إلى processing.

3. من Processing إلى Completed

يُرسَل الطلب إلى المورّد. عند نجاح التسليم تصبح الحالة completed وتُعبَّأ كل مصفوفة items[].externalData بالأكواد المُسلَّمة أو بيانات التفعيل. تظهر أخطاء كل عنصر، إن وُجدت، في items[].error.

استطلِع GET /api/orders/{order_id} للتحقق من التقدّم. لا يرسل FoxReload أي webhooks — فالاستطلاع هو النمط المدعوم.

curl "https://public-api.foxreload.com/api/orders/{order_id}" \
  -H "X-API-Key: YOUR_API_KEY"

حلقة استطلاع عملية — تحقّق كل 5 ثوانٍ لمدة تصل إلى دقيقتين، ثم كل 30 ثانية لمدة تصل إلى 10 دقائق. إذا لم يصل الطلب بعد ذلك إلى completed أو cancelled/failed، فنبّه فريق العمليات لديك.

4. مساري cancelled وfailed

عندما ينتهي الطلب بحالة cancelled أو failed، لا يُخصم رصيدك (أو يُسترد إن خُصم قبل الفشل). حدّث واجهتك وأبلغ العميل وفقًا لذلك.

5. الطلبات الاختبارية

مرّر "isMock": true في جسم الطلب لتلقّي أكواد واقعية لكنها وهمية. يمرّ الطلب عبر دورة حياة الحالات الكاملة كي تختبر منطق الاستطلاع والتسليم لديك دون استخدام رصيد فعلي أو مخزون مورّد حقيقي. لا يوجد رابط بيئة اختبار منفصل — تذهب الطلبات الوهمية إلى نفس عنوان القاعدة https://public-api.foxreload.com.

هل أنت جاهز للتكامل؟ سجّل في foxreload.com — تُنشأ مفاتيح الـ API في Dashboard ← API ويمكن تقييدها بقائمة عناوين IP مسموح بها لمزيد من الأمان.