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

TypeScript · npm
npm install @dz-delivery/core
PHP · Composer
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

OptionValeurNotes
tokenToken API du tableau de bord du transporteurEnvoyé en Authorization: Bearer <token>
courierClé intégrée (dhd, anderson, …)Exactement un de courier / baseUrl
baseUrlURL HTTPS du tenant, ex. https://xyz.ecotrack.dzPour tout autre transporteur Ecotrack
autoValidatefalse par défauttrue : valide la commande juste après sa création

Ecotrack en TypeScript / Node.js

TypeScript
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

PHP
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éthodeSupportNotes
createParcelouiReste pending jusqu’à validation (voir autoValidate).
trackouiStatut unifié + historique.
getFeesouiTarifs par wilaya.
getWilayas / getCommunesouiUniquement les wilayas desservies par le tenant.
getStopDesksouiCommunes avec stop desk (id = code postal Ecotrack).
listParcelsNOT_SUPPORTEDPas encore implémenté côté SDK.
cancelParcelouiUniquement avant validation de la commande.
healthCheckouiVé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).

TransporteurcourierDomaine
DHDdhdplatform.dhd-dz.com
Anderson Deliveryandersonanderson-ecommerce.ecotrack.dz
World Expressworldexpressworld-express.ecotrack.dz
48Hr Express48hrexpress48hr.ecotrack.dz
EcoRapidecorapidecorapide-express.ecotrack.dz
Conexlogconexlogapp.conexlog-dz.com
MSM Gomsmgomsmgo.ecotrack.dz
Packerspackerspackers.ecotrack.dz
Rocket Deliveryrocketdeliveryrocketdelivery.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.
  • cancelParcel ne fonctionne qu’avant validation ; ensuite l’API renvoie VALIDATION_ERROR.
  • L’id des communes et des stop desks est le code postal Ecotrack (« station code ») : utilisez-le tel quel comme stopDeskId.
  • Un baseUrl se terminant par /api/v1 est 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…).