Intégrer Yalidine à son site web : guide technique de l'API

Intégrer Yalidine à votre site consiste à appeler son API REST depuis votre serveur pour créer une expédition, puis à interroger régulièrement le statut du colis — il n'existe pas de notification automatique. Ce guide couvre l'authentification, la création de colis, le suivi et les limites réelles de l'API, sans intermédiaire.

Avant de commencer

Trois prérequis, dans l'ordre :

1. Un compte marchand Yalidine actif. L'accès à l'API n'est pas ouvert au public ; il suppose un compte professionnel déjà validé.
2. Des identifiants API. Générés depuis la section développeur du tableau de bord, sur yalidine.app. Deux valeurs à récupérer : un API ID et un API Token.
3. Un serveur capable d'appeler l'API. L'API bloque les requêtes cross-origin (CORS) : impossible d'appeler api.yalidine.app directement depuis le JavaScript du navigateur. Chaque appel doit partir de votre backend, jamais du client — ce qui évite aussi d'exposer votre Token dans le code source public de la boutique.

Aucun environnement de test (sandbox) n'est documenté. Vos premiers appels créent de vraies expéditions : validez votre intégration avec un colis réel à faible montant avant de brancher le flux de commande complet.

Authentification

L'API est en REST, réponses JSON, base https://api.yalidine.app/v1/. Chaque requête doit porter deux en-têtes HTTP :

X-API-ID: votre_api_id
X-API-TOKEN: votre_api_token
Content-Type: application/json

Sans ces deux en-têtes, l'API répond 401 Unauthorized avec un message explicite (API ID and/or Token must be specified). Stockez ces deux valeurs comme n'importe quel secret d'environnement — jamais dans un fichier versionné ou envoyé au navigateur.

Créer une expédition

La création de colis se fait par POST /v1/parcels, avec un tableau d'objets — l'API accepte la création groupée en un seul appel. Les champs qui comptent pour un premier envoi :

Champ	Rôle
order_id	Votre propre référence de commande, pour faire le lien avec votre base
firstname, familyname, contact_phone	Coordonnées du destinataire
to_wilaya_name, to_commune_name, address	Adresse de livraison
from_wilaya_name	Wilaya d'expédition (votre dépôt)
price	Montant à encaisser à la livraison, en DZD (0 à 150 000)
is_stopdesk + stopdesk_id	Livraison en point relais plutôt qu'à domicile ; l'identifiant du point relais vient de l'endpoint /centers
freeshipping	Indique si les frais de livraison sont à la charge du client ou absorbés par vous
weight, length, width, height	Dimensions du colis, utilisées pour le tarif

La réponse renvoie un code de suivi (tracking, par exemple yal-12345A) à conserver pour l'étape suivante. to_wilaya_name et to_commune_name doivent correspondre exactement aux libellés retournés par les endpoints de référence ci-dessous — une faute de frappe sur le nom de commune fait échouer la création.

Concrètement, un appel de création ressemble à ceci :

POST https://api.yalidine.app/v1/parcels/
X-API-ID: votre_api_id
X-API-TOKEN: votre_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 Coque téléphone",
    "price": 2500,
    "is_stopdesk": false,
    "freeshipping": false,
    "weight": 1
  }
]

Si un champ obligatoire manque ou qu'un libellé de commune ne correspond à rien dans le référentiel, l'API répond avec un code d'erreur et un message explicite plutôt que de créer un colis mal adressé — traitez cette réponse dans votre code plutôt que de supposer que l'appel a réussi. Sur un volume de plusieurs dizaines de commandes par jour, une validation systématique des noms de wilaya/commune avant l'appel API (par rapport aux listes mises en cache) évite l'essentiel de ces rejets.

Suivre le statut d'un colis

Pas de webhook côté Yalidine : votre serveur doit interroger l'API, pas l'inverse. Le suivi se fait via l'historique des statuts (GET /v1/histories/), filtrable par colis.

Les statuts observés côté transporteur, dans l'ordre du cycle de vie normal :

1. Pas encore expédié
2. Ramassé
3. Expédié
4. Sorti en livraison
5. Livré (ou : Échec livraison, Retourné au vendeur)

Un statut de paiement s'y ajoute séparément (not-ready, ready, receivable, payed) qui indique où en est le reversement du montant encaissé, distinct du statut de livraison du colis lui-même.

En pratique : programmez une tâche planifiée qui interroge les colis en cours toutes les quelques heures plutôt qu'à chaque minute — l'API impose des quotas par seconde, minute, heure et jour (visibles dans les en-têtes de réponse), et les valeurs exactes ne sont pas publiées. Un appel trop fréquent déclenche un 429 avant que vous ayez identifié la limite réelle.

Ne réinterrogez pas l'intégralité de votre historique de commandes à chaque passage : limitez la requête aux colis dont le statut n'est pas encore final (« Livré », « Retourné au vendeur »). Sur une boutique à fort volume, c'est ce qui fait la différence entre une tâche planifiée qui tient dans les quotas et une qui les dépasse dès la première heure.

Les endpoints de référence

Avant de créer des colis, interrogez ces endpoints une fois et mettez les résultats en cache côté serveur — ils changent rarement :

Endpoint	Contenu
GET /v1/wilayas/	Liste des wilayas desservies
GET /v1/communes/	Communes, avec indicateurs has_stop_desk et is_deliverable
GET /v1/centers/	Points relais (stop-desk), avec leur identifiant à utiliser dans stopdesk_id
GET /v1/deliveryfees/	Grille tarifaire par wilaya

Utiliser ces libellés exacts dans vos formulaires de commande évite la quasi-totalité des échecs de création de colis liés à une adresse mal formée. Rafraîchissez ce cache une fois par semaine, pas à chaque commande : la liste des wilayas et communes desservies évolue rarement, et une lecture à chaque passage consomme inutilement votre quota.

Les limites à connaître avant de s'engager

Trois points qui changent la manière de construire l'intégration :

• Pas de webhook. Toute notification de livraison passe par de l'interrogation périodique, jamais par une notification poussée par Yalidine vers votre serveur.
• Pas de SDK officiel. Yalidine ne publie pas de bibliothèque cliente. Des paquets communautaires existent pour Python, JavaScript/TypeScript et Laravel, ainsi que des modules WordPress/WooCommerce — utiles pour démarrer vite, mais non maintenus par Yalidine elle-même : vérifiez leur activité avant d'en dépendre en production.
• Pas de sandbox. Chaque test de création de colis est une vraie expédition. Isolez vos tests avec un order_id reconnaissable et annulez les colis de test rapidement.

Une fois l'intégration branchée

Trois vérifications avant d'ouvrir le flux à tous vos clients : un colis créé depuis votre formulaire de commande réel apparaît bien dans le tableau de bord Yalidine avec le bon montant à encaisser ; le statut remonté par votre tâche planifiée correspond à ce qu'affiche le tableau de bord ; et une commune mal orthographiée dans votre formulaire déclenche une erreur claire plutôt qu'un colis mal adressé. Faites passer une dizaine de commandes réelles par ce chemin avant de le considérer comme fiable — les cas limites (adresse incomplète, doublon de commande, changement de statut manqué par la tâche planifiée) n'apparaissent presque jamais sur les tout premiers essais.

Pour resituer cette intégration dans le flux complet du paiement à la livraison — confirmation téléphonique, calcul de marge avec le taux de retour, choix entre plusieurs transporteurs — consultez le guide sur le paiement à la livraison et le comparatif des sociétés de livraison en Algérie. Le détail des paliers d'abonnement est sur la page tarifs.