dzship — Algerian shipping, explained for developers

API reference · Try it now · Couriers · Wilaya dataset · freeship.dzbuild.com

Create and track cash-on-delivery parcels with 99 Algerian couriers through one API — Yalidine, ZR Express, Maystro, NOEST, and every courier running on Ecotrack. Plus the field notes on how each one actually behaves, and the complete wilaya + commune dataset.

The code examples run against dzship, the free hosted API at freeship.dzbuild.com. No signup, no API key. You bring your own courier account credentials per call and they are never stored.

Maintained by DZBuild, the e-commerce platform that moves real COD orders across all wilayas every day. These guides are the field notes from that shipping engine.

Try it now, no account needed

Every other courier needs a merchant contract before you can send one request. This one doesn't exist, so you can start in ten seconds — it validates exactly what a real courier validates, and creates nothing:

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-…" }

When your Yalidine (or DHD, or Maystro…) credentials arrive, change two fields.

Create a real parcel in 60 seconds

curl -X POST https://freeship.dzbuild.com/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "courier": "yalidine",
    "credentials": { "apiId": "YOUR_API_ID", "apiToken": "YOUR_API_TOKEN" },
    "options": { "fromWilaya": 16 },
    "order": {
      "recipient": {
        "fullName": "Amine Bouzid",
        "phone": "0551234567",
        "wilayaCode": 16,
        "communeName": "Bab Ezzouar"
      },
      "deliveryType": "home",
      "productList": "Sneakers Air x1",
      "codAmount": 4500
    }
  }'

{ "trackingNumber": "yal-ABC123", "status": "created", "reference": "FS-…" }

Swap "courier" and "credentials" to ship with any other courier. The request shape stays the same. Full reference: docs/endpoints.md.

Start here

| Guide | What it answers | |---|---| | API reference | Every endpoint and field, errors, rate limits | | Integrating dzship | Ready-made clients (Node, PHP, Python) and copy-paste snippets for every stack | | Choosing a courier | Which delivery company fits your project: coverage, stop-desk, exchanges, API quality | | Wilayas & communes | The complete dataset, and why Algeria's new 69-wilaya division must not reach a courier yet | | Yalidine | The biggest network. Also Yalitec, Guepex, Easy & Speed, Economiqua, We Can | | ZR Express | Procolis. Strong in the center, simple credential model | | Maystro | Fulfillment-style courier with a strict duplicate policy | | NOEST | Why parcels get stranded if you skip the validation step | | Ecotrack couriers | DHD, Conexlog, MSM Go, Rocket, World Express and 78 more — one key each | | Delivery statuses | One status vocabulary for all couriers, with French and Arabic UI labels | | Cash on delivery | COD mechanics: fees, returns, the deep-south surcharge, confirmation calls |

Your courier is probably already in here

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 — also answers to abexexpress, leopardexpress, colilog, flashdelivery | token, key | | ZR Express (new platform) | zrexpressnew | apiKey, tenantId | | Maystro | maystro | apiKey | | NOEST | noest | apiToken, guid | | 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 |

You name the courier; dzship keeps the address. Nothing to look up, nothing to configure — and no way for a request to point the server at somewhere a courier does not own.

Or skip the raw HTTP — ready-made clients

The clients/ directory has MIT-licensed clients that wrap the same calls, with typed errors and retry-after handling built in:

• Node.js — npm install dzship (zero dependencies, TypeScript types included):

  import dzship from 'dzship';
  
  const client = dzship({ courier: 'yalidine', credentials: { apiId: '…', apiToken: '…' } });
  const { trackingNumber } = await client.createOrder({ /* recipient, productList, codAmount… */ });
  const communes = await client.communes(16);

• PHP — copy the single file clients/php/Dzship.php (ext-curl only, shared-hosting friendly).

• Python — copy the single file clients/python/dzship.py (standard library only, 3.8+).

The integration guide has full examples for Laravel, WooCommerce, Django, Google Sheets and raw HTTP in any language.

Free dataset: 58 wilayas, 69 wilayas, 1,541 communes

Most Algerian projects rebuild this list by hand, badly. It is in data/ as JSON and CSV — French + Arabic names, numeric codes:

| File | Contents | |---|---| | wilayas.json | The 58 wilayas couriers deliver to | | communes.json · .csv | All 1,541 communes | | 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 → new code, as a flat join |

const wilayas = await fetch(
  "https://raw.githubusercontent.com/DZBuild-com/dzship/main/data/wilayas.json"
).then((r) => r.json());

Free to use in any project, no attribution needed.

Algeria became 69 wilayas in April 2026 — and no courier accepts a code above 58 yet, because the parent wilayas keep running the new territories until the handover completes. Send wilayaCode: 60 today and the parcel is rejected. So the two lists are kept apart on purpose, and every new wilaya tells you what to ship it as:

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

The wilayas & communes guide has the gazette references, the full table, and the spelling traps (Aïn Ouessara in the law, Ain Oussera in every courier's database).

Why couriers are the hard part

Every Algerian courier ships its own API: different auth, different field names, statuses in French, Arabic, or bare numbers, and documentation that ranges from thin to wrong. The failure modes are quiet ones. A commune spelled differently than the courier's list, a validation step the docs never mention, a status code that looks inverted. Your integration works in the demo and strands parcels in production.

These guides exist so you don't relearn each trap the expensive way. Where a trap is already handled by the dzship API, the guide says so and you can stop worrying about it.

Fair use

The hosted API is free and stays free: 200 orders/hour per IP, 60 tracking calls per minute, and reference data you should cache rather than poll. The full table is in docs/endpoints.md. Call it from a server — courier credentials in browser JavaScript are public credentials.

Building a whole store?

If the shipping integration is part of a bigger build for a merchant, look at DZBuild before writing more code: Arabic/French storefronts, landing pages, COD order management with confirmation workflows, 100+ couriers pre-wired, stock and analytics. You keep dzship for the custom pieces.

Contributing

Courier missing, commune misspelled, status mapped wrong? That 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 — the datasets are public domain on top of that. The hosted service itself is proprietary and is not in this repository; see NOTICE.md.