دليل تكامل Xsolla API — الوصول إلى منتجات Xsolla عبر FoxReload

سمعة Xsolla في صناعة مدفوعات الألعاب مبنية على 20 عاماً من العمل في البنية التحتية، وأكثر من 3,000 شراكة مع الناشرين، وشبكة عالمية تغطي أكثر من 200 دولة. بالنسبة لموزع السلع الرقمية، هذا الكتالوج — Steam Wallet وPlayStation Store وXbox وBattle.net وعشرات منتجات العملات داخل اللعبة — هو بالضبط ما تريد الوصول إليه.

المشكلة في الباب الرئيسي. التكامل المباشر مع Xsolla API ليس مشروع عطلة نهاية الأسبوع. إنه عملية B2B رسمية تتضمن تفاوضاً على العقد ومراجعة الامتثال والموافقة على خط الائتمان وتسلسل إعداد تقني مع فريق هندسة الشركاء في Xsolla. الجدول الزمني الواقعي من الاتصال الأول إلى أول معاملة مباشرة هو 4-12 أسبوعاً — قيد زمني حاد للشركات التي تحتاج للعمل بمرونة.

هذا الدليل يغطي لماذا هذا التعقيد موجود، وكيف يوفر FoxReload مساراً عملياً لنفس كتالوج منتجات Xsolla عبر واجهة API للمطورين مع وصول في نفس اليوم.

لماذا التكامل المباشر مع Xsolla معقد؟

طبقة العقد هي العقبة الأولى. لا تقدم Xsolla وصولاً للجملة بالخدمة الذاتية. كل علاقة موزع B2B تحكمها اتفاقية موزع رسمية تغطي طبقات التسعير وأسواق البيع المعتمدة وحالات الاستخدام المحظورة وتوزيع المسؤولية.

متطلبات خط الائتمان أو الدفع المسبق العائق التالي. تحتاج Xsolla للتأكد من الدفع. يبدأ الشركاء الجدد عادةً بالدفع المسبق. الوصول لخط الائتمان يتطلب تقييماً ائتمانياً يُمنح عادةً بعد 3-6 أشهر من التداول.

الإعداد التقني ليس خدمة ذاتية. بعد توقيع العقود، يجدول فريق هندسة الشركاء في Xsolla مكالمات التكامل ويراجع تنفيذك ويوافق على الاختبار قبل الإطلاق المباشر.

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

البديل عبر FoxReload: وصول عبر API موحد

FoxReload مجمّع B2B للجملة يجلس بين الموردين كـ Xsolla وموزعين مثلك. يحتفظ FoxReload بعلاقات الموردين المباشرة ويدير العقود وخطوط الائتمان ويعرض كل شيء عبر REST API نظيف وموحد.

كعميل لـ FoxReload، تتكامل مرة واحدة. تحصل على وصول لكتالوج Xsolla بالإضافة إلى 12 موردًا آخر — كل ذلك من خلال نفس طلبات API ونفس المصادقة ونفس تنسيق الاستجابة.

مزايا محددة للوصول إلى Xsolla:

• لا عقد Xsolla مباشر — FoxReload هو الطرف التعاقدي
• لا تفاوض على خط الائتمان — FoxReload يدير دفع الموردين
• وصول في نفس اليوم — إعداد KYC في FoxReload يستغرق ساعات
• تحويل مدمج — إذا كان SKU معين من Xsolla غير متاح مؤقتاً، يمكن لـ FoxReload التوجيه لمورد بديل تلقائياً

جولة التكامل

هذا ما يبدو عليه تكامل FoxReload على مستوى الكود. الأمثلة بـ curl لكن النمط ينتقل مباشرة لأي عميل HTTP.

المصادقة

جميع طلبات FoxReload API تتطلب رمز Bearer في ترويسة Authorization:

Authorization: Bearer مفتاح_API_الخاص_بك

تصفح الكتالوج

curl -X GET https://api.foxreload.com/v1/catalog \
  -H "Authorization: Bearer مفتاح_API_الخاص_بك" \
  -H "Content-Type: application/json"

مثال على الاستجابة (مختصر):

{
  "products": [
    {
      "productId": "steam-wallet-usd-20",
      "name": "Steam Wallet Code $20",
      "supplier": "xsolla",
      "category": "game-top-up",
      "denomination": 20,
      "currency": "USD",
      "countryCode": "US",
      "wholesalePrice": 18.60,
      "available": true
    },
    {
      "productId": "psn-gbp-20",
      "name": "PlayStation Store £20",
      "supplier": "xsolla",
      "category": "gift-card",
      "denomination": 20,
      "currency": "GBP",
      "countryCode": "GB",
      "wholesalePrice": 17.40,
      "available": true
    }
  ],
  "totalProducts": 847
}

استخدم معاملات الاستعلام للتصفية: ?supplier=xsolla، ?category=game-top-up، ?countryCode=SA.

تقديم طلب

curl -X POST https://api.foxreload.com/v1/orders \
  -H "Authorization: Bearer مفتاح_API_الخاص_بك" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "steam-wallet-usd-20",
    "quantity": 5,
    "clientReference": "رقم-طلبك-الداخلي-12345"
  }'

تنتقل معظم الطلبات من processing إلى completed في غضون 30 ثانية.

التحقق من حالة الطلب

curl -X GET https://api.foxreload.com/v1/orders/fr-ord-9a3b7c2d \
  -H "Authorization: Bearer مفتاح_API_الخاص_بك"

استجابة الطلب المكتمل تتضمن رموز التسليم.

إعداد Webhook

سجل نقطة نهاية Webhook في لوحة تحكم FoxReload. عند تغيير حالة الطلب، يرسل FoxReload POST لنقطة النهاية:

{
  "event": "order.completed",
  "orderId": "fr-ord-9a3b7c2d",
  "clientReference": "رقم-طلبك-الداخلي-12345",
  "status": "completed",
  "deliveryCodes": [...]
}

نفّذ المعالجة المتسقة — يعيد FoxReload التسليم عند ردود غير 2xx. استخدم orderId كمفتاح إزالة التكرار.

قائمة تدقيق قبل الإطلاق المباشر

• التحقق من KYC مكتمل ومعتمد
• مفتاح API الإنتاجي محفوظ بأمان في متغيرات البيئة (ليس في الكود)
• نقطة نهاية Webhook نشطة وتستجيب بـ HTTP 200
• منطق التسوية لـ Webhook مُطبّق باستخدام clientReference
• معالجة الأخطاء تشمل: insufficient_balance وproduct_unavailable وregional_restriction
• عملية تعبئة الرصيد محددة
• المراقبة مُعدّة على أوقات استجابة API ومعدلات فشل الطلب

الحالة العملية لاستخدام FoxReload

إذا كنت تحتاج منتجات Xsolla اليوم وليس لديك أسابيع لقضائها في الإعداد المباشر، فـ FoxReload هو الإجابة المباشرة. تكلفة التكامل: API واحد وعملية KYC واحدة وبضع ساعات من التطوير.

إذا كنت تريد في نهاية المطاف علاقة مباشرة مع Xsolla — وهذا يستحق المتابعة عند حجم كافٍ — يوفر FoxReload تكاملاً يعمل في هذه الأثناء. لا يوجد سبب لخسارة أسابيع من الإيرادات في انتظار انتهاء عملية تعاقدية.

لا يوجد سبب يمنعك من التحرك الآن. الكتالوج شامل، وبنية التحويل تعني أنك لست معتمداً على وقت تشغيل أي مورد واحد.