# ZR Express

تُشغّل ZR واجهتَي API: واجهة **Procolis** الكلاسيكية على `procolis.com` والمنصة الأحدث على `api.zrexpress.app`، لكن في DZBuild توجد **بطاقة واحدة باسم «ZR Express»**. أمّا الولايات والبلديات والمكاتب التي تستطيع الشحن إليها فتأتي من حسابك أنت لدى ZR: تُزامن DZBuild ما يُرجعه ذلك الحساب بالضبط، ولا تضيف أي تغطية من عندها.

أنت لا تختار API. الصق أيّ زوج بيانات لديك وتتولّى DZBuild الباقي: تجرّب المنصة الجديدة أولاً، ثم ترجع إلى زوج Procolis الكلاسيكي، وتحفظ الربط تحت المنصة التي قبلت البيانات (النجاح على الكلاسيكية يظهر برسالة «تم الاتصال بنجاح مع ZR Express (المنصة القديمة)»).

المتاجر التي رُبطت قبل دمج البطاقتين تحتفظ بربطها الكلاسيكي القائم مع ZR Express وتُديره من نفس البطاقة.

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

قيمتان، مهما كانت منصتك. في البطاقة يحمل الحقلان اسمَي **API Key** و **Tenant ID**:

| منصتك              | حقل API Key | حقل Tenant ID                                               |
| ------------------ | ----------- | ----------------------------------------------------------- |
| المنصة الجديدة     | Secret Key  | Tenant ID (UUID مثل `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) |
| Procolis الكلاسيكي | Token       | Key                                                         |

كلتاهما من حسابك في ZR Express — البوابة الجديدة تعرضهما في قسم API/التكاملات، واللوحة الكلاسيكية في إعدادات API الخاصة بها.

أما **Abex Express** فتعمل على نفس بنية API Procolis وعلى نفس النطاق، ولا تزال تعرض تسميتَي Token / Key — لكن لها بطاقتها الخاصة وبياناتها الصادرة عن Abex وبيانات بلدياتها المُزامَنة الخاصة. والاثنتان غير قابلتين للتبديل.

## ربط ZR Express في DZBuild[​](#ربط-zr-express-في-dzbuild "رابط مباشر إلى ربط ZR Express في DZBuild")

1. افتح **[`/dashboard/link-shipping`](https://dzbuild.com/dashboard/link-shipping)** وابحث عن «ZR Express».
2. اضغط **ربط** على البطاقة.
3. الصق القيمتين في **API Key** و **Tenant ID** (في المنصة الجديدة: Secret Key ثم Tenant ID؛ وفي Procolis الكلاسيكي: Token ثم Key).
4. اضغط **اختبار الاتصال**. تجرّب هذه الضغطة الواحدة المنصتين بالتتابع — الجديدة أولاً ثم Procolis الكلاسيكية — وتخبرك أيّهما قبلت بياناتك.
5. اضغط **ربط وحفظ**.

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

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

**منصة Procolis الكلاسيكية لا تنشر أي قائمة مكاتب إطلاقاً**. لذلك تُعتبر كل بلديات الولاية مؤهّلة للتوصيل للمكتب كلما كان سعر Stopdesk في تلك الولاية أكبر من صفر؛ ثم يختار الزبون خياراً عاماً على مستوى البلدية يظهر باسم ZR Express متبوعاً باسم البلدية، وتختار ZR المكتب الفعلي عند إرسال الطرد.

المنصة الجديدة: معرّفات المناطق (UUID)

تتعامل المنصة الجديدة مع الأماكن عبر UUID للمنطقة لا عبر الاسم. وإن لم تجد بيانات المناطق المُزامَنة أي تطابق، تبحث DZBuild مباشرةً لدى ZR؛ وإن فشل ذلك أيضاً يتوقف الإرسال برسالة «لم يتم العثور على: … في …» (للبلدية) أو «لم يتم العثور على الولاية في نظام شركة التوصيل» (للولاية). تحقّق من كتابة البلدية على الطلب، واضغط **تحديث البيانات** على بطاقة ZR Express (أو انتظر التحديث اليومي التلقائي) ثم أعد الإرسال.

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

تُرسل DZBuild بيانات الزبون والولاية والبلدية ووصف المنتج ورقم طلبك كمرجع خارجي ومبلغ COD — وهو في **كلتا** المنصتين **مجموع الطلب** (المنتجات مع الشحن) لا المجموع الفرعي.

ويُعبَّر عن التوصيل للمكتب بطريقة مختلفة في كل منصة، ولا تستعمل أيّ منهما `is_stopdesk` أو `stopdesk_id`:

* **Procolis الكلاسيكي**: `TypeLivraison = 1` (و 0 = بيت). ولا يُرسَل أي وزن.
* **المنصة الجديدة**: `deliveryType: "pickup-point"` مع `hubId`. وإن لم يُزوَّد أي مركز تختار DZBuild الأقرب تلقائياً؛ وإن فشل ذلك يُرفَض الإرسال بدل أن يُخفَّض إلى توصيل بيت.

تُرجع ZR Express **رقم تتبع** تحفظه DZBuild على الطلب وتعرضه للزبون.

ووصف المنتج محدود بـ **100 حرف** على المنصة الجديدة (و 250 على Procolis الكلاسيكي)، وأي `|` في اسم منتج تُستبدل بشرطة.

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

| الرسالة                            | السبب                                                        | الحل                                                                                                                                                                                                    |
| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `API Key و Tenant ID مطلوبان`      | أحد الحقلين فارغ                                             | الحقلان مطلوبان معاً — تأكّد من لصق UUID كاملاً.                                                                                                                                                        |
| فشل اختبار الاتصال برسالة ZR نفسها | لم تقبل أي من المنصتين الزوج                                 | تُظهر DZBuild خطأ **المنصة الجديدة** عندما تفشل المحاولتان، لذا قد لا تذكر الرسالة التي تراها Procolis حتى لو كان حسابك كلاسيكياً. أعد نسخ القيمتين؛ وإن استمر الخطأ اطلب من ZR Express تفعيل وصول API. |
| `لم يتم العثور على: … في …`        | تعذّر على المنصة الجديدة تحديد معرّفات منطقة الولاية/البلدية | تحقّق من البلدية على الطلب، واضغط **تحديث البيانات** على البطاقة، ثم أعد إرسال الطلب.                                                                                                                   |

ورسائل Procolis الكلاسيكية مثل *Clé non détectée S1 / S2* و *Token désactivé* قد تظهر أيضاً على حالة التوصيل الخاصة بالطلب للحسابات على المنصة القديمة — وتعني على الترتيب: Token خاطئ، Key خاطئ، وحساب معطّل.

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

* المتجر المربوط على Procolis الكلاسيكي يفتح ذلك الربط من البطاقة بحقلَي **Token** و **Key**، ولا يجرّب اختبار الاتصال فيه سوى Procolis الكلاسيكي. للانتقال إلى المنصة الجديدة، اضغط **إلغاء الربط** في تلك النافذة، ثم اربط الزوج الجديد وفعّل **تعيين كشركة افتراضية** إن كانت ZR شركتك الافتراضية. تحفظ DZBuild مزوّد ZR Express واحداً لكل متجر.
* إدارة المزوّدين (الربط، الإدارة، الاختبار، إلغاء الربط، التعيين كافتراضي) مكانها [`/dashboard/link-shipping`](https://dzbuild.com/dashboard/link-shipping)؛ أما أسعار الولايات فمكانها [`/dashboard/shipping`](https://dzbuild.com/dashboard/shipping).
* إن كان زبائنك يحتاجون فعلاً إلى اختيار مكتب *بالاسم*، فأنت بحاجة إلى المنصة الجديدة — فالـ API الكلاسيكي لا يقدّم سوى خيار الوكالة العام على مستوى البلدية.