DEV Community: developing-off

Intégrer Yalidine, ZR Express et DHD dans votre boutique avec un seul SDK (Node.js et PHP)

developing-off — Sat, 24 Oct 2026 08:31:22 +0000

🇬🇧 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 🙏

One SDK for every Algerian delivery carrier: Yalidine, ZR Express, DHD and Maystro in Node.js and PHP

developing-off — Sat, 24 Oct 2026 08:29:32 +0000

🇫🇷 Version française : lire ici

If you have built an online store in Algeria, you know the drill: every delivery carrier has its own API, and none of them look alike.

Yalidine: X-API-ID / X-API-TOKEN headers, a mandatory origin wilaya, page_size pagination.
ZR Express: X-Api-Key + X-Tenant, a create endpoint that only returns a UUID, territory lookups through POST search endpoints.
DHD, Anderson, World Express (all on the Ecotrack platform): Bearer token, query-string parameters, orders that must be validated after creation.
Maystro: no tracking API at all — everything comes through webhooks.

And every one of them speaks its own status language: "En préparation", OrderReceived, 41…

So I built dz-delivery, an open-source (MIT) SDK that exposes one interface for all of these carriers, in TypeScript and PHP.

Install

npm install @dz-delivery/core      # Node.js ≥ 18, zero runtime dependencies
composer require dz-delivery/sdk   # PHP ≥ 8.2

Same code, any carrier

import { createClient } from '@dz-delivery/core';

const shipping = createClient('yalidine', {
  apiId: process.env.YALIDINE_API_ID!,
  apiToken: process.env.YALIDINE_API_TOKEN!,
  fromWilayaId: 16, // origin wilaya (Algiers)
});
// or: createClient('zrexpress', { apiKey, tenant })
// or: createClient('ecotrack', { token, courier: 'dhd' })

const quote = await shipping.getFees({ toWilayaId: 31 });
// { deliveryFee, stopDeskFee, currency: 'DZD' }

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, // cash on delivery, in DZD
});

const { parcel: current, events } = await shipping.track(parcel.trackingNumber);
console.log(current.status); // 'pending' | 'in_transit' | 'delivered' | 'returned' | ...

In PHP / Laravel it is the same thing with ClientFactory::create('yalidine', [...]).

What the SDK handles for you

Wilayas and communes: pass the official code (1–58), the carrier's own id, or a name — the SDK resolves it before calling the API.
Phone numbers: normalized to the format each carrier expects.
Unified statuses: pending, created, in_transit, delivered, returned, cancelled, unknown. The native response is still available in raw.
Typed errors: AUTH_FAILED, VALIDATION_ERROR, NOT_FOUND, RATE_LIMITED, NOT_SUPPORTED…
Stop desks: getStopDesks({ wilayaId }) for carrier offices and pickup points.
Account sync: listParcels() to pull parcel statuses (ZR Express).
ZR Express extras: PDF labels, bulk create/delete, signed webhook verification.

Carrier guides

Contributing

The code is on GitHub: https://github.com/developing-off/dz-delivery. Contributions are very welcome — especially new carriers (NoEST, MDM…) or anonymized real API responses to strengthen the test fixtures.

If you use it in production, let me know in the comments 🙏