dzship

mcp
Security Audit
Warn
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 29 GitHub stars
Code Warn
  • network request — Outbound network request in clients/node/index.cjs
  • network request — Outbound network request in clients/ruby/dzship.rb
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Shipping SDK and free API for Algeria: one integration for 101 delivery couriers (Yalidine, ZR Express, Maystro, NOEST, Osen Express, Zimou, DHD and every Ecotrack courier). Create, track, label and cancel COD parcels from Node, PHP, Python or Ruby. Includes the wilaya and commune dataset.

README.md

dzship

The shipping SDK for Algeria: one API for 101 delivery couriers. Create a
parcel, track it, print its label, cancel it, quote the fee and list stop desks
with the same code for Yalidine, ZR Express, Maystro, NOEST, Osen Express and
96 more.

SDK et API de livraison pour l'Algérie : un seul code pour Yalidine, ZR Express,
Maystro, NOEST, Osen Express, DHD et tous les transporteurs Ecotrack.

npm requests served couriers license

Documentation · API reference · Couriers · Wilaya dataset · FAQ

Install

npm install dzship                                           # Node 18+, types included, no dependencies
composer require dzbuild/dzship                              # PHP 7.2+, ext-curl only
pip install git+https://github.com/DZBuild-com/dzship.git    # Python 3.8+, standard library only

Ruby is one file to copy: clients/ruby/dzship.rb.
So are the PHP and Python clients, if you would rather not use a package
manager. Any other language talks to the same HTTP API.

Send your first parcel

You do not need a courier account to start. The sandbox courier takes no
credentials, checks your order the way a real courier does, and creates
nothing.

import dzship from 'dzship';

const shipping = dzship('sandbox');

const { trackingNumber } = await shipping.createOrder({
  recipient: {
    fullName: 'Amine Bouzid',
    phone: '0551234567',
    wilayaCode: 16,
    communeName: 'Bab Ezzouar',
  },
  deliveryType: 'home',
  productList: 'Sneakers x1',
  codAmount: 4500,
});

const { status, events } = await shipping.track(trackingNumber);

When your courier account is ready, one line changes:

const shipping = dzship('yalidine', { apiId: '…', apiToken: '…' });
// dzship('zrexpressnew', { apiKey: '…', tenantId: '…' })
// dzship('osenexpress', { token: '…' })
// dzship('dhd', { token: '…' })

The order, the tracking result and the status names keep the same shape for
every courier, so moving a store from one courier to another is that one line.

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

$shipping = new Dzship('yalidine', ['apiId' => '…', 'apiToken' => '…']);

$parcel = $shipping->createOrder([
    'recipient' => [
        'fullName' => 'Amine Bouzid', 'phone' => '0551234567',
        'wilayaCode' => 16, 'communeName' => 'Bab Ezzouar',
    ],
    'deliveryType' => 'home', 'productList' => 'Sneakers x1', 'codAmount' => 4500,
]);

echo $shipping->track($parcel['trackingNumber'])['status'];

Works in plain PHP, Laravel and WooCommerce. Examples for each are in the
integration guide.

Python
from dzship import Dzship

shipping = Dzship("yalidine", {"apiId": "…", "apiToken": "…"})

parcel = shipping.create_order({
    "recipient": {"fullName": "Amine Bouzid", "phone": "0551234567",
                  "wilayaCode": 16, "communeName": "Bab Ezzouar"},
    "deliveryType": "home", "productList": "Sneakers x1", "codAmount": 4500,
})

print(shipping.track(parcel["trackingNumber"])["status"])
curl
curl -X POST https://freeship.dzbuild.com/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "courier": "sandbox",
    "order": {
      "recipient": { "fullName": "Amine Bouzid", "phone": "0551234567",
                     "wilayaCode": 16, "communeName": "Bab Ezzouar" },
      "deliveryType": "home", "productList": "Sneakers x1", "codAmount": 4500
    }
  }'
{ "trackingNumber": "DZTEST-1A2B3C", "status": "created", "reference": "FS-…" }

What the clients do

Node PHP Python HTTP
Create a parcel createOrder(order) createOrder($order) create_order(order) POST /v1/orders
Track it track(trackingNumber) track($trackingNumber) track(tracking_number) POST /v1/track
Quote the delivery fee rates(query) rates($query) rates(query) POST /v1/rates
List a courier's stop desks desks(wilayaCode) desks($wilayaCode) desks(wilaya_code) POST /v1/desks
Print the label label(trackingNumber) label($trackingNumber) label(tracking_number) POST /v1/label
Cancel a parcel cancel(trackingNumber) cancel($trackingNumber) cancel(tracking_number) POST /v1/cancel
List couriers dzship.couriers() Dzship::couriers() dzship.couriers() GET /v1/couriers
List wilayas dzship.wilayas() Dzship::wilayas() dzship.wilayas() GET /v1/wilayas
List communes dzship.communes(16) Dzship::communes(16) dzship.communes(16) GET /v1/communes

No signup and no API key. You bring your own courier credentials on each call.

TypeScript knows your courier

courier completes to every courier key in your editor, and the credentials are
checked against that courier:

dzship('noest', { apiToken: '…' });
//              ~~~~~~~~~~~~~~~~~~ Property 'guid' is missing

dzship('yalidine', { token: '…' });
//                   ~~~~~ 'token' does not exist in type '{ apiId: string; apiToken: string }'

A courier chosen at runtime, from a settings form for example, still works: pass
the string and any credential map.

Couriers

curl 'https://freeship.dzbuild.com/v1/couriers?q=rocket'
Family courier keys Credentials
Yalidine yalidine yalitec guepex easyandspeed economiqua wecan apiId, apiToken
ZR Express (Procolis) zrexpress, which also answers to abexexpress, leopardexpress, colilog, flashdelivery token, key
ZR Express (new platform) zrexpressnew apiKey, tenantId
Maystro maystro apiKey
NOEST noest apiToken, guid
Osen Express osenexpress token
Terminal Delivery terminaldelivery token
Ecotrack (82 couriers) dhd conexlog msmgo rocketdelivery worldexpress andersondelivery … token
Zimou Express zimou token
Colivraison colivraison publicKey, token
Ecom Delivery ecomdelivery apiKey, apiToken
Elogistia elogistia apiKey
Near Delivery neardelivery apiKey, apiSecret
MDM Express mdm apiKey
Test courier sandbox none

Every key, with its credential fields and what it supports, is in
data/couriers.json. You name the courier and dzship does
the rest: there is no URL to find and nothing to configure.

Is yours missing? Open an issue
with its name.

What each courier supports

Couriers do not all offer the same calls. A label or a cancel that a courier has
no call for answers NOT_SUPPORTED, and you do it from that courier's dashboard.

Courier Create Track Rates Stop desks Label Cancel
Yalidine, Yalitec, Guepex, Easy & Speed, Economiqua, We Can ✅ ✅ ✅ ✅ ✅ ✅
ZR Express (Procolis) ✅ ✅ ✅ ❌ ❌ ❌
ZR Express (new platform) ✅ ✅ ✅ ✅ ❌ ❌
Maystro ✅ ✅ ✅ ✅ ✅ ✅
NOEST ✅ ✅ ✅ ✅ ✅ ✅
DHD, Conexlog, MSM Go and every other Ecotrack courier ✅ ✅ ✅ ✅ ✅ ❌
Zimou Express ✅ ✅ ✅ ✅ ✅ ❌
Colivraison ✅ ✅ ✅ ❌ ✅ ❌
Ecom Delivery ✅ ✅ ✅ ✅ ❌ ✅
Elogistia ✅ ✅ ✅ ✅ ✅ ✅
Near Delivery ✅ ✅ ✅ ✅ ✅ ❌
MDM Express ✅ ✅ ❌ ✅ ❌ ❌
Osen Express ✅ ✅ ✅ ✅ ✅ ❌
Terminal Delivery ✅ ✅ ✅ ✅ ✅ ❌
Sandbox (test courier) ✅ ✅ ✅ ✅ ✅ ✅

The table is written from the live courier list by scripts/sync-couriers.mjs.
GET /v1/couriers gives the same answer per courier at run time.

const label = await shipping.label(trackingNumber);
if (label.format === 'pdf') await writeFile('label.pdf', Buffer.from(label.data, 'base64'));
else console.log(label.url); // some couriers hand out a link instead of a file

await shipping.cancel(trackingNumber); // only before the courier collects the parcel

What dzship handles for you

Each Algerian courier has its own auth, field names and status words, and most
of the failures are quiet ones. These are the ones dzship absorbs:

  • NOEST and Osen Express ignore a parcel until a second call validates it.
    createOrder makes both calls.
  • Maystro, MDM, Osen and Terminal address parcels by their own commune ids. You
    send a commune name.
  • Statuses arrive in French, in Arabic or as bare numbers. You get one
    status vocabulary, with labels ready for a French or Arabic UI.
  • A commune spelled differently from the courier's list strands a parcel. The
    dataset uses the spellings couriers accept.
  • Algeria has 69 wilayas in law since April 2026 and couriers still accept 58.
    Every new wilaya tells you which code to ship with.

The courier guides list what each one does that the others do not:
Yalidine ·
ZR Express ·
Maystro ·
NOEST ·
Osen Express ·
Terminal Delivery ·
Ecotrack couriers

When a courier refuses a parcel

The clients throw one error type with a machine code and the courier's own
reason:

import dzship, { DzshipError } from 'dzship';

try {
  await shipping.createOrder(order);
} catch (e) {
  if (e instanceof DzshipError && e.code === 'COURIER_ERROR') {
    console.log(e.message); // "[osenexpress] the token was refused (HTTP 401): check the API token (osn_...)"
  }
}
HTTP code Meaning
400 VALIDATION_ERROR A field is wrong. fields says which
422 invalid_phone Not an Algerian mobile number
424 COURIER_ERROR The courier refused: rejected credentials, unknown commune, duplicate order
429 rate_limited Wait retryAfter seconds

A create is never retried for you, because a retried create is a second parcel.
The full table is in the API reference.

Wilaya and commune dataset

Most Algerian projects rebuild this list by hand. It is in data/ as
JSON and CSV, with French and Arabic names and numeric codes, free to use with
no attribution:

File Contents
wilayas.json The 58 wilayas couriers deliver to
communes.json · .csv All 1,541 communes
couriers.json Every courier key with its credential fields
wilayas-2026.json All 69 wilayas of the 2026 division, each with courierSupported and shipAs
new-wilayas-2026.json The 11 new wilayas with the 108 communes transferred into them
communes-moved-2026.csv Old code to new code, as a flat join
const communes = await dzship.communes(16); // or fetch the raw file:
// https://raw.githubusercontent.com/DZBuild-com/dzship/main/data/communes.json

Send wilayaCode: 60 to a courier today and the parcel is rejected, because the
parent wilayas still run the new territories. Ask for a new wilaya and you get
the code to use instead:

curl https://freeship.dzbuild.com/v1/wilayas?68
# { "code": 68, "nameFr": "Bou Saâda", "courierSupported": false, "shipAs": 28, … }

The wilayas and communes guide has the gazette
references and the spelling traps.

Guides

Guide What it answers
Integrating dzship Laravel, WooCommerce, Django, Rails, Google Sheets and raw HTTP, copy-paste ready
API reference Every endpoint and field, errors, rate limits
Choosing a courier Coverage, stop desks, exchanges and API quality per courier
Delivery statuses One status vocabulary, with French and Arabic labels
Cash on delivery Fees, returns, the deep-south surcharge, confirmation calls
Wilayas and communes The dataset, and why codes above 58 must not reach a courier yet

The same guides, with search and a browsable API reference, are on
freeship.dzbuild.com/docs.

Where your courier credentials go

They travel inside the request that needs them, go to that courier, and are not
stored. That also means anyone who holds them can create parcels on your
account, so call dzship from your server and never from browser JavaScript.

The hosted API is free: 200 orders an hour per IP, 60 tracking calls a minute,
and reference data you should cache. The limits are in the
API reference.

FAQ

How do I use the Yalidine API in Node.js or PHP?
dzship('yalidine', { apiId, apiToken }) in Node, new Dzship('yalidine', [...])
in PHP. The Yalidine guide covers the origin wilaya
and stop desks. Guepex, Yalitec and the other Yalidine networks use the same
call with their own key.

Comment intégrer l'API ZR Express dans mon site e-commerce ?
Installez dzship (npm) ou dzbuild/dzship (Composer), puis créez un client
zrexpress avec votre token et votre key, ou zrexpressnew avec apiKey
et tenantId si votre compte est sur la nouvelle plateforme. Voir le
guide ZR Express.

Does it work with DHD and the other Ecotrack couriers?
Yes. Each of the 82 has its own key (dhd, conexlog, rocketdelivery, …) and
takes the token from that courier's dashboard. The
Ecotrack guide lists them.

Est-ce que ça marche avec Laravel, WooCommerce ou Django ?
Oui. Le client PHP fonctionne dans tout projet Composer, et le
guide d'intégration donne un exemple pour chacun.

Is dzship an SDK or an API?
Both. The API is hosted and free, and the SDKs are thin typed clients for it:
npm install dzship, composer require dzbuild/dzship, or one file for Python
and Ruby. You write no courier integration yourself, and there is nothing to
host.

Can I switch couriers without rewriting my code?
Yes, for creating, tracking, quoting and listing desks. The courier key and the
credentials change, the rest of your code stays. Labels and cancels depend on
the courier: the support table says which.

Is there a test mode?
The sandbox courier. No account, no credentials, nothing created.

Building a whole store?

If shipping is one part of a store you are building for a merchant, look at
DZBuild before writing more code: Arabic and French
storefronts, landing pages, COD order management with confirmation workflows,
100+ couriers already connected, stock and analytics. dzship stays useful for
the custom pieces.

Contributing

A missing courier, a misspelled commune or a status mapped wrong is the most
useful issue you can open. See CONTRIBUTING.md. Security
reports go to SECURITY.md.


© DZBuild. The guides, clients and datasets here are MIT licensed,
and the datasets are public domain on top of that. The hosted service is
proprietary and is not in this repository; see NOTICE.md.

Reviews (0)

No results found