Terminal Delivery

Terminal Delivery شركة توصيل جزائرية تقدّم التوصيل إلى المنزل، ومكاتب استلام خاصة بها، ونقاط استلام شريكة (محلات تحتفظ بالطرد للمشتري). يحتاج الربط إلى قيمة واحدة: رمز الـ API الخاص بمتجرك.

ما تحتاجه

• قيمة واحدة، تظهر باسم API Token في نافذة بيانات الاعتماد، تحصل عليها من حسابك لدى Terminal Delivery. يتحقق Terminal من الهوية عبر Authorization: Token <القيمة>.

إذا لم يكن لحسابك رمز بعد، اطلب من Terminal Delivery تفعيل الوصول عبر API.

ربط Terminal Delivery في DZBuild

1. افتح /dashboard/link-shipping وابحث عن بطاقة Terminal Delivery.
2. اضغط ربط.
3. الصق API Token في حقل الاعتماد الوحيد.
4. اضغط اختبار الاتصال. يتصل DZBuild بـ Terminal مباشرة؛ الرمز الخاطئ يُرفض فوراً.
5. اضغط ربط وحفظ.

تُعدَّل أسعار الولايات من /dashboard/shipping.

ما الذي تتم مزامنته

• الولايات التي يخدمها Terminal.
• البلديات لكل ولاية، بمعرّفات البلديات الخاصة بـ Terminal.
• أسعار المنزل والمكتب لكل ولاية.
• مكاتب الاستلام ونقاط الاستلام الشريكة من أجل قائمة اختيار المكتب.

الأسعار

مزامنة الأسعار من شركة التوصيل تقرأ خيارات التوصيل لدى Terminal لكل ولاية وتملأ سعر المنزل وسعر المكتب معاً. هذه هي الأسعار العادية (غير السريعة).

يحدد Terminal الأسعار لكل بلدية، لذلك يقرأ DZBuild بلدية مركز كل ولاية. الولاية التي لا يملك مركزها سعراً لمتجرك تبقى على 0؛ أدخل السعر يدوياً من /dashboard/shipping.

المكاتب ونقاط الاستلام

يعرض Terminal نوعين من المواقع لكل بلدية: مكاتب الاستلام الخاصة به ونقاط الاستلام الشريكة. يعرض DZBuild النوعين في قائمة اختيار المكتب. يقرأ أولاً بلدية مركز كل ولاية؛ وعندما تملك الولاية سعر مكتب لكن مركزها لا يعرض أي موقع، يفحص DZBuild حتى 15 بلدية أخرى من تلك الولاية.

التوصيل إلى المكتب يُعرض فقط في البلديات التي أدرج فيها Terminal مكتب استلام أو نقطة استلام. الطلب المرسل إلى نقطة استلام شريكة يحمل معرّف النقطة، فيصل الطرد إلى ذلك المحل.

ماذا يحدث عند إرسال الطلب

يرسل DZBuild الطلب مع اسم العميل وهاتفه وعنوانه، والبلدية على شكل معرّف بلدية Terminal (أو اسم البلدية واسم الولاية عندما لا تكون البلدية في القائمة المزامنة؛ يتعرف Terminal عليهما باللاتينية أو بالعربية)، ونوع التوصيل (1 منزل، 2 مكتب استلام، 3 نقطة استلام)، وقائمة المنتجات في سطر واحد، ورقم طلبك في external_id، وtotal_price. طلب المكتب يُرسل ببلدية المكتب المختار.

ثلاث قواعد يجب معرفتها:

• total_price يشمل التوصيل. هو المبلغ الذي يدفعه العميل ويجب ألا يقل عن سعر توصيل Terminal لتلك البلدية، وإلا رُفض الطلب (الرمز 10).
• الطلبات المكررة تُرفض لمدة 24 ساعة. الطلب الذي يحمل نفس اسم العميل ونفس الهاتف لطلب نشط من آخر 24 ساعة يُرفض (الرمز 55). صحّح الهاتف أو انتظر؛ لا تُعِد الإرسال كما هو.
• لا إلغاء عبر API. ألغِ الطرد من حسابك لدى Terminal Delivery.

يرد Terminal بمعرّف الطلب (يُحفظ كرقم تتبع) ورقم تتبع يُطبع على الملصق. يجلب DZBuild الملصق (البوردرو) فوراً؛ زر طباعة الملصق على الطلب يطبعه.

معاني الحالات

حالة Terminal	معناها	حالة DZBuild
4 Created، 5 Pickup requested، 6 In process، 8 Waiting transit، 9 In transit، 11 Pending، 12 Out of stock، 15 Ready to ship، 22 Assigned	الطرد لدى Terminal ولم يخرج للتوصيل بعد	قيد المعالجة
31 Shipped، 32 Alerted، 42 Postponed، 51 Ready to return	خرج للتوصيل، أو محاولة فاشلة	تم الشحن
33 Ready for pickup	بانتظار العميل في المكتب أو نقطة الاستلام	تم الشحن
41 Delivered	تم التوصيل	تم التوصيل
50 Aborted	ألغاه Terminal	ملغى
10 In transit to be returned، 53 Not received	الطرد في طريق العودة	مرتجع (المخزون ينتظر)
52 Taken by store	الطرد عاد إليك	مرتجع (أُعيد المخزون)

المرتجع الذي لا يصل أبداً إلى الحالة 52 يستعيد مخزونه بعد 15 يوماً، أو قبل ذلك عندما تحدده كمستلَم على الطلب.

الأخطاء الشائعة وحلولها

يعرض DZBuild رفض Terminal بالعربية. وعندما يرسل Terminal شرحه الخاص، يظهر بعد الرسالة بين قوسين.

العرض	السبب المحتمل	الحل
« بيانات الاعتماد غير صحيحة لدى Terminal Delivery (HTTP 401) - تأكد من رمز الـ Token »	رمز خاطئ أو منتهٍ	انسخ الرمز مجدداً من حسابك لدى Terminal.
« فشل التحقق: السعر الإجمالي أقل من الحد الأدنى لدى Terminal Delivery، السعر يجب أن يشمل تكلفة التوصيل » (الرمز 10)	إجمالي الطلب أقل من سعر توصيل Terminal لتلك البلدية	تأكد أن الإجمالي يشمل سعر التوصيل، وارفع سعر التوصيل في الطلب إن لم يكن كذلك.
« فشل التحقق: لا يوجد سعر توصيل لهذه البلدية في حساب Terminal Delivery » (الرمز 70)	حسابك لدى Terminal لا يملك سعراً لتلك البلدية	اطلب من Terminal Delivery فتح البلدية، أو أرسل هذا الطلب مع شركة أخرى.
« لم يتم العثور على البلدية لدى Terminal Delivery أو المنطقة غير مغطاة » (الرمز 40)	Terminal لا يعرف البلدية أو لا يخدمها	صحّح البلدية، أو اضغط تحديث البيانات على البطاقة لإعادة مزامنة قائمة البلديات.
« مكتب الاستلام (Stop Desk) أو نقطة الاستلام غير متوفرة في هذه البلدية لدى Terminal Delivery » (الرمز 45)	لا مكتب استلام ولا نقطة استلام في تلك البلدية	حوّل الطلب إلى التوصيل للمنزل أو اختر مكتباً آخر.
« طلب مكرر لدى Terminal Delivery: يوجد طلب نشط بنفس اسم العميل ورقم الهاتف خلال آخر 24 ساعة، لا تُعِد الإرسال » (الرمز 55)	نفس الاسم ونفس الهاتف لطلب نشط من آخر 24 ساعة	انتظر، أو صحّح الهاتف؛ لا تُعِد الإرسال كما هو.
« فشل التحقق: المنتج غير موجود أو غير متطابق في كتالوج Terminal Delivery » (الرمز 50)	تعذر إنشاء سطر المنتج أو مطابقته في كتالوج Terminal	أعد تسمية المنتج في DZBuild، أو أنشئه في Terminal بنفس الاسم.
« فشل التحقق: حساب Terminal Delivery غير مفعّل للإرسال عبر API، تواصل مع Terminal » (الرمز 120)	حسابك لدى Terminal غير مفعّل لطلبات API	اطلب من Terminal Delivery تفعيله.
« ملصق Terminal Delivery غير متوفر لهذا الطلب، اطبعه من لوحة Terminal Delivery »	لم يُرجع Terminal الملصق عند إرسال الطلب	اطبع الملصق من حسابك لدى Terminal Delivery.

نصائح

• اختبار الاتصال يعمل على حساب لم يرسل أي شحنة بعد.
• اسم المنتج الجديد ينشئ منتجاً في كتالوج Terminal الخاص بك؛ حافظ على أسماء ثابتة حتى تبقى شاشة المخزون لدى Terminal مقروءة. وعندما يكون الاسم موجوداً هناك، يعيد DZBuild استخدام ذلك المنتج.
• يسمح Terminal بـ 300 طلب API في الدقيقة لكل حساب؛ ينتظر DZBuild الثواني التي يطلبها Terminal (حتى 10) قبل محاولة واحدة إضافية.