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

#algeria #ecommerce #typescript #php

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

DEV Community