ZR Express covers all 58 wilayas with a strong stop-desk network and a familiar tracking app. ZR 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.
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 ID and API TOKEN:
Your platform | API ID | API TOKEN |
New platform | Secret Key | Tenant ID (a UUID like |
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
Open
/dashboard/link-shippingand search "ZR Express".Click Lier / ربط on the tile.
Paste your two values into API ID and API TOKEN.
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.
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.
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 "ZR Express agency" option and ZR chooses the actual pickup desk when the parcel is dispatched.
⚠️ Warning — New platform: territory UUIDs
The new platform addresses places by territory UUID, not by name. If the synced territory data is stale the send fails with « تعذر العثور على معرّفات المنطقة ». Fix it by clicking Actualiser on the ZR Express tile (or waiting for the automatic daily refresh) and re-sending.
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 ahubId. 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 |
| 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 | 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
No manual unlink is needed when you move between platforms: saving either credential pair automatically replaces the other ZR Express link and inherits its default-courier setting. DZBuild keeps one ZR Express provider per store.
Provider management (link, manage, test, unlink, set default) lives at
/dashboard/link-shipping; per-wilaya prices live at/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.