⚿ توثيق APIs بوابة الزبون والاشتراكات

كود واحد يُعطى لجهاز الزبون فيسحب به كل أكواد تفعيلاته (بكب/تطبيق هاتف/دنكل/منيو…). هنا كل نقاط اتصال جهاز الزبون + إدارة البوابات والاشتراكات.

جهاز الزبون: /api/gw الإدارة: /api/alraed/gateways البكب: /api/alraed/backup كود البوابة: ALR-XXXX-XXXX

i الفكرة والغلاف

بدل كود لكل خدمة، الزبون يأخذ كوداً واحداً ALR-XXXX-XXXX لجهازه، والجهاز يسحب به كل خدماته وأكوادها. للزبون أكثر من بوابة (واحدة لكل جهاز/فرع)، ولكل بوابة اشتراك بكب مستقل بحصّته وملفاته.

يوجد جمهوران لهذه الـAPIs:

الجمهورالأساسالمصادقة
جهاز الزبون (العقد الجديد)/api/gwترويسة X-Gateway-Code
جهاز الزبون (العقد القديم — توافق)/customerحقل Guid_Customer بالجسم
إدارة الويب (بوابات/اشتراكات)/api/alraed/gateways · /api/alraed/backupBearer Token
غلاف الرد لنقاط الإدارة والعقد الجديد موحّد: { success, message, data }. العقد القديم /customer يرجّع صيغة النظام القديم (success:1 + حقول بأسماء legacy) للتوافق مع الأجهزة المنصّبة.

الفهرس

1) جهاز الزبون — العقد الجديد (/api/gw) 2) جهاز الزبون — العقد القديم (/customer) 3) إدارة البوابات 4) إدارة الاشتراكات العامة 5) التجديد والتقارير 6) اشتراكات البكب وملفاته 7) الصلاحيات 8) أمثلة عملية

1 جهاز الزبون — العقد الجديد /api/gw

كل نقطة تتطلّب ترويسة X-Gateway-Code: ALR-XXXX-XXXX (الكود بالترويسة لا بالجسم كي لا يُسجَّل بالروابط). ترويسات اختيارية: X-Machine (بصمة الجهاز — لكشف مشاركة الكود) وX-App-Version. حماية: خانق 20 محاولة فاشلة/10 دقائق لكل IP.

POST /api/gw/resolve
النقطة الأساسية: كود واحد ⇒ كل خدمات الزبون وأكوادها. الجهاز يناديها عند الإقلاع ويوزّع الأكواد على وحداته.
الترويسة
X-Gateway-Code: ALR-7K3M-92QX
X-Machine: DESKTOP-ABC (اختياري)   X-App-Version: 2.1 (اختياري)
الطلب (اختياري)
{ "appVersion": "2.1", "machine": "DESKTOP-ABC" }
الرد (data)
{
  "code": "ALR-7K3M-92QX",
  "customerName": "شركة النور",
  "customerPhone": "07701234567",
  "isActive": true,
  "serverTimeUtc": "2026-07-24T09:00:00Z",
  "services": [
    {
      "key": "backup", "name": "الباك أب أونلاين",
      "isActive": true, "isExpired": false,
      "code": "12", "endDate": "2027-01-01", "daysRemaining": 160,
      "extra": { "quotaMb":"1024", "usedBytes":"...", "remainingBytes":"..." }
    },
    { "key": "phoneapp", "name": "تطبيق الهاتف — ...", "code": "user01", ... }
  ]
}
تظهر فقط الخدمات المفعّلة بالوحدة. أي خدمة تُضاف مستقبلاً تظهر هنا تلقائياً بلا تعديل التطبيق.
GET /api/gw/backup/info
معلومات مساحة البكب لهذه البوابة (الحصّة/المستهلك/المتبقّي/الملفات/آخر رفع/الانتهاء).
الرد (data)
{ "quotaMb":1024, "quotaBytes":1073741824, "usedBytes":52428800,
  "remainingBytes":1021313024, "fileCount":3, "lastUploadAt":"...",
  "isActive":true, "isExpired":false, "endDate":"2027-01-01" }
GET /api/gw/backup/files
سرد نسخ هذه البوابة. الرد: مصفوفة { id, originalName, sizeBytes, contentType, createdAt }.
POST /api/gw/backup/files
رفع نسخة (multipart، الحقل file). يفحص التفعيل والانتهاء والامتداد (bak/zip/sql/gz) والحجم والحصّة.
الرد (data)
{ "id": 45, "originalName": "backup_2026.zip", "sizeBytes": 2195727 }
الملفات تُخزَّن على الخادم بمجلد باسم كود البوابة: uploads/backups/ALR-7K3M-92QX/.
GET /api/gw/backup/files/{id}/download
تنزيل نسخة (تدفّق) — الجهاز يفكّها ويستعيدها محلياً.
DEL /api/gw/backup/files/{id}
حذف نسخة من البوابة.

2 جهاز الزبون — العقد القديم /customer (توافق)

طبقة توافق مع الأجهزة المنصّبة بالنظام القديم — تشتغل بمجرّد تغيير BaseUrl إلى alraed.space بلا تحديث للتطبيق. المصادقة عبر Guid_Customer (معرّف البوابة) في جسم الطلب.

الأسلوبالمسارالوظيفةالطلب
POST/customer/getسرد الملفات (+ رابط تنزيل){ Guid_Customer }
POST/customer/infoمعلومات الزبون والمساحة والانتهاء{ Guid_Customer }
POST/customer/postرفع نسخةmultipart: Guid_Customer + Name_Fileupload
GET/customer/download/{guid}/{fileId}تنزيل مباشر—
POST/customer/deleteحذف ملف{ Guid_Customer, ID_Fileupload }
POST/customer/multideleteحذف عدة ملفات{ Guid_Customer, ids[] }
الرد بصيغة النظام القديم: { success:1, ... } وبحقول legacy (مثل ID_Fileupload / remaining_space / Active_Customer). تشديد أمني: الحذف صار يتطلّب Guid_Customer (كان يحذف بمعرّف الملف وحده — ثغرة أُغلقت).

3 إدارة البوابات /api/alraed/gateways

تحتاج Bearer Token. صلاحيات gateway.view للعرض وgateway.manage للتعديل.

الأسلوبالمسارالوظيفةصلاحية
GET/gatewaysقائمة البوابات (بحث/تصفية)view
GET/gateways/{id}تفاصيل بوابة (+ حواسيبها)view
GET/gateways/by-customer/{customerId}بوابات عميلview
GET/gateways/dongle-options/{customerId}دناكل العميل للربطview
POST/gatewaysإنشاء بوابة (يولّد الكود)manage
PUT/gateways/{id}تعديل (اسم/تفعيل/ربط دنكل)manage
POST/gateways/{id}/regenerateتوليد كود جديد للبوابةmanage
DEL/gateways/{id}حذف بوابةmanage
PUT/gateways/{id}/backupإضافة/تعديل اشتراك بكب للبوابةmanage
DEL/gateways/{id}/backupإزالة اشتراك البكبmanage
PUT/gateways/{id}/services/{key}إضافة/تعديل خدمة عامة للبوابةmanage
DEL/gateways/{id}/services/{key}إزالة خدمةmanage
POST/gateways/cleanup-empty-dongle-gatewaysحذف بوابات الدناكل بلا اشتراكmanage
POST/gateways/backfill-donglesفتح بوابات لدناكل قديمةmanage
POST /gateways
إنشاء بوابة لعميل. الكود يُولَّد تلقائياً. الربط بدنكل اختياري.
الطلب
{ "customerId": 31908, "name": "جهاز المحاسبة", "isActive": true,
  "note": null, "dongleActivationId": null }

4 إدارة الاشتراكات العامة

الاشتراكات العامة (منيو/دومين/أي خدمة تُضاف) — نقطة التوسّع بلا migration.

الأسلوبالمسارالوظيفةصلاحية
GET/gateways/service-keysمفاتيح الخدمات المتاحة وحالتهاview
PUT/gateways/service-keysتفعيل/تعطيل خدمات (المطفأة تختفي)manage
GET/gateways/servicesقائمة الاشتراكات العامةview
POST/gateways/servicesإضافة اشتراك خدمة لعميلmanage
PUT/gateways/services/{id}تعديل اشتراكmanage
DEL/gateways/services/{id}حذف اشتراكmanage

5 التجديد والتقارير

POST /gateways/renew/{serviceKey}/{targetId}
تجديد اشتراك بمدة أشهر. serviceKey = نوع الخدمة (backup/domain/menu…)، targetId = معرّف الاشتراك. التمديد يبدأ من الأبعد بين اليوم والانتهاء الحالي (التجديد المبكر لا يُهدر المتبقّي). يُسجَّل بسجل التجديدات.
الصلاحية: gateway.renew
الطلب
{ "months": 12, "note": "تجديد سنوي" }   // months: 1–120
GET /gateways/renewals?serviceKey=&targetId=
سجل تجديدات اشتراك (منو جدّد ومتى وكم مدة).
الصلاحية: gateway.view
GET /gateways/summary
إحصاء الاشتراكات: كم مشترك وكم لا لكل خدمة + قائمة «تنتهي قريباً».
الصلاحية: gateway.view
GET /gateways/subscriptions-report
تقرير احترافي بكل الاشتراكات (بكب/دومين/تطبيق هاتف): الزبون وهاتفه، الخدمة، الكود، الانتهاء والمتبقّي، والحالة (ساري/ينتهي قريباً/منتهٍ/موقوف).
الصلاحية: gateway.view

6 اشتراكات البكب وملفاته /api/alraed/backup

إدارة اشتراكات البكب من الويب (الموظف). صلاحيات backup.view / backup.manage.

الأسلوبالمسارالوظيفةصلاحية
GET/backup/subscriptions?q=&status=قائمة الاشتراكات + عدّاداتview
GET/backup/subscriptions/{id}تفاصيل اشتراكview
GET/backup/subscriptions/{id}/infoمعلومات المساحةview
POST/backup/subscriptionsإنشاء اشتراكmanage
PUT/backup/subscriptions/{id}تعديل (حصّة/انتهاء/تفعيل)manage
DEL/backup/subscriptions/{id}حذف اشتراك وكل ملفاتهmanage
GET/backup/subscriptions/{id}/filesملفات الاشتراكview
POST/backup/subscriptions/{id}/filesرفع نسخة (multipart file)manage
GET/backup/files/{id}/downloadتنزيل نسخةview
DEL/backup/files/{id}حذف نسخةmanage
POST /backup/subscriptions
الطلب
{ "customerId":31908, "quotaMb":1024, "endDate":"2027-01-01",
  "isActive":true, "note":null, "gatewayId":1 }   // gatewayId فارغ = اشتراك عام على مستوى العميل

7 الصلاحيات

المفتاحيسمح بـ
gateway.viewعرض البوابات والاشتراكات والملخّص والتقرير وسجل التجديد.
gateway.manageإنشاء/تعديل/حذف البوابات والاشتراكات، توليد كود، تفعيل/تعطيل الخدمات.
gateway.renewتجديد الاشتراكات.
backup.view / backup.manageعرض / إدارة اشتراكات البكب وملفاته من الويب.
نقاط جهاز الزبون (/api/gw و/customer) لا تحتاج صلاحيات نظام — تُصادَق بكود البوابة نفسه، لأن جهاز الزبون ليس مستخدماً بالنظام.

8 أمثلة عملية

أ) جهاز الزبون — سحب الخدمات ثم رفع نسخة

# 1) سحب كل خدمات الزبون بكود البوابة
curl -s -X POST https://alraed.space/api/gw/resolve \
  -H "X-Gateway-Code: ALR-7K3M-92QX" \
  -H "Content-Type: application/json" -d '{"machine":"DESKTOP-ABC"}'

# 2) معلومات مساحة البكب
curl -s -H "X-Gateway-Code: ALR-7K3M-92QX" \
  https://alraed.space/api/gw/backup/info

# 3) رفع نسخة (multipart)
curl -s -X POST https://alraed.space/api/gw/backup/files \
  -H "X-Gateway-Code: ALR-7K3M-92QX" \
  -F "file=@backup_2026.zip"

ب) الإدارة — إنشاء بوابة ثم تجديد اشتراك (Bearer)

TOKEN="eyJhbGciOi..."   # من auth/login

# إنشاء بوابة لعميل
curl -s -X POST https://alraed.space/api/alraed/gateways \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"customerId":31908,"name":"جهاز المحاسبة","isActive":true}'

# تجديد اشتراك بكب (id=12) سنة
curl -s -X POST https://alraed.space/api/alraed/gateways/renew/backup/12 \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"months":12,"note":"تجديد سنوي"}'
خلاصة: جهاز الزبون يتكلّم بكود البوابة (X-Gateway-Code أو Guid_Customer القديم) بلا حساب نظام. الموظف يدير البوابات والاشتراكات بالتوكن (Bearer). كود بوابة واحد يجمع كل خدمات الزبون عبر /resolve.
توثيق APIs بوابة الزبون والاشتراكات — نظام الرائد بلس · single-tenant (alraed)