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.
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.
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
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
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 dzshipimport 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
- Endpoints: every field, every error code and the rate limits.
- Stop desks: let the customer pick where to collect the parcel.
- Wilayas and communes: the spellings couriers accept.
Last updated on
Introduction
dzship is a free HTTP API that creates, tracks and prices cash-on-delivery parcels with 99 Algerian couriers. No signup and no API key.
Integrating
Ready-made dzship clients for Node.js, PHP, Python and Ruby, plus snippets for Laravel, WooCommerce, Django, Rails, Google Sheets and raw HTTP.