E-com Delivery API for Node.js and PHP

Install

npm install @dz-delivery/core

composer require dz-delivery/sdk

Node.js ≥ 18 (zero dependencies) or PHP ≥ 8.2 (Guzzle 7). Every carrier implements the same interface, so the same code works with the others once the client is configured; some operations are not available on every carrier and throw NOT_SUPPORTED (see the capability matrix).

E-com Delivery credentials

E-com Delivery in TypeScript / Node.js

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

const ecom = createClient('ecom', {
  apiKey: process.env.ECOM_API_KEY!,
  apiToken: process.env.ECOM_API_TOKEN!,
  autoValidate: true,          // hand the parcel to the carrier right away
});

try {
  const desks = await ecom.getStopDesks({ wilayaId: 16 });
  const quote = await ecom.getFees({ toWilayaId: 16 });

  const parcel = await ecom.createParcel({
    recipientName: 'Mohamed Amine',
    phone: '0550123456',
    address: 'Cité 221 lots, n°98',
    wilayaId: 16,
    communeName: 'Bab Ezzouar',
    productName: 'T-shirt',
    price: 2500,
    orderId: 'ORDER-1001',
  });

  const { parcel: current, events } = await ecom.track(parcel.trackingNumber);

  // Parcels updated since yesterday, all pages
  const page = await ecom.listParcels({ updatedSince: new Date(Date.now() - 86400000).toISOString(), allPages: true });
} catch (err) {
  if (isShippingError(err)) console.error(err.code, err.message);
}

E-com Delivery in PHP / Laravel

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

$ecom = ClientFactory::create('ecom', [
    'apiKey' => getenv('ECOM_API_KEY'),
    'apiToken' => getenv('ECOM_API_TOKEN'),
    'autoValidate' => true,
]);

try {
    $quote = $ecom->getFees(['toWilayaId' => 16]);

    $parcel = $ecom->createParcel([
        'recipientName' => 'Mohamed Amine',
        'phone'         => '0550123456',
        'address'       => 'Cité 221 lots, n°98',
        'wilayaId'      => 16,
        'communeName'   => 'Bab Ezzouar',
        'productName'   => 'T-shirt',
        'price'         => 2500,
        'orderId'       => 'ORDER-1001',
    ]);

    $result = $ecom->track($parcel->trackingNumber);
} catch (ShippingError $e) {
    echo "{$e->code}: {$e->getMessage()}";
}

Full PHP guide (Laravel, errors, testing): PHP guide.

Supported methods

E-com Delivery statuses → unified statuses

The SDK recognizes E-com’s situation and logistics-state labels, ignoring case and accents. For a parcel’s status, a final situation (« Livrée », « Annuler », « Commande Annuler »…) wins, then the logistics state, then any other situation.

« Récupérer », « Retour Fournisseur » and « Retour Stock » are missing from the E-com documentation but are returned live. In track history, notes (« Information », « Type de Colis », « Type de Livraison », « BIZ », steps without a situation) keep the previous status.

Full list of unified statuses and what they mean: SDK statuses.

Good to know about the E-com Delivery API

• Tested live (October 2026): reads, create then delete, errors.
• The recipient name is limited to 60 characters and the address to 100: beyond that, E-com returns an error, mapped to VALIDATION_ERROR on recipientName / address.
• A rejected parcel still returns HTTP 201: the SDK reads the line result and throws VALIDATION_ERROR (e.g. unknown office → stopDeskId).
• updatedSince follows the date of the last logistics action: a parcel that has not been handled yet does not show up.
• Statuses: « Récupérer » (payment collected) → delivered; « Retour Fournisseur » (returned to seller) → returned.
• The baseUrl must use HTTPS.

Detailed native mapping (endpoints, fields, statuses): PROVIDERS.md.

E-com Delivery FAQ

Other carriers

Same interface, same normalized statuses (pending, in_transit, delivered…).

• Yalidine API
• ZRExpress API
• Maystro API
• Ecotrack · DHD API
• NoEST API
• MDM Express API
• Elogistia API
• Full documentation