التكامل والـ API

9.1 نظرة عامة

يضم البرنامج خادم API مدمجاً (Shelf) يعمل افتراضياً على المنفذ 8080، ويفتح REST على /api/* و WebSocket على /ws. يُستخدم لربط تطبيقات الموظفين والهاتف والفروع، ويمكن لأي نظام خارجي التكامل معه.

9.2 المصادقة

الطريقة	الترويسة (Header)	الاستخدام
مفتاح API	X-API-Key: <key> أو Authorization: Bearer <key>	تكاملات الإدارة والأنظمة الخارجية
رمز جلسة الموظف	X-Session-Token: <token>	عملاء الموظفين (ينتهي بعد 8 ساعات)

• مسارات عامة بدون مصادقة: /, /api/status, /api/auth/login, /api/auth/verify, /ws.
• حماية من التخمين: 5 محاولات فاشلة خلال 5 دقائق ← قفل 15 دقيقة.

9.3 أمثلة طلب/رد

مثال 1 — حالة الخادم (بدون مصادقة):

GET http://192.168.1.10:8080/api/status

{
  "status": "online",
  "role": "main",
  "version": "1.0.0",
  "authRequired": true,
  "lanId": "<معرّف الشبكة>",
  "lanName": "<اسم الشبكة>",
  "lanFp": "<بصمة شهادة TLS>"
}

مثال 2 — تسجيل دخول موظف:

POST http://192.168.1.10:8080/api/auth/login
Content-Type: application/json

{
  "username": "cashier1",
  "password": "********"
}

{
  "success": true,
  "token": "<session-token>",
  "user": {
    "id": 3,
    "username": "cashier1",
    "displayName": "كاشير 1",
    "role": "cashier",
    "permissions": ["pos_sell", "invoices_view"]
  }
}

مثال 3 — قراءة الأصناف بمفتاح API:

GET http://192.168.1.10:8080/api/items?limit=20
X-API-Key: <api-key>

مثال 4 — WebSocket:

ws://192.168.1.10:8080/ws?token=<session-token>

أول رسالة يجب أن تكون مصادقة:

{ "action": "auth", "token": "<session-token>" }

من أحداث الخادم: chat_message, chat_typing, webrtc_signal, plugin_state, force_logout, server_shutdown.

9.4 مجموعات نقاط النهاية الرئيسية

المجموعة	المسار الأساسي
الحالة والمعلومات	/api/status, /api/plugins
المصادقة والمستخدمون	/api/auth/*, /api/users/*, /api/roles/*
الفواتير	/api/invoices/* (تأكيد، إلغاء، دفع، مرتجعات، أرقام تالية…)
الأصناف والمخازن	/api/items/*, /api/warehouses/*, /api/bundles/*
العملاء والموردون	/api/customers, /api/suppliers, /api/parties/*
السندات والصناديق	/api/vouchers/*, /api/cash-box/*, /api/cash-registers/*
المحاسبة	/api/accounting/*, /api/expenses/*
التقارير	/api/reports/*
الموظفون	/api/employees/* (بما فيها heartbeat وstats)
المحادثات	/api/chat/*
سير العمل والتصنيع	/api/workflow/*, /api/manufacturing/*
الإضافات	/api/telegram/*, /api/website/*, /api/tasks/*, /api/debt-collector/*, /api/margin-guard/*, /api/sales-copilot/*, /api/dead-stock/*, /api/delegate*/*
سلامة البيانات	/api/integrity/*
العملات	/api/currencies/*, /api/pricelists/*

العدد الكلي للمسارات في الكود يتجاوز 540 مساراً. القائمة أعلاه هي المجموعات الرئيسية.

9.5 حدود الاستخدام

الحد	القيمة
قفل المصادقة	5 محاولات فاشلة / 5 دقائق ← قفل 15 دقيقة
عمر الجلسة	8 ساعات
مهلة WebSocket قبل المصادقة	15 ثانية (يُقطع الاتصال)