# Yalidine

Yalidine من شركات التوصيل الوطنية واسعة الاستعمال في الجزائر، ولها API مستقرّ. أمّا الولايات والبلديات والمكاتب التي تستطيع الشحن إليها فتأتي من API الخاص بـ Yalidine نفسها: تُزامن DZBuild ما تُرجعه Yalidine، ولا تضيف أي تغطية من عندها. ويدعم نفس التكامل في DZBuild أيضاً **Yalitec** و**Guepex** و**Easy & Speed** و**Economiqua** و**We Can Services** التي تشترك مع Yalidine في بنية API لكن لها لوحات تحكم مستقلة.

## ما تحتاجه[​](#ما-تحتاجه "رابط مباشر إلى ما تحتاجه")

تحتاج فقط قيمتين من لوحة تحكم Yalidine:

* **API ID**
* **API Token**

كلاهما يُصدر من حسابك في Yalidine؛ إن لم تجدهما اطلب من Yalidine تفعيل وصول API لحسابك. عادةً يتطلب الوصول إلى API حساباً تجارياً موثّقاً.

## ربط Yalidine في DZBuild[​](#ربط-yalidine-في-dzbuild "رابط مباشر إلى ربط Yalidine في DZBuild")

1. افتح **[`/dashboard/link-shipping`](https://dzbuild.com/dashboard/link-shipping)** في لوحة التحكم وابحث عن «Yalidine» في شبكة البطاقات (أو Yalitec / Guepex / Easy & Speed / Economiqua / We Can Services إن كانت شركتك).
2. اضغط **ربط** على البطاقة.
3. الصق **API ID** في الحقل الأول.
4. الصق **API Token** في الحقل الثاني.
5. اضغط **اختبار الاتصال**. تتصل لوحة التحكم بـ Yalidine مباشرةً وتُظهر علامة خضراء عند صحة البيانات.
6. اضغط **ربط وحفظ**. وفعّل **تعيين كشركة افتراضية** إن أردت أن تكون Yalidine هي الافتراضية للمتجر.

أما الأسعار فمكانها الصفحة المنفصلة **[`/dashboard/shipping`](https://dzbuild.com/dashboard/shipping)**. من هناك يمكنك:

* **مزامنة الأسعار** — لسحب أسعار البيت ونقاط الاستلام لكل ولاية من Yalidine.
* تجاوز سعر أي ولاية يدوياً إن أردت تحمّل جزء من الشحن أو تطبيق هامش.

حدّد ولاية متجرك أولاً

تحتاج مزامنة الأسعار لعائلة Yalidine (Yalidine و Yalitec و Guepex و Easy & Speed و Economiqua و We Can Services) إلى ولاية متجرك أنت. وإن لم تكن محدّدة في إعدادات المتجر تفشل المزامنة بالرسالة «يرجى تحديد ولاية المتجر أولاً من إعدادات المتجر قبل مزامنة الأسعار.». ونفس الولاية تُرسَل كـ `from_wilaya_name` مع كل طرد، وتصبح Alger افتراضياً إن لم تُحدَّد.

## Express مقابل Économique (لـ Guepex فقط)[​](#express-مقابل-économique-لـ-guepex-فقط "رابط مباشر إلى Express مقابل Économique (لـ Guepex فقط)")

تعرض نافذة البيانات مُحدِّد درجة التوصيل، **Express** أو **Économique**، لـ **Guepex فقط**. أما Yalidine و Yalitec و Easy & Speed و Economiqua و We Can Services فتشحن دائماً Express: لا ترسل لها DZBuild المعامل `economic` أبداً، لأن API الخاص بـ Yalidine يرفضه رفضاً تاماً.

الدرجة التي تختارها تُستعمل في الطرد المُرسَل وفي الأسعار التي تسحبها DZBuild عند الضغط على **مزامنة الأسعار**، لذا بعد تغييرها أعد مزامنة الأسعار ليتغيّر ما يدفعه زبونك. ولا تُطبَّق Économique إلا حيث يوفّرها حسابك لدى Guepex؛ وفي غير ذلك يُستعمل سعر Express.

## ما الذي يُسحب[​](#ما-الذي-يُسحب "رابط مباشر إلى ما الذي يُسحب")

* قائمة كاملة من **الولايات** و**البلديات**. تُؤخذ أسماء البلديات أساساً من قائمة البلديات المُزامَنة من المزوّد (بكتابة Yalidine نفسها)، مع قائمة البلديات المدمجة في DZBuild كخيار احتياطي. أما البلدية التي لا تنتمي إلى ولاية الطلب فتجعل الإرسال يفشل («البلدية المحددة لا تنتمي إلى الولاية المختارة») بدل أن تُصحَّح تلقائياً.
* **سعر التوصيل للبيت** لكل ولاية.
* **سعر نقطة الاستلام** لكل ولاية.
* قائمة **نقاط الاستلام** في كل ولاية، تُستعمل في [مُختار نقاط الاستلام](https://dzbuild.com/ar/ar/docs/couriers/stop-desk.md).

## أبعاد المنتج[​](#أبعاد-المنتج "رابط مباشر إلى أبعاد المنتج")

لا تظهر حقول **الطول / العرض / الارتفاع** في نموذج المنتج إلا عند ربط شركة من عائلة Yalidine — فلا عائلة أخرى تقبل الأبعاد. وإن تركتها فارغة يخرج الطرد بأبعاد 10 × 10 × 10 سم ووزن 0.5 كغ.

## ماذا يحدث عند شحن طلب[​](#ماذا-يحدث-عند-شحن-طلب "رابط مباشر إلى ماذا يحدث عند شحن طلب")

عند إرسال طلب إلى التوصيل من [`/dashboard/orders`](https://dzbuild.com/dashboard/orders) واختيار Yalidine في نافذة الإرسال إلى التوصيل، تُنشئ DZBuild الطرد لدى Yalidine بالبيانات التالية:

* الاسم واللقب ورقم الهاتف (يُهيّأ تلقائياً للصيغة المحلية `0X`). يصل إلى Yalidine رقم هاتف **واحد** فقط، لأن الطلب في DZBuild يحمل رقم زبون واحداً لا غير.
* العنوان، الولاية الوجهة، البلدية الوجهة (محوّلة للاسم الفرنسي).
* ولاية الانطلاق (ولاية متجرك — تُستخدم كـ `from_wilaya_name`).
* ملخص قائمة المنتجات.
* مبلغ COD (`price` = المجموع الفرعي، يدفعه الزبون عند الاستلام).
* القيمة المعلنة، الطول، العرض، الارتفاع، الوزن.
* الراية `is_stopdesk` إضافة إلى `stopdesk_id` صحيح عند توصيل المكتب.
* `freeshipping` و `do_insurance` ورايات التبديل عند الحاجة.

تُرجع Yalidine:

* **رقم تتبع** (يُحفظ على الطلب).
* رابط **ملصق** (PDF) يُلتقَط ويُحفَظ على الطلب.

طباعة ملصق Yalidine

لا يوجد في لوحة تحكم DZBuild أي زر يفتح رابط ملصق Yalidine. والضغط على **طباعة الملصق** في طلب Yalidine يطبع وصل DZBuild الخاص بصيغة HTML — أما ملصق Yalidine الرسمي فاطبعه من بوابة Yalidine.

ينتقل الطلب إلى حالة **`processing`** عند الإرسال (وفقط إن كان `pending` أو `confirmed`)، ويرى الزبون رقم التتبع على صفحة طلبه. ثم يصبح `shipped` عندما ترى مزامنة التتبع التلقائية حالة نقل من Yalidine مثل «Ramassé» أو «Expédié» أو «En cours de livraison»، ثم `delivered` (أو `returned` / `cancelled`).

### اختصار قائمة المنتجات[​](#اختصار-قائمة-المنتجات "رابط مباشر إلى اختصار قائمة المنتجات")

الطلبات الطويلة متعددة المنتجات تُختصر قائمة منتجاتها لتتّسع لحد الـ **150 حرفاً** عند Yalidine. وتتدرّج DZBuild في الاختصار: القائمة الكاملة `a | b | c`، ثم نفس القائمة بعد حذف لواحق المتغيّرات بين قوسين، ثم أول بضعة منتجات مع `+N`، وأخيراً اسم المنتج الأول مقطوعاً مع `+N`. وتتيح لك إضافة **Custom Delivery Label** (خطة Pro) التحكّم بما يُكتب هناك.

## نقاط الاستلام مع Yalidine[​](#نقاط-الاستلام-مع-yalidine "رابط مباشر إلى نقاط الاستلام مع Yalidine")

المكاتب التي تستطيع عرضها هي مكاتب Yalidine التي زامنتها DZBuild من API الخاص بـ Yalidine، وتُحدَّث كل ليلة أو فوراً بزر **تحديث البيانات** على بطاقة Yalidine. عند اختيار الزبون لتوصيل المكتب:

* تعرض إضافة [Stop Desk](https://dzbuild.com/ar/ar/docs/couriers/stop-desk.md) المكاتب في الولاية المحدّدة مع الاسم والعنوان والهاتف.
* يحفظ الطلب `desk_id` / `desk_name` الخاصين بـ DZBuild. أما `stopdesk_id` الخاص بـ Yalidine فيُحدَّد لحظة الإرسال: المكتب الذي اختاره الزبون، وإلا أي مكتب في بلديته، وإلا أي مكتب في الولاية. ثم تُفرَض على الطرد بلدية المكتب نفسه، فيتطابق المعرّف والبلدية دائماً.
* يُرفَض الإرسال — **ولا يُخفَّض أبداً إلى توصيل بيت** — فقط عندما لا تملك الولاية كلها أي مكتب Yalidine. وقد ترفضه DZBuild قبل الاتصال بـ Yalidine أصلاً، اعتماداً على بيانات المكاتب المُزامَنة لديها.

## أخطاء شائعة وحلولها[​](#أخطاء-شائعة-وحلولها "رابط مباشر إلى أخطاء شائعة وحلولها")

| الرسالة                                                                                    | السبب                                                                            | الحل                                                                                              |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `Invalid credentials` (عند **اختبار الاتصال**) / `بيانات الاعتماد غير صحيحة` (عند الإرسال) | رفضت Yalidine قيمة API ID أو API Token                                           | أعد نسخ القيمتين من لوحة Yalidine؛ من السهل تبديل الحقلين. وتأكّد أن الحساب ما زال يملك وصول API. |
| `بيانات API لشركة التوصيل غير صالحة أو منتهية الصلاحية، الإرسال متوقف`                     | رفضت Yalidine المفاتيح المحفوظة مراراً، فتوقّف الإرسال والتتبع الآلي لهذه الشركة | الصق مفاتيح جديدة على بطاقة Yalidine واضغط **حفظ التعديلات**.                                     |
| `حسابك لدى شركة التوصيل معطّل ولا يمكنه إنشاء طرود جديدة`                                  | Yalidine عطّلت حسابك                                                             | تواصل مع Yalidine لإعادة تفعيله، ثم أعد الإرسال.                                                  |
| `تتجاوز الحد الأقصى المسموح به لدى شركة التوصيل (150000 دج)`                               | المجموع الفرعي للطلب يتجاوز سقف Yalidine البالغ 150000 دج                        | قسّم الطلب إلى طردين، أو أرسله مع شركة توصيل أخرى.                                                |
| `Create Order failed:` متبوعة بكلام Yalidine نفسها                                         | رفضت Yalidine الطرد                                                              | صحّح ما تذكره الرسالة، ثم أعد الإرسال.                                                            |
| `لا يوجد مكتب استلام (Stop Desk) متاح`                                                     | الولاية كلها بلا أي مكتب Yalidine                                                | حدّث بيانات المزوّد من البطاقة، أو حوّل الطلب إلى توصيل بيت.                                      |
| `البلدية المحددة لا تنتمي إلى الولاية المختارة`                                            | عدم تطابق البلدية مع الولاية في الطلب                                            | صحّح البلدية على الطلب ثم أعد الإرسال.                                                            |
| إنشاء الطلب دون رقم تتبع                                                                   | عنوان أو بلدية غير مفهومين                                                       | تحقق من كتابة البلدية على الطلب ثم أعد الإرسال.                                                   |

## نصائح[​](#نصائح "رابط مباشر إلى نصائح")

* تتوقّع Yalidine البلديات بالفرنسية. تطابق DZBuild أولاً مع قائمة البلديات المُزامَنة من Yalidine نفسها ثم تعود إلى قائمة البلديات المدمجة لديها، لكن الكتابات النادرة قد تفشل — حافظ على نظافة قائمة بلديات متجرك، واضغط **تحديث البيانات** على بطاقة Yalidine إن بدت القائمة المُزامَنة قديمة.
* القيمة `price` التي تُرسَل إلى Yalidine هي **المجموع الفرعي** (سعر المنتجات) لا الإجمالي مع الشحن. هذا هو ما تجمعه الشركة في COD.
* إن كان لديك حساب في Yalitec أو Guepex أو Easy & Speed أو Economiqua أو We Can Services، اربطه تحت معرّفه؛ بنية API نفسها لكن البيانات غير قابلة للتبديل.