Skip to Content
dzshipBY DZBUILD

Quickstart: your first parcel through the dzship API

Send a sandbox parcel to the dzship API with one request, switch to a real Algerian courier, then track the parcel and quote its delivery fee.

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.

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
    }
  }'
{ "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.

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
    }
  }'
{ "trackingNumber": "yal-ABC123", "status": "created", "reference": "ORD-1042" }

The parcel now exists on your Yalidine account. Couriers 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

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 has the full list with French and Arabic labels.

4. Quote the fee

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" }
  }'
{ "deliveryFee": 600, "returnFee": 250, "total": 600, "currency": "DZD" }

Use a client instead of raw HTTP

npm install dzship
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 covers them, along with Laravel, WooCommerce, Django, Rails and Google Sheets.

Next

Last updated on

On this page