EcoTrack est une API de livraison partagée qui propulse une grande famille de transporteurs algériens. Il n'y a pas de tuile « EcoTrack » à choisir — vous choisissez la tuile de votre propre transporteur, et DZBuild dialogue avec lui via l'API EcoTrack au moyen d'un unique jeton bearer. 37 transporteurs ont leur propre tuile :

DHD, Conexlog, MSM Go, Rex Livraison, RB Livraison, Speed Delivery, Areex, Prest, Rocket Delivery, WorldExpress, BA Consult, Packers, 48Hr Livraison, Mono Hub, Anderson Delivery, GOLIVRI, Coyote Express, Salva Delivery, Distazero, FRET.Direct, TSL Express, Negmar Express, Ultra Express, OM Express, Med Express, Allo Livraison, Assil Delivery, Expedia Chrono, HHD Express, Imir Logistics, Navex Delivery, Swift Express, Univer Delivery, Colireli, FZ Delivery, Delivromail, PDEX.

Si votre transporteur figure dans cette liste, choisissez sa tuile — pas besoin d'intégration sur mesure.

Deux d'entre eux ne vivent pas sur des hôtes *.ecotrack.dz mais sont malgré tout des locataires EcoTrack : DHD (platform.dhd-dz.com) et Conexlog (app.conexlog-dz.com). Aucun des deux n'est une intégration directe distincte.

Mono Hub est un cas particulier : la tuile existe, mais son hôte mono.ecotrack.dz renvoie actuellement un 404 et le locataire semble désaffecté. Si Mono Hub est votre transporteur, demandez-lui son URL d'API actuelle et utilisez Custom EcoTrack.

Ce qu'il vous faut

Une seule valeur depuis le tableau de bord EcoTrack de votre transporteur :

API token (parfois appelé "Bearer token", "API key" ou "clé API").

Certains tableaux de bord EcoTrack la séparent sur deux écrans (compte → API → générer). Si vous ne la trouvez pas, demandez à votre interlocuteur d'activer l'accès API.

Lier un transporteur EcoTrack dans DZBuild

Ouvrez /dashboard/link-shipping et cherchez le nom de votre transporteur dans la grille de tuiles (par ex. DHD, Conexlog, MSM Go, …).
Cliquez sur Lier sur sa tuile.
Collez votre API token dans le champ d'identifiant unique. Les fournisseurs EcoTrack n'utilisent qu'un seul champ.
Cliquez sur Tester la connexion. Le tableau de bord interroge le transporteur en direct et confirme la validité du jeton.
Cliquez sur Lier et enregistrer.

Les prix par wilaya s'éditent sur la page distincte /dashboard/shipping.

Custom EcoTrack

Si votre transporteur n'est pas dans la grille de tuiles mais s'appuie sur EcoTrack, choisissez Custom EcoTrack et fournissez :

L'API URL de l'instance EcoTrack de votre transporteur — l'hôte de base uniquement, par ex. https://yourcourier.ecotrack.dz. DZBuild ajoute /api/v1 lui-même.
Un nom d'affichage. Ce que vous saisissez est ce qui apparaîtra partout dans le tableau de bord pour ce transporteur.
Le jeton bearer.

L'URL doit commencer par https:// et pointer vers un hôte public ; les adresses internes, loopback et réservées sont refusées pour des raisons de sécurité. Chaque URL personnalisée conserve ses propres données synchronisées de communes, bureaux et tarifs : changer l'URL relance donc une synchronisation à zéro. Préférez toujours une tuile native quand il en existe une pour votre transporteur.

Ce qui est synchronisé

Liste des wilayas et communes desservies.
Tarifs domicile par wilaya.
Tarifs stop-desk par wilaya.
Liste des stop-desks par wilaya (utilisée par le sélecteur Stop Desk).

Ce qui se passe à l'expédition d'une commande

Quand vous confirmez une commande dont la boutique est liée à un transporteur EcoTrack, DZBuild envoie le colis vers l'endpoint EcoTrack du transporteur avec :

nom_client, telephone et telephone_2, adresse.
code_wilaya + commune.
montant — le total de la commande (produits + livraison − remise), c'est-à-dire ce que paie le client à la livraison. Seuls les colis de la famille Yalidine utilisent le sous-total, parce que Yalidine facture les frais de livraison séparément.
produit (le résumé des articles), remarque (votre note), weight, et reference (votre numéro de commande DZBuild).
type — 1 pour une livraison, 2 pour un échange.
stop_desk — 0 ou 1. Il n'y a pas de champ delivery_type ni de stopdesk_id : un colis en bureau s'exprime en envoyant la commune du bureau comme commune avec stop_desk = 1.
fragile = 1, uniquement quand le produit est marqué fragile.

Le transporteur retourne un numéro de suivi.

Drapeau fragile

Marquer un produit Fragile ajoute fragile = 1 aux colis EcoTrack — et aux colis EcoTrack seulement. Aucune autre famille de transporteurs ne le reçoit (l'API de Yalidine rejette purement et simplement les paramètres inconnus).

Limite de la description produit

Le résumé des articles envoyé à EcoTrack est plafonné à 255 caractères. Une commande longue à plusieurs articles est raccourcie par paliers : la liste complète, puis la même liste sans les suffixes de variantes entre parenthèses, puis les premiers articles suivis de +N, et enfin un résumé du type x8 ORD-12345.

Imprimer le bordereau officiel du transporteur

EcoTrack est l'une des deux seules familles (l'autre étant Elogistia) dont le bordereau PDF officiel s'imprime directement depuis DZBuild. Cliquer sur Imprimer l'étiquette sur une commande EcoTrack télécharge l'étiquette officielle du transporteur en PDF — instances Custom EcoTrack comprises, via l'URL d'API que vous avez enregistrée.

Les commandes EcoTrack disposent aussi d'un bouton Expédier (« تأكيد الشحن ») propre à EcoTrack sur le panneau de détail de la commande, pour confirmer l'expédition auprès du transporteur.

Erreurs fréquentes

Symptôme	Cause probable	Correction
Le test de connexion renvoie "unauthorized"	Jeton incorrect ou expiré	Régénérez le jeton dans le tableau de bord du transporteur et recollez-le.
« يرجى إدخال رابط API » (Custom EcoTrack)	Le champ API URL est vide	Collez l'hôte de base de votre transporteur.
« يرجى إدخال رابط صحيح يبدأ بـ https:// » (Custom EcoTrack)	L'URL n'est pas en `https://`	Ressaisissez-la avec le schéma `https://`.
« يرجى إدخال رابط عام صحيح (لا يُسمح بعناوين داخلية) » (Custom EcoTrack)	L'URL pointe vers une adresse privée, loopback ou réservée	Utilisez le nom d'hôte public du transporteur. Un domaine public mais erroné se manifeste plutôt par un échec du test de connexion venant de l'API du transporteur.
Commande créée mais sans numéro de suivi	Adresse refusée par le transporteur	Vérifiez l'adresse sur la commande ; généralement une commune absente ou non reconnue.
« لا يوجد مكتب استلام (Stop Desk) متاح في هذه الولاية لشركة … »	Aucun bureau nulle part dans cette wilaya	Repassez la commande en livraison à domicile, ou cliquez sur Actualiser sur la tuile si vous pensez que la liste des bureaux est périmée.

Routage stop-desk

Une expédition EcoTrack en bureau n'est jamais rétrogradée en livraison à domicile. Si la commune du client n'a aucun bureau, DZBuild réachemine le colis vers une autre commune à bureau de la même wilaya, garde le drapeau bureau actif, et inscrit la redirection dans la remarque du colis (« مكتب الاستلام: X (بلدية الزبون: Y) »). Ce n'est que lorsque la wilaya n'a aucun bureau du tout que l'envoi échoue, avec un message vous invitant à passer en livraison à domicile.

Astuces

Beaucoup de transporteurs EcoTrack ont une force régionale (un cluster de wilayas). Demandez à votre interlocuteur où il est le plus rapide avant de promettre une livraison J+1.
Si vous changez de transporteur tout en restant sur EcoTrack, il suffit de lier la tuile du nouveau transporteur avec son jeton — les commandes, adresses et données client ne bougent pas.
Utilisez Custom EcoTrack pour les nouveaux transporteurs absents du tableau de bord DZBuild ; cela fonctionne tant qu'ils exposent les endpoints EcoTrack standards.