CourierDZ

CourierDZ is a PHP client designed to simplify the integration of Algerian shipping providers into your applications. Whether you're working on an e-commerce platform or logistics solution, CourierDZ provides a unified and easy-to-use interface for managing orders, tracking shipments, and more.

Features

• Multi-Provider Support: Integrate with popular Algerian shipping services such as:
  • Procolis ( Zr Express , E-Com Delivery, Abex Express , Flash Delivery, E-Send , WIN DELIVERY , COLILOG EXPRESS, GODYMA EXPRESS , LETS GO DELIVERY, LEOPARD EXPRESS , MR LIVREUR, EL AMANA DELIVERY, ALLO LIVRAISON, COLIRELI )
  • Yalidine ( Yalitec , GuepEX , Zimou Express )
  • Ecotrack ( DHD , Conexlog (UPS) )
  • Mayesto Delivery
  • Elogistia
  • And more to come!
• Unified API: A consistent interface to interact with all supported providers.
• Order Management: Create, update, and cancel shipping orders effortlessly.
• Extensible Design: Easily add new providers or customize existing ones.

Requirements

• PHP 8.2 or higher
• cURL extension

Installation

You can install the package via composer:

composer require piteurstudio/courierdz

Current Supported Methods

Provider/Feature	Yalidine	Procolis	Ecotrack	Mayesto Delivery
testCredentials	✅	✅	✅	✅
getRates	❌	✅	✅	❔
getRates(null , $to_wilaya_id)	❌	✅	✅	❔
getRates($from_wilaya_id , $to_wilaya_id)	✅	❌	❌	❔
getCreateValidationRules	✅	✅	✅	❔
createOrder	✅	✅	✅	❔
getOrder	✅	✅	❔	❔
updateOrder	❔	❔	❔	❔
cancelOrder	❔	❔	❔	❔
orderLabel	✅	❌	✅	❔

• ✅ Implemented
• ❌ Unsupported by the provider
• ⌛ In Progress
• ❔ Not implemented yet ( unknown if supported or not )

Note : Unsupported method can be implemented in the future by using user and password instead of API.

Usage

List Available Providers

use CourierDZ\CourierDZ;
    
$providersMetaData = CourierDZ::providers();

Output :

Setup

/*
 * Provider name can be one of the following: `ShippingProvider::ZREXPRESS` ( check ShippingProvider class for more information )
 * ------------------------------------------------------------------------------
 * For example, to setup a shipping service for Procolis ( ZREXPRESS ), 
 * you need to provide an array of credentials like this: ['token' => '****', 'key' => '****']
 * 
 * For Ecotrack, you only need to provide a token like this: ['token' => '****']
 * For Yalidine you need to provide an id & token like this:  [ 'id' => '****', 'token' => '****']
 * 
 * Check ShippingProvider class for more information.
 */
 
$shippingProvider = CourierDZ::provider(ShippingProvider::ZREXPRESS, $credentials);

Get Shipping Provider Metadata

$metadata = $shippingProvider->metadata();

Output :

Validate Credentials

/*
 * Check if the provided credentials are valid.
 * 
 * return bool
 */
 
echo $shippingProvider->testCredentials() ? 'Valid.' : 'Invalid.';

Get Rates

/*
 * return array of rates of shipping from one wilaya to another 
 * or all rates depending on the parameters / provider api.
 */
 
$rates = $shippingProvider->getRates();  // all rates

$rates = $shippingProvider->getRates(null , $to_wilaya_id); // rates to specific wilaya
        
$rates = $shippingProvider->getRates($from_wilaya_id , $to_wilaya_id); // Yalidine require $from_wilaya_id , $to_wilaya_id

Order Management

- Get Create Validation Rules

/*
 * usefull for form validation and which fields are required to create a new order
 * Note : results may vary depending on the provider
 */
 
$orderCreationRules = $shippingProvider->getCreateOrderValidationRules();

Output :

- Create Order

/*
 * return array of provider response
 * Note : results may vary depending on the provider
 */
 
$result = $shippingProvider->createOrder([
        'Tracking' => 'CourierDz-123',
        'TypeLivraison' => 1,
        'TypeColis' => 0,
        'Confrimee' => 0,
        'Client' => 'Mohamed',
        'MobileA' => '0990909090',
        'MobileB' => '0880808080',
        'Adresse' => 'Rue 39',
        'IDWilaya' => "09",
        'Commune' => 'Maraval',
        'Total' => "2000",
        'Note' => 'test test',
        'TProduit' => 'Article1',
        "id_Externe" => 'CourierDz-123',
        "Source" => 'CourierDz',
    ]))

- Get Order

/*
 * return array of order details 
 * Note : results may vary depending on the provider
 */
 
$result = $shippingService->getOrder('CourierDz-123');

- Order Label

/*
 * return array of label data ( base64 encoded string or url )
 */
 
$label = $shippingProvider->orderLabel('CourierDz-123');

Output :

[
    [type] => 'pdf'
    [data] => 'base64 encoded string'
]
         -- OR --
[     
    [type] => 'url'
    [url] => 'https://example.com/label.pdf'
]

---

Contribution

We welcome all contributions! Please follow these guidelines:

1. Document any changes in behavior — ensure README.md updated accordingly.
2. Write tests to cover any new functionality.
3. Please ensure that your pull request passes all tests.

Testing

composer test

Issues & Suggesting Features

If you encounter any issues or have ideas for new features, please open an issue.

We appreciate your feedback and contributions to help improve this package.

Provider not yet included?

Request Provider and provide the following information:

• Provider Name
• Provider Website
• API Documentation
• Any other relevant information

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Nassim / Piteur Studio
• All Contributors

Disclaimer

• This package is not officially affiliated with or endorsed by any shipping providers.
• Names, logos, and trademarks are the property of their respective owners.
• Before using any shipping provider, ensure it is authorized by ARPCE. ( Check the approved list here. )
• This package may include providers not listed by ARPCE; verify their compliance before use.

⭐ Support Us

If you find this package helpful, please consider giving it a ⭐ on GitHub ! Your support encourages us to keep improving the project. Thank you!

License

The MIT License (MIT). Please see License File for more information.