dzship
Health Gecti
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 29 GitHub stars
Code Uyari
- network request — Outbound network request in clients/node/index.cjs
- network request — Outbound network request in clients/ruby/dzship.rb
Permissions Gecti
- Permissions — No dangerous permissions requested
Bu listing icin henuz AI raporu yok.
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.
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.
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.
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.
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 indata/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.
createOrdermakes 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 clientzrexpress 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.
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi