# ZR Express

ZR Express runs two APIs, the legacy **Procolis** API at `procolis.com` and the newer platform at `api.zrexpress.app`, but in DZBuild there is **one "ZR Express" tile**. Which wilayas, communes and desks you can ship to comes from your own ZR account: DZBuild syncs exactly what it returns, and never adds coverage of its own.

You do not choose an API. Paste whichever credential pair you have and DZBuild works it out: it tries the new platform first, then falls back to the legacy Procolis pair, and stores the link under whichever platform accepted the credentials (a legacy match reports « تم الاتصال بنجاح مع ZR Express (المنصة القديمة) »).

Stores that were linked before the two tiles were merged keep their existing legacy ZR Express link and manage it from the same tile.

## What you need

Two values, whichever platform you are on. On the tile the fields are labelled **API Key** and **Tenant ID**:

| Your platform   | API Key field | Tenant ID field                                                |
| --------------- | ------------- | -------------------------------------------------------------- |
| New platform    | Secret Key    | Tenant ID (a UUID like `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) |
| Legacy Procolis | Token         | Key                                                            |

Both come from your ZR Express account — the new portal exposes them in the API/integrations area, the legacy dashboard under its API settings.

**Abex Express** runs on the same Procolis API shape and the same host, and still shows the Token / Key labels — but it has its own tile, its own credentials issued by Abex, and its own synced commune data. The two are not interchangeable.

## Linking ZR Express in DZBuild

1. Open **[`/dashboard/link-shipping`](https://dzbuild.com/dashboard/link-shipping)** and search "ZR Express".
2. Click **Lier / ربط** on the tile.
3. Paste your two values into **API Key** and **Tenant ID** (on the new platform the Secret Key, then the Tenant ID; on legacy Procolis the Token, then the Key).
4. Click **Tester la connexion** (« اختبار الاتصال »). That one click tries both platforms in turn — new first, then legacy Procolis — and tells you which one accepted your credentials.
5. Click **Lier et enregistrer** (« ربط وحفظ »).

## What gets synced

* The list of **wilayas** and **communes** the courier serves.
* **Home delivery rates** per wilaya.
* **Stop-desk rates** per wilaya.
* The **stop-desk list** — **new platform only**. It comes from ZR's hub search, keeping the hubs flagged as pickup points, and feeds the [Stop Desk picker](https://dzbuild.com/docs/couriers/stop-desk.md).

The **legacy Procolis platform publishes no desk list at all**. Every commune in a wilaya counts as desk-eligible whenever that wilaya's Stopdesk price is above zero; the customer then picks a generic commune-level option, shown as ZR Express followed by the commune name, and ZR chooses the actual pickup desk when the parcel is dispatched.

New platform: territory UUIDs

The new platform addresses places by territory UUID, not by name. When the synced territory data has no match, DZBuild searches ZR live; if that also fails the send stops with « لم يتم العثور على: … في … » (commune) or « لم يتم العثور على الولاية في نظام شركة التوصيل » (wilaya). Check the commune spelling on the order, click **Actualiser** on the ZR Express tile (or wait for the automatic daily refresh) and re-send.

## What happens when an order ships

DZBuild sends the customer's details, wilaya and commune, the product description, your order number as the external reference, and the COD amount — which on **both** platforms is the **order total** (products plus shipping), not the subtotal.

Desk delivery is expressed differently per platform, and neither uses `is_stopdesk` or `stopdesk_id`:

* **Legacy Procolis**: `TypeLivraison = 1` (0 = home). No weight is sent.
* **New platform**: `deliveryType: "pickup-point"` plus a `hubId`. If no hub is supplied DZBuild auto-selects the closest one; if that fails the send is **refused** rather than downgraded to home delivery.

ZR Express returns a **tracking number** that DZBuild stores on the order and exposes to the customer.

The product description is capped at **100 characters** on the new platform (250 on legacy Procolis), and any `|` in a product name is replaced with a hyphen.

## Common errors and fixes

| Message                                         | Cause                                                       | Fix                                                                                                                                                                                                                                  |
| ----------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `API Key و Tenant ID مطلوبان`                   | One of the two fields is empty                              | Both are required — make sure the UUID is pasted in full.                                                                                                                                                                            |
| The connection test fails with ZR's own message | Neither platform accepted the pair                          | DZBuild surfaces the **new platform's** error when both attempts fail, so the message you see may not mention Procolis even if you are a legacy account. Re-copy both values; if it persists, ask ZR Express to activate API access. |
| `لم يتم العثور على: … في …`                     | New platform can't resolve the wilaya/commune territory IDs | Check the commune on the order, click **Actualiser** on the tile, then re-send the order.                                                                                                                                            |

Legacy Procolis messages such as *Clé non détectée S1 / S2* and *Token désactivé* can still show up on the order's delivery status for accounts on the old platform — they mean, respectively, a wrong Token, a wrong Key, and a disabled account.

## Tips

* A store linked on legacy Procolis opens that link from the tile, with **Token** and **Key** fields, and its connection test tries legacy Procolis only. To move to the new platform, click **Délier** (« إلغاء الربط ») in that window, then link the new pair and switch on **Définir comme transporteur par défaut** (« تعيين كشركة افتراضية ») if ZR was your default courier. DZBuild keeps one ZR Express provider per store.
* Provider management (link, manage, test, unlink, set default) lives at [`/dashboard/link-shipping`](https://dzbuild.com/dashboard/link-shipping); per-wilaya prices live at [`/dashboard/shipping`](https://dzbuild.com/dashboard/shipping).
* If your customers depend on picking a *named* desk, you need the new platform — the legacy API can only offer the generic commune-level agency option.