dz-delivery — SDK livraison Algérie (Yalidine, ZRExpress, Maystro, Ecotrack)

One SDK, every Algerian shipping carrier. Available for TypeScript / Node.js (npm) and PHP / Laravel (Composer).

Un seul SDK pour créer, suivre et tarifer des colis avec les transporteurs algériens.

🌐 Docs & site : https://developing-off.github.io/dz-delivery/

dz-delivery gives e-commerce developers in Algeria a single, simple interface to create parcels, track shipments, quote fees and list wilayas/communes — regardless of which carrier is behind it.

It is not a 1:1 wrapper of every carrier endpoint. It focuses on the handful of operations every shop needs, with the same names and shapes in TypeScript and PHP.

Install

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

Supported carriers

Carrier	Key	TypeScript	PHP	Guide
Yalidine	yalidine	yes	yes	Yalidine API
GuepEx (Yalidine platform)	yalidine + GuepEx baseUrl	yes	yes	Yalidine API
ZRExpress	zrexpress	yes (+ bulk, labels, webhooks)	yes (+ bulk, labels, webhooks)	ZRExpress API
Maystro Delivery	maystro	yes (track / cancel via webhooks)	yes (track / cancel via webhooks)	Maystro API
Ecotrack (DHD, Anderson, World Express, 48Hr Express, EcoRapid, Conexlog, MSM Go, Packers, …)	ecotrack	yes	yes	Ecotrack API
NoEST, MDM, Ecom…	—	backlog	backlog

The unified API

Every provider implements the same ShippingProvider interface:

#	Operation	Method(s)
1	Create a parcel	createParcel(input)
2	Track a parcel	track(trackingNumber)
3	Quote delivery fees	getFees(query)
4	List locations	getWilayas() / getCommunes(wilayaId) / getStopDesks({ wilayaId, communeId? })
5	List account parcels	listParcels(query?)
6	Cancel a parcel	cancelParcel(trackingNumberOrId)
7	Health probe	healthCheck()

Statuses are normalized to: pending | created | in_transit | delivered | returned | cancelled | unknown. Every returned object can carry an optional raw field with the native API response for power users.

📄 The source of truth is docs/CONTRACT.md. Provider-specific endpoint mapping lives in docs/PROVIDERS.md. ZRExpress extras (bulk, labels, webhooks): docs/ZREXPRESS.md.

Status: 0.x — the API may still change between minor versions. Tests replay shared fixtures (mocked HTTP, no network) in both languages. Reports with anonymized real carrier responses are very welcome, see TASKS.md.

Quickstart

Copy .env.example to .env and fill in your credentials.

TypeScript

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

const shipping = createClient('zrexpress', {
  apiKey: process.env.ZREXPRESS_API_KEY!,
  tenant: process.env.ZREXPRESS_TENANT!,
});

const parcel = await shipping.createParcel({
  recipientName: 'Amine B.',
  phone: '0550123456',
  address: '12 rue Didouche Mourad',
  wilayaId: 16,
  communeName: 'Alger Centre',
  productName: 'T-shirt',
  price: 2500,
});

const { parcel: current, events } = await shipping.track(parcel.trackingNumber);
console.log(current.status, events);

Full TypeScript reference: packages/ts/README.md.

PHP

use DzDelivery\ClientFactory;

$shipping = ClientFactory::create('zrexpress', [
    'apiKey' => getenv('ZREXPRESS_API_KEY'),
    'tenant' => getenv('ZREXPRESS_TENANT'),
]);

$parcel = $shipping->createParcel([
    'recipientName' => 'Amine B.',
    'phone'         => '0550123456',
    'address'       => '12 rue Didouche Mourad',
    'wilayaId'      => 16,
    'communeName'   => 'Alger Centre',
    'productName'   => 'T-shirt',
    'price'         => 2500,
]);

$result = $shipping->track($parcel->trackingNumber);
echo $result->parcel->status;

Full PHP guide (install, every method, errors, Laravel, webhooks): docs/guide-php.md.

FAQ

How do I use the Yalidine API in Node.js or PHP? createClient('yalidine', { apiId, apiToken, fromWilayaId }) in TypeScript, ClientFactory::create('yalidine', [...]) in PHP. See the Yalidine guide.

Comment intégrer l'API ZR Express dans mon site e-commerce ? Installez @dz-delivery/core (Node.js) ou dz-delivery/sdk (PHP / Laravel), puis créez un client zrexpress avec votre apiKey et votre tenant. Voir le guide ZRExpress.

Does it work with DHD and other Ecotrack couriers? Yes — one ecotrack provider covers every courier on the Ecotrack platform, with a built-in courier key (dhd, anderson, worldexpress, …) or your tenant baseUrl. See the Ecotrack guide.

Can I switch carriers without rewriting my code? Yes. Every carrier returns the same models and the same normalized statuses, so only the client configuration changes.

Est-ce que ça marche avec Laravel, WooCommerce ou Shopify ? Le SDK PHP fonctionne dans n'importe quel projet Composer (exemple Laravel dans le guide PHP). Pour Shopify ou un backend Node, utilisez le package npm.

Repository layout

docs/            Shared contract, provider mapping, test fixtures
packages/ts/     TypeScript package (@dz-delivery/core)
packages/php/    PHP package (dz-delivery/sdk)
examples/ts/     TypeScript examples
examples/php/    PHP examples

Contributing

Contributions are very welcome — especially new providers. See CONTRIBUTING.md and the CHANGELOG.

License

MIT © 2026 dz-delivery contributors