يقدّم هذا الملف توثيقًا يدويًا ومبسّطًا لأهم نقاط التكامل في المنصتين الداخليتين LoginApi و BusinessApi. تم تلخيص طريقة العمل، الحقول المطلوبة، والعلاقات بين الواجهات وفق فهم فريق RoadFN للكود المصدري الحالي لكي يتوافر لديك مرجع سريع حتى في حال تعذر الاطلاع على Swagger.
// أمثلة سريعة
POST /api/Login
{
"userName": "demo",
"password": "demo123",
"deviceToken": "abcdef"
}
GET /api/Business/GenerateShipmentLink
Authorization: Bearer <token>
تعتمد أغلب العمليات على هوية المستخدم التجاري (BusinessUser) التي يتم الحصول عليها بعد تسجيل الدخول، مع استخدام
رمز JWT في ترويسة Authorization: Bearer. تم استخراج الحقول أدناه من نماذج البيانات داخل
المشروع: قد تختلف في حال تغيير قاعدة البيانات، لذا راجع Swagger عند الشك.
معظم الحقول التي تنتهي بـ Id تشير إلى جداول مرجعية مثل المدن، المناطق، حالة الشحنة، أو
أنواع الشحنات. استخدم واجهات مثل GET /api/Areas و
GET /api/Business/ListStatus للحصول على القيم الصحيحة قبل إرسالها.
يتم تحديد صلاحيات الوصول من خلال مطالبات المستخدم في رمز JWT. لا يمكن الوصول إلى BusinessApi إلا من
خلال أدوار business و Marketer.
استخدم عناوين النطاق التالية لتجربة الواجهات برمجيًا. كلا البيئتين متاحتان مع نفس نقاط النهاية الموثقة في هذا الملف.
العنوان الأساسي: https://api.roadfn.com/. تأكد من استخدام مفاتيح الاعتماد الحقيقية واحترام حدود المعدل الخاصة بالحسابات الفعلية.
العنوان الأساسي: https://uat.roadfn.com/. تسمح هذه البيئة بالتحقق من عمليات التكامل دون التأثير على بيانات الإنتاج، ويمكنك إنشاء حسابات تجريبية بحرية.
نقاط النهاية العامة التي تستخدم غالبًا قبل الحصول على رمز المصادقة.
يدقق بيانات الاعتماد ويصدر رمز JWT مع بيانات إضافية عن المستخدم.
اسم المستخدم كما هو مخزن في جدول Users.
كلمة المرور بنفس الترميز الموجود في قاعدة البيانات (Plain Text وفق التطبيق الحالي).
معرف الجهاز المستخدم للإشعارات (FCM Token). يتم حفظه في Users.DeviceToken.
application/json
Role (admin، business، Marketer...).LoginTrimAndConditions.true إذا حان موعد تغيير كلمة المرور.{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"role": "business",
"userName": "demo",
"fullName": "Demo Merchant",
"expires": "2024-03-12T21:36:00Z",
"requiredChangePassword": false,
"loginTrimAndConditions": false,
"loginTrimAndConditionsValue": "...النص...",
"mobileRoles": []
}تتطلب جميع الطلبات ترويسة Authorization مع رمز JWT من /api/Login.
إنشاء رابط خاص يمكن مشاركته مع العميل لإدخال بيانات شحنة جديدة.
لا توجد مدخلات إضافية. يتم الاعتماد على هوية المستخدم من الرمز.
text/plain
القيم المضمنة مشتقة من رقم المستخدم مع تشفير .
https://api.roadfn.com/Client/AddShipment?token=4d9a...&merchant=cf2b...يجلب المحادثة الخاصة بشحنة معينة.
معرف الشحنة في جدول Shipments.
GET /api/Business/ShipmentChat?ShipmentId=1024إضافة تعليق جديد على محادثة شحنة وإرسال إشعار فوري.
معرف الشحنة المطلوب التعليق عليها.
النص الفعلي للتعليق.
يتم تجاهله إذا تم اشتقاقه من الرمز. يُترك 0 عادة.
{
"shipmentId": 1024,
"userCommint": "تم التواصل مع العميل",
"userId": 0
}إنشاء مستخدم تابع (موظف) لنفس التاجر مع صلاحية Business.
يتم تمرير كائن UserViewModel بالحقول التالية:
يتم نسخ معرف الفرع والمدينة من حساب التاجر الحالي، ويُعاد ضبط الدور إلى قيمة "3".
{
"title": "مندوب",
"firstName": "أحمد",
"lastName": "خالد",
"userName": "ahmad.k",
"userPassword": "Pass1234",
"mobileNo1": "0790000000",
"mobileNo2": null,
"tel": null,
"address": "عمّان - الصويفية"
}إضافة مسوّق ميداني مرتبط بالتاجر مع تحديد الحالات التي يمكنه متابعتها.
الكائن UserViewModelM يتضمن حقول الموظف السابقة بالإضافة إلى:
{
"title": "مسوّق",
"firstName": "سارة",
"lastName": "علي",
"userName": "sara.m",
"userPassword": "Sara1234",
"mobileNo1": "0791111111",
"roleIds": [1, 2],
"statuses": [10, 23]
}جلب بيانات مسوّق محدد مع الصلاحيات المرتبطة به.
معرف المسوّق كما أعادته ListMarketer.
users و mobileRoles.
تعيد users قائمة (غالبًا عنصر واحد) من جدول Users، بينما mobileRoles تجمع تفاصيل الأدوار.
{
"users": [
{
"id": 45,
"firstName": "سارة",
"userName": "sara.m",
"allowStatus": "10,23"
}
],
"mobileRoles": [
{ "id": 1, "roleName": "FollowUp", "roleNote": "متابعة العملاء" }
]
}تعديل بيانات موظف تابع.
يتم إرسال UserViewModel مثل AddEmployee مع تمرير معرف المستخدم بالتالي:
تحديث بيانات مسوّق وإعادة تعيين صلاحياته.
نفس حقول UserViewModelM مع تمرير UserId كاستعلام. يتم حذف جميع الأدوار القديمة وإضافة القوائم الجديدة.
عرض جميع صلاحيات المسوّقين المتاحة لاستخدامها مع AddMarketer.
لا توجد معاملات.
جميع حالات الشحنات الممكنة.
لا يوجد.
جلب جميع الموظفين المرتبطين بالتاجر الحالي .
لا توجد معاملات.
استرجاع كل المسوقين التابعين للتاجر.
لا توجد معاملات.
بيانات Profile UserProfile.
لا يوجد.
قائمة الإشعارات الخاصة بالتاجر.
لا توجد معاملات.
تعليم إشعار معين كمقروء وتحديث سجل NotificationLogs.
ملخص شامل للأداء (مدن الوجهة، أهم الموظفين...).
لا توجد معاملات.
تجميع متعدد: يعيد بيانات من CountOfShipmentsPerToCityAndUser ويتم دمج مساهمات الموظفين التابعين.
إنشاء شحنة جديدة بالاعتماد على نموذج BussCreateShipmentViewModel.
أبرز الحقول المطلوبة:
يتم حساب shipmentFees وshipmentPrice داخليًا عبر IShipmentService.
{
"clientName": "محمد",
"clientCityId": "1",
"clientAreaId": "5",
"clientPhone": "0792222222",
"clientAddress": "إربد - الحي الشرقي",
"shipmentTotal": 50.0,
"retPay": false,
"shipmentContains": "ملابس"
}نسخة إضافية من قائمة الحالات مفلترة بحسب صلاحيات المسوّق عند الحاجة.
حفظ شحنة كمسودة قبل التأكيد النهائي.
نفس حقول إنشاء الشحنة مع إمكانية ترك بعض الحقول فارغة، لكن يجب توفير معلومات العميل الأساسية.
تعيد معرف المسودة مع تفاصيلها.
حساب رسوم التوصيل بناءً على المدينة والمنطقة.
تعيد كائنًا يحتوي على deliveryFee وحقول مساعدة أخرى لحساب السعر النهائي.
إرجاع نص التحذير المرتبط بنوع الشحنة.
ملاحظات عامة حول الشحنات للعرض في الواجهة.
إضافة ملاحظة داخلية على شحنة.
يتوقع الحقول shipmentId وnote على الأقل، بالإضافة إلى بيانات الحالة الجديدة إذا تطلب الأمر.
حجز رقم تتبع جديد بناءً على هوية المستخدم.
قائمة المدن المتاحة لعمليات الشحن.
إرجاع المناطق لمدينة محددة (مماثل لواجهة LoginApi لكن ضمن سياق تجاري).
أنواع الشحنات مع رسائل التحذير المرتبطة بها.
ملخص إحصائي لأعداد الشحنات بحسب الحالة.
تفاصيل شحنة فردية بما في ذلك العناوين وتتبع الحالة.
إحصاء الشحنات المسجلة لرقم هاتف معين لضبط محاولات التكرار.
قائمة الشحنات مع إمكانية التصفية حسب الحالة أو التاريخ (يتم تمرير معاملات Query متعددة في التطبيق).
عرض الشحنات بين تاريخين محددين.
إرجاع مجموعة شحنات بناءً على قائمة معرفات يتم تمريرها في الجسم.
تعديل تفاصيل شحنة موجودة (العنوان، القيمة، المحتوى...).
تحديث عنوان العميل في شحنة معينة.
تعديل رقم هاتف المستلم.
جميع رسوم الشحن المرتبطة بالتاجر.
إرجاع الحالات التي يمكن التحويل إليها بناءً على الحالة الحالية للشحنة ودور المستخدم.
تغيير حالة الشحنة مع تسجيل السجل التاريخي.
معلومات العميل التجاري الحالي .
تقرير تاريخ المدفوعات للتاجر.
شحنات الفواتير المفتوحة للتاجر.
تقرير الفواتير الصادرة.
تقرير الفواتير الخاصة بالشحنات المرتجعة.
قائمة الشحنات المرتجعة المرتبطة بالفواتير.
تأكيد استلام دفعة مالية من المكتب.
تأكيد استلام فواتير المرتجعات.
رفع ملف مرتبط بالشحنة (مثل إثبات التسليم).
يتوقع ملفًا مرفوعًا عبر multipart/form-data مع الحقل file، بالإضافة إلى معرف الشحنة.
تحميل ملف تم رفعه مسبقًا لشحنة.
عرض طلبات إصدار الفواتير التي قدمها التاجر.
تقديم طلب جديد لإصدار فاتورة اشتراك أو مستحقات.
شرح الطلب (اختياري لكنه مفيد للتواصل).
يعيد رسالة نصية توضح حالة الطلب (على سبيل المثال "تم استلام طلبك").