Ship with every Algerian courier through one API

Try it before you have an account

Every courier needs a merchant contract before it will take a single request. "courier": "sandbox" needs nothing at all: it checks the phone, the wilaya, the commune and every field limit exactly as a real courier does, then answers like one, and creates no parcel.

How it works

Every request carries three things: which courier to use, your own credentials for that courier, and the order itself. The parcel is created on your courier account; credentials are used for that one call and never stored. Switching courier is a one-line change: the request shape and the response shape stay the same.

Endpoints

Base URL https://freeship.dzbuild.com · all bodies JSON.

Create a parcel

The hero example above is complete and real: run it with your Yalidine credentials and a parcel lands on your account, label included. The fields that matter:

Track a parcel

On demand: call it on page load, from a cron, wherever. rawStatus always carries the courier's original wording.

$ curl -X POST https://freeship.dzbuild.com/v1/track \
  -H 'Content-Type: application/json' -d '{
    "courier": "yalidine",
    "credentials": { "apiId": "…", "apiToken": "…" },
    "trackingNumber": "yal-ABC123"
  }'

→ 200 {
  "status": "out_for_delivery",
  "events": [
    { "status": "picked_up",        "rawStatus": "Ramassé",            "timestamp": "2026-07-08T09:00:00Z" },
    { "status": "out_for_delivery", "rawStatus": "Sorti en livraison", "timestamp": "2026-07-09T08:30:00Z" }
  ]
}

One status vocabulary

Every courier's dialect (French sentences, Arabic labels, bare numbers) maps onto one closed set. Build your UI against it once.

delivered, returned, cancelled, lost are terminal. unknown means the courier emitted new wording: show rawStatus and keep polling. French + Arabic UI labels for all fourteen are in the status guide.

Quote a fee

$ curl -X POST https://freeship.dzbuild.com/v1/rates \
  -H 'Content-Type: application/json' -d '{
    "courier": "yalidine",
    "credentials": { "apiId": "…", "apiToken": "…" },
    "query": { "fromWilaya": 16, "toWilaya": 31, "deliveryType": "home" }
  }'

→ 200 { "deliveryFee": 600, "returnFee": 250, "total": 600, "currency": "DZD" }

Note the returnFee: your COD unit economics depend on it as much as on the delivery fee. query.toCommune refines per-commune pricing; query.tier accepts express (default) or economic. Deep-south wilayas (isDeepSouth in /v1/wilayas) carry surcharges everywhere, so quote rather than hardcode.

Stop desks

Let the customer choose where to collect the parcel. POST /v1/desks takes the same courier and credentials as an order, plus the wilaya, and returns the desks you can offer. Try it as written: the sandbox answers with no account.

$ curl -X POST https://freeship.dzbuild.com/v1/desks \
  -H 'Content-Type: application/json' -d '{
    "courier": "sandbox",
    "wilayaCode": 31
  }'

→ 200 [ { "id": "SBX-31", "name": "Sandbox desk Oran", "wilayaCode": 31,
          "communeName": "Oran", "address": "Sandbox address, Oran" } ]

To ship to the chosen desk, send deliveryType: "stopdesk", the desk's id as order.stopDeskId and, when the desk has one, its communeName as recipient.communeName. That one rule works for every courier:

Couriers

Ninety-nine couriers, one request shape. Credentials come from your own account on each courier's dashboard. GET /v1/couriers returns the live list with capabilities; ?q=rocket finds yours.

Choosing between them, per-courier behavior, COD mechanics: the dzship field guides cover what the comparison tables don't.

58 wilayas, 69 wilayas

Algeria became 69 wilayas in April 2026 (loi n° 26-06; codes 59–69 fixed by décret n° 26-206). No courier accepts a code above 58 yet. The parent wilayas keep running the new territory until the handover completes, and a parcel addressed to 60 is rejected.

So GET /v1/wilayas answers with the 58 you can actually ship to. Ask for the rest explicitly, and each one tells you what to ship it as:

Errors

One envelope everywhere: { "error": { "code", "message", "fields?" } }

Fair use

Hard server-side limits keep the API fast and free for everyone.

Design around them: track on page-view rather than tight loops. The reference endpoints (/v1/wilayas, /v1/communes, /v1/couriers) are cacheable and cost you nothing. They ship a Cache-Control header, so cache them and stop asking.