Skip to main content

Rates

This guide explains how to create and retrieve rates and comments for various content types in the Sumaya369 application. The API provides endpoints for managing user ratings, reviews, and comments on different types of content such as courses, bundles, ebooks, and publications.

Get Combined Comments and Rates​

Retrieve a paginated list of approved comments and ratings for a specific content item. This endpoint combines both ratings and comments into a single sorted list, making it easy to display user feedback.

Endpoint​

  • Method: GET
  • URL: /v1/customer/rateable

Request Parameters​

ParameterTypeRequiredDescription
rateable_idUUIDYesThe ID of the content (course, bundle, ebook)
rateable_typestringYesType of content. Must be one of: 'courses', 'bundles', 'ebooks'
sortstringNoSort direction for results. Default: 'desc'
orderBystringNoField to sort by. Default: 'created_at'
search_textstringNoFilter comments/rates by text content

Success Response​

{
    "success": true,
    "message": "تم جلب البيانات بنجاح.",
    "data": {
        "current_page": 1,
        "first_page_url": "http://127.0.0.1:8000/v1/customer/rateable?rateable_type=courses&rateable_id=7530da80-c7ba-11ef-b949-0155f1835368&page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://127.0.0.1:8000/v1/customer/rateable?rateable_type=courses&rateable_id=7530da80-c7ba-11ef-b949-0155f1835368&page=1",
        "links": [
            {
                "url": null,
                "label": "« السابق",
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/v1/customer/rateable?rateable_type=courses&rateable_id=7530da80-c7ba-11ef-b949-0155f1835368&page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "التالي »",
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "http://127.0.0.1:8000/v1/customer/rateable",
        "per_page": 10,
        "prev_page_url": null,
        "to": 9,
        "total": 9,
        "rates": [
            {
                "id": "ac68d2c0-d1b7-11ef-a78b-ad444f6fb471",
                "rate": "5",
                "email": "ghfranalshamre@gmail.com",
                "name": "Ghufran abd",
                "comment": "شكراً د. سميه الحب / التمرين جداً جميل وخفيف وبدون تعقيدات والاسئله تكشف وتنضف الداخل عن الثراء الموسيقى والاسئله والفيديو كل جوانب التمرين مميزه وهذا كان اول اشتراك لي مع الدكتوره واكيد ليس اخر مره",
                "source": "rate",
                "status": "approved",
                "avatar": "https://i.ibb.co/YhTw0wR/7-512.png",
                "created_at": "2025-01-13",
                "reply": null
            },
            {
                "id": "02ebaa80-d1ad-11ef-b1f6-e14149854783",
                "rate": "5",
                "email": "maha.sh.q.alharbi@gmail.com",
                "name": "مها الحربي",
                "comment": "اول يوم شفت المقطع ..جاني الم اسفل الظهر؟ متحمسة وراح اكتب النتيجة ان شاء الله بعد 21 يوم",
                "source": "rate",
                "status": "approved",
                "avatar": "https://i.ibb.co/YhTw0wR/7-512.png",
                "created_at": "2025-01-13",
                "reply": null
            },
            {
                "id": "0a39a4d0-d171-11ef-87e6-b3591bf6f068",
                "rate": "5",
                "email": "saraxalturkey@gmail.com",
                "name": "SARA ALTURKEY",
                "comment": "بديت أول يوم وأقول واااو! استمتعت باللي شفتو وسمعتو بالتمرين حتى نسيت الفلوس 😄 ماتوقعت كذا أبدًا! فاق توقعاتي لأني بحثت عن إعادة تأطير العقل اللاواعي ولقيت أسئلة مملة، لكن ذا التمرين كان على جوي، مرا حبيته!",
                "source": "rate",
                "status": "approved",
                "avatar": "http://127.0.0.1:8000/storage/15592/IMG_3018.jpeg",
                "created_at": "2025-01-13",
                "reply": null
            },
            {
                "id": "25ff2f10-d00d-11ef-80f4-bb18294160ee",
                "rate": "5",
                "email": "hiba.ereqat@gmail.com",
                "name": "هبة عريقات",
                "comment": "جميلة حصلت على مبلغ في أول أيام من الشهر ممتنة دكتورة ونبهتني على أشياء مهمة ووعيت عليها",
                "source": "rate",
                "status": "approved",
                "avatar": "https://i.ibb.co/YhTw0wR/7-512.png",
                "created_at": "2025-01-11",
                "reply": null
            }
        ]
    },
    "status_code": 200
}

Store Rate​

Create a new rating or review for a specific content item. This endpoint allows authenticated users to submit ratings and optional comments for courses, bundles, ebooks, and publications. All submissions require admin approval before becoming publicly visible.

Endpoint​

  • Method: POST
  • URL: /v1/customer/rates

Request Parameters​

ParameterTypeRequiredDescription
ratenumberYesRating value between 0.5 and 5
commentstringNoReview comment (3-255 characters)
rateable_idUUIDYesID of the content being rated
rateable_typestringYesType of content. Must be one of: 'courses', 'bundles', 'ebooks'

Success Response​

{
    "success": true,
    "message": "تم حفظ البيانات بنجاح.",
    "data": {
        "id": "330cd920-f30c-11ef-9583-035c21250f77",
        "rate": 4.5,
        "email": "developer@sumaya369.net",
        "name": "Hamad Alshabanah",
        "comment": "كورس رائع جدًا",
        "status": null,
        "meta": null,
        "verified": null,
        "rateable_id": "7530da80-c7ba-11ef-b949-0155f1835368",
        "rateable_type": "App\\Models\\Course",
        "writerable_id": "9f2ecd22-5c07-48ec-9415-2979deec4493",
        "writerable_type": "App\\Models\\Customer",
        "reply": null,
        "created_at": "2025-02-25 03:05:19",
        "updated_at": "2025-02-25 03:05:19"
    },
    "status_code": 200
}

Error Responses​

Rating Not Allowed (400)​

{
    "success": false,
    "message": "لا يمكنك التقييم. اما انك غير مشترك او تمت عملية التقييم مسبقا",
    "errors": "لا يمكنك التقييم. اما انك غير مشترك او تمت عملية التقييم مسبقا",
    "data": null,
    "status_code": 400
}

Content Not Found (404)​

{
    "success": false,
    "message": "لم يتم العثور على السجل",
    "data": [],
    "status_code": 404
}

Example Implementation Flow​

  1. Retrieving Comments and Rates

    • Application sends GET request to /v1/customer/rateable
    • Provide required parameters:
      • rateable_id for the content
      • rateable_type to specify content type
    • Optional parameters:
      • sort and orderBy for custom sorting
      • search_text to filter by content
    • System combines comments and rates into a single list
    • Only approved items are included
    • Results are paginated (10 items per page)

  2. Creating New Rates

    • User must be authenticated
    • Application sends POST request to /v1/customer/rates
    • Provide required data:
      • rate value (0.5 to 5)
      • rateable_id and rateable_type
    • Optional: Include comment (3-255 characters)
    • System sets initial status as 'pending'
    • Admin approval required before rate appears publicly

Key Considerations​

  • Comments are distinguished by source: 'comment'
  • Rates are distinguished by source: 'rate'
  • Comments have null rate value
  • Replies are only visible when approved
  • For ebooks and courses, verify can_rate property