Isht Chat API - التوثيق

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

⚠️ API محمي بمفتاح خاص + نظام جلسات

جميع طلبات API تتطلب مفتاح API صالح. يجب إرسال المفتاح في رأس الطلب (Header):

X-API-Key: YOUR_API_KEY_HERE

🔑 نظام الجلسات (Sessions)

بعض endpoints تتطلب تسجيل دخول. بعد تسجيل الدخول، استخدم session_id في header:

X-API-Key: YOUR_API_KEY_HERE X-Session-ID: YOUR_SESSION_ID

مثال باستخدام cURL:

curl -X GET "https://api.ysnapp.com/api/users" \ -H "X-API-Key: YOUR_API_KEY_HERE"

⚠️ تحذير: لا تشارك مفتاح API الخاص بك مع أي شخص. احتفظ به آمناً.

📍 نقاط النهاية (Endpoints)

� المصادقة والجلسات (Auth & Sessions)

POST /api/auth/register

تسجيل حساب جديد (يتطلب: username, password, name)

✓ يرجع session_id تلقائياً

POST /api/auth/login

تسجيل الدخول (يتطلب: username, password)

✓ يرجع session_id للاستخدام في الطلبات اللاحقة

POST /api/auth/logout

تسجيل الخروج من الجلسة الحالية (يتطلب: X-Session-ID)

GET /api/auth/validate

التحقق من صحة الجلسة (يتطلب: X-Session-ID)

GET /api/auth/sessions

عرض جميع الجلسات النشطة للمستخدم (يتطلب: X-Session-ID)

POST /api/auth/logout-all

تسجيل الخروج من جميع الأجهزة (يتطلب: X-Session-ID)

POST /api/auth/change-password

تغيير كلمة المرور (يتطلب: X-Session-ID, old_password, new_password)

�👥 المستخدمين (Users)

GET /api/users

جلب قائمة المستخدمين

GET /api/users/{id}

جلب معلومات مستخدم محدد

GET /api/users/online

جلب المستخدمين المتصلين حالياً

GET /api/users/search

البحث عن مستخدمين (يتطلب معامل: ?q=keyword)

GET /api/users/statistics

إحصائيات المستخدمين

POST /api/users

إنشاء مستخدم جديد

PUT /api/users/{id}

تحديث معلومات مستخدم

DELETE /api/users/{id}

حذف مستخدم

🏠 الغرف (Rooms)

GET /api/rooms

جلب قائمة غرف الدردشة

GET /api/rooms/{id}

جلب معلومات غرفة محددة

GET /api/rooms/statistics

إحصائيات الغرف

GET /api/rooms/{id}/messages

جلب رسائل غرفة محددة

POST /api/rooms

إنشاء غرفة جديدة

PUT /api/rooms/{id}

تحديث معلومات غرفة

DELETE /api/rooms/{id}

حذف غرفة

💬 الرسائل (Messages)

POST /api/messages

إرسال رسالة جديدة

GET /api/messages/private

جلب الرسائل الخاصة

GET /api/messages/search

البحث في الرسائل (يتطلب معامل: ?q=keyword)

DELETE /api/messages/{id}

حذف رسالة

📝 أمثلة كاملة

1️⃣ تسجيل الدخول:

curl -X POST "https://api.ysnapp.com/api/auth/login" \ -H "X-API-Key: YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "username": "mohamed123", "password": "SecurePass123" }'

الاستجابة:

{ "success": true, "message": "تم تسجيل الدخول بنجاح", "data": { "session_id": "a1b2c3d4e5f6...", "user": { "id": 1, "username": "mohamed123", "name": "محمد أحمد", "email": "[email protected]", "points": 1500 } }, "timestamp": "2026-02-06 10:00:00" }

2️⃣ طلب محمي (يتطلب session_id):

curl -X GET "https://api.ysnapp.com/api/users" \ -H "X-API-Key: YOUR_API_KEY_HERE" \ -H "X-Session-ID: a1b2c3d4e5f6..." \ -H "Content-Type: application/json"

الاستجابة المتوقعة:

{ "success": true, "message": "تم جلب المستخدمين بنجاح", "data": [ { "id": 1, "name": "محمد", "username": "mohamed123", "email": "[email protected]", ... } ] }

3️⃣ تسجيل حساب جديد:

curl -X POST "https://api.ysnapp.com/api/auth/register" \ -H "X-API-Key: YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{ "username": "newuser", "password": "Password123", "name": "مستخدم جديد", "email": "[email protected]", "gender": 0, "country": "SA" }'

🔴 رسائل الخطأ

401 Unauthorized - مفتاح API مطلوب

{ "success": false, "message": "مفتاح API مطلوب", "errors": null }

401 Unauthorized - مفتاح API غير صالح

{ "success": false, "message": "مفتاح API غير صالح", "errors": null }

401 Unauthorized - معرف الجلسة مطلوب

{ "success": false, "message": "معرف الجلسة مطلوب", "errors": null }

401 Unauthorized - الجلسة غير صالحة

{ "success": false, "message": "الجلسة غير صالحة أو منتهية", "errors": null }

401 Unauthorized - كلمة المرور غير صحيحة

{ "success": false, "message": "اسم المستخدم أو كلمة المرور غير صحيحة", "errors": null }

ℹ️ معلومات إضافية

• جميع الطلبات والاستجابات بصيغة JSON

• الترميز: UTF-8

• المنطقة الزمنية: Asia/Riyadh

• نسخة API: 1.1.0

• الحد الأقصى للطلبات: 100 طلب/دقيقة

• نظام المصادقة: API Key + Session-based Authentication

• الجلسات: دعم تعدد الأجهزة (Multi-Device Support)

• تشفير كلمات المرور: bcrypt

🔄 تدفق العمل (Workflow)

1️⃣ تسجيل الدخول/التسجيل

• استخدم POST /api/auth/login أو POST /api/auth/register

• ستحصل على session_id في الاستجابة

• احفظ session_id في localStorage أو cookies

2️⃣ الطلبات اللاحقة

• أضف X-API-Key في header (دائماً)

• أضف X-Session-ID في header (للطلبات المحمية)

3️⃣ إدارة الجلسات

• استخدم GET /api/auth/validate للتحقق من صحة الجلسة

• استخدم GET /api/auth/sessions لعرض الجلسات النشطة

• استخدم POST /api/auth/logout-all لتسجيل الخروج من جميع الأجهزة

🔒 Isht Chat API