Search by

dzbuild / dzship

ogyamada

Shipping SDK for Algeria: the PHP client for dzship, the free API. Create, track, label and cancel COD parcels with 101 couriers (Yalidine, ZR Express, Maystro, NOEST, Osen Express, DHD and every Ecotrack courier) through one request shape.

Package info

github.com/DZBuild-com/dzship

Homepage

Documentation

Language:JavaScript

pkg:composer/dzbuild/dzship

Statistics

Installs: 5

Dependents: 0

Suggesters: 0

Stars: 29

Open Issues: 0

v1.3.2 2026-11-22 11:18 UTC

This package is auto-updated.

Last update: 2026-11-22 11:40:14 UTC


README

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 · MCP server · Couriers · Wilaya dataset · FAQ · Français

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.

Use it from an AI assistant

dzship is also an MCP server. Claude Code, Cursor, VS Code and any other MCP client can find a courier, create a parcel, track it, quote its fee and cancel it, with no login:

claude mcp add --transport http dzship https://freeship.dzbuild.com/mcp
{ "mcpServers": { "dzship": { "url": "https://freeship.dzbuild.com/mcp" } } }

The first line is for Claude Code, the second is .cursor/mcp.json. Ask for a sandbox parcel to try it. For a real courier, keep your credentials in an X-Courier-Credentials header of the connection so they never pass through the conversation: the MCP guide shows how. The server is in the official MCP registry as com.dzbuild/dzship.

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
MCP server Connecting an assistant, the eight tools, where credentials go
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 an MCP server for Algerian couriers? Yes: https://freeship.dzbuild.com/mcp, over Streamable HTTP and with no login. Its tools are the API's own calls, so it covers the same 101 couriers.

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.