# EcoTrack

EcoTrack is a shared shipping API that powers a large family of Algerian couriers. There is no "EcoTrack" tile to pick: you pick **your own courier's tile**, and DZBuild talks to it over the EcoTrack API with a single bearer token. 82 couriers have their own tile:

DHD, Conexlog, MSM Go, Rex Livraison, RB Livraison, Speed Delivery, Areex, Prest, Rocket Delivery, WorldExpress, BA Consult, Packers, 48Hr Livraison, Mono Hub, Anderson Delivery, GOLIVRI, Coyote Express, Salva Delivery, Distazero, FRET.Direct, TSL Express, Negmar Express, Ultra Express, OM Express, Med Express, Allo Livraison, Assil Delivery, Expedia Chrono, HHD Express, Imir Logistics, Navex Delivery, Swift Express, Univer Delivery, Colireli, FZ Delivery, Delivromail, PDEX, SI Express, Colex, OKS Box, Majorex, Chronorex, Samex, Aranex, Amana Speed, Wassim Express, One Express, AB Delivery, Royaume Delivery, Eco Rapide Express, SBL Express, Wee Wee Delivery, Jaguar Livraison, RJ 360 Express, Lynx Express, RM Express, Rihal Express, Atlas Express, Boogi Technologie, Cirta Express, Colizone, GS Ecommerce, Jo Express, On Time Express, Quick Delivery DZ, RS Express, Ruta Express, Tawsil Star, Vitrans, BFK Express, Alania Express, Champion Logistics, El Guide Delivery, Fast Horse Express, LIH LIH Express, Mazaya Logistics, Ovred, Speed Mail, Win Delivery, Zinya Tec, Sultan Colis Express, Red Ex.

If your courier is on this list, pick its tile — there is no need for a custom integration.

Two of them do not sit on `*.ecotrack.dz` hosts but are EcoTrack tenants all the same: **DHD** (`platform.dhd-dz.com`) and **Conexlog** (`app.conexlog-dz.com`). Neither is a separate direct integration.

## What you need

A single value from your courier's EcoTrack-powered dashboard:

* **API token** (sometimes called "Bearer token", "API key" or "clé API").

Some EcoTrack-based dashboards split it across two screens (account → API → generate). If you can't find it, ask your account manager to enable API access.

## Linking an EcoTrack courier in DZBuild

1. Open **[`/dashboard/link-shipping`](https://dzbuild.com/dashboard/link-shipping)** and search your courier's name in the tile grid (e.g. **DHD**, **Conexlog**, **MSM Go**, …).
2. Click **Lier / ربط** on its tile.
3. Paste your **API token** into the single credential field, labelled **Bearer Token**. EcoTrack-based providers use one field only.
4. Click **Tester la connexion** (« اختبار الاتصال »). The dashboard hits the courier live and confirms the token is valid.
5. Click **Lier et enregistrer** (« ربط وحفظ »).

Per-wilaya prices are edited on the separate page [`/dashboard/shipping`](https://dzbuild.com/dashboard/shipping).

### Custom EcoTrack

If your courier is **not** in the tile grid but is built on EcoTrack, pick **Ecotrack personnalisé** (« Ecotrack مخصص ») and provide:

* The **API URL** of your courier's EcoTrack instance — the base host only, e.g. `https://yourcourier.ecotrack.dz`. DZBuild appends `/api/v1` itself.
* A **display name** (field **Nom du transporteur**, « اسم الشركة »), up to 100 characters. Whatever you type is what appears throughout the dashboard for that courier.
* The bearer token.

The URL must start with `https://` and point at an EcoTrack host: an address ending in `.ecotrack.dz`, or the DHD and Conexlog hosts above. Any other domain is refused with « رابط API غير مسموح », and internal, loopback and reserved addresses are refused for security. Each custom URL keeps its own synced commune, desk and rate knowledge, so switching the URL starts a fresh sync. Prefer a native tile whenever one exists for your courier.

## What gets synced

* The list of **wilayas** and **communes** the courier serves.
* **Home delivery rates** per wilaya.
* **Stop-desk rates** per wilaya.
* Which **communes have a stop desk**. EcoTrack publishes no named desk list, so the [Stop Desk picker](https://dzbuild.com/docs/couriers/stop-desk.md) offers one entry per desk commune, shown as the courier name and the commune.

## What happens when an order ships

When you send an order to an EcoTrack courier (the **Envoyer à** « إرسال إلى » button on the order, or a bulk send), DZBuild posts the parcel to the courier's EcoTrack endpoint with:

* `nom_client`, `telephone` and `adresse`. `telephone_2` stays empty, because a DZBuild order holds a single customer phone.
* `code_wilaya` + `commune`.
* `montant`: the **order total** (products plus shipping, minus discount), i.e. what the customer pays on delivery. Every courier family has its own field name and its own amount, so read the per-family table in the [couriers overview](https://dzbuild.com/docs/couriers/overview.md) rather than assuming this one applies elsewhere. Yalidine is the family that sends the subtotal instead, because it bills the delivery fee separately.
* `produit` (the item summary), `remarque` (your note), `weight`, and `reference` (your DZBuild order number).
* `type` — 1 for a delivery, 2 for an exchange.
* `stop_desk` — 0 or 1. There is **no** `delivery_type` field and **no** `stopdesk_id`: a desk parcel is expressed by sending the *desk's commune* as `commune` while `stop_desk = 1`.
* `fragile = 1`, only when the product is flagged fragile.

The courier returns a **tracking number**.

### Fragile flag

Marking a product **Fragile** adds `fragile = 1` to EcoTrack parcels. Outside the EcoTrack family, only MDM Express also receives a fragile flag; no other courier gets one (Yalidine's API rejects unknown parameters outright).

### Product description limit

The item summary sent to EcoTrack is capped at **255 characters**. A long multi-item order is shortened in steps: the full list, then the same list with variant suffixes in parentheses stripped, then the first few items plus `+N`, and finally the first item's name cut short, followed by `+N` when the order has other items.

## Printing the courier's own bordereau

EcoTrack is one of only two families (the other is Elogistia) whose **own PDF bordereau** prints straight from DZBuild. Clicking **Print label** on an EcoTrack order downloads the courier's official label as a PDF — Custom EcoTrack instances included, using the API URL you stored.

EcoTrack orders also get an EcoTrack-only **Expédier** (« تأكيد الشحن ») button on the order detail panel, to confirm the shipment with the courier.

## Common errors and fixes

| Symptom                                                                                                                                          | Likely cause                                              | Fix                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The connection test fails with "Invalid or expired API credentials"                                                                              | Wrong or expired token                                    | Regenerate the token in the courier's dashboard and paste it again.                                                                                                                                                     |
| « يرجى إدخال رابط API » (Custom EcoTrack)                                                                                                        | The API URL field is empty                                | Paste your courier's base host.                                                                                                                                                                                         |
| « يرجى إدخال رابط صحيح يبدأ بـ https\:// » (Custom EcoTrack)                                                                                     | The URL isn't `https://`                                  | Re-enter it with the `https://` scheme.                                                                                                                                                                                 |
| « يرجى إدخال رابط عام صحيح (لا يُسمح بعناوين داخلية) » (Custom EcoTrack)                                                                         | The URL points at a private, loopback or reserved address | Use the courier's public hostname. A public domain outside EcoTrack is refused with « رابط API غير مسموح »; a wrong address on an EcoTrack host shows up as a failed connection test coming from the courier's own API. |
| Order created but no tracking number                                                                                                             | Address rejected by courier                               | Check the address on the order; usually a missing or unrecognized commune.                                                                                                                                              |
| « مكتب الاستلام (Stop Desk) غير متوفر في هذه الولاية لشركة التوصيل المختارة » or « لا يوجد مكتب استلام (Stop Desk) متاح في هذه الولاية لشركة … » | No desk anywhere in that wilaya                           | Switch the order to home delivery, or click **Actualiser** on the tile if you think the desk data is stale.                                                                                                             |

## Stop-desk routing

An EcoTrack desk shipment is **never** downgraded to home delivery. If the customer's commune has no desk, DZBuild reroutes the parcel to another desk commune in the same wilaya, keeps the desk flag on, and writes the redirect into the parcel remark (« مكتب الاستلام: X (بلدية الزبون: Y) »). Only when the wilaya has no desk at all does the send fail, with a message telling you to switch to home delivery.

## Tips

* Many EcoTrack-based couriers have **regional** strengths (a specific wilaya cluster). Ask your account manager where they're fastest before promising next-day delivery.
* If you change couriers but stay inside EcoTrack, you only need to link the new courier's tile with its token — orders, addresses and customer data are unaffected.
* Use **Ecotrack personnalisé** for new couriers that haven't shown up in the DZBuild dashboard yet; it works as long as the courier's API sits on an EcoTrack host (an address ending in `.ecotrack.dz`) and exposes the standard EcoTrack endpoints.