dzship

dzship creates and tracks cash-on-delivery parcels with 99 Algerian couriers through a single HTTP request. Yalidine, ZR Express, Maystro, NOEST, DHD, Conexlog and every courier running on Ecotrack all take the same request body. It’s free to call, with no signup and no API key.

I work on it with the DZBuild team. It comes out of the shipping engine DZBuild uses to move real orders across every wilaya each day.

Why it exists

Selling online in Algeria means shipping cash on delivery, and every courier does it differently. Each one has its own authentication, its own field names, and statuses in French, Arabic or bare numbers. Most want a signed merchant contract before they’ll answer a single test request. The failures are quiet: a commune spelled differently from the courier’s list, or a validation step the documentation never mentions, and parcels get stranded after the demo worked fine.

Then the map changed. Algeria went from 58 to 69 wilayas in April 2026, and no courier accepts a code above 58 yet. An order sent with wilayaCode: 60 is rejected.

dzship absorbs all of that in one place, so nobody has to relearn it courier by courier.

From test to delivered

1. Send an order to the sandbox courier. It checks exactly what a real courier checks and creates nothing, so the whole flow can be built before any courier contract exists.
2. When the courier account is ready, change courier to its name and add its credentials. Nothing else in the request changes. Credentials travel with each call and are never stored.
3. Track the parcel. Every courier’s statuses come back as one shared list, with French and Arabic labels ready to show customers.
4. For pickup instead of home delivery, POST /v1/desks lists the courier’s stop desks in the customer’s wilaya.

The first step, as it runs today:

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

For the 11 new wilayas, the API says which code to ship under (shipAs) until the couriers finish the handover.

Clients and data

For Node, npm install dzship gives a client with no dependencies and TypeScript types. The PHP, Python and Ruby clients are single files with no dependencies, so they run on shared hosting. The guides have examples for Laravel, WooCommerce, Django, Rails and Google Sheets.

import dzship from 'dzship';

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

The repository also carries the list most Algerian projects end up typing by hand: the 58 wilayas couriers deliver to, all 69 of the 2026 division, all 1,541 communes with French and Arabic names, and the 108 communes that moved into the new wilayas. It’s public domain.

What’s free

Calling the API is free, with fair-use limits of 200 orders an hour and 60 tracking calls a minute per IP. The clients and guides are MIT licensed and the datasets are CC0. The hosted service is run by DZBuild and its own code is not public.

Shipping APIs usually sit behind a contract, a key or a fee per parcel. This one doesn’t.