API Yalidine en Node.js et PHP

Créez, suivez et tarifez vos colis Yalidine (et GuepEx, même plateforme) avec le SDK dz-delivery — sans écrire vous-même les appels HTTP, la pagination ni le mapping des statuts.

Installer

TypeScript · npm

npm install @dz-delivery/core

PHP · Composer

composer require dz-delivery/sdk

Node.js ≥ 18 (aucune dépendance) ou PHP ≥ 8.2 (Guzzle 7). Le même code fonctionne ensuite pour les autres transporteurs : seule la configuration du client change.

Identifiants Yalidine

Option	Header envoyé	Où la trouver
`apiId`	`X-API-ID`	Tableau de bord développeur Yalidine
`apiToken`	`X-API-TOKEN`	Tableau de bord développeur Yalidine
`fromWilayaId` ou `fromWilayaName`	—	Votre wilaya d’origine (code `1`–`58`), requise pour `createParcel` et `getFees`

Yalidine en TypeScript / Node.js

TypeScript

import { createClient, isShippingError } from '@dz-delivery/core';

const yalidine = createClient('yalidine', {
  apiId: process.env.YALIDINE_API_ID!,
  apiToken: process.env.YALIDINE_API_TOKEN!,
  fromWilayaId: 16, // wilaya d'origine (Alger)
});

// Wilayas, communes, bureaux (stop desks)
const wilayas = await yalidine.getWilayas();            // id = code officiel 1–58
const communes = await yalidine.getCommunes(16);
const desks = await yalidine.getStopDesks({ wilayaId: 31 });

// Frais de livraison (poids en kg, dimensions en cm)
const quote = await yalidine.getFees({ toWilayaId: 31, weight: 2 });
// { deliveryFee, stopDeskFee, returnFee?, currency: 'DZD' }

// Créer un colis (contre-remboursement)
try {
  const parcel = await yalidine.createParcel({
    recipientName: 'Mohamed Amine',
    phone: '0550123456',
    address: 'Cité 221 lots, n°98',
    wilayaName: 'Oran',
    communeName: 'Bir El Djir',
    productName: 'T-shirt',
    price: 2500,
    orderId: 'ORDER-1001',
  });

  // Suivi : statut unifié + historique (le plus ancien en premier)
  const { parcel: current, events } = await yalidine.track(parcel.trackingNumber);
  console.log(current.status, events.at(-1)?.label);
} catch (err) {
  if (isShippingError(err)) console.error(err.code, err.message, err.details);
}

Yalidine en PHP / Laravel

PHP

use DzDelivery\ClientFactory;
use DzDelivery\Errors\ShippingError;

$yalidine = ClientFactory::create('yalidine', [
    'apiId'        => getenv('YALIDINE_API_ID'),
    'apiToken'     => getenv('YALIDINE_API_TOKEN'),
    'fromWilayaId' => 16, // ou 'fromWilayaName' => 'Alger'
]);

$wilayas = $yalidine->getWilayas();
$desks   = $yalidine->getStopDesks(['wilayaId' => 31]);
$quote   = $yalidine->getFees(['toWilayaId' => 31, 'weight' => 2]);

try {
    $parcel = $yalidine->createParcel([
        'recipientName' => 'Mohamed Amine',
        'phone'         => '0550123456',
        'address'       => 'Cité 221 lots, n°98',
        'wilayaName'    => 'Oran',
        'communeName'   => 'Bir El Djir',
        'productName'   => 'T-shirt',
        'price'         => 2500,
        'orderId'       => 'ORDER-1001',
    ]);

    $result = $yalidine->track($parcel->trackingNumber);
    echo $result->parcel->status; // pending | in_transit | delivered | ...
} catch (ShippingError $e) {
    echo "{$e->code}: {$e->getMessage()}";
}

Guide PHP complet (Laravel, erreurs, tests) : guide-php.md.

Méthodes supportées

Méthode	Support	Notes
`createParcel`	oui	Les nouveaux colis sont « En préparation » → `pending`.
`track`	oui	Statut unifié + historique complet.
`getFees`	oui	Poids volumétrique facturé s’il est plus élevé (`length` / `width` / `height` en cm).
`getWilayas / getCommunes`	oui	Le `id` de wilaya est le code officiel.
`getStopDesks`	oui	Bureaux Yalidine (`centers`), `communeId` optionnel.
`listParcels`	NOT_SUPPORTED	Pas encore implémenté côté SDK.
`cancelParcel`	oui	Uniquement les colis encore « En préparation ».
`healthCheck`	oui	Vérifie les identifiants (appel réel).

API GuepEx

GuepEx utilise la même API que Yalidine sur un autre domaine. Utilisez le provider yalidine avec vos identifiants GuepEx et l’URL GuepEx :

TypeScript

import { createClient, GUEPEX_DEFAULT_BASE_URL } from '@dz-delivery/core';

const guepex = createClient('yalidine', {
  apiId: process.env.GUEPEX_API_ID!,
  apiToken: process.env.GUEPEX_API_TOKEN!,
  fromWilayaId: 16,
  baseUrl: GUEPEX_DEFAULT_BASE_URL, // https://api.guepex.app/v1
});

PHP

use DzDelivery\ClientFactory;
use DzDelivery\Providers\YalidineProvider;

$guepex = ClientFactory::create('yalidine', [
    'apiId'        => getenv('GUEPEX_API_ID'),
    'apiToken'     => getenv('GUEPEX_API_TOKEN'),
    'fromWilayaId' => 16,
    'baseUrl'      => YalidineProvider::GUEPEX_DEFAULT_BASE_URL,
]);

À savoir sur l’API Yalidine

Wilaya d’origine obligatoire : sans fromWilayaId / fromWilayaName, createParcel et getFees renvoient VALIDATION_ERROR.
Wilaya et commune peuvent être passées par id, par code officiel ou par nom : le SDK les résout avant l’appel HTTP.
Le numéro de suivi Yalidine sert aussi d’identifiant (parcel.id === parcel.trackingNumber).
La pagination (page_size = 1000) et les wilayas/communes non livrables sont gérées pour vous.
En cas de limite de débit, l’erreur RATE_LIMITED indique le délai d’attente (retryAfter) quand Yalidine l’envoie.

Mapping natif détaillé (endpoints, champs, statuts) : PROVIDERS.md.

FAQ Yalidine

Comment obtenir une clé API Yalidine ?

Depuis votre espace marchand Yalidine, section développeur : vous y trouverez l’API ID et l’API token à passer en apiId et apiToken.

Comment calculer les frais de livraison Yalidine ?

getFees({ toWilayaId, weight }) renvoie deliveryFee (domicile) et stopDeskFee (bureau) en DZD, à partir de votre wilaya d’origine.

Comment envoyer un colis vers un bureau Yalidine (stop desk) ?

Listez les bureaux avec getStopDesks({ wilayaId }), puis créez le colis avec isStopDesk: true et stopDeskId = l’id du bureau.

Le SDK fonctionne-t-il avec GuepEx ?

Oui, voir la section API GuepEx : même provider, autre baseUrl.

Autres transporteurs

Même interface, mêmes statuts normalisés (pending, in_transit, delivered…).