ZR exploite deux API : l'ancienne API Procolis sur procolis.com et la plateforme plus récente sur api.zrexpress.app, mais dans DZBuild il n'y a qu'une seule tuile « ZR Express ». Les wilayas, communes et bureaux vers lesquels vous pouvez expédier viennent de votre propre compte ZR : DZBuild synchronise exactement ce qu'il renvoie et n'ajoute aucune couverture de son côté.
Vous ne choisissez pas d'API. Collez la paire d'identifiants dont vous disposez et DZBuild s'en charge : il tente d'abord la nouvelle plateforme, puis se rabat sur la paire Procolis classique, et enregistre le lien sous la plateforme qui a accepté les identifiants (une correspondance classique signale « تم الاتصال بنجاح مع ZR Express (المنصة القديمة) »).
Les boutiques liées avant la fusion des deux tuiles conservent leur lien ZR Express classique existant et le gèrent depuis la même tuile.
Ce qu'il vous faut
Deux valeurs, quelle que soit votre plateforme. Sur la tuile, les champs s'appellent API Key et Tenant ID :
Votre plateforme | Champ API Key | Champ Tenant ID |
Nouvelle plateforme | Secret Key | Tenant ID (un UUID type |
Procolis classique | Token | Key |
Les deux viennent de votre compte ZR Express — le nouveau portail les expose dans la zone API/intégrations, l'ancien tableau de bord dans ses paramètres API.
Abex Express tourne sur la même structure d'API Procolis et sur le même hôte, et affiche toujours les libellés Token / Key — mais il a sa propre tuile, ses propres identifiants émis par Abex et ses propres données de communes synchronisées. Les deux ne sont pas interchangeables.
Lier ZR Express dans DZBuild
Ouvrez
/dashboard/link-shippinget cherchez « ZR Express ».Cliquez sur Lier sur sa tuile.
Collez vos deux valeurs dans API Key et Tenant ID (sur la nouvelle plateforme la Secret Key puis le Tenant ID ; sur Procolis classique le Token puis la Key).
Cliquez sur Tester la connexion. Ce seul clic essaie les deux plateformes l'une après l'autre — la nouvelle d'abord, puis Procolis classique — et vous indique laquelle a accepté vos identifiants.
Cliquez sur Lier et enregistrer.
Ce qui est synchronisé
Liste des wilayas et communes desservies.
Tarifs domicile par wilaya.
Tarifs stop-desk par wilaya.
La liste des stop-desks — nouvelle plateforme uniquement. Elle provient de la recherche de hubs de ZR, en ne gardant que les hubs marqués comme points de retrait, et alimente le sélecteur Stop Desk.
L'ancienne plateforme Procolis ne publie aucune liste de bureaux. Toutes les communes d'une wilaya sont alors considérées éligibles au bureau dès que le prix Stopdesk de cette wilaya est supérieur à zéro ; le client choisit alors une option générique au niveau commune, affichée comme ZR Express suivi du nom de la commune, et ZR choisit le bureau de retrait réel au moment de l'expédition.
⚠️ Attention — Nouvelle plateforme : UUID de territoires
La nouvelle plateforme désigne les lieux par UUID de territoire, pas par nom. Quand les données de territoires synchronisées ne donnent aucune correspondance, DZBuild interroge ZR en direct ; si cela échoue aussi, l'envoi s'arrête avec « لم يتم العثور على: … في … » (commune) ou « لم يتم العثور على الولاية في نظام شركة التوصيل » (wilaya). Vérifiez l'orthographe de la commune sur la commande, cliquez sur Actualiser sur la tuile ZR Express (ou attendez le rafraîchissement quotidien automatique), puis renvoyez.
Ce qui se passe à l'expédition d'une commande
DZBuild envoie les coordonnées du client, la wilaya et la commune, la description du produit, votre numéro de commande comme référence externe, et le montant COD — qui sur les deux plateformes est le total de la commande (produits plus livraison), pas le sous-total.
La livraison au bureau s'exprime différemment selon la plateforme, et aucune des deux n'utilise is_stopdesk ni stopdesk_id :
Procolis classique :
TypeLivraison = 1(0 = domicile). Aucun poids n'est envoyé.Nouvelle plateforme :
deliveryType: "pickup-point"plus unhubId. Si aucun hub n'est fourni, DZBuild sélectionne automatiquement le plus proche ; si cela échoue, l'envoi est refusé au lieu d'être rétrogradé en livraison à domicile.
ZR Express retourne un numéro de suivi que DZBuild stocke sur la commande et expose au client.
La description du produit est plafonnée à 100 caractères sur la nouvelle plateforme (250 sur Procolis classique), et tout | dans un nom de produit est remplacé par un tiret.
Erreurs fréquentes
Message | Cause | Correction |
| L'un des deux champs est vide | Les deux sont requis — collez l'UUID en entier. |
Le test de connexion échoue avec le message propre à ZR | Aucune des deux plateformes n'a accepté la paire | DZBuild remonte l'erreur de la nouvelle plateforme quand les deux tentatives échouent : le message affiché peut donc ne pas mentionner Procolis même si votre compte est classique. Recopiez les deux valeurs ; si cela persiste, demandez à ZR Express d'activer l'accès API. |
| La nouvelle plateforme n'arrive pas à résoudre les identifiants de territoire wilaya/commune | Vérifiez la commune sur la commande, cliquez sur Actualiser sur la tuile, puis renvoyez la commande. |
Les messages Procolis classiques comme Clé non détectée S1 / S2 et Token désactivé peuvent encore apparaître sur le statut de livraison de la commande pour les comptes sur l'ancienne plateforme — ils signifient respectivement un Token incorrect, une Key incorrecte et un compte désactivé.
Astuces
Une boutique liée sur Procolis classique ouvre ce lien depuis la tuile, avec les champs Token et Key, et son test de connexion n'essaie que Procolis classique. Pour passer à la nouvelle plateforme, cliquez sur Délier dans cette fenêtre, puis liez la nouvelle paire et activez Définir comme transporteur par défaut si ZR était votre transporteur par défaut. DZBuild ne garde qu'un fournisseur ZR Express par boutique.
La gestion des fournisseurs (lier, gérer, tester, délier, définir par défaut) se trouve sur
/dashboard/link-shipping; les prix par wilaya sur/dashboard/shipping.Si vos clients ont besoin de choisir un bureau nommé, il vous faut la nouvelle plateforme — l'API classique ne peut proposer que l'option générique d'agence au niveau commune.