### GET /v1/couriers

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

Lists every supported courier by name, with credentials and capabilities.

```APIDOC
## GET /v1/couriers

### Description
Lists every supported courier by name, with credentials and capabilities.

### Method
GET

### Endpoint
/v1/couriers

### Parameters
None

### Response
#### Success Response (200)
- **couriers** (array) - List of couriers with their details

#### Response Example
{
  "couriers": []
}
```

--------------------------------

### GET /health

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

Liveness check for the API.

```APIDOC
## GET /health

### Description
Liveness check for the API.

### Method
GET

### Endpoint
/health

### Parameters
None

### Response
#### Success Response (200)
- **status** (string) - Health status

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### GET /openapi.json

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

Returns the whole contract in machine-readable format. Also available as /llms.txt for agents.

```APIDOC
## GET /openapi.json

### Description
Returns the whole contract in machine-readable format. Also available as /llms.txt for agents.

### Method
GET

### Endpoint
/openapi.json

### Parameters
None

### Response
#### Success Response (200)
- **openapi** (object) - The OpenAPI specification

#### Response Example
{
  "openapi": "3.0.0"
}
```

--------------------------------

### Create a parcel with POST /v1/orders

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

Sends a POST request to create a new parcel order. The example includes the required courier credentials, recipient details, and delivery information.

```bash
$ curl -X POST https://freeship.dzbuild.com/v1/orders \
  -H 'Content-Type: application/json' -d '{
    "courier":     "yalidine",
    "credentials": { "apiId": "…", "apiToken": "…" },
    "options":     { "fromWilaya": 16 },
    "order": {
      "recipient": {
        "fullName":    "Amine Bouzid",
        "phone":       "0551234567",
        "wilayaCode":  16,
        "communeName": "Bab Ezzouar"
      },
      "deliveryType": "home",
      "productList":  "Sneakers Air x1",
      "codAmount":    4500
    }
  }'

→ 201 { "trackingNumber": "yal-ABC123", "status": "created" }
```

--------------------------------

### GET /v1/wilayas

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

Returns the list of wilayas that couriers can deliver to. By default, only the 58 shippable wilayas are returned.

```APIDOC
## GET /v1/wilayas

### Description
Returns the list of wilayas that couriers can deliver to. By default, only the 58 shippable wilayas are returned.

### Method
GET

### Endpoint
/v1/wilayas

### Parameters
#### Query Parameters
- **all** (integer) - Optional - If set to 1, returns all 69 wilayas, each with `courierSupported` and `shipAs` fields.
- **q** (string) - Optional - Name search, French or Arabic, accents optional.
- **wilaya code** (integer) - Optional - If a wilaya code is provided (e.g., 60), returns that specific wilaya with its `courierSupported` and `shipAs` fields.

### Response
#### Success Response (200)
- **wilayas** (array) - List of wilaya objects.
- **courierSupported** (boolean) - Whether the courier supports this wilaya.
- **shipAs** (integer) - The wilaya code to use for shipping.

#### Response Example
{
  "wilayas": [
    {
      "code": 60,
      "name": "Barika",
      "courierSupported": false,
      "shipAs": 5
    }
  ]
}
```

--------------------------------

### GET /v1/wilayas

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

Returns the 58 wilayas couriers deliver to. Supports query parameters for filtering.

```APIDOC
## GET /v1/wilayas

### Description
Returns the 58 wilayas couriers deliver to. Supports query parameters for filtering.

### Method
GET

### Endpoint
/v1/wilayas

### Parameters
#### Query Parameters
- **?16** (integer) - Optional - Filter by wilaya code
- **?q=oran** (string) - Optional - Search by name
- **?all=1** (boolean) - Optional - Return all wilayas

### Response
#### Success Response (200)
- **wilayas** (array) - List of wilayas

#### Response Example
{
  "wilayas": []
}
```

--------------------------------

### GET /v1/communes

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

Returns all 1,541 communes. Supports query parameters for filtering.

```APIDOC
## GET /v1/communes

### Description
Returns all 1,541 communes. Supports query parameters for filtering.

### Method
GET

### Endpoint
/v1/communes

### Parameters
#### Query Parameters
- **?16** (integer) - Optional - Filter by wilaya code
- **?q=bab** (string) - Optional - Search by name

### Response
#### Success Response (200)
- **communes** (array) - List of communes

#### Response Example
{
  "communes": []
}
```

--------------------------------

### GET /v1/communes?60

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

Returns the communes that belong to a specific wilaya, using the spelling that couriers expect.

```APIDOC
## GET /v1/communes?60

### Description
Returns the communes that belong to a specific wilaya, using the spelling that couriers expect.

### Method
GET

### Endpoint
/v1/communes

### Parameters
#### Query Parameters
- **wilaya code** (integer) - Required - The wilaya code (e.g., 60) to get its communes.

### Response
#### Success Response (200)
- **communes** (array) - List of commune names.

#### Response Example
{
  "communes": [
    "Commune 1",
    "Commune 2"
  ]
}
```

--------------------------------

### Quote a fee with curl

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

POST to /v1/rates with courier credentials and query parameters. Returns deliveryFee, returnFee, total, and currency. Note returnFee for COD economics; query.toCommune refines pricing; query.tier accepts express (default) or economic.

```bash
$ 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" }
```

--------------------------------

### POST /v1/orders

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

Creates a shipment with any supported courier. The request includes the courier name, your credentials for that courier, and the order details. The parcel is created on your courier account.

```APIDOC
## POST /v1/orders

### Description
Creates a shipment with any supported courier. The request includes the courier name, your credentials for that courier, and the order details. The parcel is created on your courier account.

### Method
POST

### Endpoint
/v1/orders

### Parameters
#### Request Body
- **courier** (string) - Required - Supported courier: `yalidine`, `zrexpress`, `maystro`, `noest`, `ecotrack`
- **credentials** (object) - Required - Your courier account's API credentials
- **order.recipient.fullName** (string) - Required - 2-120 characters
- **order.recipient.phone** (string) - Required - Valid Algerian mobile (05/06/07...) else `422 invalid_phone`
- **order.recipient.wilayaCode** (integer) - Required - 1-58, see GET /v1/wilayas
- **order.recipient.communeName** (string) - Required - The courier's exact French spelling
- **order.deliveryType** (string) - Required - `home` or `stopdesk` (+ `stopDeskId` for Yalidine/NOEST desks)
- **order.productList** (array) - Required - Printed on the label; long lists truncated safely per courier
- **order.codAmount** (integer) - Required - Cash to collect, integer DZD. `0` = prepaid
- **options.fromWilaya** (integer) - Optional - Your origin wilaya (required for Yalidine)
- **order.reference** (string) - Optional - Your order id; omitted → generated (`FS-...`)
- **order.recipient.phoneAlt** (string) - Optional - Second phone
- **order.recipient.addressLine** (string) - Optional - Street address; optional for stop-desk
- **order.weightKg** (number) - Optional - Parcel weight
- **order.declaredValue** (number) - Optional - Enables insurance where supported (Yalidine)
- **order.freeShipping** (boolean) - Optional - Customer not charged shipping
- **order.isExchange** (boolean) - Optional - Exchange / swap parcel
- **order.hasOpenPackage** (boolean) - Optional - Customer may open before paying (NOEST)
- **order.notes** (string) - Optional - Remark for the driver
- **options.baseUrl** (string) - Optional - Ecotrack tenant URL, or a Yalidine-family network host
- **options.timeoutMs** (integer) - Optional - Upstream courier timeout

### Request Example
{
  "courier": "yalidine",
  "credentials": {},
  "order": {
    "recipient": {
      "fullName": "John Doe",
      "phone": "0551234567",
      "wilayaCode": 16,
      "communeName": "Alger Centre"
    },
    "deliveryType": "home",
    "productList": [],
    "codAmount": 0
  }
}

### Response
#### Success Response (200)
- **parcel** (object) - The created parcel details

#### Response Example
{
  "parcel": {}
}
```

--------------------------------

### POST /v1/orders

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

Creates a cash-on-delivery parcel with a specified courier. Supports real couriers like yalidine and a sandbox mode for testing without credentials.

```APIDOC
## POST /v1/orders

### Description
Creates a cash-on-delivery parcel with a specified courier. Supports real couriers like yalidine and a sandbox mode for testing without credentials.

### Method
POST

### Endpoint
https://freeship.dzbuild.com/v1/orders

### Parameters
#### Request Body
- **courier** (string) - Required - Courier key, e.g., "yalidine" or "sandbox".
- **credentials** (object) - Optional - Courier credentials, required for real couriers. Contains apiId and apiToken.
- **options** (object) - Optional - Additional options, e.g., fromWilaya.
- **order** (object) - Required - Order details.
  - **recipient** (object) - Required - Recipient information.
    - **fullName** (string) - Required - Recipient full name.
    - **phone** (string) - Required - Recipient phone number.
    - **wilayaCode** (number) - Required - Wilaya code.
    - **communeName** (string) - Required - Commune name.
  - **deliveryType** (string) - Required - Delivery type, e.g., "home".
  - **productList** (string) - Required - Product description.
  - **codAmount** (number) - Required - Cash on delivery amount.

### Request Example
{
  "courier": "yalidine",
  "credentials": { "apiId": "...", "apiToken": "..." },
  "options": { "fromWilaya": 16 },
  "order": {
    "recipient": {
      "fullName": "Amine Bouzid",
      "phone": "0551234567",
      "wilayaCode": 16,
      "communeName": "Bab Ezzouar"
    },
    "deliveryType": "home",
    "productList": "Sneakers Air x1",
    "codAmount": 4500
  }
}

### Response
#### Success Response (201)
- **trackingNumber** (string) - Tracking number assigned to the parcel.
- **status** (string) - Status of the parcel, e.g., "created".

#### Response Example
{
  "trackingNumber": "yal-ABC123",
  "status": "created"
}
```

--------------------------------

### POST /v1/rates

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

Returns the delivery and return fee for a route.

```APIDOC
## POST /v1/rates

### Description
Returns the delivery and return fee for a route.

### Method
POST

### Endpoint
/v1/rates

### Parameters
#### Request Body
- **fromWilaya** (integer) - Required - Origin wilaya code
- **toWilaya** (integer) - Required - Destination wilaya code
- **deliveryType** (string) - Required - `home` or `stopdesk`
- **weightKg** (number) - Optional - Parcel weight

### Request Example
{
  "fromWilaya": 16,
  "toWilaya": 31,
  "deliveryType": "home"
}

### Response
#### Success Response (200)
- **deliveryFee** (number) - Delivery fee
- **returnFee** (number) - Return fee

#### Response Example
{
  "deliveryFee": 500,
  "returnFee": 250
}
```

--------------------------------

### POST /v1/rates

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

Quotes delivery and return fees for a given courier and delivery query. Returns the delivery fee, return fee, total, and currency.

```APIDOC
## POST /v1/rates

### Description
Quotes delivery and return fees for a given courier and delivery query. Returns the delivery fee, return fee, total, and currency.

### Method
POST

### Endpoint
https://freeship.dzbuild.com/v1/rates

### Parameters
#### Request Body
- **courier** (string) - Required - The courier identifier (e.g., "yalidine").
- **credentials** (object) - Required - Courier-specific credentials.
  - **apiId** (string) - Required - API ID for the courier.
  - **apiToken** (string) - Required - API token for the courier.
- **query** (object) - Required - Delivery query parameters.
  - **fromWilaya** (integer) - Required - Origin wilaya code.
  - **toWilaya** (integer) - Required - Destination wilaya code.
  - **deliveryType** (string) - Required - Type of delivery (e.g., "home").
  - **toCommune** (string) - Optional - Refines per-commune pricing.
  - **tier** (string) - Optional - Service tier: "express" (default) or "economic".

### Request Example
{
  "courier": "yalidine",
  "credentials": { "apiId": "…", "apiToken": "…" },
  "query": { "fromWilaya": 16, "toWilaya": 31, "deliveryType": "home" }
}

### Response
#### Success Response (200)
- **deliveryFee** (number) - The delivery fee.
- **returnFee** (number) - The return fee.
- **total** (number) - The total fee.
- **currency** (string) - The currency code (e.g., "DZD").

#### Response Example
{
  "deliveryFee": 600,
  "returnFee": 250,
  "total": 600,
  "currency": "DZD"
}
```

--------------------------------

### Track a parcel with curl

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

POST to /v1/track with courier credentials and tracking number. Returns 200 with status and events; rawStatus carries the courier's original wording.

```bash
$ 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" }
  ]
}
```

--------------------------------

### POST /v1/rates

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

Quotes fees for shipping with supported couriers. The endpoint is listed in the API overview but no detailed parameters or response schema are provided in the source.

```APIDOC
## POST /v1/rates

### Description
Quotes fees for shipping with supported couriers. The endpoint is listed in the API overview but no detailed parameters or response schema are provided in the source.

### Method
POST

### Endpoint
https://freeship.dzbuild.com/v1/rates
```

--------------------------------

### POST /v1/track

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

Returns the current status and full event history for a tracking number.

```APIDOC
## POST /v1/track

### Description
Returns the current status and full event history for a tracking number.

### Method
POST

### Endpoint
/v1/track

### Parameters
#### Request Body
- **trackingNumber** (string) - Required - The tracking number to look up

### Request Example
{
  "trackingNumber": "FS-12345"
}

### Response
#### Success Response (200)
- **status** (string) - Current status
- **events** (array) - Full event history

#### Response Example
{
  "status": "in_transit",
  "events": []
}
```

--------------------------------

### POST /v1/track

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

Tracks a parcel using the specified courier and tracking number. Returns the current status and a list of events, with rawStatus preserving the courier's original wording.

```APIDOC
## POST /v1/track

### Description
Tracks a parcel using the specified courier and tracking number. Returns the current status and a list of events, with rawStatus preserving the courier's original wording.

### Method
POST

### Endpoint
https://freeship.dzbuild.com/v1/track

### Parameters
#### Request Body
- **courier** (string) - Required - The courier identifier (e.g., "yalidine").
- **credentials** (object) - Required - Courier-specific credentials.
  - **apiId** (string) - Required - API ID for the courier.
  - **apiToken** (string) - Required - API token for the courier.
- **trackingNumber** (string) - Required - The tracking number of the parcel.

### Request Example
{
  "courier": "yalidine",
  "credentials": { "apiId": "…", "apiToken": "…" },
  "trackingNumber": "yal-ABC123"
}

### Response
#### Success Response (200)
- **status** (string) - The normalized status (e.g., "out_for_delivery").
- **events** (array) - List of tracking events.
  - **status** (string) - Normalized status of the event.
  - **rawStatus** (string) - Original status text from the courier.
  - **timestamp** (string) - ISO 8601 timestamp of the event.

#### Response Example
{
  "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" }
  ]
}
```

--------------------------------

### POST /v1/track

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

Tracks a parcel using its tracking number. The endpoint is listed in the API overview but no detailed parameters or response schema are provided in the source.

```APIDOC
## POST /v1/track

### Description
Tracks a parcel using its tracking number. The endpoint is listed in the API overview but no detailed parameters or response schema are provided in the source.

### Method
POST

### Endpoint
https://freeship.dzbuild.com/v1/track
```

--------------------------------

### Error Envelope

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

All errors follow a single envelope structure with an error object containing code, message, and optional fields.

```APIDOC
## Error Envelope

### Description
All errors follow a single envelope structure with an error object containing code, message, and optional fields.

### Error Response Format
{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {}
  }
}

### Error Codes
- **400** - `VALIDATION_ERROR` - Fix the fields listed in `error.fields`.
- **422** - `invalid_phone` - Not a valid Algerian mobile — correct the number.
- **422 / 502** - `NOT_SUPPORTED` / `COURIER_ERROR` - The courier rejected it — read `message` (bad credentials, unknown commune, missing stop desk…).
- **400** - `EGRESS_BLOCKED` - `options.baseUrl` is not one of that courier's own addresses — check the host, or use the courier's own key.
- **429** - `rate_limited` - Wait `Retry-After` seconds, then retry.
- **503** - `overloaded` - Momentary capacity protection — retry shortly.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.