توثيق API — محفظة الأرستقراطية

دليل دمج محفظة الأرستقراطية لتطبيقات الموبايل (Aristocracy Wallet — Mobile Integration Guide).

معلومات هامة

جميع الطلبات تتطلب Bearer Token للمستخدم المسجّل دخول.

Base URL: https://api.megchat.cc/api/v1

Header مطلوب في كل الطلبات:

Authorization: Bearer {user_token}
Content-Type: application/json
Accept: application/json

1. عرض كروت المحفظة

يجلب جميع كروت الأرستقراطية الموجودة في محفظة المستخدم الحالي (الكروت غير المفعّلة، المخزّنة للاستخدام لاحقاً).

GET /api/v1/privilege-wallet

الرد — نجاح 200

{
  "data": [
    {
      "id": 14,
      "privilege_package_id": 3,
      "privilege_package_name": "أرستقراطي ذهبي",
      "icon_path": "privilege-packages/gold.png",
      "icon_url": "https://api.megchat.cc/storage/privilege-packages/gold.png",
      "valid_days": 30,
      "created_at": "2026-05-13T05:30:00.000000Z"
    }
  ]
}

وصف الحقول

الحقل النوع الوصف
id integer معرّف الكارت الفريد في المحفظة ← هذا هو الـ ID المستخدم في طلبات التفعيل والإهداء
privilege_package_id integer معرّف نوع الأرستقراطية
privilege_package_name string اسم الأرستقراطية
icon_url string رابط أيقونة الأرستقراطية (جاهز للعرض مباشرة)
valid_days integer عدد الأيام التي سيضيفها هذا الكارت عند التفعيل
created_at datetime تاريخ إضافة الكارت للمحفظة

نصيحة: لعرض الكروت مجمّعة حسب النوع، يمكن للتطبيق تجميع النتائج بـ privilege_package_id لعرض "لديك 2 من الذهبي و1 من البلاتيني" بدلاً من عرض كل كارت منفرد.

2. تفعيل كارت من المحفظة

يقوم بتفعيل كارت أرستقراطية محدد من المحفظة لنفس المستخدم.

POST /api/v1/privilege-wallet/{wallet_card_id}/activate

لا يحتاج Body — فقط الـ id في الـ URL.

قواعد التفعيل التلقائي حسب الرتبة:

الحالة النتيجة
لا توجد أرستقراطية مفعّلةتفعيل فوري بكامل الأيام
نفس الرتبة مفعّلةتمديد الأيام الحالية بـ 100%
الكارت رتبة أعلىالغاء القديمة + تفعيل الجديدة كاملاً
الكارت رتبة أدنى بـ 1 درجةإضافة 45% من أيام الكارت
الكارت رتبة أدنى بـ 2 درجةإضافة 25% من أيام الكارت
الكارت رتبة أدنى بـ 3+ درجاتإضافة 10% من أيام الكارت

الرد — نجاح 200

{
  "data": {
    "days_added": 30,
    "valid_until": "2026-06-12 05:30:00"
  },
  "meta": {
    "message": "تم تفعيل الأرستقراطية بنجاح"
  }
}

أخطاء محتملة

403: لا تملك هذا الكارت
422: هذه الأرستقراطية مفعّلة بالفعل
404: الكارت غير موجود

3. إهداء كارت لمستخدم آخر

ينقل كارت أرستقراطية من محفظة المستخدم الحالي إلى محفظة مستخدم آخر.

  • يُهدى الكارت بكامل أيامه الأصلية
  • يصل للمستقبِل كـ كارت في محفظته
  • يتلقى المستقبِل إشعار push notification
  • لا يمكن إهداء كارت لنفس المستخدم
POST /api/v1/privilege-wallet/{wallet_card_id}/transfer

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

الحقل النوع مطلوب الوصف
receiver_id integer ✅ ID المستخدم المستقبِل

نموذج الطلب

{
  "receiver_id": 10042
}

الرد — نجاح 200

{
  "meta": {
    "message": "تم إرسال الأرستقراطية بنجاح"
  }
}

أخطاء محتملة

422: أنت لا تملك هذه الأرستقراطية
422: لا يمكن إرسال أرستقراطية مفعّلة

📱 سيناريو الاستخدام (UI Flow)


┌─────────────────────────────────────┐
│         شاشة المحفظة                │
│                                     │
│  GET /privilege-wallet              │
│                                     │
│  ┌──────────┐  ┌──────────┐         │
│  │ 🟡 ذهبي  │  │ 💎 بلات  │         │
│  │  × 2     │  │  × 1     │         │
│  │ 30 يوم   │  │ 60 يوم   │         │
│  └──────────┘  └──────────┘         │
│                                     │
│  [اضغط على كارت]                    │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│         خيارات الكارت               │
│                                     │
│  📦 أرستقراطي ذهبي                  │
│  ⏱️ صالح لمدة 30 يوم                │
│                                     │
│  ┌─────────────┐ ┌───────────────┐  │
│  │ ⚡ تفعيل   │ │ 🎁 إهداء     │  │
│  │ لنفسي      │ │ لصديق        │  │
│  └─────────────┘ └───────────────┘  │
└──────────────┬──────────────────────┘
          ┌────┴────┐
          │         │
          ▼         ▼
   POST activate  POST transfer
                  + receiver_id

🔔 الإشعارات (Push Notifications)

عند الإهداء، يتلقى المستقبِل إشعاراً من نوع reward (يظهر في قسم الجوائز):

{
  "title": "وصلتك أرستقراطية جديدة! 🎉",
  "body": "قام {اسم المرسل} بإرسال {اسم الباقة} إلى محفظتك.",
  "type": "reward",
  "identifier": "privilege-package-wallet"
}

⚠️ ملاحظات مهمة للمطور

  • الـ id في الطلبات هو معرّف الكارت في المحفظة (privilege_package_user.id) وليس privilege_package_id.
  • مستخدم واحد قد يمتلك أكثر من كارت من نفس الأرستقراطية — كل كارت له id مختلف.
  • بعد التفعيل أو الإهداء، أعد جلب المحفظة (GET /privilege-wallet) لتحديث الواجهة.