Skip to Content
dzshipBY DZBUILD

Endpoints: every endpoint and every field

Every dzship endpoint and field: orders, tracking, rates, stop desks, couriers, wilayas and communes, with errors and rate limits.

Edit on GitHub

Base URL https://freeship.dzbuild.com. Bodies and responses are JSON. There is no signup and no API key: you send your own courier credentials with each call and they are used for that one call, never stored.

Call it from a server. Courier credentials in browser JavaScript are public credentials.

Machine-readable spec: /openapi.json (OpenAPI 3.1), with a copy on GitHub at docs/openapi.json.

No credentials yet? "courier": "sandbox" needs none. It validates exactly what a real courier validates — phone, wilaya, commune, field limits — and creates nothing. Swap in a real courier key when your account is ready.

EndpointWhat it does
POST /v1/ordersCreate a parcel on your courier account
POST /v1/trackStatus + full event history for a tracking number
POST /v1/ratesDelivery and return fees for a route
POST /v1/desksThe stop desks a courier runs in one wilaya
GET /v1/couriersEvery supported courier, its credentials and capabilities
GET /v1/wilayasThe 58 wilayas couriers deliver to (?all=1 for all 69)
GET /v1/communesAll 1,541 communes, filterable by wilaya
GET /healthLiveness
GET /statsTotal requests served, as one number

POST /v1/orders

curl -X POST https://freeship.dzbuild.com/v1/orders \
  -H 'Content-Type: application/json' \
  -d '{
    "courier": "yalidine",
    "credentials": { "apiId": "YOUR_ID", "apiToken": "YOUR_TOKEN" },
    "options": { "fromWilaya": 16 },
    "order": {
      "reference": "ORD-1042",
      "recipient": {
        "fullName": "Amine Bouzid",
        "phone": "0551234567",
        "wilayaCode": 16,
        "communeName": "Bab Ezzouar",
        "addressLine": "Cité 1200 logements, Bt 4"
      },
      "deliveryType": "home",
      "productList": "Sneakers Air x1",
      "codAmount": 4500
    }
  }'
{ "trackingNumber": "yal-ABC123", "status": "created", "reference": "ORD-1042" }
FieldRequiredNotes
courieryesA key from GET /v1/couriers
credentialsyes1–8 string fields, exactly what that courier needs
options.fromWilayaYalidine familyOrigin wilaya code
options.baseUrlgeneric ecotrack onlyYour tenant, must be a *.ecotrack.dz host
options.timeoutMsno1000–30000
order.referencenoYour order id. Generated if omitted — send yours, it is your idempotency handle
order.recipient.fullNameyes2–120 chars
order.recipient.phoneyesAlgerian mobile: 05, 06, 07
order.recipient.phoneAltnoSecond number the courier may call
order.recipient.wilayaCodeyes1–58
order.recipient.communeNameyesFrench spelling from GET /v1/communes
order.recipient.addressLinehome deliveryUp to 255 chars
order.deliveryTypeyeshome or stopdesk
order.stopDeskIdstopdeskThe id of a desk from POST /v1/desks
order.productListyesWhat is in the parcel. Truncated per courier's real limit
order.codAmountyesInteger DZD. 0 for a prepaid parcel
order.weightKgno
order.declaredValuenoInteger DZD
order.freeShippingnoYou absorb the delivery fee
order.isExchangenoExchange parcel, where the courier supports it
order.hasOpenPackagenoCustomer may open before paying
order.notesnoUp to 255 chars

Creation is never retried automatically — a retried create is a duplicate parcel. Send your own reference and check before resending.

POST /v1/track

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

Returns the canonical status plus every event the courier reports, oldest first. Status vocabulary: statuses.md.

POST /v1/rates

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,
                   "toCommune": "Oran", "deliveryType": "home" } }'

query.tier accepts express (default) or economic where the courier runs a slower cheap lane.

POST /v1/desks

The stop desks a courier runs in one wilaya, so the customer can pick one. It takes the same courier and credentials as an order. The sandbox answers without an account:

curl -X POST https://freeship.dzbuild.com/v1/desks \
  -H 'Content-Type: application/json' \
  -d '{ "courier": "sandbox", "wilayaCode": 31 }'
[ { "id": "SBX-31", "name": "Sandbox desk Oran", "wilayaCode": 31,
    "communeName": "Oran", "address": "Sandbox address, Oran" } ]

To ship to the chosen desk, create the order with deliveryType: "stopdesk", the desk's id as order.stopDeskId and, when the desk has one, its communeName as order.recipient.communeName. That one rule covers every courier, because they route a desk parcel in one of two ways:

CourierWhat routes the parcel to the desk
Yalidine family, NOEST, ZR Express (new platform), Zimou, Ecom Delivery, MDM, Near DeliveryThe desk id. Yalidine also checks the desk's commune
Every Ecotrack courier, Maystro, ElogistiaThe commune. Their APIs take no desk id
ZR Express (Procolis), ColivraisonNo desk list over their API: 422 NOT_SUPPORTED

An empty list means the courier has no desk in that wilaya. Desk lists change a few times a year, so cache them per courier and wilaya for a day.

GET /v1/couriers

curl https://freeship.dzbuild.com/v1/couriers
curl 'https://freeship.dzbuild.com/v1/couriers?platform=ecotrack'
curl 'https://freeship.dzbuild.com/v1/couriers?q=rocket'

Each entry carries key, name, platform, requiredCredentials, capabilities, and either endpoint (dzship knows the address) or requiresBaseUrl with the host suffixes you may name.

GET /v1/wilayas

curl https://freeship.dzbuild.com/v1/wilayas          # the 58 you can ship to
curl https://freeship.dzbuild.com/v1/wilayas?16       # one wilaya
curl 'https://freeship.dzbuild.com/v1/wilayas?code=16'
curl 'https://freeship.dzbuild.com/v1/wilayas?q=oran' # search, FR or AR
curl 'https://freeship.dzbuild.com/v1/wilayas?all=1'  # all 69, 2026 division
{ "code": 16, "nameAr": "الجزائر", "nameFr": "Alger", "isDeepSouth": false,
  "communeCount": 57, "courierSupported": true }

A wilaya created in 2026 answers courierSupported: false and adds shipAs — the code couriers still expect for that territory. Why: wilayas-and-communes.md.

GET /v1/communes

curl https://freeship.dzbuild.com/v1/communes            # all 1,541
curl https://freeship.dzbuild.com/v1/communes?16         # one wilaya
curl 'https://freeship.dzbuild.com/v1/communes?wilaya=16'
curl 'https://freeship.dzbuild.com/v1/communes?q=bab'    # search
curl 'https://freeship.dzbuild.com/v1/communes?q=el+marsa&wilaya=16'
{ "wilayaCode": 16, "nameFr": "Bab Ezzouar", "nameAr": "باب الزوار" }

Search returns at most 100 rows. Ask for a new wilaya (59–69) and every commune carries the shipAs code for the parcel.

Errors

One envelope everywhere:

{ "error": { "code": "VALIDATION_ERROR", "message": "…", "fields": { "order.recipient.phone": "…" } } }
HTTPcodeWhat to do
400VALIDATION_ERRORFix the fields in error.fields
400CONFIGURATION_ERRORUnknown courier, or a credential is missing
400EGRESS_BLOCKEDoptions.baseUrl is not one of that courier's own addresses
404NOT_FOUNDNo such route, wilaya or commune
422invalid_phoneNot a valid Algerian mobile
422NOT_SUPPORTEDThat courier does not implement this operation
429rate_limitedWait Retry-After seconds
502COURIER_ERRORThe courier rejected it — the message is theirs
502HTTP_ERRORThe courier endpoint failed or timed out
503overloadedMomentary capacity guard — retry shortly

Error messages never contain the address dzship connected to. That is deliberate: an API that echoes its outbound URLs is a network scanner for anyone who asks.

Rate limits

LimitValue
Orders / hour / IP200
Orders / day / IP1,000
Orders / day / recipient phone10
Tracking calls / minute / IP60
Tracking calls / day / IP5,000
Rate quotes / minute / IP60
Desk lists / minute / IP60

GET /v1/wilayas, /v1/communes and /v1/couriers are reference data: they ship a Cache-Control header, so cache them and stop asking.

Need more than the limits allow? Open an issue and say what you are building.

Last updated on

On this page