دليل ربط واجهات عملة الشيبس (Chips API)

تم إدراج عملة جديدة للألعاب باسم شيبس (Chips) وتوفير واجهات برمجية آمنة للتحويل بينها وبين عملة الماس (Diamonds) الأساسية للتطبيق.

الماس إلى شيبس

النسبة: 1 ماسة = 5 شيبس

الحد الأدنى للتحويل هو 50,000 ماسة.

شيبس إلى ماس

النسبة: 5 شيبس = 0.9 ماسة

أي ما يعادل (1 شيبس = 0.18 ماسة) مع تقريب النواتج لأقرب رقم صحيح.

الحد الأدنى للاسترجاع

الحد الأدنى: 100,000 شيبس

لا يمكن استرجاع كمية أقل من 100,000 شيبس في العملية الواحدة.

ملاحظة التوثيق المالي:

تتطلب جميع نقاط النهاية إرسال رمز التوثيق (API Token) الخاص بالمستخدم في الترويسات (Bearer Token).

شراء عملة الشيبس (التحويل من ماس إلى شيبس)

يتم استدعاء هذا الرابط لتبديل رصيد الماس الخاص بالمستخدم إلى عملة الشيبس بمعدل (1 ماسة = 5 شيبس):

POST /api/v1/users/{user_id}/chips/convert-from-diamonds

معاملات الطلب (Payload):

الحقل النوع الوصف
amount عدد صحيح (Integer) كمية الماس المراد تحويلها (يجب ألا تقل عن 50,000 ماسة).

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

{
    "meta": {
        "message": "تم تحويل العملة إلى شيبس بنجاح"
    }
}

استجابة الخطأ لعدم بلوغ الحد الأدنى (422 Unprocessable Entity):

{
    "error": "الحد الأدنى لعملية التحويل هو 50,000 عملة"
}

استجابة الخطأ لعدم كفاية الرصيد (422 Unprocessable Entity):

{
    "error": "ليس لديك ما يكفي من العملة للتحويل"
}

استرجاع الماس (التحويل من شيبس إلى ماس)

يتم استدعاء هذا الرابط لتبديل رصيد الشيبس إلى ماس بمعدل (1 شيبس = 0.18 ماسة)، بشرط ألا تقل الكمية المحولة عن 100,000 شيبس:

POST /api/v1/users/{user_id}/chips/convert-to-diamonds

معاملات الطلب (Payload):

الحقل النوع الوصف
amount عدد صحيح (Integer) كمية الشيبس المراد استرجاعها (يجب ألا تقل عن 100,000 شيبس).

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

{
    "meta": {
        "message": "تم استرجاع العملة من الشيبس بنجاح"
    }
}

استجابة الخطأ عند إدخال قيمة أقل من الحد الأدنى (422 Unprocessable Entity):

{
    "error": "الحد الأدنى لعملية الاسترجاع هو 100,000 شيبس"
}

استجابة الخطأ لعدم كفاية رصيد الشيبس (422 Unprocessable Entity):

{
    "error": "ليس لديك ما يكفي من عملة شيبس للتحويل"
}

المحفظة وسجل النشاطات (Database Schema & Activity Logs)

حقل المحفظة في الاستجابات:

يعود رصيد الشيبس المتاح للمستخدم ضمن كائن المحفظة (Wallet Resource Object) تحت حقل chip: 

"wallet": {
    "diamond": 25000,
    "gold": 50000,
    "chip": 150000
}

تتبع السجلات بقاعدة البيانات:

عند تسجيل نشاط تحويل يتعلق بالشيبس (نوع العملة chips)، يسجل النظام آلياً:

  • الرصيد قبل الحركة: chips_currencies_count_before_action
  • الرصيد بعد الحركة: chips_currencies_count_after_action