🚀 البداية والتهيئة
توثيق شامل لجميع مسارات واجهة برمجة تطبيقات المشتركين في منظومة FreeNet. يغطي هذا التوثيق 35+ نقطة وصول (Endpoint) تشمل المصادقة، إدارة الباقات، المحفظة، الفواتير، الاستهلاك، الدعم الفني والمجلة الرقمية.
⚙️ تخصيص رابط الـ Base URL المباشر للطلبات
| Header | القيمة | الوصف | إلزامي؟ |
|---|---|---|---|
| Accept | application/json | دائماً لاستقبال JSON | مطلوب |
| Content-Type | application/json | في طلبات POST فقط | مطلوب مع POST |
| Authorization | Bearer {token} | في المسارات المحمية بعد Login | مطلوب بعد Login |
| Accept-Language | ar / en | لغة رسائل الاستجابة | اختياري |
🔐 إرشادات الأمان للمطورين
- تخزين التوكن بأمان: لا تحفظ الـ Token في نص صريح (Plaintext) أو SharedPreferences. استخدم Android Keystore أو iOS Keychain حصراً.
- حظر Hardcoded Keys: لا تضع أي بيانات حساسة ثابتة داخل الكود المصدري. يجب جلبها من endpoint آمن عند الحاجة.
- فرض HTTPS: يُمنع استخدام HTTP العادي. فعّل SSL Pinning لمنع هجمات MITM (رجل المنتصف).
- فحص كسر الحماية: فعّل Root/Jailbreak Detection لمنع استخراج التوكنز من ذاكرة الجهاز المخترق.
- انتهاء الجلسة: نفّذ منطق تسجيل الخروج التلقائي عند عدم النشاط وامسح التوكن المحلي عند الخروج.
- التحقق من المدخلات: تحقق من جميع المدخلات على جانب العميل قبل إرسالها وعلى جانب الخادم (الخادم يتحقق دائماً بالفعل).
📊 رموز حالة الاستجابة
| الكود | المعنى | الحالة الشائعة |
|---|---|---|
| 200 | نجاح العملية | أي طلب ناجح |
| 400 | بيانات خاطئة أو رصيد غير كافٍ | subscribe, renew, recharge |
| 401 | التوكن منتهي أو غير صالح | أي endpoint محمي |
| 403 | الميزة غير مفعّلة في الترخيص | login, deposit |
| 404 | العنصر غير موجود | plans, invoices/{id} |
| 422 | بيانات التحقق فاشلة (Validation) | كل طلبات POST |
| 500 | خطأ داخلي في الخادم | نادر جداً |
🌐 المسارات العامة (بدون مصادقة)
يُستدعى عند تشغيل التطبيق لأول مرة لجلب اسم الشبكة، الشعار، معلومات التواصل، وآخر إصدار للتطبيق.
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| username | string | اسم المستخدم أو رقم الهاتف | مطلوب |
| password | string | كلمة المرور | مطلوب |
| device_name | string | اسم أو معرّف الجهاز لفصل جلسات متعددة | اختياري |
token في كل الطلبات التالية عبر ترويسة: Authorization: Bearer {token}| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| device_name | string | اسم الجهاز للتمييز | اختياري |
🔑 المصادقة (Auth)
يُرجع كائن JSON بجميع بيانات المشترك الحالي بما في ذلك الحقول المخصصة.
يحذف التوكن من قاعدة البيانات ويُبطل أي طلبات مستقبلية باستخدامه. لا يتطلب Body.
🏠 لوحة التحكم والتحكم السريع
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| cycles | integer | عدد دورات التجديد (افتراضي: 1) | اختياري |
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| voucher_code | string | رمز الكارت / الكوبون (6 أرقام على الأقل) | مطلوب |
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| speed_percentage | integer | نسبة تعديل السرعة (مثال: 50 لرفع السرعة بمقدار 50%، أو -25 لخفض السرعة بمقدار 25%) | مطلوب |
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| action | string | نوع الإجراء: pause لفصل الخدمة، أو resume لإعادة تشغيلها | مطلوب |
| password | string | رمز PIN لحماية الفصل والوصل (إلزامي إذا تم تعيين رمز سابق، وإذا كانت هذه أول مرة تقوم بالفصل فسيتم حفظ هذا الرمز كرمز PIN جديد للحساب) | اختياري / إلزامي |
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| password | string | رمز PIN المراد التحقق منه | مطلوب |
قم بإرسال طلب GET لمعرفة حالة الجدول والرقابة الأبوية الحالية، أو طلب POST لتحديث إعدادات الجدولة والتحكم بالإنترنت.
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| type | string | نوع الجدولة: none (إلغاء)، instant (تحكم فوري)، routine (روتيني يومي/أسبوعي)، once (لمرة واحدة فقط)، vacation (فترة إجازة) | مطلوب |
| password | string | الرمز السري PIN لحماية الإعدادات (إذا تم تعيينه مسبقاً) | اختياري |
| start_time | string | وقت بدء القطع بصيغة 24 ساعة (مثال: 22:00) | مطلوب للـ routine/once |
| end_time | string | وقت انتهاء القطع بصيغة 24 ساعة (مثال: 07:00) | مطلوب للـ routine/once |
| date | string | تاريخ القطع بصيغة YYYY-MM-DD | مطلوب للـ once |
| routine_days | array | مصفوفة بالأيام المطبق عليها القطع الروتيني (مثال: ["friday", "saturday"]) | مطلوب للـ routine |
| vacation_start | string | تاريخ ووقت بدء إجازة قطع الاتصال (مثال: 2026-07-01 12:00:00) | مطلوب للـ vacation |
| vacation_end | string | تاريخ ووقت انتهاء إجازة قطع الاتصال (مثال: 2026-07-15 12:00:00) | مطلوب للـ vacation |
📦 الباقات والاشتراكات
يُرجع مصفوفة بجميع الباقات المتاحة للمشترك (المرئية، المناسبة لإدارته) مع السعر المحسوب والمدة بالأيام.
يُستخدم لعرض التكلفة المتوقعة للمشترك إذا انتقل لباقة معينة (مع الأخذ بعين الاعتبار الرصيد الحالي والخصومات).
| Query Param | النوع | الوصف | الحالة |
|---|---|---|---|
| plan_id | integer | رقم الباقة المراد المحاكاة | مطلوب |
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| plan_id | integer | رقم الباقة من كتالوج الباقات | مطلوب |
💰 المحفظة والفواتير
يُرجع قائمة بطرق الإيداع المفعّلة (فودافون كاش، بنوك، إلخ) مع أرقام التواصل والحد الأدنى/الأقصى لكل طريقة.
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| code | string | كود الكارت (أرقام فقط، موجود في جدول vouchers) | مطلوب |
electronic_payment_services في ترخيص النظام.| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| phone | string | رقم المحفظة المحوَّل منها (صيغة مصرية: 01XXXXXXXXX) | مطلوب |
| amount | numeric | المبلغ المراد إيداعه (الحد الأدنى 1) | مطلوب |
يُرجع جميع فواتير المشترك مرتبة من الأحدث للأقدم.
استبدل {invoice_id} برقم الفاتورة. يُرجع الفاتورة مع بنودها (items) إذا كانت تتبع للمشترك الحالي.
📊 إحصائيات الاستهلاك (Usage)
| Query Param | النوع | الوصف | الحالة |
|---|---|---|---|
| start_date | date | بداية الفترة (YYYY-MM-DD)، الافتراضي: بداية الشهر الحالي | اختياري |
| end_date | date | نهاية الفترة (YYYY-MM-DD)، الافتراضي: نهاية الشهر الحالي | اختياري |
| Query Param | النوع | الوصف |
|---|---|---|
| start_date | date | اختياري، YYYY-MM-DD |
| end_date | date | اختياري، YYYY-MM-DD |
يُرجع مصفوفة بآخر 50 سجل RADIUS تشمل وقت الاتصال، الانقطاع، البايتات المستهلكة، والـ IP المُعيَّن.
🔌 الخدمات الإضافية (Addons & Loans)
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| package_id | integer | معرّف الإضافة/القرض من قائمة الخدمات | مطلوب |
👤 الملف الشخصي والإعدادات
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| name | string | الاسم الكامل (max: 255) | اختياري |
| phone | string | رقم الهاتف (يجب أن يكون فريداً) | اختياري |
| password | string | كلمة المرور الجديدة (min: 6 أحرف) | اختياري |
يُرجع سجل الرسائل والإشعارات المرسلة للمشترك (SMS، WhatsApp) مرتبة من الأحدث.
يُرجع معلومات خيارات الدعم الفني المتاحة للمشترك (WhatsApp، هاتف، تذاكر إلكترونية).
🎫 الدعم الفني (Support Tickets)
| Query Param | النوع | الوصف | الحالة |
|---|---|---|---|
| status | string | open / closed / أي حالة محددة | اختياري |
| search | string | بحث في العنوان أو رقم التذكرة | اختياري |
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| title | string | عنوان المشكلة (5–200 حرف) | مطلوب |
| description | string | تفاصيل المشكلة (10 أحرف على الأقل) | مطلوب |
| department_id | integer | رقم القسم من قائمة الأقسام | مطلوب |
| priority | string | low / medium / high / critical | اختياري |
يُرجع بيانات التذكرة كاملةً مع مصفوفة الرسائل والردود والأنشطة مرتبة زمنياً.
| الحقل | النوع | الوصف | الحالة |
|---|---|---|---|
| message | string | نص الرد (10 أحرف على الأقل) | مطلوب |
لا يتطلب Body. يُغيّر حالة التذكرة إلى closed ولا يمكن إعادة فتحها.
📰 المجلة الرقمية (Magazine)
/api/subscriber/magazine/ وتتطلب مصادقة وتفعيل ميزة المجلة في الترخيص.يُرجع ما إذا كانت المجلة مفعّلة لهذا المشترك وإحصائيات عامة.
أفلام، مسلسلات، برامج، أطفال... إلخ.
| Query Param | النوع | الوصف |
|---|---|---|
| category_id | integer | فلترة حسب الفئة (اختياري) |
| search | string | بحث في عنوان المحتوى (اختياري) |
| Query Param | النوع | الوصف |
|---|---|---|
| item_id | integer | معرّف العنصر المراد تشغيله |
POST /api/subscriber/magazine/heartbeat لتسجيل وقت المشاهدة.🛠️ دليل دمج تطبيقات الهواتف والأنظمة (Integration Guide)
يوفر هذا القسم أمثلة عملية جاهزة للاستخدام في تطبيقات الهواتف الذكية (Android Kotlin) والإطارات الهجينة (Flutter) والأنظمة البرمجية الأخرى لتسهيل عملية الربط بأفضل الممارسات البرمجية والأمنية.
1. إعداد الـ Service Interface (Retrofit)
يتطابق هذا مع الملف ApiService.kt الموجود في تطبيق المشتركين الفعلي:
2. إعداد الـ Interceptor لإضافة التوكن تلقائياً
يستخدم لإرفاق ترويسة المصادقة بجميع الطلبات الصادرة تلقائياً:
1. إعداد Dio Client مع Interceptor
طريقة احترافية لتهيئة مكتبة Dio وتمرير التوكن في Flutter:
1. هيكلية كلاس الـ PHP SDK (جاهز للنسخ والتشغيل)
يوفر هذا الكلاس تغليفاً (Wrapper) كاملاً للربط الآمن وسهل التنفيذ مع خادم FreeNet:
2. مثال التشغيل الفعلي (تسجيل، رصيد، شحن كرت، استهلاك)
مثال توضيحي للربط المتكامل مع الأنظمة الأخرى في بضع أسطر: