Integrating Yalidine with Your Website: API Technical Guide

Integrating Yalidine with your site means calling its REST API from your server to create a shipment, then regularly polling the parcel's status — there is no automatic notification. This guide covers authentication, parcel creation, tracking, and the API's real limits, with no middleman.

Before you start

Three prerequisites, in order:

1. An active Yalidine merchant account. API access is not open to the public; it requires an already-validated professional account.
2. API credentials. Generated from the dashboard's developer section, on yalidine.app. Two values to retrieve: an API ID and an API Token.
3. A server capable of calling the API. The API blocks cross-origin (CORS) requests: you cannot call api.yalidine.app directly from the browser's JavaScript. Every call must come from your backend, never from the client — which also avoids exposing your Token in the store's public source code.

No test (sandbox) environment is documented. Your first calls create real shipments: validate your integration with a real, low-value parcel before wiring up the full order flow.

Authentication

The API is REST, JSON responses, base URL https://api.yalidine.app/v1/. Every request must carry two HTTP headers:

X-API-ID: your_api_id
X-API-TOKEN: your_api_token
Content-Type: application/json

Without these two headers, the API responds 401 Unauthorized with an explicit message (API ID and/or Token must be specified). Store these two values like any environment secret — never in a versioned file or sent to the browser.

Creating a shipment

Parcel creation happens via POST /v1/parcels, with an array of objects — the API accepts bulk creation in a single call. The fields that matter for a first shipment:

Field	Role
order_id	Your own order reference, to link back to your database
firstname, familyname, contact_phone	Recipient's contact details
to_wilaya_name, to_commune_name, address	Delivery address
from_wilaya_name	Shipping wilaya (your warehouse)
price	Amount to collect on delivery, in DZD (0 to 150,000)
is_stopdesk + stopdesk_id	Pickup-point delivery rather than home delivery; the pickup point ID comes from the /centers endpoint
freeshipping	Indicates whether shipping fees are charged to the customer or absorbed by you
weight, length, width, height	Parcel dimensions, used for pricing

The response returns a tracking code (tracking, e.g. yal-12345A) to keep for the next step. to_wilaya_name and to_commune_name must exactly match the labels returned by the reference endpoints below — a typo in the commune name causes creation to fail.

In practice, a creation call looks like this:

POST https://api.yalidine.app/v1/parcels/
X-API-ID: your_api_id
X-API-TOKEN: your_api_token
Content-Type: application/json

[
  {
    "order_id": "CMD-4821",
    "from_wilaya_name": "Alger",
    "firstname": "Karim",
    "familyname": "B.",
    "contact_phone": "0555xxxxxx",
    "to_wilaya_name": "Oran",
    "to_commune_name": "Es Senia",
    "address": "Cité 500 logements, bloc B",
    "product_list": "1x Phone case",
    "price": 2500,
    "is_stopdesk": false,
    "freeshipping": false,
    "weight": 1
  }
]

If a required field is missing or a commune label matches nothing in the reference data, the API responds with an error code and an explicit message rather than creating a badly addressed parcel — handle this response in your code rather than assuming the call succeeded. At a volume of several dozen orders a day, systematically validating wilaya/commune names before the API call (against cached lists) avoids most of these rejections.

Tracking a parcel's status

No webhook on Yalidine's side: your server must poll the API, not the other way around. Tracking is done via the status history (GET /v1/histories/), filterable by parcel.

The statuses observed on the carrier's side, in normal lifecycle order:

1. Not yet shipped
2. Picked up
3. Shipped
4. Out for delivery
5. Delivered (or: Delivery failed, Returned to sender)

A separate payment status is added on top (not-ready, ready, receivable, payed), which indicates the progress of the collected amount being transferred back, distinct from the parcel's own delivery status.

In practice: schedule a job that polls in-progress parcels every few hours rather than every minute — the API enforces per-second, per-minute, per-hour and per-day quotas (visible in response headers), and the exact values aren't published. A call that's too frequent triggers a 429 before you've even identified the real limit.

Don't re-poll your entire order history on every pass: limit the query to parcels whose status isn't yet final ("Delivered", "Returned to sender"). On a high-volume store, this is what makes the difference between a scheduled job that stays within quota and one that exceeds it within the first hour.

Reference endpoints

Before creating parcels, query these endpoints once and cache the results on your server — they rarely change:

Endpoint	Content
GET /v1/wilayas/	List of served wilayas
GET /v1/communes/	Communes, with has_stop_desk and is_deliverable flags
GET /v1/centers/	Pickup points (stop-desk), with the ID to use in stopdesk_id
GET /v1/deliveryfees/	Rate card by wilaya

Using these exact labels in your order forms avoids nearly all parcel creation failures caused by a badly formed address. Refresh this cache once a week, not on every order: the list of served wilayas and communes rarely changes, and reading it on every pass needlessly eats into your quota.

Limits to know before committing

Three points that change how you build the integration:

• No webhook. Every delivery notification relies on periodic polling, never on a notification pushed by Yalidine to your server.
• No official SDK. Yalidine does not publish a client library. Community packages exist for Python, JavaScript/TypeScript and Laravel, as well as WordPress/WooCommerce modules — useful to get started quickly, but not maintained by Yalidine itself: check their activity before relying on them in production.
• No sandbox. Every parcel creation test is a real shipment. Isolate your tests with a recognizable order_id and cancel test parcels promptly.

Once the integration is wired up

Three checks before opening the flow to all your customers: a parcel created from your real order form does appear in the Yalidine dashboard with the correct amount to collect; the status reported by your scheduled job matches what the dashboard shows; and a misspelled commune in your form triggers a clear error rather than a badly addressed parcel. Run about ten real orders through this path before considering it reliable — edge cases (an incomplete address, a duplicate order, a status change missed by the scheduled job) almost never show up in the very first attempts.

To place this integration back into the full cash-on-delivery flow — phone confirmation, margin calculation with the return rate, choosing between several carriers — see the guide on cash on delivery and the comparison of delivery carriers in Algeria. Subscription tier details are on the pricing page.