API E-com Delivery en Node.js et PHP

E-com Delivery propose une API v2 complète (ecom-dz.com/api_v2). Avec dz-delivery, le provider ecom la couvre entièrement, y compris la liste des colis du compte.

Installer

TypeScript · npm
npm install @dz-delivery/core
PHP · Composer
composer require dz-delivery/sdk

Node.js ≥ 18 (aucune dépendance) ou PHP ≥ 8.2 (Guzzle 7). Le même code fonctionne ensuite pour les autres transporteurs : seule la configuration du client change.

Identifiants E-com Delivery

OptionValeurNotes
apiKeyKEY de la page « Développement » du tableau de bordEnvoyé en X-API-Key
apiTokenToken de la même page (régénérable)Envoyé en X-API-Token
autoValidatefalse par défauttrue : colis créé déjà confirmé (« En Traitement »)

E-com Delivery en TypeScript / Node.js

TypeScript
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,          // remettre le colis au transporteur tout de suite
});

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

try {
  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);
} catch (err) {
  if (isShippingError(err)) console.error(err.code, err.message);
}

// Colis modifiés depuis hier, toutes pages
const page = await ecom.listParcels({ updatedSince: new Date(Date.now() - 86400000), allPages: true });

E-com Delivery en PHP / Laravel

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

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

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

try {
    $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()}";
}

Guide PHP complet (Laravel, erreurs, tests) : guide-php.md.

Méthodes supportées

MéthodeSupportNotes
createParcelouiDomicile ou stop desk. Reste « En Préparation » sans autoValidate.
trackouiStatut unifié (situation + état logistique) + historique.
getFeesouiTarifs domicile / stop desk par wilaya.
getWilayas / getCommunesouiCommunes livrables uniquement.
getStopDesksouiBureaux E-com (id = code_stopdesk, ex. 16B).
listParcelsouiPagination, filtre par tracking, n° de commande, statut et updatedSince.
cancelParcelouiUniquement les colis encore « En Préparation ».
healthCheckouiVérifie les identifiants (appel réel).

À savoir sur l’API E-com Delivery

  • Testé en réel (octobre 2026) : lectures, création puis suppression, erreurs.
  • Le nom du destinataire est limité à 60 caractères et l’adresse à 100 : au-delà, E-com renvoie une erreur, traduite en VALIDATION_ERROR sur recipientName / address.
  • Un colis refusé renvoie quand même HTTP 201 : le SDK lit le résultat de la ligne et lève VALIDATION_ERROR (ex. bureau inconnu → stopDeskId).
  • updatedSince suit la date de la dernière action logistique : un colis pas encore pris en charge n’y apparaît pas.
  • Statuts : « Récupérer » (paiement reçu) → delivered ; « Retour Fournisseur » → returned.
  • Le baseUrl doit être en HTTPS.

Mapping natif détaillé (endpoints, champs, statuts) : PROVIDERS.md.

FAQ E-com Delivery

Où trouver ma KEY et mon Token E-com ?

Dans le tableau de bord E-com, page « Développement ». Le Token peut être régénéré à tout moment.

Comment synchroniser mes colis E-com ?

Avec listParcels({ updatedSince, allPages: true }), puis track pour l’historique détaillé.

Pourquoi je ne peux pas supprimer un colis ?

E-com n’accepte la suppression que pour les colis encore « En Préparation » ; ensuite cancelParcel renvoie VALIDATION_ERROR.

Autres transporteurs

Même interface, mêmes statuts normalisés (pending, in_transit, delivered…).