مرجع APIs - نظام البياع

دليل شامل لجميع واجهات برمجة التطبيقات المتاحة في النظام

الرابط الأساسي للـ API

http://localhost:1234/api/v1

ملاحظة: جميع الـ APIs تتطلب المصادقة باستثناء APIs المصادقة نفسها

فهرس الـ APIs

المصادقة والمستخدمين البنوك وفروعها الموردين العملاء الأصناف الوحدات المشتريات المبيعات العمليات الموظفين المصروفات الإعدادات النسب المئوية

المصادقة والمستخدمين

APIs الخاصة بالمصادقة وإدارة المستخدمين

POST /api/v1/users/signup
تسجيل مستخدم جديد
POST /api/v1/users/login
تسجيل الدخول
POST /api/v1/users/logout
تسجيل الخروج
POST /api/v1/users/forgotPassword
نسيان كلمة المرور
PATCH /api/v1/users/resetPassword/:token
إعادة تعيين كلمة المرور
PATCH /api/v1/users/updateMyPassword
تحديث كلمة المرور
🔒 يتطلب مصادقة
GET /api/v1/users/me
الحصول على بيانات المستخدم الحالي
🔒 يتطلب مصادقة
PATCH /api/v1/users/updateMe
تحديث بيانات المستخدم
🔒 يتطلب مصادقة
DELETE /api/v1/users/deleteMe
حذف حساب المستخدم
🔒 يتطلب مصادقة
GET /api/v1/users
الحصول على جميع المستخدمين
🔒 يتطلب صلاحيات إدارية
POST /api/v1/users
إنشاء مستخدم جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/users/:id
الحصول على مستخدم محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/users/:id
تحديث مستخدم محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/users/:id
حذف مستخدم محدد
🔒 يتطلب صلاحيات إدارية

ملاحظات عامة

معلومات مهمة حول استخدام APIs

🔐 المصادقة والتفويض

  • جميع APIs تتطلب JWT token في header: Authorization: Bearer <token>
  • يتم الحصول على Token من خلال تسجيل الدخول: POST /api/v1/users/login
  • APIs الإدارية تتطلب دور "admin" أو "manager"
  • APIs العامة متاحة لجميع المستخدمين المسجلين

📄 الترقيم والبحث

  • معظم APIs تدعم الترقيم باستخدام query parameters: ?page=1&limit=10
  • البحث متاح باستخدام: ?search=keyword
  • الفلترة متاحة باستخدام: ?filter[field]=value
  • الترتيب متاح باستخدام: ?sort=field أو ?sort=-field للترتيب العكسي

📊 تصدير PDF

  • معظم التقارير تدعم تصدير PDF بإضافة /pdf لنهاية URL
  • مثال: GET /api/v1/sales/pdf لتصدير تقرير المبيعات
  • يمكن تطبيق نفس الفلاتر المستخدمة في APIs العادية

📱 رموز الاستجابة

  • 200 - نجح الطلب
  • 201 - تم إنشاء المورد بنجاح
  • 400 - خطأ في البيانات المرسلة
  • 401 - غير مصرح بالوصول
  • 403 - ممنوع الوصول
  • 404 - المورد غير موجود
  • 500 - خطأ في الخادم

🔄 معدل الطلبات

  • الحد الأقصى: 100 طلب لكل 15 دقيقة لكل IP
  • في حالة تجاوز الحد، ستحصل على رمز الخطأ 429
  • يتم إعادة تعيين العداد كل 15 دقيقة

🛡️ الأمان

  • جميع الطلبات يجب أن تكون عبر HTTPS في الإنتاج
  • يتم تطهير جميع المدخلات من XSS و NoSQL injection
  • يتم ضغط الاستجابات تلقائياً
  • Headers الأمان مفعلة (Helmet.js)

البنوك وفروعها

APIs الخاصة بإدارة البنوك وفروعها

البنوك

GET /api/v1/banks
الحصول على جميع البنوك مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/banks/all
الحصول على جميع البنوك بدون ترقيم مع فروعها
🔒 يتطلب صلاحيات إدارية
GET /api/v1/banks/pdf
إنشاء ملف PDF للبنوك
🔒 يتطلب صلاحيات إدارية
POST /api/v1/banks
إنشاء بنك جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/banks/:id
الحصول على بنك محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/banks/:id
تحديث بنك محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/banks/:id
حذف بنك محدد
🔒 يتطلب صلاحيات إدارية
⚠️ يتم التحقق من عدم وجود فروع أو موردين مرتبطين

فروع البنوك

GET /api/v1/bankBranches
الحصول على جميع فروع البنوك مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/bankBranches/all
الحصول على جميع فروع البنوك بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/bankBranches
إنشاء فرع بنك جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/bankBranches/:id
الحصول على فرع بنك محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/bankBranches/:id
تحديث فرع بنك محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/bankBranches/:id
حذف فرع بنك محدد
🔒 يتطلب صلاحيات إدارية
⚠️ يتم التحقق من عدم وجود موردين مرتبطين

الموردين

APIs الخاصة بإدارة الموردين ومدفوعاتهم

GET /api/v1/suppliers
الحصول على جميع الموردين مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/suppliers/all
الحصول على جميع الموردين بدون ترقيم مع الأصناف والوحدات
🔒 يتطلب صلاحيات إدارية
POST /api/v1/suppliers
إنشاء مورد جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/suppliers/:id
الحصول على مورد محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/suppliers/:id
تحديث مورد محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/suppliers/:id
حذف مورد محدد
🔒 يتطلب صلاحيات إدارية
⚠️ يتم التحقق من عدم وجود مشتريات مرتبطة أو رصيد مستحق

مدفوعات الموردين

GET /api/v1/suppliers/:supplierId/payment
الحصول على مدفوعات مورد محدد
🔒 يتطلب صلاحيات إدارية
POST /api/v1/suppliers/:supplierId/payment
إضافة دفعة جديدة لمورد
🔒 يتطلب صلاحيات إدارية
📝 يتم تحديث رصيد المورد وإنشاء سجل في التاريخ
DELETE /api/v1/suppliers/:supplierId/payment/:id
حذف دفعة مورد
🔒 يتطلب صلاحيات إدارية
📝 يتم تحديث رصيد المورد وحذف السجل من التاريخ

مشتريات الموردين

GET /api/v1/suppliers/:supplierId/purchases
الحصول على مشتريات مورد محدد
🔒 يتطلب صلاحيات إدارية

كشف حساب الموردين

GET /api/v1/suppliers/:supplierId/statementPdf
إنشاء كشف حساب PDF لمورد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/suppliers/:supplierId/showStatement
عرض كشف حساب مورد
🔒 يتطلب صلاحيات إدارية

العملاء

APIs الخاصة بإدارة العملاء ومبيعاتهم

GET /api/v1/customers
الحصول على جميع العملاء مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/customers/all
الحصول على جميع العملاء بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/customers
إنشاء عميل جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/customers/:id
الحصول على عميل محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/customers/:id
تحديث عميل محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/customers/:id
حذف عميل محدد
🔒 يتطلب صلاحيات إدارية

مدفوعات العملاء

GET /api/v1/customers/:customerId/payment
الحصول على مدفوعات عميل محدد
🔒 يتطلب صلاحيات إدارية
POST /api/v1/customers/:customerId/payment
إضافة دفعة جديدة لعميل
🔒 يتطلب صلاحيات إدارية
📝 يتم تحديث رصيد العميل وإنشاء سجل في التاريخ
DELETE /api/v1/customers/:customerId/payment/:id
حذف دفعة عميل
🔒 يتطلب صلاحيات إدارية
📝 يتم تحديث رصيد العميل وحذف السجل من التاريخ

مبيعات العملاء

GET /api/v1/customers/:customerId/sales
الحصول على مبيعات عميل محدد
🔒 يتطلب صلاحيات إدارية

كشف حساب العملاء

GET /api/v1/customers/:customerId/statementPdf
إنشاء كشف حساب PDF لعميل
🔒 يتطلب صلاحيات إدارية
GET /api/v1/customers/:customerId/showStatement
عرض كشف حساب عميل
🔒 يتطلب صلاحيات إدارية

الأصناف

APIs الخاصة بإدارة أصناف المنتجات

GET /api/v1/kinds
الحصول على جميع الأصناف مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/kinds/all
الحصول على جميع الأصناف بدون ترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/kinds/getAverageByArdab
الحصول على متوسط السعر بالأردب
🔒 يتطلب صلاحيات إدارية
GET /api/v1/kinds/stock
الحصول على تقرير المخزون
🔒 يتطلب صلاحيات إدارية
POST /api/v1/kinds
إنشاء صنف جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/kinds/:id
الحصول على صنف محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/kinds/:id
تحديث صنف محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/kinds/:id
حذف صنف محدد
🔒 يتطلب صلاحيات إدارية
⚠️ يتم التحقق من عدم وجود عمليات مرتبطة

الوحدات

APIs الخاصة بإدارة وحدات القياس

GET /api/v1/units
الحصول على جميع الوحدات مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/units/all
الحصول على جميع الوحدات بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/units
إنشاء وحدة جديدة
🔒 يتطلب صلاحيات إدارية
📝 يتم التحقق من نوع الوحدة إذا كانت بالكيلوجرام
GET /api/v1/units/:id
الحصول على وحدة محددة
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/units/:id
تحديث وحدة محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم التحقق من نوع الوحدة إذا كانت بالكيلوجرام
DELETE /api/v1/units/:id
حذف وحدة محددة
🔒 يتطلب صلاحيات إدارية
⚠️ يتم التحقق من عدم وجود عمليات مرتبطة

المشتريات

APIs الخاصة بإدارة عمليات الشراء

GET /api/v1/purchases
الحصول على جميع المشتريات مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/purchases/all
الحصول على جميع المشتريات بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/purchases
إنشاء عملية شراء جديدة
🔒 يتطلب صلاحيات إدارية
📝 يتم التحقق من البيانات، حساب السعر، تحديث المخزون، رصيد المورد، وإنشاء المصروفات
GET /api/v1/purchases/:id
الحصول على عملية شراء محددة
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/purchases/:id
تحديث عملية شراء محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم إعادة حساب جميع القيم وتحديث المخزون ورصيد المورد
DELETE /api/v1/purchases/:id
حذف عملية شراء محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم عكس جميع التأثيرات على المخزون ورصيد المورد

المبيعات

APIs الخاصة بإدارة عمليات البيع

GET /api/v1/sales
الحصول على جميع المبيعات مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/sales/all
الحصول على جميع المبيعات بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/sales
إنشاء عملية بيع جديدة
🔒 يتطلب صلاحيات إدارية
📝 يتم التحقق من البيانات، تحديث المخزون، رصيد العميل، وإنشاء السجلات
GET /api/v1/sales/:id
الحصول على عملية بيع محددة
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/sales/:id
تحديث عملية بيع محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم إعادة حساب جميع القيم وتحديث المخزون ورصيد العميل
DELETE /api/v1/sales/:id
حذف عملية بيع محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم عكس جميع التأثيرات على المخزون ورصيد العميل

العمليات

APIs الخاصة بإدارة عمليات التصنيع والمعالجة

GET /api/v1/process
الحصول على جميع العمليات مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/process/all
الحصول على جميع العمليات بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/process
إنشاء عملية تصنيع جديدة
🔒 يتطلب صلاحيات إدارية
📝 يتم حساب كمية الزيت، تحديث العمليات، وتحديث مراجع الأصناف
POST /api/v1/process/kingPrice
إنشاء عملية تسعير الملك
🔒 يتطلب صلاحيات إدارية
📝 يتم حساب كمية الزيت، تحديث أكياس الملك، وتحديث مراجع الأصناف
GET /api/v1/process/:id
الحصول على عملية محددة
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/process/:id
تحديث عملية محددة
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/process/:id
حذف عملية محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم عكس جميع التأثيرات على المخزون والعمليات

الموظفين

APIs الخاصة بإدارة الموظفين ومدفوعاتهم

GET /api/v1/employees
الحصول على جميع الموظفين مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/employees/all
الحصول على جميع الموظفين بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/employees
إنشاء موظف جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/employees/:id
الحصول على موظف محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/employees/:id
تحديث موظف محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/employees/:id
حذف موظف محدد
🔒 يتطلب صلاحيات إدارية

مدفوعات الموظفين

GET /api/v1/employeePayments
الحصول على جميع مدفوعات الموظفين مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/employeePayments/all
الحصول على جميع مدفوعات الموظفين بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/employeePayments
إنشاء دفعة موظف جديدة
🔒 يتطلب صلاحيات إدارية
📝 يتم تحديث رصيد الموظف وإنشاء سجل في التاريخ
GET /api/v1/employeePayments/:id
الحصول على دفعة موظف محددة
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/employeePayments/:id
تحديث دفعة موظف محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم إعادة حساب رصيد الموظف وتحديث السجل
DELETE /api/v1/employeePayments/:id
حذف دفعة موظف محددة
🔒 يتطلب صلاحيات إدارية
📝 يتم تحديث رصيد الموظف وحذف السجل من التاريخ

المصروفات

APIs الخاصة بإدارة المصروفات والنفقات

GET /api/v1/expenses
الحصول على جميع المصروفات مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/expenses/all
الحصول على جميع المصروفات بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/expenses
إنشاء مصروف جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/expenses/:id
الحصول على مصروف محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/expenses/:id
تحديث مصروف محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/expenses/:id
حذف مصروف محدد
🔒 يتطلب صلاحيات إدارية

الإعدادات

APIs الخاصة بإدارة إعدادات النظام

GET /api/v1/settings
الحصول على جميع الإعدادات
🔒 يتطلب صلاحيات إدارية
POST /api/v1/settings
إنشاء إعداد جديد
🔒 يتطلب صلاحيات إدارية
GET /api/v1/settings/:id
الحصول على إعداد محدد
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/settings/:id
تحديث إعداد محدد
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/settings/:id
حذف إعداد محدد
🔒 يتطلب صلاحيات إدارية

نسب المنتجات

APIs الخاصة بإدارة نسب المنتجات والعمولات

GET /api/v1/productPercentage
الحصول على جميع نسب المنتجات مع الترقيم
🔒 يتطلب صلاحيات إدارية
GET /api/v1/productPercentage/all
الحصول على جميع نسب المنتجات بدون ترقيم
🔒 يتطلب صلاحيات إدارية
POST /api/v1/productPercentage
إنشاء نسبة منتج جديدة
🔒 يتطلب صلاحيات إدارية
GET /api/v1/productPercentage/:id
الحصول على نسبة منتج محددة
🔒 يتطلب صلاحيات إدارية
PATCH /api/v1/productPercentage/:id
تحديث نسبة منتج محددة
🔒 يتطلب صلاحيات إدارية
DELETE /api/v1/productPercentage/:id
حذف نسبة منتج محددة
🔒 يتطلب صلاحيات إدارية

ملاحظات عامة

معلومات مهمة حول استخدام APIs

🔐 المصادقة والتفويض

  • جميع APIs تتطلب JWT token في header: Authorization: Bearer <token>
  • يتم الحصول على Token من خلال تسجيل الدخول: POST /api/v1/users/login
  • APIs الإدارية تتطلب دور "admin" أو "manager"
  • APIs العامة متاحة لجميع المستخدمين المسجلين

📄 الترقيم والبحث

  • معظم APIs تدعم الترقيم باستخدام query parameters: ?page=1&limit=10
  • البحث متاح باستخدام: ?search=keyword
  • الفلترة متاحة باستخدام: ?filter[field]=value
  • الترتيب متاح باستخدام: ?sort=field أو ?sort=-field للترتيب العكسي

📊 تصدير PDF

  • معظم التقارير تدعم تصدير PDF بإضافة /pdf لنهاية URL
  • مثال: GET /api/v1/sales/pdf لتصدير تقرير المبيعات
  • يمكن تطبيق نفس الفلاتر المستخدمة في APIs العادية

📱 رموز الاستجابة

  • 200 - نجح الطلب
  • 201 - تم إنشاء المورد بنجاح
  • 400 - خطأ في البيانات المرسلة
  • 401 - غير مصرح بالوصول
  • 403 - ممنوع الوصول
  • 404 - المورد غير موجود
  • 500 - خطأ في الخادم

🔄 معدل الطلبات

  • الحد الأقصى: 100 طلب لكل 15 دقيقة لكل IP
  • في حالة تجاوز الحد، ستحصل على رمز الخطأ 429
  • يتم إعادة تعيين العداد كل 15 دقيقة

🛡️ الأمان

  • جميع الطلبات يجب أن تكون عبر HTTPS في الإنتاج
  • يتم تطهير جميع المدخلات من XSS و NoSQL injection
  • يتم ضغط الاستجابات تلقائياً
  • Headers الأمان مفعلة (Helmet.js)