A shop app or a backend that ships parcels in Algeria has the same few jobs to do with a delivery company: create parcels, quote the delivery fee for a wilaya, get a label, and follow each parcel until the cash on delivery is collected. Each delivery company has its own API, its own field names and its own list of status strings.
So the integration code is written once per company, and each one leaks into the rest of the app: a different JSON shape for the parcel, a different way to say "out for delivery", a different error when the phone number is wrong.
dz_delivery is a Dart package that puts those APIs behind one typed interface, DeliveryProvider, usable from a Flutter app or a Dart backend.
There is a caveat, and the README puts it at the top: the package is unverified against the live API. Every client in it was built from the provider's public API documentation, not from live traffic, because no API keys were available. If a call does not behave as described, the README asks you to report the mismatch as an issue.
What it does
One interface. DeliveryProvider has createParcels (batched where the provider allows it), getParcel, listParcels with filter and pagination, trackingHistory, deleteParcel, cancelParcel, deliveryFees, wilayas, communes, stopDesks and labelUrl. A capabilities object tells you what each provider supports, and anything unsupported throws DeliveryUnsupportedException.
Provider-neutral models. ParcelRequest carries the recipient, phones, address, wilaya code, commune, product description, COD amount in whole DZD, declared value, stop desk, free shipping, exchange, weight, dimensions, order id and notes. On the way back you get Parcel, TrackingEvent, DeliveryFee, Wilaya, Commune, StopDesk and ParcelBatchResult. A batch can partly succeed, so the result lists both the created and the failed parcels.
One status enum. ParcelStatus is the same for every provider. Each provider maps the raw status strings its documentation lists. The raw string is kept in rawStatus, and anything undocumented maps to ParcelStatus.unknown.
Typed errors. DeliveryAuthException (401/403), DeliveryValidationException (with fieldErrors), DeliveryRateLimitException (with retryAfter from the Retry-After header), DeliveryNotFoundException, DeliveryServerException, DeliveryNetworkException and DeliveryHttpException. They all extend the sealed DeliveryException.
Checks before any request. Algerian phone numbers (0550…, +213…, 00213…, Arabic-Indic digits), wilaya codes 1 to 69, and required fields. Invalid batches are rejected before anything is sent.
Rate limiting. An optional RateLimiter with per-second, per-minute, per-hour and per-day sliding windows, shared by all requests of a provider. It also pauses when the server answers 429 with Retry-After, and maxRetries retries 429 responses.
Injectable HTTP and raw clients. You can pass any package:http Client, for example a MockClient in tests. Every provider also exposes its provider-specific client, which returns the decoded JSON for fields the common model does not cover, plus a send() escape hatch.
Which providers
Today, one: ZR Express, through ZrExpressProvider. It targets the ZR Express Suppliers Services API at https://api.zrexpress.app/api/v1/, and authenticates with the X-Api-Key and X-Tenant headers. It was built from the public docs at docs.zrexpress.app as read on 2026-09-25.
The rule of the package is to implement only what a provider documents publicly. That is why the others are listed as not included, each with the reason:
- Yalidine and Guepex. The API documentation is behind the merchant login. Third-party reconstructions exist, but they are not the provider's documentation, so no endpoint was taken from them.
- Ecotrack couriers (DHD, Conexlog, World Express and others). No public API documentation was found. It is reached from each courier's dashboard.
- ZR Express legacy API (Procolis). Its developer page was not reachable and has no archived copy. The current ZR Express API replaces it.
- Maystro Delivery. API access is by request. No public reference exists.
- Noest. No public API reference was found.
If you have a public link to any of these docs, the README asks you to open an issue. Adding a provider means implementing DeliveryProvider.
How to use it
Add it from GitHub:
dependencies:
dz_delivery:
git: https://github.com/AbdeldjalilChougui/dz_delivery
Then, from the README:
import 'package:dz_delivery/dz_delivery.dart';
Future<void> main() async {
final DeliveryProvider zr = ZrExpressProvider(
apiKey: 'YOUR-API-KEY',
tenantId: 'YOUR-TENANT-ID',
rateLimiter: RateLimiter.windows(perSecond: 5), // optional
maxRetries: 2, // retry 429 responses after Retry-After
);
try {
final fee = await zr.deliveryFees(16, 31, stopDesk: true);
print('Stop desk in Oran: ${fee.amount} DZD');
final result = await zr.createParcels([
const ParcelRequest(
recipientName: 'Amine Bouzid',
phones: ['0551 23 45 67'],
address: '12 rue Larbi Ben Mhidi',
wilayaCode: 31,
commune: 'Oran',
productDescription: 'Sneakers 42',
codAmount: 4500, // ZR Express: total collected, delivery fee included
orderId: 'ORD-1001',
),
]);
for (final f in result.failed) {
print('#${f.index} rejected: ${f.code} ${f.message}');
}
for (final c in result.created) {
final parcel = await zr.getParcel(c.tracking);
print('${parcel.tracking}: ${parcel.status} (${parcel.rawStatus})');
}
} on DeliveryValidationException catch (e) {
print(e.fieldErrors.join('\n'));
} on DeliveryRateLimitException catch (e) {
print('Retry after ${e.retryAfter}');
} on DeliveryException catch (e) {
print(e);
} finally {
zr.close();
}
}
For fields the common model does not cover, use the raw client:
final raw = await zr.api.getParcel('16-IB3HI9-ZR');
print(raw['situation']); // ZR Express "situation" (sub-status)
final profile = await zr.api.send('GET', 'users/profile');
In tests, pass httpClient: MockClient(...) to the provider and no request leaves your machine.
ZR Express details worth reading
The README maps every ParcelRequest field to its ZR Express field, and every documented state name to a ParcelStatus (commande_recue is created, vers_wilaya is inTransit, livre is delivered, encaisse is codCollected, and so on). A few notes from the provider's docs affect your code:
- Parcels created without a
stateIdstart as "OrderReceived" and must be moved to "ReadyToDispatch" before a hub accepts them. PassinitialStateIdto create them ready to dispatch. -
createParcelsuses the bulk endpoint, with at most 100 parcels per request. The client splits larger batches automatically. -
cancelParcelis not supported by ZR Express. Delete the parcel before pickup instead. -
codAmountis sent asamount, which the docs describe as at most 150,000 DZD, delivery fee included.freeShipping,declaredValueandnoteshave no field and are not sent.exchange: trueis rejected, because exchanges are a separate ZR Express operation. - Delivery prices depend only on the destination, so
deliveryFeesignoresfromWilaya. - The state-history endpoint is rate limited, and the docs recommend webhooks instead of polling.
Things to know
- Nothing here has run against a live server. Request and response shapes follow the public documentation as of 2026-09-25. The README also notes places where that documentation is inconsistent with itself, and says which version the client follows.
- Only ZR Express is included.
-
Not wrapped for ZR Express: exchanges, refunds, pickup bags, products, claims, webhooks and treasury. Reach them with
api.send. -
Status mapping covers only the state names shown in the docs. ZR Express workflows can be configured per tenant, so other names come back as
ParcelStatus.unknownwithrawStatusset. - Amounts are converted to whole dinars with
round(). - Phone validation checks the shape only (mobile 5/6/7 plus 8 digits, landline 2/3/4 plus 7 digits). It does not check operator block allocations.
- Wilaya codes 1 to 69 are accepted. Whether a provider serves a given code is up to the provider.
- Test data. The fixtures are response examples copied verbatim from the ZR Express documentation, each citing its page, plus a few constructed responses that are labelled as constructed.
Why I built it
The problem is the one in the first lines of the README: creating parcels, quoting fees and tracking shipments should look the same in your code whichever delivery company carries the parcel. One ParcelRequest, one ParcelStatus, one family of exceptions, and the provider differences kept inside the provider class.
I also wanted the package to be straight about what it knows. It implements only what a provider documents publicly, it says which date the docs were read, and it lists the providers it could not include and why, instead of guessing endpoints from third-party code.
Get the code
The source, the endpoint and field mapping tables, and the tests are on GitHub: https://github.com/AbdeldjalilChougui/dz_delivery. It is MIT licensed. If you have API keys and something does not match, an issue with the mismatch is the most useful contribution.
Originally published at abdeldjalilchougui.biz.
Top comments (0)