Parcel statuses, models and error codes

The 7 unified parcel statuses

Parcel.status and TrackingEvent.status always hold one of these values, whatever the carrier:

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

The examples above are excerpts. Each carrier’s full native → unified table is in PROVIDERS.md; it is identical in TypeScript and PHP, enforced by shared fixtures (docs/fixtures/).

Mapping a native status (webhooks, imports)

The mappers are exported: use them when you receive a native status outside track(), for example in a Maystro webhook.

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

mapYalidineStatus('Sorti en livraison');  // 'in_transit'
mapMaystroStatus(41);                     // 'delivered' (code or name)
PARCEL_STATUSES;                          // the 7 statuses, in order
// Also: 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 or name)
ParcelStatus::DELIVERED;                               // constants, ParcelStatus::ALL for the list

Error codes

Every failure is thrown as a ShippingError (fields in Models). Its code is one of:

Default HTTP → code mapping: 400, 422 → VALIDATION_ERROR, 401, 403 → AUTH_FAILED, 404 → NOT_FOUND, 429 → RATE_LIMITED, 5xx → PROVIDER_ERROR, other 4xx → UNKNOWN.

Handling examples (retry on RATE_LIMITED, showing validation errors): PHP guide.

Conventions

The raw field

Every returned model (Parcel, TrackingEvent, FeeQuote, Location, ShippingError) may carry an optional raw field with the unmodified native API response (or the relevant fragment).

• raw is for power users and debugging. Its shape is not part of the contract and may change when the carrier changes its API.
• Application code should not depend on raw for core logic.
• raw is populated by default; the client option includeRaw: false disables it.

Models

The same models, with the same field names, in TypeScript and PHP.

ParcelInput (input to createParcel)

¹ Exactly one of wilayaId / wilayaName. ² Exactly one of communeId / communeName. ³ Exactly one of productName / productList: providers that need a list convert productName to [{ name, quantity: 1, unitPrice: price }]; providers that need a string join the productList names.

Whether price includes the delivery fee depends on the carrier (documented in PROVIDERS.md).

ProductItem

Parcel

TrackingEvent and TrackResult

track() returns a TrackResult = { parcel, events }: parcel is the current state, events the history sorted by at ascending (oldest first), possibly empty if the carrier exposes no history.

FeeQuery (input to getFees)

FeeQuote

Location (wilayas and communes)

ShippingError

Thrown as an exception (TS: class ShippingError extends Error; PHP: class ShippingError extends \RuntimeException).

StopDeskQuery and StopDesk

Input to getStopDesks: wilayaId (string | int, required: provider Location.id, code 1–58 or name) and communeId (string | int, optional: provider Location.id or name). Some carriers require communeId (Maystro); elsewhere it is an optional filter, and wilaya-only is the safer choice when unsure.

ParcelListQuery and ParcelListPage

The ShippingProvider interface

Every client implements the same interface: ShippingProvider in TypeScript, ShippingProviderInterface in PHP.

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

export interface HealthCheckResult {
  ok: true;
  provider: string;
  /** Round-trip duration in milliseconds. */
  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;
}

Method behavior

• createParcel: validates required fields client-side (VALIDATION_ERROR before any HTTP call) and resolves wilayaName / communeName / wilaya codes to provider IDs. If the carrier only returns an ID on creation, the provider may do a follow-up read to fill trackingNumber and status.
• track: returns the current Parcel plus history. If the carrier needs an internal ID for history, the provider resolves it from the tracking number.
• getFees: returns a single quote for the requested destination and mode. NOT_FOUND if the destination has no rate.
• getWilayas / getCommunes: return only deliverable locations when the carrier exposes that information. Results may be cached in memory for the client’s lifetime.
• cancelParcel: accepts a tracking number or an internal ID. NOT_SUPPORTED if the carrier cannot cancel, VALIDATION_ERROR / PROVIDER_ERROR if the parcel is past the cancellable state. Returns void because some carriers answer 204 No Content: call track() afterwards if you need the new status.
• getStopDesks: lists the stop desks / pickup points of a wilaya (optionally one commune). VALIDATION_ERROR when a carrier needs communeId and it is missing, NOT_SUPPORTED when the carrier exposes no listing. May throw NOT_FOUND with an actionable details hint when a commune filter yields no desks but the wilaya still has some (typical for ZRExpress hubs).
• listParcels: paginated list of the account’s parcels with their unified status, without history (call track() for that). NOT_SUPPORTED when the carrier exposes no listing. Prefer webhooks over aggressive polling when available.
• healthCheck: probes credentials and connectivity with a lightweight authenticated request (the wilayas listing). Always hits the network (bypasses the cache). Returns { ok: true, provider, latencyMs }, otherwise throws ShippingError (AUTH_FAILED, NETWORK_ERROR, RATE_LIMITED, …). Never throws NOT_SUPPORTED.

Creating a client

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

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

Provider-specific credentials:

A baseUrl override must be an https: URL, because credentials go with every request (in headers, or in the query string for Elogistia). The Ecotrack, NoEST, E-com, MDM and Elogistia clients reject any other URL with VALIDATION_ERROR. Detailed PHP configuration: PHP guide.

Outside the unified contract

Intentionally not part of the common interface: catalog endpoints (products, categories, stock), parcel updates (address, amount, products), exchanges, refunds, pickup bags, claims, customers, treasury and payments, reports, and webhook endpoint management. They may come later as optional, carrier-specific modules that do not change ShippingProvider.

Richer carrier features ship as extras on the concrete provider class, for example ZRExpress bulk create/delete, labels and webhook verification (ZRExpress page, ZREXPRESS.md).

This contract is versioned (v0.1): breaking changes to the models or the interface require a version bump and a matching release of both packages.

Further reading

• PHP / Laravel guide
• Yalidine API
• ZRExpress API
• Maystro API
• Ecotrack API
• NoEST API
• E-com Delivery API
• MDM Express API
• Elogistia API
• Full documentation