🇬🇧 English version: read it here

Si vous avez déjà développé une boutique en ligne en Algérie, vous connaissez le problème : chaque transporteur a sa propre API.

  • Yalidine : headers X-API-ID / X-API-TOKEN, wilaya d'origine obligatoire, pagination par page_size.
  • ZR Express : X-Api-Key + X-Tenant, création qui ne renvoie qu'un UUID, recherche des territoires par POST.
  • DHD, Anderson, World Express (plateforme Ecotrack) : token Bearer, paramètres en query string, commandes à valider après création.
  • Maystro : pas d'API de suivi du tout, tout passe par webhooks.

Et chacun a ses propres statuts : « En préparation », OrderReceived, 41…

J'ai écrit dz-delivery, un SDK open source (MIT) qui expose la même interface pour tous ces transporteurs, en TypeScript et en PHP.

Installation 

npm install @dz-delivery/core # Node.js ≥ 18, zéro dépendance composer require dz-delivery/sdk # PHP ≥ 8.2

Le même code pour chaque transporteur 

import { createClient } from '@dz-delivery/core'; const shipping = createClient('yalidine', { apiId: process.env.YALIDINE_API_ID!, apiToken: process.env.YALIDINE_API_TOKEN!, fromWilayaId: 16, }); // ou : createClient('zrexpress', { apiKey, tenant }) // ou : createClient('ecotrack', { token, courier: 'dhd' }) const quote = await shipping.getFees({ toWilayaId: 31 }); const parcel = await shipping.createParcel({ recipientName: 'Mohamed Amine', phone: '0550123456', address: 'Cité 221 lots, n°98', wilayaName: 'Oran', communeName: 'Bir El Djir', productName: 'T-shirt', price: 2500, }); const { parcel: current, events } = await shipping.track(parcel.trackingNumber); console.log(current.status); // 'pending' | 'in_transit' | 'delivered' | 'returned' | ...

En PHP / Laravel, c'est la même chose avec ClientFactory::create('yalidine', [...]).

Ce que le SDK gère pour vous

  • Wilayas et communes : par code officiel (1–58), par id du transporteur ou par nom. Le SDK les résout avant l'appel.
  • Téléphones : normalisés au format attendu par chaque transporteur.
  • Statuts unifiés : pending, created, in_transit, delivered, returned, cancelled, unknown. La réponse native reste disponible dans raw.
  • Erreurs typées : AUTH_FAILED, VALIDATION_ERROR, NOT_FOUND, RATE_LIMITED…
  • Stop desks : getStopDesks({ wilayaId }) pour les bureaux et points relais.
  • Extras ZR Express : étiquettes PDF, création en masse, vérification des webhooks signés.

Guides par transporteur

Contribuer

Le projet est sur GitHub : https://github.com/developing-off/dz-delivery. Les contributions sont bienvenues, surtout pour ajouter des transporteurs (NoEST, MDM…) ou partager des réponses réelles anonymisées pour renforcer les tests.

Si vous l'utilisez en production, dites-le moi en commentaire 🙏