مسار التوصيل للمندوب عبر واجهة الجوال

الغرض#

يتتبّع هذا الدليل طرداً واحداً من لحظة إسناد الشركة له إلى مندوب حتى يسجّل المندوب النتيجة: فتح القائمة وقراءة التفاصيل والتسليم الكامل أو الجزئي أو الإبلاغ عن رفض أو فشل. لا توجد لوحة ويب للمندوب. كل ما ورد هنا يتم عبر واجهة الجوال /api/v10/deliveryman/*، ويستدعيها أي تطبيق جوال يوفّره مشغّل المنصة للمناديب؛ ولا يغطي هذا الدليل تطبيقاً بعينه ولا روابط تحميله (اسأل مشغّل المنصة عن التطبيق الذي يستعمله مناديبك). وتصف هذه الصفحة ما تتيحه الواجهة.

من يستطيع استخدامها#

حسابات المناديب لدى شركة توصيل، ومنهم مناديب شركة التوصيل الخاصة بالتاجر. المندوب الموقوف لا يستطيع الدخول (HTTP 403). وموظفو الشركة يتولّون ما لا يستطيعه المندوب: إسناد الطرود وإعادة الجدولة والتراجع عن النتيجة المسجَّلة.

ما الذي تحتاجه#

• ترويسة apiKey (مفتاح واحد على مستوى المنصة مضبوط على الخادم، وهو نفسه لجميع الحسابات)، وترويسة Accept: application/json، ورمز Bearer من POST /api/v10/deliveryman/login، ويطلب هذا الطلب driver_id (رقم المندوب أو رقم الموبايل أو البريد الإلكتروني) وpassword (6 أحرف على الأقل)، والحد الأقصى لطلبات الدخول 10 طلبات في الدقيقة.
• طرد أسندته إليك الشركة.
• إذا كانت شركتك تشترط أن يكون المندوب متصلاً، أرسل أولاً POST /api/v10/deliveryman/duty مع {"on_duty": true}؛ وإلا فلن يتمكّن موظفو التوزيع في الشركة من إسناد طرود إليك.

الخطوات#

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

   أرسل طلب الدخول مع ترويسة apiKey. يحمل الرد data.token؛ أرسله بصيغة Authorization: Bearer ... في كل طلب لاحق. إذا كان معرّف الدخول أو كلمة السر خاطئاً يعيد الطلب HTTP 401، وغياب apiKey يعيد HTTP 400 مع Invalid Api Key.

2. افتح طرودك

   يجمع GET /api/v10/deliveryman/dashboard الطرود حسب الحالة: المسندة والمعاد جدولتها والراجعة للشركة والمسلَّمة (كاملة وجزئية). ويعرض GET .../parcel/index كل طرد ارتبط بك يوماً كمندوب توصيل أو استلام، لا الطرود النشطة فقط. ويعيد GET .../parcel/details/{id} الطرد وأحداثه، أو HTTP 404 إن لم يكن مرتبطاً بك. وتُظهر قوائم نقطة dashboard لكل طرد المبلغ المطلوب تحصيله (cod_display وcod_original وcod_currency) وis_amount_collected.

3. سلّم بالكامل

   POST /api/v10/deliveryman/parcel/delivered/{id} مع note وimage وsignatureImage اختيارياً. يُسجَّل كامل المبلغ المطلوب كمحصَّل. يجب أن تكون الصور JPEG أو PNG أو WebP أو GIF بحجم حتى 5 ميغابايت؛ والصورة غير الصالحة تُتجاهل دون خطأ.

4. سلّم جزئياً

   POST /api/v10/deliveryman/parcel/partial-delivered/{id} مع cash_collection (مطلوب) والحقول الاختيارية نفسها. يجب أن يكون المبلغ بين 0 والمبلغ المطلوب تحصيله للطرد.

5. أبلغ عن رفض أو فشل

   POST /api/v10/deliveryman/parcel-status-update مع parcel_id وstatus_action، ويمكنك إضافة reason (أو note) بنص التوضيح. استخدم 5 عندما يرفض المستلم أو تفشل هذه المحاولة: يعود الطرد إلى المستودع لمحاولة أخرى، ويُحفظ السبب الذي أرسلته (ويُسجَّل سبب افتراضي بمعنى «تعذّر التسليم» إن لم ترسل شيئاً)، ويُلغى إسناده إليك. واستخدم 24 للفشل النهائي: يرجع الطرد إلى الشركة ويبدأ مسار إرجاعه إلى التاجر.

النتيجة المتوقعة#

تأتي الردود بصيغة {success, message, data}؛ أما غياب parcel_id أو status_action فيعيد HTTP 422 مع message وerrors القياسيين في Laravel لطلبات JSON، وبدون ترويسة Accept يرد Laravel بإعادة توجيه (redirect) إلى صفحة أخرى بدلاً من ذلك. وفي delivered/{id} وpartial-delivered/{id} تتكرر رسائل القواعد المقتبسة أدناه بعد شرطة وتنتهي بمرجع مثل (ref: E1A2B3) (لا في parcel-status-update)؛ لذا فالنصوص المقتبسة أدناه هي بداية الرسالة فقط، فاعتمد على رمز HTTP وجزء من النص. وتأتي The fields is required! كما هي. ويُسجَّل كل تغيير كحدث على الطرد ويُطلق الإشعارات المضبوطة له.

القواعد التي يفرضها النظام#

• لا تستطيع التصرف إلا بطرد مسند إليك وحالته «مع مندوب التوصيل» أو «إعادة جدولة التوصيل». وإلا فالرد HTTP 422 برسالة تبدأ بـ This parcel is not assigned to you. وتكرار التسليم على طرد سُلّم فعلاً يعطي الرد نفسه. والطرد المسند إليك لإرجاعه إلى التاجر يجتاز هذا الفحص؛ ثم يرفض الفحص التالي عليه التسليم الكامل والجزئي والرفض (status_action = 9 و32 و5)، ويقبل 24 من حالة «راجع للتاجر» فينقله إلى «فشل التوصيل — راجع للشركة».
• تُقبل فقط الانتقالات الواردة في القائمة المسموحة؛ والانتقال المرفوض يعيد HTTP 422 مع رسالة تذكر الحالتين.
• إعادة الجدولة وخطوات الاستلام والإرجاع النهائي إلى التاجر يقوم بها موظفو الشركة، ولا نقطة نهاية لها في واجهة المندوب. والطرد المعاد جدولته يبقى في قائمتك بالتاريخ الجديد وتُنهيه بالطريقة نفسها.
• تُبنى القوائم من الأحداث التي تذكرك، فقد يبقى طرد رفضتَه أو أُعيد إسناده ظاهراً فيها.

أخطاء شائعة#

• status_action غير 5 و9 و24 و32. يعيد HTTP 400، ونص الرسالة هو المفتاح غير المترجم parcel.invalid_status_action. ويعرض GET .../parcel-status الإجراءات 9 و24 و32 فقط مع أن 5 مقبول أيضاً.
• غياب cash_collection في التسليم الجزئي. نقطة partial-delivered/{id} وحدها ترفضه (HTTP 422 والرسالة The fields is required!)؛ أما parcel-status-update مع status_action = 32 فتقرأ غيابه صفراً وتسجّل الطرد «تسليم جزئي» بلا مبلغ محصَّل. فأرسله دائماً.
• مبلغ محصَّل أكبر من مبلغ الطرد أو سالب. HTTP 422 برسالة تبدأ بـ The collected amount exceeds the parcel COD amount أو The collected amount cannot be negative.

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

• يحتاج الدخول وطلبات الطرود إلى ترويسة apiKey. أما نقاط الموقع والدوام وإعدادات التتبّع فمسجّلة خارج هذا الفحص وتحتاج رمز Bearer فقط.
• الحد الافتراضي للواجهة 60 طلباً في الدقيقة لكل حساب؛ ويُحدّ POST /api/v10/deliveryman/location بـ 30 طلباً في الدقيقة وPOST /api/v10/deliveryman/duty بـ 20 طلباً في الدقيقة.
• يعمل المندوب على طرود شركته فقط.
• يُفحص المبلغ الجزئي مقابل مبلغ الطرد بالدولار الأمريكي؛ راجع دليل تسجيل المندوب للتحصيل عند الاستلام.