API Ecotrack — DHD, Anderson, World Express… en Node.js et PHP
Ecotrack est la plateforme utilisée par DHD, Anderson, World Express et des dizaines d’autres transporteurs algériens. Avec dz-delivery, un seul provider ecotrack les couvre tous.
Installer
npm install @dz-delivery/core
composer require dz-delivery/sdk
Node.js ≥ 18 (aucune dépendance) ou PHP ≥ 8.2 (Guzzle 7). Le même code fonctionne ensuite pour les autres transporteurs : seule la configuration du client change.
Identifiants Ecotrack
| Option | Valeur | Notes |
|---|---|---|
token | Token API du tableau de bord du transporteur | Envoyé en Authorization: Bearer <token> |
courier | Clé intégrée (dhd, anderson, …) | Exactement un de courier / baseUrl |
baseUrl | URL HTTPS du tenant, ex. https://xyz.ecotrack.dz | Pour tout autre transporteur Ecotrack |
autoValidate | false par défaut | true : valide la commande juste après sa création |
Ecotrack en TypeScript / Node.js
import { createClient, isShippingError } from '@dz-delivery/core'; const dhd = createClient('ecotrack', { token: process.env.ECOTRACK_TOKEN!, courier: 'dhd', // ou baseUrl: 'https://<tenant>.ecotrack.dz' autoValidate: true, // remettre la commande au transporteur tout de suite }); const wilayas = await dhd.getWilayas(); // wilayas desservies par ce transporteur const desks = await dhd.getStopDesks({ wilayaId: 16 }); const quote = await dhd.getFees({ toWilayaId: 16 }); try { const parcel = await dhd.createParcel({ recipientName: 'Mohamed Amine', phone: '0550123456', address: 'Cité 221 lots, n°98', wilayaId: 16, communeName: 'Bab Ezzouar', productName: 'T-shirt', price: 2500, orderId: 'ORDER-1001', }); const { parcel: current, events } = await dhd.track(parcel.trackingNumber); } catch (err) { if (isShippingError(err)) console.error(err.code, err.message); }
Ecotrack en PHP / Laravel
use DzDelivery\ClientFactory; use DzDelivery\Errors\ShippingError; $dhd = ClientFactory::create('ecotrack', [ 'token' => getenv('ECOTRACK_TOKEN'), 'courier' => 'dhd', // ou 'baseUrl' => 'https://<tenant>.ecotrack.dz' 'autoValidate' => true, ]); $quote = $dhd->getFees(['toWilayaId' => 16]); try { $parcel = $dhd->createParcel([ 'recipientName' => 'Mohamed Amine', 'phone' => '0550123456', 'address' => 'Cité 221 lots, n°98', 'wilayaId' => 16, 'communeName' => 'Bab Ezzouar', 'productName' => 'T-shirt', 'price' => 2500, 'orderId' => 'ORDER-1001', ]); $result = $dhd->track($parcel->trackingNumber); } catch (ShippingError $e) { echo "{$e->code}: {$e->getMessage()}"; }
Guide PHP complet (Laravel, erreurs, tests) : guide-php.md.
Méthodes supportées
| Méthode | Support | Notes |
|---|---|---|
createParcel | oui | Reste pending jusqu’à validation (voir autoValidate). |
track | oui | Statut unifié + historique. |
getFees | oui | Tarifs par wilaya. |
getWilayas / getCommunes | oui | Uniquement les wilayas desservies par le tenant. |
getStopDesks | oui | Communes avec stop desk (id = code postal Ecotrack). |
listParcels | NOT_SUPPORTED | Pas encore implémenté côté SDK. |
cancelParcel | oui | Uniquement avant validation de la commande. |
healthCheck | oui | Vérifie le token (appel réel). |
Transporteurs Ecotrack intégrés
Ces clés courier sont prêtes à l’emploi. Pour un autre transporteur Ecotrack, passez son URL en baseUrl (HTTPS uniquement).
| Transporteur | courier | Domaine |
|---|---|---|
| DHD | dhd | platform.dhd-dz.com |
| Anderson Delivery | anderson | anderson-ecommerce.ecotrack.dz |
| World Express | worldexpress | world-express.ecotrack.dz |
| 48Hr Express | 48hrexpress | 48hr.ecotrack.dz |
| EcoRapid | ecorapid | ecorapide-express.ecotrack.dz |
| Conexlog | conexlog | app.conexlog-dz.com |
| MSM Go | msmgo | msmgo.ecotrack.dz |
| Packers | packers | packers.ecotrack.dz |
| Rocket Delivery | rocketdelivery | rocketdelivery.ecotrack.dz |
À savoir sur l’API Ecotrack
- Validation : sans
autoValidate: true, les commandes restent en attente jusqu’à leur validation dans le tableau de bord du transporteur. cancelParcelne fonctionne qu’avant validation ; ensuite l’API renvoieVALIDATION_ERROR.- L’
iddes communes et des stop desks est le code postal Ecotrack (« station code ») : utilisez-le tel quel commestopDeskId. - Un
baseUrlse terminant par/api/v1est accepté (le suffixe est retiré automatiquement).
Mapping natif détaillé (endpoints, champs, statuts) : PROVIDERS.md.
FAQ Ecotrack
Comment intégrer l’API DHD ?
DHD tourne sur Ecotrack : créez un client ecotrack avec votre token DHD et courier: 'dhd'.
Mon transporteur utilise Ecotrack mais n’est pas dans la liste ?
Passez l’URL de son tenant en baseUrl (ex. https://moncoursier.ecotrack.dz) ; l’API est identique.
Pourquoi mes colis Ecotrack restent en attente ?
Ecotrack crée les commandes non validées. Activez autoValidate: true ou validez-les depuis le tableau de bord du transporteur.
Autres transporteurs
Même interface, mêmes statuts normalisés (pending, in_transit, delivered…).