دليل دمج نظام البريميوم (Premium System)

هذا المستند يشرح كيفية ربط نظام البريميوم وتفعيل ميزاته وحساب حدود استهلاكها وتفضيلات المشتركين من التطبيق مع الـ APIs.

خطط الباقات والخصومات

باقات مرنة (شهري، ربع سنوي، سنوي) بأسعار وخصومات ديناميكية قابلة للتخصيص من الإدارة.

حدود استهلاك الميزات

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

1. خطط الاشتراك والشراء (Plans & Purchase)

أ. جلب خطط الباقات والأسعار

عرض خطط الاشتراك النشطة وحساب السعر الأصلي والخصومات تلقائياً بالماسات (Diamonds).

GET /api/v1/premium/plans

نموذج استجابة الباقات (JSON Example)

{
    "data": [
        {
            "id": 1,
            "period": "monthly",
            "period_label": "شهري",
            "days": 30,
            "price": 1000,
            "discount_percent": 10,
            "final_price": 900,
            "savings": 100
        }
    ]
}

ب. شراء اشتراك بريميوم

خصم العملات تلقائياً من محفظة المستخدم وتفعيل الاشتراك.

POST /api/v1/premium/purchase

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

الحقل النوع الوصف ملاحظات
plan_id numeric معرف خطة الاشتراك مطلوب ويجب أن يكون ID لخطة نشطة.

نموذج الطلب (JSON Example)

{
    "plan_id": 1
}

2. حالة الاشتراك والميزات (Subscription Status)

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

GET /api/v1/premium/status

نموذج استجابة الحالة (JSON Example)

{
    "data": {
        "has_premium": true,
        "subscription": {
            "id": 5,
            "period": "monthly",
            "period_label": "شهري",
            "started_at": "2026-08-14 15:00:00",
            "expires_at": "2026-09-14 15:00:00",
            "days_remaining": 30
        },
        "features": {
            "hide_gravity_level": {
                "enabled": true,
                "value": false
            },
            "show_visitors_list": {
                "enabled": true,
                "value": true
            },
            "special_badge": {
                "enabled": true,
                "badge_url": "https://url-to-storage/badges/premium.png"
            },
            "change_country": {
                "enabled": true,
                "used": 1,
                "limit": 3,
                "remaining": 2
            },
            "change_gender": {
                "enabled": true,
                "used": 0,
                "limit": 3,
                "remaining": 3
            },
            "chat_bubble": {
                "enabled": true,
                "decoration": {
                    "id": 12,
                    "name": "إطار التاج الذهبي",
                    "image_url": "https://url-to-storage/decorations/bubble.png"
                }
            }
        }
    }
}

3. تغيير الدولة والجنس (Limit Execution)

يتم تغيير وتعديل الدولة والجنس من خلال رابط تحديث الملف الشخصي الحالي والأساسي في التطبيق وليس عبر روابط منفصلة. يقوم النظام تلقائياً بفرض حدود الاستهلاك شهرياً حسب حالة الاشتراك:

  • المستخدم العادي (غير المشترك): مسموح له بالتغيير مرة واحدة (1) فقط شهرياً.
  • المشترك في البريميوم: مسموح له بالتغيير 3 مرات شهرياً (أو حسب الحد المخصص من الإدارة).
POST /api/v1/profile

المعاملات المقبولة (Request Body)

الحقل النوع الوصف ملاحظات
country_id numeric معرف الدولة الجديدة اختياري - في حال رغبة المستخدم في تغيير دولته.
gender string الجنس الجديد اختياري - يجب أن يكون male أو female.

الاستجابة في حال تجاوز الحد المسموح (Validation Error 422)

{
    "message": "The given data was invalid.",
    "errors": {
        "country_id": [
            "عذراً، لقد استنفدت الحد الأقصى المسموح به لـ تغيير الدولة هذا الشهر. المتاح لك هو (1 من المرات شهرياً)."
        ]
    }
}

4. تفضيلات المشترك وحجب المستوى (Preferences & Level Hiding)

أ. تعديل تفضيلات الميزات الفردية

يسمح للمشتركين بتفعيل خيارات إخفاء المستويات أو إخفاء قائمة الزوار الخاصة بهم.

POST /api/v1/premium/features/toggle-preference

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

الحقل النوع الوصف ملاحظات
feature string اسم الميزة المراد تعديلها يجب أن تكون hide_gravity_level أو show_visitors_list.
value boolean قيمة التفضيل الجديد true لتفعيل الإخفاء / false للتعطيل.

نموذج الطلب (JSON Example)

{
    "feature": "hide_gravity_level",
    "value": true
}

ب. آلية حجب المستوى (Level Hiding Logic)

عند قيام المشترك بتحديد hide_gravity_level: true، ستقوم استجابة الـ API في موارد المستخدمين (Public, Single, Basic) بإخفاء وتصفير المستويات وإعادتها كالتالي تلقائياً:
"level": null، "karizma_level": null، "exp_level": null، "payment_level": null، "uid_level": "".
ملاحظة لمطوري التطبيق: يرجى إخفاء أيقونات وشارات المستويات في الواجهة للمستخدمين الذين تعود قيم مستوياتهم بـ null.

5. أكواد الحالة (Response Codes)

200 OK: تمت العملية بنجاح.
422: خطأ بالبيانات، رصيد غير كافٍ، أو استنفاد حدود الاستخدام.
401: التوكن مفقود أو غير فعال.
403: المستخدم غير مشترك في نظام البريميوم.