Algeria delivery in PHP and Laravel with dz-delivery

composer require dz-delivery/sdk

{
  "repositories": [
    { "type": "path", "url": "../dz-delivery/packages/php" }
  ],
  "require": {
    "dz-delivery/sdk": "*@dev"
  }
}

use DzDelivery\ClientFactory;

$zr = ClientFactory::create('zrexpress', [
    'apiKey' => getenv('ZREXPRESS_API_KEY'),   // sent as X-Api-Key
    'tenant' => getenv('ZREXPRESS_TENANT'),    // sent as X-Tenant
]);

$yalidine = ClientFactory::create('yalidine', [
    'apiId'        => getenv('YALIDINE_API_ID'),     // sent as X-API-ID
    'apiToken'     => getenv('YALIDINE_API_TOKEN'),  // sent as X-API-TOKEN
    'fromWilayaId' => 16,                            // or 'fromWilayaName' => 'Alger'
]);

$maystro = ClientFactory::create('maystro', [
    'apiToken' => getenv('MAYSTRO_API_TOKEN'),  // sent as Authorization: Token <apiToken>
]);

$dhd = ClientFactory::create('ecotrack', [
    'token'   => getenv('ECOTRACK_TOKEN'),  // sent as Authorization: Bearer <token>
    'courier' => 'dhd',                     // or 'baseUrl' => 'https://<tenant>.ecotrack.dz'
    // 'autoValidate' => true,              // hand each order to the courier right after creation
]);

$noest = ClientFactory::create('noest', [
    'apiToken' => getenv('NOEST_API_TOKEN'),  // sent as Authorization: Bearer <apiToken>
    'userGuid' => getenv('NOEST_USER_GUID'),  // partner GUID, sent as user_guid
    // 'autoValidate' => true,                // hand each order to NOEST right after creation
]);

$ecom = ClientFactory::create('ecom', [
    'apiKey'   => getenv('ECOM_API_KEY'),    // KEY, sent as X-API-Key
    'apiToken' => getenv('ECOM_API_TOKEN'),  // Token, sent as X-API-Token
    // 'autoValidate' => true,               // create parcels already confirmed
]);

$mdm = ClientFactory::create('mdm', [
    'apiKey'  => getenv('MDM_API_KEY'),   // sent as x-api-key
    'storeId' => getenv('MDM_STORE_ID'),  // STR-…, required to create parcels
]);

$elogistia = ClientFactory::create('elogistia', [
    'apiKey' => getenv('ELOGISTIA_API_KEY'),  // sent in the query string (Elogistia's design)
]);

$parcel = $client->createParcel([
    'recipientName' => 'Client Test',
    'phone'         => '0550123456',
    'address'       => '12 rue des Tests',
    'wilayaId'      => 16,               // or 'wilayaName' => 'Alger'
    'communeName'   => 'Bab Ezzouar',    // or 'communeId' => ...
    'productList'   => [
        ['name' => 'Mug', 'quantity' => 2],
        ['name' => 'T-shirt', 'quantity' => 1],
    ],                                   // or 'productName' => 'T-shirt'
    'price'         => 3200,             // what the recipient pays, in DZD
    'weight'        => 1.5,
    'orderId'       => 'ORD-1001',
]);

echo $parcel->trackingNumber;  // store it with your order
echo $parcel->status;          // usually 'pending' right after creation

$desks = $yalidine->getStopDesks(['wilayaId' => 16, 'communeId' => 1630]);

$parcel = $yalidine->createParcel([
    'recipientName' => 'Client Test',
    'phone'         => '0550123456',
    'address'       => 'Retrait au bureau',
    'wilayaId'      => 16,
    'communeId'     => 1630,
    'productName'   => 'T-shirt',
    'price'         => 2500,
    'isStopDesk'    => true,
    'stopDeskId'    => $desks[0]->id,
]);

$result = $client->track('yal-ABC123');

echo $result->parcel->status;               // current unified status
foreach ($result->events as $event) {        // oldest first
    echo "{$event->at}  {$event->status}  {$event->label}\n";
}

$quote = $yalidine->getFees([
    'toWilayaId'  => 31,
    'toCommuneId' => 3101,   // prices are per commune on Yalidine and Maystro
    'weight'      => 2,
    'length'      => 50,     // cm: Yalidine bills the volumetric weight when it is higher
    'width'       => 40,
    'height'      => 30,
]);

echo $quote->deliveryFee;   // 950 when oversize_fee = 50 DA/kg (see below)
echo $quote->stopDeskFee;
echo $quote->returnFee;

foreach ($client->getWilayas() as $wilaya) {
    echo "{$wilaya->code} {$wilaya->name} ({$wilaya->id})\n";
}

$communes = $client->getCommunes(16);       // code, carrier id or (Yalidine/Maystro) name

// ZRExpress: start with wilaya only — commune filter often returns no hubs.
$desks = $client->getStopDesks(['wilayaId' => 16]);

foreach ($desks as $desk) {
    echo "{$desk->id}  {$desk->name}  {$desk->address}\n";
}

$page = $zr->listParcels(['page' => 1, 'pageSize' => 50]);
foreach ($page->parcels as $parcel) {
    echo "{$parcel->trackingNumber} {$parcel->status}\n";
}

// Sync helpers:
// $zr->listParcels(['orderId' => 'ORD-1001']);
// $zr->listParcels(['keyword' => '0550', 'status' => 'pending']);
// $zr->listParcels(['updatedSince' => '2026-10-01T00:00:00+00:00', 'allPages' => true]);

$client->cancelParcel($parcel->trackingNumber);

$health = $client->healthCheck();
// $health->ok === true
// $health->provider  // 'yalidine' | ...
// $health->latencyMs // milliseconds

use DzDelivery\Support\StatusMapper;

StatusMapper::map('yalidine', 'Sorti en livraison');  // 'in_transit'
StatusMapper::maystro(41);                             // 'delivered' (code or name)

use DzDelivery\Errors\ShippingError;

function withRetry(callable $call, int $attempts = 3): mixed
{
    for ($i = 1; ; $i++) {
        try {
            return $call();
        } catch (ShippingError $e) {
            if ($e->code !== ShippingError::RATE_LIMITED || $i >= $attempts) {
                throw $e;
            }
            sleep($e->retryAfter ?? 2 ** $i);
        }
    }
}

$wilayas = withRetry(fn () => $client->getWilayas());

try {
    $client->createParcel($input);
} catch (ShippingError $e) {
    if ($e->code === ShippingError::VALIDATION_ERROR) {
        foreach ($e->details ?? [] as $d) {
            $errors[$d['field'] ?? 'general'][] = $d['message'];
        }
    } else {
        error_log("[{$e->provider}] {$e->code}: {$e->getMessage()}");
        throw $e;
    }
}

'dz_delivery' => [
    'default' => env('DZ_DELIVERY_PROVIDER', 'yalidine'),
    'zrexpress' => ['apiKey' => env('ZREXPRESS_API_KEY'), 'tenant' => env('ZREXPRESS_TENANT')],
    'yalidine' => [
        'apiId' => env('YALIDINE_API_ID'),
        'apiToken' => env('YALIDINE_API_TOKEN'),
        'fromWilayaId' => (int) env('YALIDINE_FROM_WILAYA_ID', 16),
    ],
    'maystro' => ['apiToken' => env('MAYSTRO_API_TOKEN')],
],

namespace App\Providers;

use DzDelivery\ClientFactory;
use DzDelivery\Contracts\ShippingProviderInterface;
use Illuminate\Support\ServiceProvider;

final class ShippingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Default carrier, injectable anywhere. One instance per app = location caches are shared.
        $this->app->singleton(ShippingProviderInterface::class, function () {
            $provider = config('services.dz_delivery.default');

            // [] when the carrier has no config entry: the SDK then throws its usual AUTH_FAILED, not a TypeError
            return ClientFactory::create($provider, config("services.dz_delivery.$provider", []));
        });
    }
}

use DzDelivery\Contracts\ShippingProviderInterface;
use DzDelivery\Errors\ShippingError;

final class ShipmentController
{
    public function store(Order $order, ShippingProviderInterface $shipping)
    {
        try {
            $parcel = $shipping->createParcel([
                'recipientName' => $order->customer_name,
                'phone' => $order->phone,
                'address' => $order->address,
                'wilayaId' => $order->wilaya_code,
                'communeName' => $order->commune,
                'productName' => $order->summary(),
                'price' => $order->total,
                'orderId' => (string) $order->id,
            ]);
        } catch (ShippingError $e) {
            return back()->withErrors(['shipping' => $e->getMessage()]);
        }

        $order->update(['tracking' => $parcel->trackingNumber, 'carrier' => $parcel->provider]);

        return back();
    }
}

<?php
// public/maystro-webhook.php

require __DIR__ . '/../vendor/autoload.php';

use DzDelivery\ClientFactory;
use DzDelivery\Errors\ShippingError;

// Shared secret: register the URL as /maystro-webhook.php?key=<MAYSTRO_WEBHOOK_SECRET>
$secret = (string) getenv('MAYSTRO_WEBHOOK_SECRET');
$given  = (string) ($_GET['key'] ?? '');
if ($secret === '' || !hash_equals($secret, $given)) {
    http_response_code(401);
    exit;
}

$body = json_decode(file_get_contents('php://input') ?: '', true);
$data = $body['message']['data'] ?? null;

$event = null;
if (is_string($data)) {
    $decoded = base64_decode($data, true);
    $event = json_decode((string) $decoded, true);
    if (!is_array($event)) {                       // decoded once is still base64
        $event = json_decode((string) base64_decode((string) $decoded, true), true);
    }
}

if (!is_array($event)) {
    http_response_code(400);
    exit;
}

if (($event['event'] ?? null) === 'OrderStatusChanged') {
    $orderId = trim((string) ($event['payload']['id'] ?? ''));
    if ($orderId === '') {
        http_response_code(400);
        exit;
    }

    // Do not trust the pushed status: read the order back from Maystro.
    $maystro = ClientFactory::create('maystro', ['apiToken' => getenv('MAYSTRO_API_TOKEN')]);
    try {
        $parcel = $maystro->track($orderId)->parcel;  // accepts the order UUID
    } catch (ShippingError $e) {  // unknown order or Maystro unavailable
        http_response_code(502);  // non-2xx answer: the event is not acknowledged
        exit;
    }

    // update your order where carrier_id = $orderId with $parcel->status ...
}

http_response_code(201);

use DzDelivery\ClientFactory;
use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Psr7\Response;

$mock = new MockHandler([
    new Response(200, ['Content-Type' => 'application/json'], json_encode([
        'has_more' => false,
        'data' => [['id' => 16, 'name' => 'Alger', 'zone' => 1, 'is_deliverable' => 1]],
    ])),
]);

$client = ClientFactory::create('yalidine', [
    'apiId' => 'test', 'apiToken' => 'test', 'fromWilayaId' => 16,
    'handler' => HandlerStack::create($mock),
]);

$wilayas = $client->getWilayas();   // served by the mock, no HTTP call

use DzDelivery\Models\ClientOptions;
use DzDelivery\Providers\ZRExpressProvider;
use DzDelivery\Providers\ZRExpress\Webhook;

$zr = new ZRExpressProvider(ClientOptions::fromArray([
    'apiKey' => getenv('ZREXPRESS_API_KEY'),
    'tenant' => getenv('ZREXPRESS_TENANT'),
]));

$bulk = $zr->createParcelsBulk([
    // each item MUST include orderId (externalId)
    [...$parcelInput, 'orderId' => 'ORD-1'],
]);
$labels = $zr->generateLabels(['16-AAA111-ZR']);

// Webhooks: use the raw request body (before JSON decode)
$raw = file_get_contents('php://input');
$event = Webhook::verify($raw, getallheaders(), getenv('ZREXPRESS_WEBHOOK_SECRET'));
// $event->type, $event->parcelId, $event->trackingNumber, $event->status