واجهة شحن الألعاب — مسار معالجة الطلب
الشحن هو الفئة الوحيدة من السلع الرقمية التي تسلّم فيها فعلاً على حساب شخص آخر، لا منتجاً. لا كود ولا تراجع، والمستلم يتحدد بنص كتبه المشتري بيده. فيما يلي مسار المعالجة الكامل لمثل هذا الطلب، والمواضع التي يكسر فيها هذا الاختلاف بنيةً منسوخة عن بيع المفاتيح.
كيف يختلف الشحن عن الكود
| الخاصية | بطاقة هدية / مفتاح | شحن حساب |
|---|---|---|
| ما يعيده المورّد | نص كود | تأكيد إيداع |
| هل تستطيع حجز البضاعة | نعم، الكود لديك | لا، الإيداع فوري وموجّه |
| المستلم يتحدد بـ | من أعطيته الكود | المعرّف الذي أدخله المشتري |
| الاسترجاع بعد التنفيذ | ممكن أحياناً عبر المُصدِر | مستحيل عملياً |
| الخطر الرئيسي | الكود لا يُستهلك | الرصيد وصل الحساب الخطأ |
ومن ذلك تنبع قاعدة التصميم المركزية: تنتقل الحماية كلها إلى ما قبل أخذ المال. فمع الأكواد يمكنك إصلاح الكثير بعد وقوعه، أما مع الشحن فلا شيء تقريباً.
الخطوة 1. التحقق من معرّف اللاعب قبل الخصم
هذا أهم جزء في التكامل كله، وهو يقع بالكامل على عاتقك.
التحقق من الصيغة
الحد الأدنى الواجب فحصه قبل أخذ المال:
- الطول ومجموعة المحارف. لكل لعبة صيغة معرّف خاصة — أرقام فقط في بعضها، أبجدية رقمية في غيرها، وأحياناً بفاصل.
- الخادم أو المنطقة. كثير من الألعاب تطلب خادماً أو نطاقاً مع المعرّف. وبدونه يذهب الشحن إلى المكان الخطأ أو يفشل تماماً.
- الشوائب. المسافات في الطرفين، بادئة «ID:» ملصوقة، محارف زائدة من تطبيق محادثة. طبّع النص قبل إرساله.
التحقق من وجود الحساب
بعض المورّدين يوفّرون نقطة نهاية مخصصة للتحقق من المعرّف تعيد اسم اللاعب المستعار. وبعضهم لا يفعل، والتوفر يختلف بحسب اللعبة. اسأل مورّدك عمّا إذا كان هذا الفحص متاحاً للألعاب التي تبيعها.
وحيث يتوفر، استعمله واعرض الاسم على المشتري قبل الدفع. فهو أرخص وسيلة لمنع النزاعات: من يرى اسم شخص غريب يصحّح معرّفه بنفسه.
تأكيد المشتري
حتى بلا فحص للاسم، تبقى شاشة التأكيد قبل الخصم إلزامية. وتعرض:
- المعرّف تماماً كما سيُرسل إلى المورّد.
- المنطقة أو الخادم.
- عبارة صريحة بأن الإيداع لا رجعة فيه.
- طابعاً زمنياً للتأكيد ينتقل إلى سجلّك.
هذا السجل هو جوابك حين يزعم المشتري بعد أسبوع أنه كتب رقماً آخر.
الخطوة 2. إنشاء الطلب
يُنشأ الطلب كأي طلب آخر، لكن مع بيانات إضافية على البند:
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
}'
في FoxReload ينتقل معرّف اللاعب داخل الحقل note الخاص بالبند — وهو كائن يقبل حتى عشرة مفاتيح بيانات إضافية. وأي مفاتيح يتوقعها منتج بعينه موصوفة في حقلَي attributes وuserGuide الخاصين به.
بشأن عدم التأثير التكراري. بعض الواجهات تقبل ترويسة Idempotency-Key كي لا تنشئ إعادة الإرسال طلباً ثانياً. تحقق مما إذا كان مورّدك يطبّقها — كثيرون لا يفعلون. ولا يفعل FoxReload، لذا فانتهاء المهلة عند الإنشاء يجب ألا يقود إلى إعادة محاولة عمياء: اطلب قائمة الطلبات أولاً وتأكد أن شيئاً لم يُنشأ. وفي الشحن تكون كلفة هذا الخطأ أعلى منها في الأكواد — فالتكرار يعني إيداعاً ثانياً لن تستعيده أبداً.
الخطوة 3. الاكتمال غير المتزامن
يتنقل الطلب بين الحالات تسلسلياً وفي اتجاه واحد فقط:
| الحالة | المعنى | ما يفعله نظامك |
|---|---|---|
active |
أُنشئ الطلب بانتظار الخصم من الرصيد | سجّل order_id وابدأ الاستطلاع |
paid |
خُصم الرصيد | لا شيء، واصل الانتظار |
processing |
المورّد يودع في الحساب | واصل الاستطلاع مع تراجع تدريجي |
completed |
أُودع الرصيد في الحساب | أبلغ المشتري وأغلق الطلب |
cancelled |
أُلغي الطلب، راجع cancelReason |
استرد للمشتري |
failed |
فشل التنفيذ، راجع items[].error |
صنّف السبب وقرّر الاسترداد أو الإعادة |
تُجلب الحالة بالاستطلاع:
curl "https://public-api.foxreload.com/api/orders/{order_id}" \
-H "X-API-Key: YOUR_API_KEY"
تحقق مما إذا كان مورّدك يوفّر الويب هوك. فإن وفّرها فاستعملها مسرِّعاً مع إبقاء الاستطلاع مصدراً للحقيقة، لأن التسليم غير مضمون أبداً. أما FoxReload فلا يدعم الويب هوك، فالاستطلاع هنا هو الآلية الوحيدة.
شكل الاستطلاع: مكثف في الدقيقة الأولى، ثم فاصل يتّسع، مع مهلة خاصة بك وطابور للطلبات التي تتجاوزها. وهذا الطابور أهم في الشحن منه في أي مكان آخر — فالمشتري الذي لا يرى الرصيد داخل اللعبة يراسل الدعم أسرع ممن ينتظر مفتاحاً.
معالجة أعمق لتصميم آلات الحالة هذه في مقال آلة حالات الطلب.
الخطوة 4. الأخطاء النهائية مقابل القابلة للإعادة
الفصل بين هذين الصنفين هو ما يميّز تكاملاً يعمل عن آخر يحرق المال.
نهائية — الإعادة بلا جدوى
- معرّف لاعب غير صالح. الحساب غير موجود أو الصيغة خاطئة. الإعادة تعيد الجواب نفسه. استرد للمشتري واطلب منه مراجعة المعرّف.
- المنطقة غير مدعومة. لا يمكن إيداع المنتج في حساب من تلك المنطقة. استرداد.
- المنتج غير متاح لذلك الحساب. كباقة لا تُباع لمن هم دون مستوى معيّن أو لا تُباع في ذلك البلد.
- أخطاء المصادقة والتحقق من الطلب —
HTTP 400و401و403. هذه علّة في شيفرتك لا انقطاع خدمة.
عند خطأ نهائي أخرج الطلب من حلقة الاستطلاع فوراً وسلّمه لمسار الاسترداد.
قابلة للإعادة — تستحق محاولة أخرى
HTTP 429— تجاوز حد المعدّل. تراجع أسّي مع تشويش عشوائي.HTTP 5xx— عطل لدى المورّد. تراجع تدريجي وعدد محاولات محدود.- انتهاء مهلة الشبكة. احترس هنا: افحص حالة الطلب أولاً ثم قرّر.
- عدم توفر اللعبة مؤقتاً. صيانة الناشر سبب كلاسيكي لبقاء الطلب عالقاً في
processing. انتظر ولا تعِد إنشاء الطلب.
الخطأ الذي يقع فيه الجميع تقريباً في البداية: اعتبار انتهاء المهلة قابلاً للإعادة وإنشاء طلب جديد فوراً. في الشحن يعني ذلك إيداعاً مزدوجاً ومالاً لن تستعيده.
الخطوة 5. الاسترداد والاسترجاع
تقبّل الواقع بصراحة هنا: لا وجود لاسترجاع آلي للإيداع.
السيناريوهات وما يُفعل بها:
- بلغ الطلب
cancelledأوfailedقبل الإيداع. تسترد للمشتري عبر وسيلة الدفع لديك، ويعيد المورّد المبلغ إلى رصيدك وفق قواعده — اعرف تلك القواعد مسبقاً. - نجح الإيداع لكن المشتري غير راضٍ. البضاعة سُلّمت. الاسترداد هنا قرار تجاري لا عملية تقنية.
- ذهب الإيداع إلى معرّف أدخله المشتري خطأً. غير قابل للإصلاح تقنياً. موقفك هو سجل التأكيد. ولهذا بالضبط ليست شاشة التأكيد اختيارية.
- تنفيذ جزئي لطلب متعدد البنود. عالج البنود باستقلال: أبقِ ما اكتمل واسترد ما لم يكتمل.
خصّص في اقتصادياتك احتياطياً صغيراً للحالات المتنازع عليها. فهي حتمية مع الحجم، ورؤيتها بنداً مستقلاً أفضل من مفاجأة انخفاض الهامش. طريقة حسابها في اقتصاديات الوحدة للموزّع.
الخطوة 6. المطابقة
المطابقة اليومية انضباط أساسي لا ميزة اختيارية.
اسحب قائمة طلبات المورّد:
curl "https://public-api.foxreload.com/api/orders/?statuses=completed,failed,cancelled&limit=100" \
-H "X-API-Key: YOUR_API_KEY"
وقارنها بقاعدة بياناتك. ما تبحث عنه:
- طلبات لدى المورّد لا سجل لها عندك. البصمة الكلاسيكية لتكرار ناتج عن إعادة محاولة عمياء.
- طلبات ما زلت تعرضها قيد التنفيذ وقد أنهاها المورّد. إما تعطّل المستطلِع أو مات المسار.
- فروق في المبالغ. سعر لحظة الطلب يختلف عن سجلّك، أي أنك تلتقط السعر في اللحظة الخاطئة.
- خصومات من الرصيد بلا طلب مقابل. حقّق فوراً.
المطابقة تُظهر المشكلات خلال ساعات لا في نهاية الشهر حين لا يبقى شيء تطابقه.
من أين تجلب عمليات الشحن بالجملة
يستحق جلب عمليات الشحن من المصدر نفسه الذي تجلب منه بقية تشكيلتك — تكامل واحد بدل عدة. FoxReload مورّد جملة للسلع الرقمية بأكثر من 900 صنف تشمل شحن حسابات الألعاب وبطاقات الهدايا والمفاتيح وشرائح eSIM ورخص البرمجيات، كلها خلف واجهة REST واحدة مع تسليم آلي وأصناف متعددة المناطق. نموذج طلب واحد ومفردات حالة واحدة عبر الفئات كلها، بما فيها المنتجات التي تتطلب معرّف لاعب.