# dzship documentation

> Index of every page: https://freeship.dzbuild.com/llms.txt

Source: https://freeship.dzbuild.com/docs

dzship is one HTTP API in front of 99 Algerian delivery couriers: Yalidine, ZR Express,
Maystro, NOEST, Zimou and every courier that runs on Ecotrack. You send the same JSON
whichever courier you ship with, and you get the same response back.

There is no signup and no API key. Each request carries your own credentials for the courier
you named. They are used for that one call and never stored, and the parcel is created on your
own courier account.

## One request shape

Every call is a courier key, that courier's credentials, and the payload of the operation.

```bash title="create-order.sh"
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
    }
  }'
```

Change `courier` and `credentials` to ship with another courier. Nothing else in the request
moves.

> **No courier account yet?**
> `"courier": "sandbox"` needs no credentials. It validates the phone, the wilaya, the commune
> and every field limit the way a real courier does, and creates no parcel. The
> [quickstart](https://freeship.dzbuild.com/docs/quickstart.md) starts there.

## What you can call

| Endpoint | What it does |
|---|---|
| `POST /v1/orders` | Create a parcel on your courier account |
| `POST /v1/track` | Status and full event history for a tracking number |
| `POST /v1/rates` | Delivery and return fees for a route |
| `POST /v1/desks` | The stop desks a courier runs in one wilaya |
| `GET /v1/couriers` | Every supported courier, its credentials and capabilities |
| `GET /v1/wilayas` | The 58 wilayas couriers deliver to (`?all=1` for all 69) |
| `GET /v1/communes` | All 1,541 communes, filterable by wilaya |

The [endpoints guide](https://freeship.dzbuild.com/docs/endpoints.md) explains each one with its fields, errors and rate
limits. The [API reference](https://freeship.dzbuild.com/docs/api.md) is the same contract generated from
[`/openapi.json`](https://freeship.dzbuild.com/openapi.json), with a request builder on every page.

## Where to go next

- [Quickstart](https://freeship.dzbuild.com/docs/quickstart.md): A sandbox parcel in one request, then a real one.

- [Integrating](https://freeship.dzbuild.com/docs/integrating.md): Clients for Node.js, PHP, Python and Ruby, and snippets for Laravel, WooCommerce, Django and Google Sheets.

- [Couriers](https://freeship.dzbuild.com/docs/couriers.md): The key and the credentials of every courier, and a guide for each of the big ones.

- [Statuses](https://freeship.dzbuild.com/docs/statuses.md): The fourteen statuses every courier is mapped onto, with French and Arabic labels.

- [Wilayas and communes](https://freeship.dzbuild.com/docs/wilayas-and-communes.md): The address data couriers accept, and what to do about the 69 wilayas of 2026.

- [Cash on delivery](https://freeship.dzbuild.com/docs/cash-on-delivery.md): Fees, returns and the order flow that cash at the door needs.

## Call it from a server

Courier credentials create parcels and read customer data on your account. Keep them on your
backend, never in browser JavaScript or a mobile app.

## Who runs it

dzship is operated by [DZBuild](https://dzbuild.com/?utm_source=freeship&utm_medium=referral&utm_campaign=dzship_docs),
an e-commerce platform for Algerian merchants. The courier integrations behind this API are
the ones DZBuild stores ship with. The guides, the clients and the wilaya dataset are public
on [GitHub](https://github.com/DZBuild-com/dzship).