🎮 دليل دمج الواجهة البرمجية للعبة Lucky Spinner 3 (Lucky Box)

يوضح هذا المستند كيفية الدمج مع الواجهة الخلفية (Backend) للعبة Lucky Spinner 3، ويشمل كافة الروابط (APIs) اللازمة لتشغيل اللعبة على تطبيقات الموبايل.

المعلومات الأساسية:
- الرابط الأساسي: /api/v1/games/lucky-spinner3
- يتطلب إرسال Bearer Token للمستخدم و api-key في الـ Header لجميع الطلبات.

1. الحصول على معلومات اللعبة (Game Info)

يستخدم هذا الرابط لجلب رصيد المستخدم، أسعار اللفات، وقائمة الجوائز (الهدايا) المعروضة في العجلة.

GET /api/v1/games/lucky-spinner3/info

الاستجابة الناجحة (200 OK)

{
  "data": {
    "user": {
      "id": 123,
      "name": "User Name",
      "wallet": {
        "diamonds": 5000,
        "playing_profit": 1500000,
        "remaining_rounds": 150
      }
    },
    "game": {
      "pricing": {
        "1": 10000,
        "10": 100000,
        "50": 500000
      },
      "gifts": [
        {
          "id": 45,
          "name": "إطار ذهبي",
          "type": "frame",
          "image_path": "https://domain.com/uploads/...",
          "currency_count": 500
        }
      ]
    }
  }
}

2. تنفيذ اللعب (Play / Spin)

يستخدم هذا الرابط عند ضغط المستخدم على زر "Spin" أو "فتح الصندوق".

POST /api/v1/games/lucky-spinner3/play

المعاملات (Body)

يجب إرسال rounds: عدد اللفات (يجب أن يكون من القيم المعرفة في التسعير: 1، 10، أو 50).

الاستجابة الناجحة (200 OK)

{
  "data": [
    {
      "id": 45,
      "name": "ماس 500",
      "image_path": "...",
      "quantity": 1
    }
  ],
  "wallet": {
    "diamonds": 5500,
    "playing_score": 10000
  }
}

3. قائمة المتصدرين (Trending/Leaderboard)

يعرض أفضل اللاعبين أو المرسلين أو المستلمين المرتبطين بالفعالية.

GET /api/v1/games/lucky-spinner3/trending

المعاملات (Query Params)

type: نوع التصنيف (يجب أن يكون: players أو senders أو receivers).

الوصف: يعرض قائمة بأعلى النقاط وأفضل 3 جوائز فاز بها كل شخص.

4. سجل الجوائز الشخصي (User History)

يعرض كافة الجوائز التي فاز بها المستخدم الحالي وكمياتها.

GET /api/v1/games/lucky-spinner3/history

الاستجابة الناجحة (200 OK)

قائمة بالديكوريشن والكميات المجمعة التي حصل عليها المستخدم.

5. ملاحظات تقنية هامة للفرونت إند

أ. أنواع الجوائز (Decoration Type):

يجب على الفرونت التعرف على نوع الجائزة (type) لتحديد كيفية عرضها أو توجيه المستخدم:

  • diamonds: تُضاف لـ "الماس" في المحفظة.
  • salary: تُضاف لـ "الراتب/الدولار" في المحفظة.
  • money: تُضاف لـ "الذهب" في المحفظة.
  • gift / frame / bubble... الخ: تُضاف لمخزن الديكوريشن (My Bag).

ب. منطق الربح (Banking logic):

اللعبة تعمل بنظام "البنك الحي" و "حظ الأوفياء"؛ لذا قد يلاحظ المستخدم أن الحظ يتحسن كلما لعب أكثر، أو أن الجوائز الكبرى تظهر في أوقات معينة (Frenzy Mode).

ج. التعامل مع الأخطاء:

  • نقص الرصيد (422 Unprocessable Entity): يعيد رسالة "لا يوجد لديك نقاط كافية".
  • اللعبة مغلقة: يعيد رسالة "Game is not active yet!".
تم إعداد هذا التوثيق لضمان الدمج السلس وتجربة مستخدم ممتازة.