# Yalidine

Yalidine is a widely used national courier in Algeria with a stable API. The wilayas, communes and desks you can ship to come from Yalidine's own API: DZBuild syncs what Yalidine returns and never adds coverage of its own. The same DZBuild integration also powers **Yalitec**, **Guepex**, **Easy & Speed**, **Economiqua** and **We Can Services**, which share Yalidine's API structure under their own dashboards.

## What you need

You only need two values from your Yalidine merchant dashboard:

* **API ID**
* **API Token**

Both are issued from your Yalidine account; if you don't see them, ask Yalidine to enable API access for your account. Yalidine API access usually requires a verified business account.

## Linking Yalidine in DZBuild

1. Open **[`/dashboard/link-shipping`](https://dzbuild.com/dashboard/link-shipping)** in your dashboard and search "Yalidine" in the tile grid (or Yalitec / Guepex / Easy & Speed / Economiqua / We Can Services if that's your reseller).
2. Click **Lier / ربط** on the tile.
3. Paste your **API ID** in the first field.
4. Paste your **API Token** in the second field.
5. Click **Tester la connexion** (« اختبار الاتصال »). The dashboard hits Yalidine live and shows a green check if the credentials are valid.
6. Click **Lier et enregistrer** (« ربط وحفظ »). Tick **Définir comme transporteur par défaut** if Yalidine should be the store's default.

Rates live on the separate page **[`/dashboard/shipping`](https://dzbuild.com/dashboard/shipping)**. From there you can:

* **Sync rates from provider** — pulls Yalidine's home + desk fees per wilaya.
* Override any wilaya's rate manually if you want to absorb part of the shipping or charge a markup.

Set your store's wilaya first

Rate syncing for the Yalidine family (Yalidine, Yalitec, Guepex, Easy & Speed, Economiqua, We Can Services) needs your store's own wilaya. If it isn't set in your store settings, the sync fails with « يرجى تحديد ولاية المتجر أولاً من إعدادات المتجر قبل مزامنة الأسعار. ». The same wilaya is sent as `from_wilaya_name` on every parcel, and defaults to Alger when unset.

## Express vs Économique (Guepex only)

The credential modal shows a delivery-tier selector, **Express** or **Économique**, for **Guepex only**. Yalidine, Yalitec, Easy & Speed, Economiqua and We Can Services always ship Express: DZBuild never sends them the `economic` parameter, which Yalidine's API rejects outright.

The tier you pick is used for the parcel you send and for the rates DZBuild pulls when you click **Sync rates from provider**, so after switching it, sync rates again to update what your customer is charged. Économique applies only where your Guepex account offers it; elsewhere the Express rate is used.

## What gets synced

* Full list of **wilayas** and **communes**. Commune names are taken primarily from the synced provider commune list (Yalidine's own spelling), with DZBuild's own built-in commune list as a fallback. A commune that doesn't belong to the wilaya on the order makes the send fail (« البلدية المحددة لا تنتمي إلى الولاية المختارة ») rather than being auto-corrected.
* Per-wilaya **home delivery rate**.
* Per-wilaya **stop-desk rate**.
* The list of **stop-desks** in each wilaya, used by the [stop-desk picker](https://dzbuild.com/docs/couriers/stop-desk.md).

## Product dimensions

The product form shows **length / width / height** fields only when a Yalidine-family courier is linked — no other family accepts dimensions. If you leave them empty, the parcel goes out as 10 × 10 × 10 cm and 0.5 kg.

## What happens when an order ships

When you send an order to delivery from [`/dashboard/orders`](https://dzbuild.com/dashboard/orders) and pick Yalidine in the send-to-delivery modal, DZBuild creates the parcel in Yalidine with:

* Customer first name, family name, phone (auto-formatted to the local `0X` shape). Only **one** phone number reaches Yalidine, because a DZBuild order carries a single customer phone.
* Address, destination wilaya, destination commune (resolved to the French name).
* Origin wilaya (your store's wilaya — used as `from_wilaya_name`).
* Product list summary.
* COD amount (`price` = subtotal, the customer pays this on delivery).
* Declared value, length, width, height, weight.
* `is_stopdesk` flag, plus a valid `stopdesk_id` when desk delivery is selected.
* `freeshipping`, `do_insurance`, and exchange flags when applicable.

Yalidine returns:

* A **tracking number** (saved on the order).
* A **label URL** (PDF), captured and stored on the order.

Printing the Yalidine label

No button in the DZBuild dashboard opens Yalidine's label URL. Clicking **Print label** on a Yalidine order prints DZBuild's own HTML bordereau — print Yalidine's official label from the Yalidine portal.

The order moves to **`processing`** on send (and only if it was `pending` or `confirmed`), and the customer sees the tracking on their order page. It becomes `shipped` when the automatic tracking sync sees a Yalidine transit status such as « Ramassé », « Expédié » or « En cours de livraison », then `delivered` (or `returned` / `cancelled`).

### Product list truncation

Long multi-item orders get their product list shortened to fit Yalidine's **150-character** limit. DZBuild degrades in steps: the full `a | b | c` list, then the same list with variant suffixes in parentheses stripped, then the first few items plus `+N`, and finally the first product name cut short plus `+N`. The **Custom Delivery Label** addon (Pro) lets you control what is written there.

## Stop desk with Yalidine

The desks you can offer are the Yalidine desks DZBuild has synced from Yalidine's API, refreshed overnight or right away with **Actualiser** on the Yalidine tile. When the customer chooses desk delivery at checkout:

* The [Stop Desk addon](https://dzbuild.com/docs/couriers/stop-desk.md) shows desks for the selected wilaya with name, address and phone.
* The order stores DZBuild's own `desk_id` / `desk_name`. Yalidine's `stopdesk_id` is resolved at send time: the desk the customer picked, else any desk in their commune, else any desk in the wilaya. The commune sent with the parcel is then forced to the desk's own commune, so the id and the commune always agree.
* The send is **refused — never downgraded to home delivery** — only when the whole wilaya has no Yalidine desk. DZBuild can refuse it even before contacting Yalidine, using the desk data it has already synced.

## Common errors and fixes

| Message                                                                                    | Cause                                                                                | Fix                                                                                                                       |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `Invalid credentials` (on **Tester la connexion**) / `بيانات الاعتماد غير صحيحة` (on send) | Yalidine rejected the API ID or API Token                                            | Re-copy both values from Yalidine's dashboard. The two fields are easy to swap. Confirm the account still has API access. |
| `بيانات API لشركة التوصيل غير صالحة أو منتهية الصلاحية، الإرسال متوقف`                     | Yalidine kept refusing the saved keys, so sending and automatic tracking stop for it | Paste fresh keys on the Yalidine tile and click **Enregistrer les modifications**.                                        |
| `حسابك لدى شركة التوصيل معطّل ولا يمكنه إنشاء طرود جديدة`                                  | Yalidine disabled your account                                                       | Contact Yalidine to reactivate it, then re-send.                                                                          |
| `تتجاوز الحد الأقصى المسموح به لدى شركة التوصيل (150000 دج)`                               | The order subtotal is above Yalidine's 150,000 DA cap                                | Split the order into two parcels, or send it with another courier.                                                        |
| `Create Order failed:` followed by Yalidine's own words                                    | Yalidine refused the parcel                                                          | Fix what the message names, then re-send.                                                                                 |
| `لا يوجد مكتب استلام (Stop Desk) متاح`                                                     | The whole wilaya has no Yalidine desk                                                | Refresh provider data from the tile, or switch the order to home delivery.                                                |
| `البلدية المحددة لا تنتمي إلى الولاية المختارة`                                            | Commune / wilaya mismatch on the order                                               | Fix the commune on the order, then re-send.                                                                               |
| Order created but no tracking returned                                                     | Address or commune not recognized                                                    | Check the commune spelling on the order, then re-send.                                                                    |

## Tips

* Yalidine expects communes in **French**. DZBuild matches against Yalidine's own synced commune list first and falls back to its built-in commune list, but uncommon spellings can still fail — keep your store's commune list clean, and click **Actualiser** on the Yalidine tile if the synced list looks stale.
* The `price` sent to Yalidine is the **subtotal** (product price), not the order total with shipping. This is what the courier collects on COD.
* If you also have a Yalitec, Guepex, Easy & Speed, Economiqua or We Can Services account, link it under its own slug. The API shape is the same but credentials are not interchangeable.