📝 توثيق ميزة مواضيع المنشورات (Post Topics)

يوفر هذا المستند المعلومات اللازمة لفريق الموبايل لدمج ميزة "مواضيع المنشورات" الجديدة في التطبيق.

رابط السيرفر الأساسي (Base URL):

https://[YOUR_DOMAIN]/api/v1

المصادقة (Authentication):

تتطلب معظم نقاط النهاية إرسال Bearer Token في العناوين:

Authorization: Bearer {token}
Accept: application/json

1. قائمة جميع المواضيع النشطة

إرجاع قائمة بجميع المواضيع المفعلة مرتبة حسب حقل sort_order.

GET /post-topics

مثال على الاستجابة الناجحة:

{
    "data": [
        {
            "id": 1,
            "name": "الرياضة",
            "description": "كل ما يتعلق بالرياضة والتمارين والأخبار الرياضية",
            "image": "https://domain.com/storage/PostTopics/filename.png"
        },
        {
            "id": 2,
            "name": "الألعاب",
            "description": "تحديات الألعاب ومشاركات اللاعبين",
            "image": "https://domain.com/storage/PostTopics/filename2.png"
        }
    ]
}

2. جلب منشورات موضوع معين

إرجاع قائمة مرقمة (Paginated) بالمنشورات المرتبطة بموضوع محدد.

GET /post-topics/{topic_id}/posts

البارامترات المطلوبة:

  • topic_id: معرف الموضوع (في الرابط).
  • page (اختياري): رقم الصفحة للتنقل.

مثال على الاستجابة الناجحة:

{
    "data": [
        {
            "id": 101,
            "content": "محتوى المنشور هنا...",
            "image": "https://domain.com/storage/Posts/image.jpg",
            "tags": [],
            "coordinates": null,
            "visibility": "public",
            "liked": false,
            "favourites_count": 5,
            "comments_count": 2,
            "creator_id": 1,
            "creator": {
                "id": 1,
                "name": "User Name",
                "avatar": "https://domain.com/storage/avatars/u1.jpg"
            },
            "favourites": {
                "like": 3,
                "dislike": 0,
                "wow": 1,
                "haha": 1,
                "sad": 0,
                "angry": 0,
                "love": 0
            }
        }
    ],
    "links": {
        "first": "...?page=1",
        "last": "...?page=10",
        "prev": null,
        "next": "...?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 10,
        "path": "...",
        "per_page": 15,
        "to": 15,
        "total": 150
    }
}

5. إضافة منشور جديد (صور متعددة ومواضيع)

إضافة منشور يدعم رفع أكثر من صورة واختيار موضوع للمنشور.

POST /posts

البارامترات (Multipart/form-data):

  • content: نص المنشور.
  • visibility: الخصوصية (public, friends, only_me).
  • images[]: (ملفات) مصفوفة من الصور المراد رفعها.
  • topic_id: (اختياري) معرف الموضوع المرتبط بالمنشور.

6. ترويج المنشور

ترويج المنشور ليكون في أعلى قائمة المقترحات لمدة 24 ساعة مقابل 1000 عملة غولدن.

POST /posts/{post_id}/promote

التكلفة:

1000 عملة يتم خصمها من رصيد المستخدم.

7. جلب منشورات مستخدم معين

استخدم هذا المسار لجلب "منشوراتي" أو منشورات أي بروفايل محدد.

GET /posts

البارامترات:

  • by: معرف المستخدم (User ID).

8. ملاحظات لفريق الموبايل

  • حقل الصورة: حقل image في المواضيع يحتوي على رابط كامل وصحيح.
  • الترقيم: قائمة المنشورات مرقمة (15 عنصر في كل صفحة).
  • التفاعلات: كائن favourites يحتوي على تفصيل لأنواع التفاعلات المختلفة.
  • الربط: استخدم topic_id المستخرج من واجهة المواضيع لجلب المنشورات في الواجهة الثانية.