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
npm install @dz-delivery/core
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
| Option | Valeur | Notes |
|---|---|---|
apiKey | KEY de la page « Développement » du tableau de bord | Envoyé en X-API-Key |
apiToken | Token de la même page (régénérable) | Envoyé en X-API-Token |
autoValidate | false par défaut | true : colis créé déjà confirmé (« En Traitement ») |
E-com Delivery en 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, // 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
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éthode | Support | Notes |
|---|---|---|
createParcel | oui | Domicile ou stop desk. Reste « En Préparation » sans autoValidate. |
track | oui | Statut unifié (situation + état logistique) + historique. |
getFees | oui | Tarifs domicile / stop desk par wilaya. |
getWilayas / getCommunes | oui | Communes livrables uniquement. |
getStopDesks | oui | Bureaux E-com (id = code_stopdesk, ex. 16B). |
listParcels | oui | Pagination, filtre par tracking, n° de commande, statut et updatedSince. |
cancelParcel | oui | Uniquement les colis encore « En Préparation ». |
healthCheck | oui | Vé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_ERRORsurrecipientName/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). updatedSincesuit 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
baseUrldoit ê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…).