كيف يعمل المناديب: واجهة الموبايل بدل لوحة الويب

الجواب المختصر#

لا توجد لوحة ويب للمندوب. يعمل المندوبون عبر واجهة الموبايل البرمجية (API) تحت المسار /api/v10/deliveryman/*: تسجيل الدخول، والطرود المسندة، وتحديث الحالة، والتسليم الجزئي، وإرسال الموقع، وتبديل «متصل»، وتسجيل المبلغ المحصَّل. ولا يغطي هذا الدليل تطبيق موبايل بعينه ولا روابط تحميله (اسأل مشغّل المنصة عن التطبيق الذي يستعمله مناديبك)؛ بل يصف ما تتيحه الواجهة (API) لتعرف كيف يعمل مناديبك مع تطبيقهم.

من ينشئ حساب المندوب؟#

موظفو الشركة، من صفحة «المناديب والعمولات» ثم «مندوب جديد»: الاسم، ورقم الموبايل (من 9 إلى 15 رقماً وغير مكرر)، وبريد اختياري، وكلمة مرور (6 أحرف على الأقل)، و«حد الطرود معه»، والحالة، والعمولة. ينشئ النظام للمندوب رقم دخول من 6 أرقام يظهر في بطاقته («رقم الدخول:»). ويمكن أيضاً إنشاء المناديب من قائمة «رجل التوصيل» القديمة المقيّدة بالصلاحيات. ويقيّد عدد المناديب بباقة الشركة (أو بباقة التاجر في «شركتي للتوصيل»). المندوب «الموقوف» لا يستطيع الدخول ولا يظهر في التوزيع.

ما الذي يتيحه الـ API للمندوب؟#

تشترط مسارات login وdashboard والطرود وparcel-status-update وpayment-logs وجود الترويسة apiKey (قيمة مشتركة واحدة تؤخذ من إعدادات المنصة، وليست خاصة بكل مندوب؛ اطلبها من مشغّل المنصة)، أما location وtracking-config وduty فلا تشترطها. وكل المسارات عدا الدخول تتطلب توكن Authorization: Bearer ولا يقبلها إلا حساب من نوع مندوب. ولا ينطبق عليها فحص اشتراك الباقة الذي يوقف الكتابة في تطبيقات التاجر والشركة.

يوم المندوب#

1. سجّل الدخول

   أرسل driver_id (رقم الدخول أو الموبايل أو البريد) وpassword (6 أحرف على الأقل). بحد 10 طلبات في الدقيقة.

   bashنسخ

   curl -X POST "https://YOUR_PLATFORM_HOST/api/v10/deliveryman/login" \
     -H "apiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"driver_id": "123456", "password": "COURIER_PASSWORD"}'
   

   يعيد الرد data.token وdata.user. الأخطاء: HTTP 422 للحقول الناقصة، و401 مع «رقم الدخول (أو الموبايل) أو كلمة المرور غلط.»، و403 مع «حساب المندوب موقوف — تواصل مع شركتك.»، و400 مع Invalid Api Key إذا غابت الترويسة أو اختلفت.

2. استقبل الطرود وافتحها

   تُسند الشركة الطرود من لوحة التوزيع (انظر دليل التوزيع)، ويضع النظام إشعاراً للمندوب في قائمة الإرسال عند التعيين أو إعادة الجدولة، ووصوله إلى الهاتف يتوقف على قواعد الإشعارات وإعداد Firebase. يعرض dashboard الطرود حسب الحالة، ويعرض parcel/details/{id} الطرد وأحداثه.

3. سجّل نتيجة التوصيل

   parcel-status-update يقبل status_action: 9 تسليم كامل، و32 تسليم جزئي (مع cash_collection)، و24 فشل نهائي (يعود الطرد للشركة)، و5 رفض أو تعذّر التسليم فيعود الطرد إلى المستودع لإعادة المحاولة. وأي قيمة أخرى تُرفض برمز 400. يقبل الإجراءان 9 و32 الحقل note مع image وتوقيع (signatureImage) اختياريين؛ ويقبل 24 الحقل note أو reason؛ ويقبل 5 الحقل reason أو note. ولا تُستعمل الصورة والتوقيع في 24 و5.

4. سجّل المبلغ المحصَّل

   لا يوجد مسار مستقل لتحصيل المال. عند التسليم الكامل يُسجَّل مبلغ التحصيل في الطرد كاملاً، وعند الجزئي يُسجَّل cash_collection، ولا يجوز أن يزيد على مبلغ التحصيل المطلوب في الطرد. ويُضاف المبلغ إلى النقد الذي بعهدة المندوب، وتستلمه الشركة منه في «تسوية المناديب».

5. أرسل الموقع والحالة

   يعيد GET .../tracking-config الحقل tracking_enabled والحقل interval بقيمة 20 ثانية وتيرةً مقترحة لإرسال الموقع، ويبدّل POST .../duty بالحقل on_duty حالة المندوب بين متصل وغير متصل. ولا يصف هذا الدليل سلوك التطبيق نفسه.

أخطاء شائعة#

• توقّع وجود لوحة ويب للمندوب: لا توجد. صفحات الويب للمناديب هي لإدارتهم من موظفي الشركة فقط.
• البحث عن تطبيق جاهز أو رابط تحميله في هذا الدليل: لا يغطيهما.
• رسالة «This parcel is not assigned to you» (HTTP 422): يردّ الـ API بهذا النص بالإنجليزية، ومعناه أن المندوب لا يغيّر إلا طرداً معيّناً له وموجوداً معه حالياً.
• طلب غير مقبول بسبب الحالة: تُرفض الانتقالات غير المسموحة برمز 422 ورسالة توضّح الحالتين.
• ظن أن المندوب يعيد الجدولة أو يسجّل الإرجاع للتاجر: لا يوجد مسار لذلك في واجهته، ويسجّله موظف الشركة.

الحدود والصلاحيات#

• المندوب يتعامل مع طرود شركته المرتبطة به فقط، وتفاصيل أي طرد آخر تُرفض.
• قائمة parcel/index تضم كل طرد مرّ عليه (للتوصيل أو الاستلام) وليس الطرود النشطة فقط.
• مسارات profile وincome-expense وparcel-payment-logs موجودة، لكن هذا الدليل لا يوثّقها وقد تعتمد أرقامها على جداول محاسبية قديمة.
• النقد والعمولات تُسوّى من الشركة، لا من التطبيق.