# dzship — the free shipping API for Algeria

> One HTTP API for 99 Algerian delivery couriers: Yalidine, ZR Express (Procolis),
> Maystro, NOEST, Zimou, Colivraison, Ecom Delivery, Elogistia, Near Delivery, MDM, and
> every courier running on Ecotrack (DHD, Conexlog, MSM Go, Rocket Delivery, World
> Express, Anderson…). Create and track cash-on-delivery parcels, quote delivery fees,
> and read the wilaya/commune reference data. No signup and no API key: the caller sends
> their own courier credentials with each request and they are never stored.

## Endpoints

- POST https://freeship.dzbuild.com/v1/orders — create a parcel
- POST https://freeship.dzbuild.com/v1/track — status and full event history
- POST https://freeship.dzbuild.com/v1/rates — delivery and return fees for a route
- GET  https://freeship.dzbuild.com/v1/couriers — every courier, its credentials and capabilities (?platform=, ?q=)
- GET  https://freeship.dzbuild.com/v1/wilayas — the 58 wilayas couriers deliver to (?16, ?code=, ?q=, ?all=1)
- GET  https://freeship.dzbuild.com/v1/communes — all 1,541 communes (?16, ?wilaya=, ?q=)
- GET  https://freeship.dzbuild.com/openapi.json — the machine-readable spec
- GET  https://freeship.dzbuild.com/health, https://freeship.dzbuild.com/stats

## How to use it

Every request body is: courier (a key from /v1/couriers) + credentials (that courier's own
fields) + the operation's payload. Switching courier is a one-line change.

Try it with no account at all: courier "sandbox" needs no credentials, 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 } }'

## Facts worth knowing before you write code

- recipient.phone must be an Algerian mobile (05/06/07). codAmount is an integer in DZD.
- wilayaCode is 1-58. communeName must match the courier's French spelling — get it from
  /v1/communes rather than from memory.
- Algeria has 69 wilayas in law since April 2026 (loi 26-06; codes 59-69 by décret 26-206),
  but NO courier accepts a code above 58 yet: the parent wilayas run the new territories
  until the handover completes. /v1/wilayas?all=1 returns all 69, each with the shipAs code
  to actually ship with.
- Courier credentials belong on a server. Never call this API from a browser.
- Fair use: 200 orders/hour/IP, 1,000/day, 60 tracking calls/minute. Reference endpoints
  are cacheable and send Cache-Control — cache them instead of polling.

## Guides and data

- https://github.com/DZBuild-com/dzship — courier field guides, the wilaya + commune dataset (CC0), and ready-made
  clients for Node (npm install dzship), PHP and Python.
- https://github.com/DZBuild-com/dzship/blob/main/docs/endpoints.md — every endpoint and field.
- https://github.com/DZBuild-com/dzship/blob/main/docs/couriers/ — what each courier does differently, and the traps.
- https://github.com/DZBuild-com/dzship/blob/main/data/ — 58 wilayas, 1,541 communes, FR + AR, plus the 2026 division.

## Optional

- https://dzbuild.com — the Algerian e-commerce platform that operates dzship: storefronts,
  landing pages, COD order management and 100+ courier integrations, for merchants who want
  the whole store rather than the shipping layer.