توثيق API

دمج Mindova في تطبيقاتك مع RESTful API لدينا

البدء

تتيح واجهة برمجة Mindova للمطورين التفاعل برمجياً مع التحديات والمساهمين والمهام والفرق. وتتطلب جميع نقاط النهاية أدناه المصادقة باستخدام رمز حامل من Laravel Sanctum.

عنوان URL الأساسي

https://mindova.online/api

روابط سريعة

المصادقة

يجب أن تتضمن جميع طلبات API رمز مصادقة في رأس Authorization.

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

الحصول على رمز

لا توجد نقطة نهاية مستقلة لتسجيل الدخول بصيغة JSON. يُصدر رمز Sanctum تلقائياً عندما يصادق المستخدم عبر تطبيق الويب — سواء بالبريد الإلكتروني وكلمة المرور أو عبر LinkedIn — ويصبح عندها متاحاً لجلسة المتصفح تلك.

POST /login (تسجيل دخول عبر نموذج الويب، ليس ضمن ‎/api)
GET /api/auth/linkedin/redirect و /api/auth/linkedin/callback (مصادقة LinkedIn)

عند نجاح تسجيل الدخول، ينشئ الخادم رمز وصول شخصياً من Sanctum ويخزّنه في الجلسة. ويكتب تخطيط التطبيق هذا الرمز في localStorage.api_token لاستخدامه من قِبل JavaScript داخل الصفحة كرمز حامل. وإذا كنت تبني تكاملاً خارجياً، فأنشئ رمزاً لحساب خدمة بالطريقة نفسها (سجّل الدخول مرة واحدة بذلك المستخدم) وخزّن الرمز الناتج بأمان لديك — فهو لا يُدوَّر تلقائياً.

إبطال رمز

POST /api/auth/logout

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

المساهمين

إكمال ملف المساهم

POST /api/volunteers/complete-profile

ينشئ ملف المساهم للمستخدم المصادق عليه. ويُرجع 422 إذا كان الملف موجوداً بالفعل.

{
  "availability_hours_per_week": 20,
  "bio": "Full-stack developer passionate about...",
  "field": "Software Engineering"
}

الحصول على ملف المساهم الحالي

GET /api/volunteers/profile

يسترجع معلومات ملف المساهم المصادق عليه بما في ذلك المهارات والإحصائيات.

الاستجابة

{
  "id": 1,
  "user_id": 1,
  "availability_hours_per_week": 20,
  "bio": "Full-stack developer passionate about...",
  "reputation_score": 75,
  "skills": [
    {
      "id": 1,
      "name": "JavaScript",
      "proficiency_level": "expert"
    }
  ]
}

تحديث ملف المساهم

PUT /api/volunteers/profile

نص الطلب

{
  "availability_hours_per_week": 25,
  "bio": "Updated bio text...",
  "field": "Data Science"
}

جميع الحقول اختيارية عند التحديث. السير الذاتية ليست جزءاً من نقطة النهاية هذه — استخدم نقطة نهاية الرفع أدناه.

رفع السيرة الذاتية

POST /api/volunteers/upload-cv

رفع متعدد الأجزاء. يستبدل أي سيرة ذاتية موجودة ويضعها في قائمة انتظار التحليل بالذكاء الاصطناعي.

cv — ملف مطلوب، بصيغة pdf أو doc أو docx، بحد أقصى 10 ميجابايت

الشركات

إكمال ملف الشركة

POST /api/companies/complete-profile

ينشئ ملف الشركة للمستخدم المصادق عليه. ويُرجع 422 إذا كان الملف موجوداً بالفعل.

{
  "company_name": "Acme Inc.",
  "industry": "Technology",
  "website": "https://acme.example.com",
  "description": "What the company does...",
  "logo": "(multipart file, optional, jpeg/png/jpg/gif, max 2MB)"
}

الحصول على ملف الشركة الحالي

GET /api/companies/profile

يُرجع ملف الشركة المصادق عليها مع تحدياتها.

تحديث ملف الشركة

PUT /api/companies/profile

يقبل نفس حقول إكمال الملف الشخصي؛ وجميع الحقول اختيارية.

التحديات

قائمة جميع التحديات

GET /api/challenges

يُرجع قائمة تحديات مقسّمة إلى صفحات.

تحدياتي

GET /api/challenges/my-challenges

يُرجع التحديات التي أرسلتها الشركة المصادق عليها.

الحصول على تحدي واحد

GET /api/challenges/{id}

يُرجع معلومات تفصيلية عن تحدٍّ معين تشمل شركته وتحليلات الذكاء الاصطناعي ومسارات العمل والمهام والأفكار.

إنشاء تحدي

POST /api/challenges

أنشئ تحدياً جديداً. يتطلب حساب شركة. ويُطلق تحليل الملخص بالذكاء الاصطناعي عند الإرسال.

نص الطلب

{
  "title": "Challenge Title",
  "description": "Detailed description (100-5000 characters)..."
}

لا تحتوي التحديات على حقول مواعيد نهائية — لا يوجد submission_deadline ولا completion_deadline.

تحديث التحدي

PUT /api/challenges/{id}

للشركة المالكة فقط، وفقط طالما كان التحدي ما زال مُرسلاً أو قيد التحليل.

{
  "title": "Updated title",
  "description": "Updated description (100-5000 characters)..."
}

كلا الحقلين اختياري عند التحديث.

أرشفة التحدي

POST /api/challenges/{id}/archive

للشركة المالكة فقط. ويضبط حالة التحدي إلى "مؤرشف".

المهام

عرض المهام

GET /api/tasks

الحصول على المهام المتاحة

GET /api/tasks/available

يُرجع المهام المفتوحة المطابقة لمهارات المساهم المصادق عليه، باستثناء المهام المُسندة إليه بالفعل.

مهامي

GET /api/tasks/my-tasks

يُرجع المهام التي لدى المساهم المصادق عليه إسناد عليها.

الحصول على مهمة واحدة

GET /api/tasks/{id}

تعيينات المهام

تربط الإسنادات المساهم بالمهمة وتمر عبر دورة حياة الحالة: مدعو ← مقبول/مرفوض ← قيد التنفيذ ← مُرسل ← مكتمل.

إسناداتي

GET /api/assignments

يُرجع إسنادات المساهم المصادق عليه، أو المهام التابعة لتحديات الشركة المصادق عليها.

الإسنادات المعلّقة

GET /api/assignments/pending

قبول / رفض الإسناد

POST /api/assignments/{id}/accept

POST /api/assignments/{id}/reject

لا يمكن الرد إلا للمساهم المدعو، وفقط طالما كانت الحالة "مدعو". ولا يجوز أن يكون للمساهم أكثر من مهمة نشطة واحدة في الوقت نفسه، لذا قد يفشل القبول بالرمز 422 إن كانت لديه مهمة قيد التنفيذ بالفعل.

// reject body (optional)
{
  "reason": "Not available this sprint"
}

بدء / إتمام الإسناد

POST /api/assignments/{id}/start

POST /api/assignments/{id}/complete

إرسال الحل

POST /api/assignments/{id}/submit-solution

{
  "description": "What was built and how (min 10 characters)",
  "deliverable_url": "https://github.com/...",
  "hours_worked": 12.5,
  "attachments[]": "(optional files, max 10MB each)"
}

ملاحظة: تستجيب نقطة النهاية هذه حالياً بإعادة توجيه بدلاً من JSON، حتى لعملاء واجهة البرمجة. تعامل مع الحالة 2xx/3xx كنجاح وأعد جلب الإسناد للتأكيد.

الفرق

تشكيل الفرق والرد على الدعوات ميزتان متاحتان حالياً على الويب فقط (قائمتان على الجلسة، وليستا جزءاً من واجهة الرموز هذه). ويقتصر نطاق واجهة البرمجة الخاص بالفرق على المراسلة داخل الفريق.

عرض رسائل الفريق

GET /api/teams/{id}/messages

يجب أن يكون الطالب عضواً في الفريق.

إرسال رسالة للفريق

POST /api/teams/{id}/messages

{
  "message": "Text content, max 2000 characters"
}

يتم قبول دعوة الفريق أو رفضها عبر تطبيق الويب على /teams/{id}/accept و /teams/{id}/decline — تتطلب هذه جلسة متصفح مسجّلة الدخول ولا يمكن الوصول إليها برمز حامل.

الإشعارات

عرض الإشعارات

GET /api/notifications

عدد غير المقروء

GET /api/notifications/unread-count

تعليم كمقروء

POST /api/notifications/{id}/mark-read

POST /api/notifications/mark-all-read

حذف الإشعار

DELETE /api/notifications/{id}

الأفكار (تحديات نقاش المجتمع)

GET /api/challenges/{challenge}/ideas — عرض أفكار تحدي نقاش مجتمعي
POST /api/challenges/{challenge}/ideas — { "title", "description" } (الوصف من 100 إلى 2000 حرف، للمساهمين فقط، ويجب أن يكون التحدي نشطاً)
GET /api/ideas/my-ideas — الأفكار المُرسلة من المساهم المصادق عليه
GET /api/ideas/{id}
POST /api/ideas/{id}/vote — { "vote": -1 | 0 | 1 } (لا يمكنك التصويت لفكرتك؛ ويجب أن تكون الفكرة مُقيَّمة بالذكاء الاصطناعي مسبقاً)

رموز الخطأ

يستخدم API رموز حالة HTTP القياسية:

كود	المعنى
200	موافق - الطلب ناجح
201	تم الإنشاء - تم إنشاء المورد بنجاح
401	غير مصرح - رمز غير صالح أو مفقود
403	محظور - صلاحيات غير كافية، مثل نوع حساب خاطئ أو أنك لست مالك المورد
404	غير موجود - المورد غير موجود
422	كيان غير قابل للمعالجة - فشل التحقق، أو أن الإجراء غير صالح للحالة الحالية للمورد
500	خطأ في الخادم - حدث خطأ ما

تنسيق استجابة الخطأ

{
  "message": "Error message",
  "errors": {
    "field": ["Validation error message"]
  }
}

يظهر كائن "errors" فقط عند إخفاقات التحقق بالرمز 422. وبعض نقاط النهاية (وأبرزها submit-solution) مبنية أساساً لواجهة الويب وتُرجع حالياً إعادة توجيه بدلاً من JSON — راجع الملاحظة على تلك النقطة أعلاه.

حدود المعدل

لا يوجد حالياً أي تحديد لمعدل الطلبات مضبوط على واجهة البرمجة. ولا تُقيَّد الطلبات بما يتجاوز سعة الخادم القياسية، ولا تُرجَع اليوم استجابات 429 ولا ترويسات X-RateLimit-*.

محاولات تسجيل الدخول هي الاستثناء: نموذج تسجيل الدخول على الويب محدود بـ 5 محاولات لكل تركيبة بريد إلكتروني/عنوان IP قبل حظر المحاولات الإضافية. ابنِ التكاملات بحذر وتجنّب حلقات الاستطلاع المتقاربة — فقد يُطبَّق تحديد صريح لمعدل واجهة البرمجة مستقبلاً.

تحتاج مساعدة؟

للحصول على دعم إضافي مع API، يرجى الاتصال بفريق دعم المطورين لدينا.

اتصل بدعم المطورين