dz-deliveryAlgeria delivery SDK

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);

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);

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

const zr = createClient('zrexpress', { apiKey, tenant });
const zrExtra = createZRExpress({ apiKey, tenant }); // typed bulk / labels

const yalidine = createClient('yalidine', {
  apiId, apiToken, fromWilayaId: 16,
});
const guepex = createClient('yalidine', {
  apiId, apiToken, fromWilayaId: 16, baseUrl: GUEPEX_DEFAULT_BASE_URL,
});
const maystro = createClient('maystro', { apiToken });
const dhd = createClient('ecotrack', { token, courier: 'dhd' });

use DzDelivery\ClientFactory;
use DzDelivery\Models\ClientOptions;
use DzDelivery\Providers\ZRExpressProvider;
use DzDelivery\Providers\YalidineProvider;

$zr = ClientFactory::create('zrexpress', ['apiKey' => $key, 'tenant' => $tenant]);
$zrExtra = new ZRExpressProvider(ClientOptions::fromArray(['apiKey' => $key, 'tenant' => $tenant]));

$yalidine = ClientFactory::create('yalidine', [
    'apiId' => $id, 'apiToken' => $token, 'fromWilayaId' => 16,
]);
$guepex = ClientFactory::create('yalidine', [
    'apiId' => $id, 'apiToken' => $token, 'fromWilayaId' => 16,
    'baseUrl' => YalidineProvider::GUEPEX_DEFAULT_BASE_URL,
]);

const parcel = await shipping.createParcel({
  recipientName: 'Client',
  phone: '0550123456',       // normalized per carrier
  phone2: '0770000000',
  address: 'Cité 221 lots',
  wilayaName: 'Alger',        // or wilayaId: 16
  communeName: 'Bab Ezzouar',
  productName: 'T-shirt',     // or productList: [{ name, quantity }]
  price: 2500,
  weight: 0.5,
  orderId: 'ORD-1001',
  remark: 'fragile',
  isStopDesk: false,
  // stockType: 'none' | 'local' | 'warehouse'  (ZRExpress)
});
// → { id, trackingNumber, status, provider, raw? }

$parcel = $shipping->createParcel([
    'recipientName' => 'Client',
    'phone'         => '0550123456',
    'address'       => 'Cité 221 lots',
    'wilayaId'      => 16,
    'communeName'   => 'Bab Ezzouar',
    'productName'   => 'T-shirt',
    'price'         => 2500,
    'orderId'       => 'ORD-1001',
]);
// $parcel->id · trackingNumber · status · provider

const { parcel, events } = await shipping.track(trackingNumber);
// events: [{ status, label, at, raw? }, …]

$result = $shipping->track($trackingNumber);
foreach ($result->events as $event) {
    echo "$event->at $event->status $event->label\n";
}

const quote = await shipping.getFees({
  toWilayaId: 16,
  toCommuneId: '1630', // useful for Maystro / Yalidine
  isStopDesk: false,
  weight: 2,
});
// { deliveryFee, stopDeskFee?, returnFee?, currency: 'DZD' }

$quote = $shipping->getFees([
    'toWilayaId'  => 16,
    'toCommuneId' => 1630,
    'isStopDesk'  => false,
    'weight'      => 2,
]);

const wilayas = await shipping.getWilayas();
const communes = await shipping.getCommunes(16);

// ZRExpress: prefer wilaya only (the commune filter often returns nothing)
const desks = await shipping.getStopDesks({ wilayaId: 16 });
// Maystro: communeId is required

await shipping.createParcel({
  /* … */
  isStopDesk: true,
  stopDeskId: desks[0].id,
});

$wilayas = $shipping->getWilayas();
$communes = $shipping->getCommunes(16);
$desks = $shipping->getStopDesks(['wilayaId' => 16]);

const page = await zr.listParcels({ page: 1, pageSize: 50 });
// page.parcels · page.hasNext · page.totalCount

await zr.listParcels({ orderId: 'ORD-1001' });
await zr.listParcels({ keyword: '0550', status: 'pending' });
await zr.listParcels({ updatedSince: '2026-10-01T00:00:00+00:00', allPages: true });

$page = $zr->listParcels(['page' => 1, 'pageSize' => 50]);
$zr->listParcels(['orderId' => 'ORD-1001']);

await shipping.cancelParcel(parcel.trackingNumber);
const health = await shipping.healthCheck();

$shipping->cancelParcel($parcel->trackingNumber);
$health = $shipping->healthCheck();

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

try {
  await shipping.createParcel(input);
} catch (err) {
  if (isShippingError(err)) {
    console.error(err.code, err.message, err.httpStatus, err.details);
  }
  throw err;
}

use DzDelivery\Errors\ShippingError;

try {
    $shipping->createParcel($input);
} catch (ShippingError $e) {
    echo $e->code . ': ' . $e->getMessage();
}

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

app.post('/webhooks/zrexpress', express.raw({ type: '*/*' }), (req, res) => {
  const event = verifyZRExpressWebhook(
    req.body, req.headers, process.env.ZREXPRESS_WEBHOOK_SECRET!,
  );
  // event.type · parcelId · trackingNumber · status · raw
  res.sendStatus(200);
});

use DzDelivery\Providers\ZRExpress\Webhook;

$raw = file_get_contents('php://input'); // not Request::json()
$event = Webhook::verify($raw, getallheaders(), getenv('ZREXPRESS_WEBHOOK_SECRET'));

const multi = await zr.generateLabels(['16-AAA111-ZR', '16-BBB222-ZR']);
// { fileUrl, failedTrackingNumbers } — max 250

const one = await zr.generateLabels(['16-AAA111-ZR'], { mode: 'individual' });
// { labels: [{ trackingNumber, fileUrl }], failedTrackingNumbers } — max 100

$multi = $zr->generateLabels(['16-AAA111-ZR']);
$one = $zr->generateLabels(['16-AAA111-ZR'], ['mode' => 'individual']);

const created = await zr.createParcelsBulk([
  { ...input, orderId: 'ORD-1' },
  { ...input, orderId: 'ORD-2' },
]);
// { successes: Parcel[], failures: [{ index, orderId?, error }] }

const deleted = await zr.deleteParcelsBulk([
  '8c1a4c53-0000-4000-8000-000000000001', // UUID
  '16-AAA111-ZR',                             // tracking
]);

$created = $zr->createParcelsBulk([
    array_merge($input, ['orderId' => 'ORD-1']),
]);
$deleted = $zr->deleteParcelsBulk([$uuid, '16-AAA111-ZR']);