Statuts de colis, modèles et erreurs

Les 7 statuts de colis unifiés

Parcel.status et TrackingEvent.status valent toujours l’une de ces valeurs, quel que soit le transporteur :

pending | created | in_transit | delivered | returned | cancelled | unknown

Les exemples ci-dessus sont des extraits. La table natif → unifié de chaque transporteur se trouve dans PROVIDERS.md ; elle est identique en TypeScript et en PHP, ce que garantissent des fixtures partagées (docs/fixtures/).

Convertir un statut natif (webhooks, imports)

Les mappers sont exportés : utilisez-les quand vous recevez un statut natif en dehors de track(), par exemple dans un webhook Maystro.

import { mapYalidineStatus, mapMaystroStatus, PARCEL_STATUSES } from '@dz-delivery/core';

mapYalidineStatus('Sorti en livraison');  // 'in_transit'
mapMaystroStatus(41);                     // 'delivered' (code ou nom)
PARCEL_STATUSES;                          // les 7 statuts, dans l'ordre
// Aussi : mapZRExpressStatus, mapEcotrackStatus, mapNoestStatus, mapEcomStatus, mapMdmStatus, mapElogistiaStatus

use DzDelivery\Support\StatusMapper;
use DzDelivery\Models\ParcelStatus;

StatusMapper::map('yalidine', 'Sorti en livraison');  // 'in_transit'
StatusMapper::maystro(41);                             // 'delivered' (code ou nom)
ParcelStatus::DELIVERED;                               // constantes, ParcelStatus::ALL pour la liste

Codes d’erreur

Toute erreur est levée sous forme de ShippingError (champs détaillés dans Modèles). Le champ code vaut l’une de ces valeurs :

Correspondance HTTP → code par défaut : 400, 422 → VALIDATION_ERROR, 401, 403 → AUTH_FAILED, 404 → NOT_FOUND, 429 → RATE_LIMITED, 5xx → PROVIDER_ERROR, autres 4xx → UNKNOWN.

Exemples de gestion (relance sur RATE_LIMITED, affichage des erreurs de validation) : guide PHP.

Conventions

Le champ raw

Chaque modèle renvoyé (Parcel, TrackingEvent, FeeQuote, Location, ShippingError) peut porter un champ optionnel raw contenant la réponse native non modifiée de l’API (ou le fragment utile).

• raw sert au débogage et aux usages avancés. Sa forme ne fait pas partie du contrat et peut changer quand le transporteur modifie son API.
• Votre code applicatif ne devrait pas en dépendre pour sa logique principale.
• raw est rempli par défaut ; l’option client includeRaw: false le désactive.

Modèles

Les mêmes modèles, avec les mêmes noms de champs, en TypeScript et en PHP.

ParcelInput (entrée de createParcel)

¹ Exactement un de wilayaId / wilayaName. ² Exactement un de communeId / communeName. ³ Exactement un de productName / productList : les providers qui exigent une liste convertissent productName en [{ name, quantity: 1, unitPrice: price }], ceux qui exigent une chaîne joignent les noms de productList.

L’inclusion ou non des frais de livraison dans price dépend du transporteur (documenté dans PROVIDERS.md).

ProductItem

Parcel

TrackingEvent et TrackResult

track() renvoie un TrackResult = { parcel, events } : parcel est l’état actuel du colis, events l’historique trié par at croissant (le plus ancien en premier), éventuellement vide si le transporteur n’expose pas d’historique.

FeeQuery (entrée de getFees)

FeeQuote

Location (wilayas et communes)

ShippingError

Levée en exception (TS : class ShippingError extends Error ; PHP : class ShippingError extends \RuntimeException).

StopDeskQuery et StopDesk

Entrée de getStopDesks : wilayaId (string | int, requis : Location.id, code 1–58 ou nom) et communeId (string | int, optionnel : Location.id ou nom). Certains transporteurs exigent communeId (Maystro) ; ailleurs c’est un filtre optionnel, et en cas de doute préférez la wilaya seule.

ParcelListQuery et ParcelListPage

Interface ShippingProvider

Tous les clients implémentent la même interface : ShippingProvider en TypeScript, ShippingProviderInterface en PHP.

export type ParcelStatus =
  | 'pending' | 'created' | 'in_transit' | 'delivered'
  | 'returned' | 'cancelled' | 'unknown';

export interface HealthCheckResult {
  ok: true;
  provider: string;
  /** Durée aller-retour en millisecondes. */
  latencyMs: number;
}

export interface ShippingProvider {
  readonly name: string; // 'zrexpress' | 'yalidine' | ...
  createParcel(input: ParcelInput): Promise<Parcel>;
  track(trackingNumber: string): Promise<TrackResult>;
  getFees(query: FeeQuery): Promise<FeeQuote>;
  getWilayas(): Promise<Location[]>;
  getCommunes(wilayaId: string | number): Promise<Location[]>;
  getStopDesks(query: StopDeskQuery): Promise<StopDesk[]>;
  listParcels(query?: ParcelListQuery): Promise<ParcelListPage>;
  cancelParcel(trackingNumberOrId: string): Promise<void>;
  healthCheck(): Promise<HealthCheckResult>;
}

namespace DzDelivery\Contracts;

use DzDelivery\Models\FeeQuery;
use DzDelivery\Models\FeeQuote;
use DzDelivery\Models\HealthCheckResult;
use DzDelivery\Models\Location;
use DzDelivery\Models\Parcel;
use DzDelivery\Models\ParcelInput;
use DzDelivery\Models\ParcelListPage;
use DzDelivery\Models\ParcelListQuery;
use DzDelivery\Models\StopDesk;
use DzDelivery\Models\StopDeskQuery;
use DzDelivery\Models\TrackResult;

interface ShippingProviderInterface
{
    public function getName(): string;
    public function createParcel(ParcelInput|array $input): Parcel;
    public function track(string $trackingNumber): TrackResult;
    public function getFees(FeeQuery|array $query): FeeQuote;
    /** @return Location[] */
    public function getWilayas(): array;
    /** @return Location[] */
    public function getCommunes(string|int $wilayaId): array;
    /** @return StopDesk[] */
    public function getStopDesks(StopDeskQuery|array $query): array;
    public function listParcels(ParcelListQuery|array|null $query = null): ParcelListPage;
    public function cancelParcel(string $trackingNumberOrId): void;
    public function healthCheck(): HealthCheckResult;
}

Comportement des méthodes

• createParcel : valide les champs requis côté client (VALIDATION_ERROR avant tout appel HTTP) et résout wilayaName / communeName / codes de wilaya en ids du transporteur. Si le transporteur ne renvoie qu’un id à la création, le provider peut relire le colis pour remplir trackingNumber et status.
• track : renvoie le Parcel actuel et son historique. Si le transporteur a besoin d’un id interne pour l’historique, le provider le retrouve à partir du numéro de suivi.
• getFees : renvoie un seul tarif pour la destination et le mode demandés. NOT_FOUND si la destination n’a pas de tarif.
• getWilayas / getCommunes : ne renvoient que les localités livrables quand le transporteur fournit l’information. Les résultats peuvent être mis en cache en mémoire pendant la vie du client.
• cancelParcel : accepte un numéro de suivi ou un id interne. NOT_SUPPORTED si le transporteur ne permet pas l’annulation, VALIDATION_ERROR / PROVIDER_ERROR si le colis n’est plus annulable. Renvoie void car certains transporteurs répondent 204 No Content : appelez track() ensuite pour connaître le nouveau statut.
• getStopDesks : liste les stop desks / points relais d’une wilaya (éventuellement d’une commune). VALIDATION_ERROR si le transporteur exige communeId et qu’il manque, NOT_SUPPORTED sans liste disponible. Peut lever NOT_FOUND avec une indication dans details quand le filtre commune ne donne rien alors que la wilaya a des bureaux (cas typique des hubs ZRExpress).
• listParcels : liste paginée des colis du compte avec leur status unifié, sans l’historique (utilisez track()). NOT_SUPPORTED si le transporteur n’expose pas de liste. Préférez les webhooks à un polling agressif quand ils existent.
• healthCheck : vérifie identifiants et connectivité avec une requête authentifiée légère (liste des wilayas). Appelle toujours le réseau (ignore le cache). Renvoie { ok: true, provider, latencyMs }, sinon lève une ShippingError (AUTH_FAILED, NETWORK_ERROR, RATE_LIMITED…). Ne lève jamais NOT_SUPPORTED.

Créer un client

const client = createClient('zrexpress', { apiKey, tenant, /* baseUrl?, timeoutMs?, includeRaw? */ });

$client = ClientFactory::create('zrexpress', ['apiKey' => ..., 'tenant' => ..., /* 'baseUrl', 'timeoutMs', 'includeRaw' */]);

Identifiants propres à chaque transporteur :

Un baseUrl personnalisé doit être une URL https:, car les identifiants accompagnent chaque requête (en en-tête, ou dans la query string chez Elogistia). Les clients Ecotrack, NoEST, E-com, MDM et Elogistia refusent toute autre URL avec VALIDATION_ERROR. Configuration détaillée en PHP : guide PHP.

Hors du contrat unifié

Volontairement absents de l’interface commune : endpoints de catalogue (produits, catégories, stock), modification de colis (adresse, montant, produits), échanges, remboursements, sacs d’enlèvement, réclamations, clients, trésorerie et paiements, rapports, gestion des endpoints webhook. Ils pourront arriver plus tard sous forme de modules propres à un transporteur, sans changer ShippingProvider.

Les fonctions plus riches d’un transporteur sont exposées comme extras sur sa classe concrète, par exemple pour ZRExpress la création / suppression en masse, les étiquettes et la vérification des webhooks (page ZRExpress, ZREXPRESS.md).

Ce contrat est versionné (v0.1) : tout changement cassant des modèles ou de l’interface implique une nouvelle version et une publication des deux paquets.

Aller plus loin

• Guide PHP / Laravel
• API Yalidine
• API ZRExpress
• API Maystro
• API Ecotrack
• API NoEST
• API E-com Delivery
• API MDM Express
• API Elogistia
• Documentation complète