# Quickstart: your first parcel through the dzship API

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

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

You need nothing installed and no account. The first request below works as written.

## 1. Create a sandbox parcel

The `sandbox` courier takes no credentials. It checks the request the way a real courier does,
answers like one, and creates nothing.

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

```json
{ "trackingNumber": "DZTEST-1A2B3C", "status": "created", "reference": "FS-…" }
```

Send a phone that is not an Algerian mobile, or a commune that does not exist in the wilaya,
and you get the same error a real courier would cause. That makes the sandbox a good place to
test your validation before any credentials exist.

## 2. Ship with a real courier

Name the courier and add its credentials. For Yalidine that is `apiId` and `apiToken` from the
Yalidine dashboard, plus the wilaya you ship from.

```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": {
      "reference": "ORD-1042",
      "recipient": {
        "fullName": "Amine Bouzid",
        "phone": "0551234567",
        "wilayaCode": 16,
        "communeName": "Bab Ezzouar"
      },
      "deliveryType": "home",
      "productList": "Sneakers Air x1",
      "codAmount": 4500
    }
  }'
```

```json
{ "trackingNumber": "yal-ABC123", "status": "created", "reference": "ORD-1042" }
```

The parcel now exists on your Yalidine account. [Couriers](https://freeship.dzbuild.com/docs/couriers.md) lists the key and
the credentials of every other courier.

> **Creating is never retried**
> A repeated create is a second parcel. Send your own `order.reference` and check it before you
> resend a request that timed out.

## 3. Track it

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

The answer carries one of fourteen statuses, the same for every courier, and the courier's own
wording in `rawStatus`. [Statuses](https://freeship.dzbuild.com/docs/statuses.md) has the full list with French and Arabic
labels.

## 4. Quote the fee

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

```json
{ "deliveryFee": 600, "returnFee": 250, "total": 600, "currency": "DZD" }
```

## Use a client instead of raw HTTP

```bash
npm install dzship
```

```js title="ship.mjs"
import dzship from 'dzship';

const client = dzship({
  courier: 'yalidine',
  credentials: { apiId: process.env.YAL_ID, apiToken: process.env.YAL_TOKEN },
  options: { fromWilaya: 16 },
});

const { trackingNumber } = await client.createOrder({
  recipient: {
    fullName: 'Amine Bouzid',
    phone: '0551234567',
    wilayaCode: 16,
    communeName: 'Bab Ezzouar',
  },
  deliveryType: 'home',
  productList: 'Sneakers Air x1',
  codAmount: 4500,
});

const { status, events } = await client.track(trackingNumber);
```

PHP, Python and Ruby have a single-file client each. [Integrating](https://freeship.dzbuild.com/docs/integrating.md) covers
them, along with Laravel, WooCommerce, Django, Rails and Google Sheets.

## Next

- [Endpoints](https://freeship.dzbuild.com/docs/endpoints.md): every field, every error code and the rate limits.
- [Stop desks](https://freeship.dzbuild.com/docs/endpoints.md#post-v1desks): let the customer pick where to collect the parcel.
- [Wilayas and communes](https://freeship.dzbuild.com/docs/wilayas-and-communes.md): the spellings couriers accept.